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.
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标签是黄底白字,对比度偏低