Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
IconPicker 图标选择器
点开面板选一个图标,绑定值是图标名(<NsIcon name> 用的名字),适合菜单、分类这类要配图标的表单项。面板顶部可以按名字搜索,下面按分组排列 @ns/icons 的内置图标,也可以只在指定的几个图标里选。
引入
import { NsIconPicker } from '@ns/ui'
基础用法
用 v-model 绑定图标名,没选时是空字符串。选中后触发器里显示图标和名字。
<script setup lang="ts">
import { ref } from 'vue'
import { NsIcon, NsIconPicker, NsSpace } from '@ns/ui'
const icon = ref('')
</script>
<template>
<NsSpace wrap>
<NsIconPicker v-model="icon" style="width: 240px" />
<NsIcon v-if="icon" :name="icon" />
</NsSpace>
</template>
面板里的内置图标分 5 组:方向和导航、操作、状态、用户和通用、文件(和图标清单一致),组内按图标名排序。鼠标停在图标上会显示图标名,当前选中的图标高亮。
搜索
面板打开后焦点在搜索框里,直接输入就能按图标名过滤,不分大小写,前后的空格会被忽略。没有匹配图标的分组不显示,都没有时显示 emptyText。输入关键字后按回车,直接选中第一个匹配的图标。
图标名都是英文,例如 arrow、user、file。每次打开面板时搜索框是空的。
<script setup lang="ts">
import { ref } from 'vue'
import { NsIconPicker } from '@ns/ui'
const icon = ref('')
</script>
<template>
<NsIconPicker v-model="icon" placeholder="打开后输入 arrow 搜索" style="width: 240px" />
</template>
可清空
clearable 打开后,有值时触发器右侧显示清空按钮(没值或禁用时不显示),点了以后值变成空字符串。
<script setup lang="ts">
import { ref } from 'vue'
import { NsIconPicker } from '@ns/ui'
const icon = ref('user')
</script>
<template>
<NsIconPicker v-model="icon" clearable style="width: 240px" />
<p style="margin-top: 12px">绑定值:{{ JSON.stringify(icon) }}</p>
</template>
限定图标范围
icons 传一组图标名,面板里只显示这些图标,按传入的顺序平铺、不再分组;重复的名字只显示一次。
<script setup lang="ts">
import { ref } from 'vue'
import { NsIconPicker } from '@ns/ui'
const icon = ref('user')
const menuIcons = ['home', 'user', 'users', 'setting', 'table', 'file', 'folder', 'bell', 'mail']
</script>
<template>
<NsIconPicker v-model="icon" :icons="menuIcons" style="width: 240px" />
</template>
传空数组时没有可选的图标,面板里显示 emptyText:
<script setup lang="ts">
import { ref } from 'vue'
import { NsIconPicker } from '@ns/ui'
const icon = ref('')
</script>
<template>
<NsIconPicker v-model="icon" :icons="[]" empty-text="还没有可选的图标" style="width: 240px" />
</template>
自定义图标
icons 里也可以放 @ns/icons 以外的名字,这些图标用 icon 插槽自己画。插槽同时用在面板的每个格子和触发器里选中的图标上,作用域参数 icon 是图标名。
<script setup lang="ts">
import { ref } from 'vue'
import { NsIcon, NsIconPicker } from '@ns/ui'
const icon = ref('brand-cube')
const custom: Record<string, string> = {
'brand-cube': 'M12 2 3 7v10l9 5 9-5V7l-9-5zm0 2.3L18.6 8 12 11.7 5.4 8 12 4.3z'
}
</script>
<template>
<NsIconPicker v-model="icon" :icons="['brand-cube', 'home', 'star']">
<template #icon="{ icon }">
<NsIcon :name="icon">
<svg v-if="custom[icon]" viewBox="0 0 24 24" fill="currentColor">
<path :d="custom[icon]" />
</svg>
</NsIcon>
</template>
</NsIconPicker>
</template>
插槽里的图标大小跟着格子走(用 1em 的图标,例如 NsIcon,会自动缩放),不用自己写尺寸。
自定义文案
组件内置的文字都可以用属性改:
<script setup lang="ts">
import { ref } from 'vue'
import { NsIconPicker } from '@ns/ui'
const icon = ref('')
</script>
<template>
<NsIconPicker
v-model="icon"
placeholder="选一个菜单图标"
filter-placeholder="输入英文名,例如 arrow"
empty-text="找不到这个图标"
:group-labels="{ navigation: '导航', user: '用户' }"
/>
</template>
groupLabels 只改写了的分组,其余分组用默认标题。分组的 key 见“类型”里的 IconPickerGroupName。
尺寸
size 有 large、default、small 三种。触发器和同尺寸的 Select 一样,面板跟着变:
| 尺寸 | 触发器高度 | 字号 | 圆角 | 箭头、选中的图标 | 面板格子 | 格子里的图标 | 格子圆角 | 面板内边距 |
|---|---|---|---|---|---|---|---|---|
| large | 40px | 16px | 8px | 18px | 40px | 20px | 8px | 12px |
| default | 32px | 14px | 6px | 16px | 32px | 18px | 6px | 8px |
| small | 24px | 12px | 4px | 14px | 24px | 16px | 4px | 8px |
格子之间留 4px,一行 8 个;面板里的搜索框也用同一个尺寸。不写 size 时依次跟随所在的 NsFormItem、NsForm、NsConfigProvider 的 size,都没有时是 default。
每一行是一种尺寸,依次是图标选择器(可清空)、同尺寸的选择器和按钮:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsIconPicker, NsSelect, NsSpace } from '@ns/ui'
const icon = ref('home')
const value = ref('home')
const options = [
{ label: '首页', value: 'home' },
{ label: '设置', value: 'setting' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsIconPicker v-model="icon" size="large" clearable style="width: 200px" />
<NsSelect v-model="value" size="large" :options="options" style="width: 160px" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsIconPicker v-model="icon" clearable style="width: 200px" />
<NsSelect v-model="value" :options="options" style="width: 160px" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsIconPicker v-model="icon" size="small" clearable style="width: 200px" />
<NsSelect v-model="value" size="small" :options="options" style="width: 160px" />
<NsButton size="small">按钮</NsButton>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
禁用
禁用时不能聚焦、不能打开面板,也不显示清空按钮。放在 NsForm 里时跟随表单的 disabled。三种尺寸的禁用状态,以及没选图标时的样子:
<script setup lang="ts">
import { ref } from 'vue'
import { NsIconPicker, NsSpace } from '@ns/ui'
const icon = ref('home')
const empty = ref('')
</script>
<template>
<NsSpace wrap>
<NsIconPicker v-model="icon" size="large" disabled clearable style="width: 180px" />
<NsIconPicker v-model="icon" disabled clearable style="width: 180px" />
<NsIconPicker v-model="icon" size="small" disabled clearable style="width: 180px" />
<NsIconPicker v-model="empty" disabled style="width: 180px" />
</NsSpace>
</template>
在表单里
放在 NsFormItem 里时和其他表单控件一样:标签通过 aria-labelledby 关联到选择器,值变化时触发 change 规则,关闭面板时触发 blur 规则。validateEvent 设为 false 可以关掉这两种触发。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsIconPicker } from '@ns/ui'
const form = reactive({ icon: '' })
const rules = {
icon: [{ required: true, message: '请选择菜单图标', trigger: 'change' }]
}
</script>
<template>
<NsForm :model="form" :rules="rules">
<NsFormItem label="菜单图标" prop="icon">
<NsIconPicker v-model="form.icon" clearable />
</NsFormItem>
</NsForm>
</template>
事件
选了另一个图标或清空时触发 change(再点一次当前已选的图标只关闭面板,不触发);点清空按钮时触发 clear;面板打开、关闭时触发 visible-change。最近的事件显示在下方:
<script setup lang="ts">
import { ref } from 'vue'
import { NsIconPicker, NsSpace } from '@ns/ui'
const icon = ref('home')
const logs = ref<string[]>([])
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onChange = (value: string) => log(`change:${JSON.stringify(value)}`)
const onVisibleChange = (visible: boolean) => log(`visible-change:${visible}`)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsIconPicker
v-model="icon"
clearable
style="width: 240px"
@change="onChange"
@clear="log('clear')"
@visible-change="onVisibleChange"
/>
<div class="logs">
<div v-if="logs.length === 0">还没有触发事件</div>
<div v-for="(item, index) in logs" :key="index">{{ item }}</div>
</div>
</NsSpace>
</template>
<style scoped>
.logs {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
调用方法
通过 ref 调用 focus()、blur()。聚焦后按回车或空格就能打开面板:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsIconPicker, NsSpace } from '@ns/ui'
const pickerRef = ref<InstanceType<typeof NsIconPicker>>()
const icon = ref('')
</script>
<template>
<NsSpace wrap>
<NsIconPicker ref="pickerRef" v-model="icon" style="width: 240px" />
<NsButton @click="pickerRef?.focus()">聚焦(focus)</NsButton>
<NsButton @click="pickerRef?.blur()">失焦(blur)</NsButton>
</NsSpace>
</template>
键盘操作
选择器可以用 Tab 聚焦,聚焦后:
| 按键 | 作用 |
|---|---|
| Enter、空格 | 打开面板,焦点移到搜索框;再按一次关闭 |
| ↓、↑ | 打开面板,焦点移到搜索框 |
| Esc | 面板打开时关闭面板 |
| Tab | 面板打开时关闭面板,焦点移到下一个元素 |
面板打开后:
| 位置 | 按键 | 作用 |
|---|---|---|
| 搜索框 | ↓ | 进入图标区,停在选中的图标上(没有时是第一个) |
| 搜索框 | Enter | 输入了关键字时选中第一个匹配的图标;输入法选词时的回车不算 |
| 图标区 | ← → | 上一个、下一个图标,跨行、跨分组按顺序走,到头后不动 |
| 图标区 | ↑ ↓ | 上一行、下一行的同一列;那一行比较短时停在它的最后一个 |
| 图标区 | ↑(第一行) | 回到搜索框 |
| 图标区 | Home、End | 第一个、最后一个图标 |
| 图标区 | Enter、空格 | 选中图标,关闭面板,焦点回到选择器 |
| 任意 | Esc | 关闭面板,焦点回到选择器,不会把外层的对话框一起关掉 |
| 任意 | Tab | 在搜索框、搜索框的清空按钮、图标区之间循环,不会跑出面板 |
图标区只有一个格子能用 Tab 进入(选中的图标,或者方向键最后停留的那个)。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | '' | 绑定值,支持 v-model。选中的图标名,没选时是空字符串 |
| icons | string[] | - | 只在这些图标里选,按传入的顺序平铺、不分组。不传时用全部内置图标并分组 |
| clearable | boolean | false | 有值时是否显示清空按钮 |
| disabled | boolean | false | 是否禁用 |
| placeholder | string | '请选择图标' | 没选图标时的占位文字 |
| filterPlaceholder | string | '搜索图标' | 面板里搜索框的占位文字,也是搜索框的 aria-label |
| emptyText | string | '没有匹配的图标' | 没有匹配的图标时显示的文字 |
| groupLabels | Partial<Record<IconPickerGroupName, string>> | - | 改内置分组的标题,没写的分组用默认标题;传了 icons 时不分组,这个属性不起作用 |
| size | 'large' | 'default' | 'small' | - | 尺寸。不写时跟随 FormItem、Form、ConfigProvider,都没有时是 default |
| validateEvent | boolean | true | 值变化和关闭面板时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string) | 选中或清空后触发,v-model 用;清空时参数是空字符串 |
| change | (value: string) | 用户选了另一个图标或清空时触发;再点一次当前已选的图标只关闭面板,不触发 |
| clear | - | 点清空按钮时触发 |
| visibleChange | (visible: boolean) | 面板打开、关闭时触发 |
模板里监听 visibleChange 写成 @visible-change。
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| icon | { icon: string } | 自定义图标的渲染,用在面板的每个格子和触发器里选中的图标上。默认是 <NsIcon :name="icon" /> |
作用域参数叫 icon 而不是 name:<slot> 上的 name 是插槽名,不能当参数传。
方法
通过 NsIconPicker 的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| focus | - | void | 让选择器获得焦点 |
| blur | - | void | 让选择器失去焦点 |
类型
import type {
IconPickerProps,
IconPickerEmits,
IconPickerSlots,
IconPickerSize,
IconPickerGroupName
} from '@ns/ui'
type IconPickerSize = 'large' | 'default' | 'small'
// 内置分组,和 @ns/icons 导出的 iconGroups 的 key 一致
type IconPickerGroupName = 'navigation' | 'action' | 'status' | 'user' | 'file'
注意事项
- 选择器默认宽度是 100%,占满父容器,需要固定宽度时用
style或class设置。面板的宽度由一行 8 个格子决定(default 约 310px),不跟着选择器变宽,搜索没有结果时也不变。 - 没选时的值是空字符串
'',清空后也是''(和NsInput一样,和NsSelect清空后是undefined不同)。null、undefined当作没选。 - 绑定值不在面板的图标里(例如不在
icons里、或者是没有用插槽画出来的自定义名字)时,触发器照样显示这个名字,图标位置是一块空白,面板里没有高亮项。 - 搜索只按图标名(英文)过滤,不支持中文关键字。
- 清空按钮和
NsSelect一样不能用 Tab 聚焦,键盘用户可以重新选一个图标;需要键盘清空时请在表单里另外放一个按钮。 - 面板通过
Teleport渲染到body下,位置跟随选择器;下方放不下时改为向上弹出。给面板写样式时用.ns-icon-picker__dropdown,不要依赖选择器的父级选择器。 - 面板里的图标第一次打开时才渲染,表单里放很多个图标选择器也不会一开始就渲染上千个图标。
优化点
- [ ] 支持中文关键字搜索(给内置图标加中文别名)
- [ ]
icons支持传分组(自定义分组标题和顺序) - [ ] 支持键盘清空