Chip 碎片标签
小块的标签,可以带图标、头像和移除按钮。放进 NsChipGroup 以后可以点击选中,常用来做筛选条件、已选项列表。只是展示状态或分类、不需要选中时用 Tag 就够了。
引入
import { NsChip, NsChipGroup } from '@ns/ui'
基础用法
文字用 label 传,也可以写在默认插槽里。
<script setup lang="ts">
import { NsChip, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsChip label="用 label 写文字" />
<NsChip>用插槽写文字</NsChip>
</NsSpace>
</template>
不同类型
type 决定颜色,有 primary、success、warning、danger、info 五种,默认是 primary。
<script setup lang="ts">
import { NsChip, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsChip label="primary" type="primary" />
<NsChip label="success" type="success" />
<NsChip label="warning" type="warning" />
<NsChip label="danger" type="danger" />
<NsChip label="info" type="info" />
</NsSpace>
</template>
描边样式
加上 outline 以后底色透明,边框用类型的主色。放在 NsChipGroup 里选中以后是实心:主色底、白色文字,描边的标签选中后也一样。
下面每一行是一种样式,从左到右是 5 种类型。第三行在组里、全部选中,点一下可以取消:
<script setup lang="ts">
import { ref } from 'vue'
import { NsChip, NsChipGroup, NsSpace } from '@ns/ui'
const selected = ref<(string | number)[]>(['primary', 'success', 'warning', 'danger', 'info'])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">默认</span>
<NsChip label="主要" type="primary" />
<NsChip label="成功" type="success" />
<NsChip label="警告" type="warning" />
<NsChip label="危险" type="danger" />
<NsChip label="信息" type="info" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">outline</span>
<NsChip label="主要" type="primary" outline />
<NsChip label="成功" type="success" outline />
<NsChip label="警告" type="warning" outline />
<NsChip label="危险" type="danger" outline />
<NsChip label="信息" type="info" outline />
</NsSpace>
<NsSpace wrap>
<span class="row-label">选中</span>
<NsChipGroup v-model="selected">
<NsChip value="primary" label="主要" type="primary" />
<NsChip value="success" label="成功" type="success" />
<NsChip value="warning" label="警告" type="warning" />
<NsChip value="danger" label="危险" type="danger" />
<NsChip value="info" label="信息" type="info" />
</NsChipGroup>
</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>
尺寸
size 有 large、default、small 三种,图标和头像的大小跟着尺寸变:高度 32、24、18px,文字 16、14、12px,前面的图标 18、16、14px,头像 24、20、16px,移除按钮 16、14、12px。带图标、头像、移除按钮时和只有文字的一样高。不传时跟随所在的 NsChipGroup,再跟随 NsConfigProvider,都没设置时是 default。
<script setup lang="ts">
import { NsChip, NsSpace } from '@ns/ui'
// 换成自己的图片地址
const avatar = '/images/user.png'
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap align="center">
<span class="row-label">large</span>
<NsChip label="文字" size="large" />
<NsChip label="图标" size="large" icon="user" />
<NsChip label="头像" size="large" :image="avatar" />
<NsChip label="可移除" size="large" removable />
<NsChip label="描边" size="large" outline />
</NsSpace>
<NsSpace wrap align="center">
<span class="row-label">default</span>
<NsChip label="文字" />
<NsChip label="图标" icon="user" />
<NsChip label="头像" :image="avatar" />
<NsChip label="可移除" removable />
<NsChip label="描边" outline />
</NsSpace>
<NsSpace wrap align="center">
<span class="row-label">small</span>
<NsChip label="文字" size="small" />
<NsChip label="图标" size="small" icon="user" />
<NsChip label="头像" size="small" :image="avatar" />
<NsChip label="可移除" size="small" removable />
<NsChip label="描边" size="small" outline />
</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>
图标和图片
icon 写图标名(和 NsIcon 的 name 一样),显示在文字前面,颜色跟着文字;要放别的内容时用 icon 插槽。image 传图片地址,显示成文字前面的圆形头像,这时标签两端也变成圆角。
<script setup lang="ts">
import { NsChip, NsSpace } from '@ns/ui'
// 换成自己的图片地址
const avatar = '/images/user.png'
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsChip label="icon 属性" icon="user" />
<NsChip label="icon 插槽">
<template #icon><span>★</span></template>
</NsChip>
<NsChip label="image 属性" :image="avatar" />
<NsChip label="头像加移除" :image="avatar" removable />
</NsSpace>
<NsSpace wrap>
<NsChip label="已完成" type="success" icon="success" />
<NsChip label="待处理" type="warning" icon="clock" />
<NsChip label="已驳回" type="danger" icon="error" />
<NsChip label="草稿" type="info" icon="file" />
<NsChip label="收藏" type="warning" icon="star" outline />
<NsChip label="地点" type="info" icon="location" outline />
</NsSpace>
</NsSpace>
</template>
可移除
加上 removable 以后右边出现移除按钮,每种类型、描边样式都能用。移除图标可以用 remove 插槽换掉。
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsChip label="主要" type="primary" removable />
<NsChip label="成功" type="success" removable />
<NsChip label="警告" type="warning" removable />
<NsChip label="危险" type="danger" removable />
<NsChip label="信息" type="info" removable />
</NsSpace>
<NsSpace wrap>
<NsChip label="主要" type="primary" outline removable />
<NsChip label="成功" type="success" outline removable />
<NsChip label="警告" type="warning" outline removable />
<NsChip label="危险" type="danger" outline removable />
<NsChip label="信息" type="info" outline removable />
</NsSpace>
</NsSpace>
</template>
点移除按钮触发 remove 事件,点标签其他地方触发 click,点移除按钮不会触发 click。组件不会自己消失,要在事件里把对应的数据删掉。点“重置”恢复全部标签:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsChip, NsSpace } from '@ns/ui'
const all = ['Vue', 'React', 'Angular', 'Svelte']
const chips = ref([...all])
const log = ref('')
const handleRemove = (name: string) => {
chips.value = chips.value.filter((item) => item !== name)
log.value = `移除了 ${name}`
}
const reset = () => {
chips.value = [...all]
log.value = ''
}
</script>
<template>
<NsSpace wrap align="center">
<NsChip
v-for="chip in chips"
:key="chip"
:label="chip"
removable
@click="log = `点击了 ${chip}`"
@remove="handleRemove(chip)"
/>
<NsChip label="自定义移除图标" type="warning" removable>
<template #remove><span>✕</span></template>
</NsChip>
<NsButton size="small" icon="refresh" @click="reset">重置</NsButton>
</NsSpace>
<p style="margin-top: 12px">{{ log || '点标签或点标签上的 × 试试' }}</p>
</template>
禁用
disabled 禁用后变淡,鼠标是禁止符号,点击、移除都不触发事件,移除按钮也不能聚焦。每种类型、描边和选中的标签都能禁用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsChip, NsChipGroup, NsSpace } from '@ns/ui'
const selected = ref<(string | number)[]>(['a', 'b'])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsChip label="主要" type="primary" disabled />
<NsChip label="成功" type="success" disabled />
<NsChip label="警告" type="warning" disabled />
<NsChip label="危险" type="danger" disabled />
<NsChip label="信息" type="info" disabled />
</NsSpace>
<NsSpace wrap>
<NsChip label="禁用且可移除" disabled removable />
<NsChip label="描边禁用" outline disabled />
<NsChip label="带图标禁用" icon="lock" disabled />
<NsChipGroup v-model="selected">
<NsChip value="a" label="选中后禁用" disabled />
<NsChip value="b" label="选中可点" />
</NsChipGroup>
</NsSpace>
</NsSpace>
</template>
多选
把 NsChip 放进 NsChipGroup,组上用 v-model 绑定一个数组,每个 NsChip 用 value 指定自己的值。点一下选中,再点一下取消,选中的标签变成实心。选中项变化时触发 change。
<script setup lang="ts">
import { ref } from 'vue'
import { NsChip, NsChipGroup } from '@ns/ui'
const selected = ref<(string | number)[]>(['vue', 'react'])
const changeCount = ref(0)
const handleChange = () => {
changeCount.value += 1
}
</script>
<template>
<NsChipGroup v-model="selected" @change="handleChange">
<NsChip value="vue" label="Vue" />
<NsChip value="react" label="React" />
<NsChip value="angular" label="Angular" />
<NsChip value="svelte" label="Svelte" />
</NsChipGroup>
<p style="margin-top: 12px">
已选:{{ selected.length ? selected.join('、') : '无' }}(change 触发了 {{ changeCount }} 次)
</p>
</template>
组的类型、尺寸、描边
type、size、outline 可以统一写在组上。某个 NsChip 自己写了这几个属性时,以自己的为准。描边的标签选中以后也是实心。
<script setup lang="ts">
import { ref } from 'vue'
import { NsChip, NsChipGroup, NsSpace } from '@ns/ui'
const outlined = ref<(string | number)[]>(['b'])
const mixed = ref<(string | number)[]>(['a'])
const large = ref<(string | number)[]>(['a'])
const small = ref<(string | number)[]>(['a'])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsChipGroup v-model="outlined" type="danger" outline>
<NsChip value="a" label="未选中是描边" />
<NsChip value="b" label="选中后变实心" />
</NsChipGroup>
<NsChipGroup v-model="mixed" type="primary">
<NsChip value="a" label="跟随组(primary)" />
<NsChip value="b" label="自己写 type=warning" type="warning" />
<NsChip value="c" label="自己写 size=small" size="small" />
</NsChipGroup>
<NsChipGroup v-model="large" type="success" size="large">
<NsChip value="a" label="组 size=large" />
<NsChip value="b" label="组 type=success" />
</NsChipGroup>
<NsChipGroup v-model="small" type="info" size="small">
<NsChip value="a" label="组 size=small" />
<NsChip value="b" label="组 type=info" />
<NsChip value="c" label="自己写 outline=false" :outline="false" />
</NsChipGroup>
</NsSpace>
</template>
组的禁用
组上的 disabled 会禁用里面没写 disabled 的标签。标签自己写了 :disabled="false" 时以自己为准,可以在禁用的组里单独启用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsChip, NsChipGroup } from '@ns/ui'
const selected = ref<(string | number)[]>(['a'])
</script>
<template>
<NsChipGroup v-model="selected" disabled>
<NsChip value="a" label="选项 A" />
<NsChip value="b" label="选项 B" />
<NsChip value="c" label="选项 C(单独启用)" :disabled="false" />
</NsChipGroup>
<p style="margin-top: 12px">已选:{{ selected.join('、') || '无' }}</p>
</template>
勾选开关切换组的禁用状态:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsChip, NsChipGroup, NsSpace } from '@ns/ui'
const disabled = ref(true)
const selected = ref<(string | number)[]>(['day'])
</script>
<template>
<NsSpace wrap align="center">
<NsCheckbox v-model="disabled">禁用</NsCheckbox>
<NsChipGroup v-model="selected" :disabled="disabled" outline>
<NsChip value="day" label="今天" />
<NsChip value="week" label="本周" />
<NsChip value="month" label="本月" />
</NsChipGroup>
</NsSpace>
</template>
键盘操作
在 NsChipGroup 里并且写了 value 的标签可以用 Tab 键聚焦,按空格或回车切换选中。不在组里的标签、禁用的标签不能聚焦。
移除按钮是原生 button,可以用 Tab 聚焦,按空格或回车触发 remove;禁用时按钮带 disabled,不能聚焦。
NsChip Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| value | string | number | - | 标签的值,在 NsChipGroup 里用来判断是否选中。不写就不能选中 |
| label | string | - | 显示的文字。写了默认插槽时不显示。同时也是 image 图片的 alt |
| disabled | boolean | - | 是否禁用。不写时跟随所在的 NsChipGroup,不在组里时是 false |
| removable | boolean | false | 是否显示移除按钮 |
| icon | string | - | 图标名,显示在文字前面 |
| image | string | - | 图片地址,显示成文字前面的圆形头像 |
| type | 'primary' | 'success' | 'warning' | 'danger' | 'info' | - | 类型。不写时跟随所在的 NsChipGroup,不在组里时是 'primary' |
| size | 'large' | 'default' | 'small' | - | 尺寸。不写时跟随所在的 NsChipGroup,不在组里时跟随 NsConfigProvider 的 size,都没有时是 'default' |
| outline | boolean | - | 是否是描边样式。不写时跟随所在的 NsChipGroup,不在组里时是 false |
NsChipGroup Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | (string | number)[] | [] | 绑定值,支持 v-model,内容是选中的标签的 value |
| disabled | boolean | false | 是否禁用组里所有标签 |
| size | 'large' | 'default' | 'small' | - | 组里标签的尺寸。不写时跟随 NsConfigProvider 的 size,都没有时是 'default' |
| type | 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'primary' | 组里标签的类型 |
| outline | boolean | false | 组里标签是否是描边样式 |
NsChip Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| click | (event: MouseEvent) | 点击标签时触发。点移除按钮不触发,禁用时不触发 |
| remove | (event: MouseEvent) | 点击移除按钮时触发。禁用时不触发 |
NsChipGroup Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: (string | number)[]) | 用户选中或取消某个标签时触发,v-model 用的就是它 |
| change | (value: (string | number)[]) | 用户选中或取消某个标签时触发,参数是新的数组 |
NsChip Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 标签文字。写了以后不再显示 label |
| icon | - | 文字前面的图标位置。写了以后不再显示 icon 属性指定的图标 |
| remove | - | 移除按钮里的图标,只在 removable 时显示。不写时是关闭图标 |
NsChipGroup Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsChip,中间可以隔着其他元素 |
类型
import type { ChipType, ChipSize, ChipProps, ChipGroupProps } from '@ns/ui'
type ChipType = 'primary' | 'success' | 'warning' | 'danger' | 'info'
type ChipSize = 'large' | 'default' | 'small'
interface ChipProps {
value?: string | number
label?: string
disabled?: boolean
removable?: boolean
icon?: string
image?: string
type?: ChipType
size?: ChipSize
outline?: boolean
}
interface ChipGroupProps {
modelValue?: (string | number)[]
disabled?: boolean
size?: ChipSize
type?: ChipType
outline?: boolean
}
另外还导出了 ChipEmits、ChipGroupEmits 和注入用的 chipGroupKey。
注意事项
- 只有放在
NsChipGroup里并且写了value的标签才能选中。单独使用的NsChip没有选中状态,只触发click。 NsChipGroup是受控的,只写:model-value不处理update:modelValue时,点击后选中状态不会变。- 组里是多选,没有单选模式。
- 用鼠标点可选中的标签时,除了组上的
update:modelValue、change,标签自己的click也会触发;用键盘切换时不触发click。 remove只是通知,标签不会自己消失;点移除按钮不会触发click,也不会改变选中状态。disabled、type、size、outline都是标签自己写的优先:组禁用以后,子项写:disabled="false"会变成可用。remove插槽的内容放在移除按钮(button)里面,插槽里不要再放按钮、链接这类可交互的元素。- 文字不换行,也不会省略,很长的文字会让标签超出容器。需要限制宽度时自己在插槽里处理。
NsChipGroup是inline-flex容器,标签之间有间距,一行放不下时会换行。
优化点
- [ ] 支持标签拖拽排序
- [ ] 支持标签自定义颜色
- [ ] 支持标签筛选搜索
- [ ] 支持标签数量限制
- [ ] 支持单选模式
- [ ] 文字过长时省略显示
- [ ] 选中的
warning标签是黄底白字,对比度偏低