n-data-tag 标签选择
通过字符串、数字或业务对象生成标签，适用于分类筛选、规格选择与兴趣多选。未绑定值时自动管理选择；绑定 modelValue 后由父级回写，单选使用字符串或数字，多选使用数组。空字符串与空数组均为受控空值，null 表示组件自行管理。
平台兼容性
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 | QQ小程序 |
|---|---|---|---|---|---|---|
| √ | √ | √ | × | × | × | × |
以上为目标支持范围。实际编译与运行验收范围见工程验收记录，未实测设备不代表已验收。
API
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| options | NDataTagOptions | [] | 字符串、数字或对象数组；对象缺少值字段时取文字字段，值须唯一且非空 |
| model-value | NDataTagModelValue / null | null | 可选的选择绑定；null 时自行管理，绑定标量或数组时由父级回写；空字符串或空数组表示受控空值 |
| text-key | string | "text" | 对象的文字字段名 |
| value-key | string | "value" | 对象的值字段名，字段缺省时取文字 |
| is-all-key | string | "isAll" | 对象的互斥选项标记字段名；最多一项为 true，选中该项会取消其他项，不执行全选 |
| disable-key | string | "disable" | 对象的禁用字段名；布尔值，禁用项保色相降透明并拦截点击 |
| multiple | boolean | false | 多选模式；自行管理时切换会转换选择值，转为单选保留首项；受控时由父级同步值类型 |
| min | number / string | 1 | 单选是否保留选中项：1 不允许再次点击取消，0 允许取消；支持数字字符串，不自动选中首项 |
| multiple-min | number / string | 0 | 多选最少保留数量；支持数字字符串，初始不足时允许逐项补选，取消或替换后不得低于下限 |
| max | number / string | -1 | 多选最多数量；支持数字字符串，-1 不限制，互斥选项计为一项 |
| width | number / string | 0 | 标签宽度；数字 px 或 px/rpx 字符串，0 随内容；窄容器中不超出可用宽度 |
| height | number / string | 0 | 标签高度；数字 px 或 px/rpx 字符串，0 随内容；最小高度 40px |
| padding | (number / string)[] | [] | 标签内边距；1～4 个数字 px 或 px/rpx 字符串，按 CSS 四向简写顺序；空数组取主题 |
| gap | number / string | -1 | 横向与纵向间隔；数字 px 或 px/rpx 字符串，-1 取主题 |
| radius | number / string | -1 | 标签圆角；数字 px 或 px/rpx 字符串，-1 取主题，0 直角 |
| size | number / string | 0 | 文字字号；数字 px 或 px/rpx 字符串，0 取主题 |
| color | string | "" | 未选中文字色；空串跟随主题 |
| active-color | string | "" | 选中文字色；空串跟随主题主文字色 |
| background | string | "" | 未选中背景；空串跟随主题，支持实色与方向关键词渐变 |
| active-bg-color | string | "" | 选中背景；空串跟随主题，支持实色与方向关键词渐变 |
| default-border-color | string | "" | 未选中边框色；空串跟随主题边框 |
| border-color | string | "" | 选中边框色；空串跟随主题主文字色 |
| mark | boolean | false | 显示右下角选中标记，建议搭配小圆角 |
| mark-size | number / string | 0 | 角标边长；数字 px 或 px/rpx 字符串，0 取主题 |
| mark-color | string | "" | 角标颜色；空串跟随主题主文字色，勾线跟随主题表面色 |
| nowrap | boolean | false | 强制单行排列；超出容器时由调用方提供横向滚动容器 |
| text-style | string | "" | 内置文字行内样式，如 font-weight:600；文字颜色可直接使用两态颜色属性 |
| custom-class | string | "" | 根节点附加类名；类须定义在组件样式表内 |
| custom-style | string | "" | 根节点行内样式，用于外距及 --n-data-tag-* 主题令牌 |
事件
| 事件名 | 说明 |
|---|---|
| update:modelValue | 有效选择时回传最新标量或数组；由父级回写，拒绝回写则显示保持原值 |
| input | 同一次选择回传最新值，与 update:modelValue 同参同发 |
| change | 回传 { detail: { value, index, item, items } }；单选 index 为选中下标，取消或多选为 -1；item 单选为字段化对象、取消为 {}、多选为对象数组，含 selected=true；items 为选中原项数组 |
| error | 回传 { field, index, message }；index=-1 为组件级错误，其他值为错误项下标 |
有效点击依次发出 update:modelValue、input、change；禁用、保留已选单选项、违反数量限制时不发选择事件。数量限制通过国际化提示反馈；外部改值只更新展示，不反向发事件。
插槽
无。
实例方法
无。
主题与样式
| 令牌 | 默认值 | 用途 |
|---|---|---|
| --n-data-tag-min-height | 40px | 最小触控高度 |
| --n-data-tag-padding-x / --n-data-tag-padding-y | 16px / 8px | 默认横纵内边距 |
| --n-data-tag-padding-top / right / bottom / left | 对应横纵内边距 | 四向单独覆盖 |
| --n-data-tag-gap | 12px | 项间距 |
| --n-data-tag-radius | 8px | 圆角 |
| --n-data-tag-font-size | 12px | 字号 |
| --n-data-tag-mark-size | 24px | 角标边长 |
| --n-data-tag-disabled-opacity | 0.5 | 禁用透明度 |
| --n-data-tag-pressed-opacity | 0.7 | 按压透明度 |
| --n-data-tag-width / --n-data-tag-height | auto | 标签宽高 |
| --n-data-tag-color | 主文字色 | 未选中文字 |
| --n-data-tag-active-color | 主题主文字色 | 选中文字 |
| --n-data-tag-background / --n-data-tag-active-background | 主题表面色 | 两态背景 |
| --n-data-tag-border-color | 主题边框色 | 未选中边框 |
| --n-data-tag-active-border-color / --n-data-tag-mark-color | 主题主文字色 | 选中边框与角标 |
尺寸 props 显式值优先于令牌；数字按 px，字符串支持 px/rpx。padding 支持 1～4 项 CSS 简写顺序，包括显式的 0；空数组恢复令牌。字体不固定行高，避免系统字体墨迹被裁。文字使用 平台支持的 white-space:nowrap 配合省略样式。宽度受容器可用宽度约束，显式高度仍至少 40px。选中角标保持在项内并随圆角裁剪，建议搭配小圆角。
外观优先使用主题令牌；customStyle 作用于根节点，textStyle 作用于内置文字。页面上的 class 无法穿透样式隔离。Web 单选提供带标签的 radio 分组、单一 Tab 入口与方向键循环切换，跳过禁用项；多选逐项 Tab 导航，Enter / Space 切换选择。选中、禁用状态提供对应辅助技术语义。
默认选中态使用主题主文字色和表面色，以保持深浅背景上的可读性；可通过 activeColor、borderColor、markColor 或对应组件变量配置品牌色。自定义填充和渐变时需同时设置可读的文字色与标记色。
渐变背景请使用方向关键词，例如 linear-gradient(to right, #0f766e, #15803d)，同时设置足够对比度的文字色。
实现说明
| 机制 | 参考做法 | 本库做法 | 分歧理由 |
|---|---|---|---|
| 数据与映射 | 原始值数组或对象数组；四个字段名可配置，值缺省取文字 | 保留 options/textKey/valueKey/isAllKey/disableKey，保留原始对象供事件回传 | 不修改传入数据，不用 JSON 深拷贝破坏业务字段 |
| 事件详情 | change.detail.item 单选为对象、多选为数组，包含文字、值与 selected 状态 | 保留 item 的单多选形态，取消单选为 {}；另保留 items 原项数组 | 字段化快照不修改输入，业务附加字段保留；嵌套业务字段沿用原引用。值数组保留选择顺序，详情项按数据顺序 |
| 选择值管理 | 无绑定时内部保留选择；绑定值会更新内部选择 | 统一 modelValue；null 时自动管理，显式值时由父级回写；复用同一选择与限制逻辑 | 保留无绑定用法，并保留父级拒绝回写的受控契约；同一时刻仅一个选择值来源 |
| 单选取消 | min=1 不取消，min=0 可取消 | 同语义；未选中值为字符串空串 | 保留既有使用方式，数字 0 是有效值 |
| 多选限制 | min/multipleMin/max 支持数字或数字字符串，达到限制时提示 | 保留两种输入类型，统一转数值后校验候选集合；少于下限时允许逐个补选 | 避免先检查旧数量导致互斥选项无法在 max=1 时换成普通项 |
| 互斥选项 | isAll 标记一个与其他项互斥的选项 | 同语义，选中互斥项仅返回该项值；不是勾选所有项 | 保留筛选语义；替换视为一次操作，不产生中间事件 |
| 禁用 | 单项 disable 守卫与 opacity | 同语义，已选禁用项仍显示选中 | 保色相并保留父级受控值 |
| 样式 | 宽高、四向 padding、间隔、圆角、字号与两态颜色可调 | 保留全部能力；数字用 px，字符串支持 px/rpx；默认尺寸与颜色走令牌；选中文字、边框和标记取主文字色，勾线取表面色 | 与本库单位、主题与样式隔离约定一致；标签至少 40px 高 |
| 排列 | 默认换行，nowrap 由外部提供横向滚动 | 同语义；间距用自有 view 的 margin，保留末行底部间距；单行按内容撑宽 | 不用 CSS gap 或不受支持的负向变量计算，不将滚动职责混进选择组件 |
| 角标 | 字体字形绘制右下角选中标记 | 常驻几何三角与勾线，mark 控制可见性；保留颜色和尺寸 | 结构指示无需新增字体，常驻节点避免原生动态插拔；不占用相邻标签点击区 |
| 背景 | 背景样式接受颜色串 | 实色和方向关键词渐变分别由静态类引用变量，原生端背景变化重建标签；Web 按选项值保持节点身份 | 遵循原生背景更新规则，同时保留 Web 键盘焦点 |
| 插槽与方法 | 无 | 无 | 数据选择职责通过属性和事件完整表达 |
| 错误输入 | 类型与重复值无明确校验 | error 报告非法数据/配置并停止交互；修正后恢复 | 错误显式处理，避免错误数据被静默裁剪 |