amis Tag 标签组件完全指南展示模式、预设配色、自定义样式与事件交互【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amisTag标签是 amis 中用于标记和选择的轻量展示组件通过一行 JSON 即可渲染出用于状态标识、分类标注、结果回显等场景的标签。本文基于 Tag 组件文档并结合 渲染器源码、amis-ui 基础组件 与 样式定义完整讲解它的三种展示模式、预设配色与自定义颜色、行内样式覆盖、关闭按钮以及 click / mouseenter / mouseleave / close 四类事件的监听与数据获取方式帮助你直接照抄可运行示例落地到自己的页面中。基本用法Tag 是典型的纯展示型组件只需配置type: tag与label即可渲染。下面这个完整 schema 展示了标签的基础形态普通圆角标签、预设配色标签、超长文本标签会被截断省略、可关闭标签以及通过onEvent监听close事件的组合用法。{ type: page, body: [ { type: tag, label: 普通的标签, displayMode: rounded, color: inactive }, { type: tag, label: 普通标签, color: processing }, { type: tag, label: 这是一个很长长长长长长长长长长长长长的标签, color: success }, { type: tag, label: 这是一个很长长长长长长长长长长长长长的标签, closable: true }, { type: tag, label: 关闭了, closable: true, onEvent: { close: { actions: [ { actionType: toast, args: { msg: ${event.data.label} } } ] } } } ] }几个值得注意的行为超长文本自动截断从 样式源码 可以看到.Tag设置了max-width: 160px内部的.Tag-text使用text-overflow: ellipsis; overflow: hidden; white-space: nowrap因此长标签不会撑破布局而是以省略号结尾鼠标悬停时通过title属性显示完整文本。相邻标签自动留白.Tag:not(:last-child)会添加margin-right: var(--gap-sm)多个标签并排时天然有间距无需手工加 margin。关闭按钮与事件联动closable: true显示关闭按钮配合onEvent.close可以感知关闭动作并拿到关闭标签的label数据详见下文「事件交互」。三种展示模式displayModedisplayMode决定标签的视觉形态取值范围为normal | rounded | status默认值是normal源码中 TagField.defaultProps 与 amis-ui Tag 的 defaultProps 均确认了这一点。{ type: page, body: [ { type: tag, label: 面性标签, displayMode: normal, color: active }, { type: tag, label: 线性标签, displayMode: rounded, color: inactive }, { type: tag, label: 状态标签, displayMode: status, color: active, closable: true }, { type: tag, label: #4096ff, displayMode: rounded, color: #4096ff }, { type: tag, label: #f70e47, displayMode: rounded, color: #f70e47 } ] }三种模式的定义与渲染差异可以直接从 AMISTagSchema 的类型注释 中得到印证模式中文名核心特征normal面性标签使用color作为背景色实心色块文字默认白色rounded线性标签白色底 彩色描边使用color作为边框与文字颜色圆角更大status状态标签带前置图标的标签图标可自定义icon适合表达运行状态从渲染逻辑看amis-ui Tag 的 render 方法 会按displayMode把自定义色值分别映射到不同的 CSS 属性上const tagStyle { backgroundColor: displayMode normal ? customColor : undefined, borderColor: displayMode rounded ? customColor : undefined, color: displayMode rounded ? customColor : undefined, ...style };也就是说自定义色值在normal模式下表现为背景色在rounded模式下表现为边框色 文字色理解这一点有助于你按预期控制视觉效果。status模式会渲染前置图标未配置icon时默认使用dot图标可设置icon覆盖。有意思的是样式源码 中对icon-dot做了细节处理——只有processing和active状态下的圆点会显示波动动画#dotWave其余状态隐藏动画让进行中的状态在视觉上更醒目。标签颜色预设配色与自定义色值标签内置了 6 种预设色彩通过color属性取active、inactive、error、success、processing、warning即可使用如果预设值不能满足需求也可以直接传具体色值如#4096ff。{ type: page, body: [ { type: tag, label: active, displayMode: normal, color: active }, { type: tag, label: inactive, displayMode: normal, color: inactive }, { type: tag, label: error, displayMode: normal, color: error }, { type: tag, label: success, displayMode: normal, color: success }, { type: tag, label: processing, displayMode: normal, color: processing }, { type: tag, label: warning, displayMode: normal, color: warning } ] }这 6 个预设值在 amis-ui 的类型定义 TagLevel 与PRESET_COLOR数组中逐一列出底层原理是渲染时会判断color是否命中预设值PRESET_COLOR.indexOf(color)命中则追加Tag--{displayMode}--{color}这类语义化 class由 SCSS 中的 CSS 变量如var(--Tag-success-bg-color)驱动配色未命中则按上文所述当作自定义色值直接写进行内 style。这也是预设色值与自定义色值的本质区别——前者可被主题变量整体换肤后者是固定值。预设色值背后的颜色全部由 CSS 变量定义见 样式源码因此跟随主题一键切换无需逐个修改标签配置。自定义样式style 行内覆盖如果预设配色和三种模式仍不能满足视觉要求可以通过style直接控制背景、边框及文字颜色。style是行内样式优先级最高会覆盖color推算出的所有默认样式从 tagStyle 的合并顺序 可以看到...style放在最后展开。{ type: page, body: [ { type: tag, label: 面性标签, displayMode: normal, color: active }, { type: tag, label: 线性标签, displayMode: rounded, color: inactive }, { type: tag, label: 自定义样式1, displayMode: normal, style: { backgroundColor: #fff, border: 1px solid #ccc, color: #666 } }, { type: tag, label: 自定义样式2, displayMode: rounded, style: { backgroundColor: #2468f2, borderColor: #2468f2, color: #fff } } ] }实战建议风格一白底描边backgroundColor: #fffborder: 1px solid #ccccolor: #666适合弱化视觉层级、纯粹做内容标注风格二品牌色填充backgroundColor与borderColor同时设置品牌色 color: #fff适合强品牌感的场景注意style是任意 CSSProperties 对象理论上所有行内样式能力间距、字体、圆角等都可用但请优先使用colordisplayMode表达语义把style留给无法覆盖的定制需求。完整属性表以下属性表在原文档基础上结合 AMISTagSchema 源码定义 补全了类型、默认值与补充说明属性名类型默认值说明displayModenormal \| rounded \| statusnormal展现模式面性 / 线性 / 状态coloractive \| inactive \| error \| success \| processing \| warning \| 具体色值无颜色主题提供默认主题并支持自定义颜色值labelstring-标签内容支持变量解析与表达式iconSchemaIcondot 图标status 模式下的前置图标可自定义classNamestring无自定义 CSS 样式类名追加到组件根元素styleobject{}自定义样式行内样式优先级最高closablebooleanfalse是否展示关闭按钮closeIconSchemaIconclose图标关闭按钮图标源码 closeIcon 字段 定义amis-ui 中默认取close图标checkablebooleanfalse是否是可选的标签可点选checkedbooleanfalse是否选中disabledbooleanfalse是否禁用其中checkable/checked/disabled三个属性在 渲染器 schema 类型 中已定义并对应 amis-ui 中的 CheckableTag 实现 与 可选中样式可用于实现可点选的标签组选中态为实心色块禁用态降低透明度且cursor: not-allowed。普通展示场景下最常用的是displayMode、color、label、closable与style。另外label、icon、displayMode、color均支持纯变量写法——渲染器在 render 前会用isPureVariableresolveVariableAndFilter基于当前数据域解析见 渲染器源码因此标签颜色、文本甚至展示模式都可以随数据动态变化例如color: ${status}直接映射业务状态字段。事件交互click / mouseenter / mouseleave / close事件能力要求 amis 2.6.1 及以上版本。Tag 组件会对外派发以下事件可以通过onEvent监听并通过actions配置执行的动作。在actions中可以通过${事件参数名}或${event.data.[事件参数名]}获取事件产生的数据关于事件动作的完整机制详见 事件动作文档。事件名称事件参数说明clicklabel: string鼠标事件对象点击时触发mouseenterlabel: string鼠标事件对象鼠标移入时触发mouseleavelabel: string鼠标事件对象鼠标移出时触发closelabel: string鼠标事件对象关闭时触发从 渲染器事件处理源码 可以看到四类事件统一走dispatchEvent(nativeEvent, params)派发其中params由getResolvedEventParams生成——它把当前数据域与{ label: 解析后的标签文本 }合并成一个新对象。因此事件动作里既能取event.data.label也能通过event.context.nativeEvent拿到浏览器原生鼠标事件对象。click鼠标点击标签时触发。可以通过${event.context.nativeEvent}获取鼠标事件对象。{ type: tag, label: success, displayMode: normal, color: success, onEvent: { click: { actions: [ { actionType: toast, args: { msgType: info, msg: ${event.context.nativeEvent.type} ${event.data.label} } } ] } } }mouseenter鼠标移入时触发。可以通过${event.context.nativeEvent}获取鼠标事件对象。{ type: tag, label: success, displayMode: normal, color: success, onEvent: { mouseenter: { actions: [ { actionType: toast, args: { msgType: info, msg: ${event.context.nativeEvent.type} ${event.data.label} } } ] } } }mouseleave鼠标移出时触发。可以通过${event.context.nativeEvent}获取鼠标事件对象。{ type: tag, label: success, displayMode: normal, color: success, onEvent: { mouseleave: { actions: [ { actionType: toast, args: { msgType: info, msg: ${event.context.nativeEvent.type} ${event.data.label} } } ] } } }close鼠标点击关闭按钮时触发需配合closable: true。与 click 不同amis-ui 的 handleClose 会先e.stopPropagation()阻止事件冒泡再向上派发因此点击关闭按钮不会同时触发 click。{ type: tag, label: success, displayMode: normal, color: success, closable: true, onEvent: { close: { actions: [ { actionType: toast, args: { msgType: info, msg: close ${event.context.nativeEvent.label} } } ] } } }事件参数与数据域说明结合上面的示例事件动作中的取值语法归纳如下${event.data.label}当前被交互标签的文本内容。它由 resolveLabel 解析得出——优先取组件的值getPropValue否则对label做变量解析| raw不做转义因此支持表达式与动态数据。${event.context.nativeEvent}浏览器原生鼠标事件对象可进一步取type、target等原生属性。注意close事件派发时会把事件对象的type改写为close见 handleClose 中的 dispatchEvent 调用以便上层识别事件类型。事件参数还包含当前组件所处数据域data即标签所在容器如 CRUD 行、Form 表单的上下文数据action 中可以直接使用这些字段做后续逻辑。渲染链路与底层实现Tag 组件的完整调用链可以概括为三层渲染器层amisTagFieldRenderer通过Renderer({ type: tag })注册为 amis 的tag类型渲染器见 渲染器注册。它负责 schema 到 props 的映射、变量解析与事件派发然后调用 amis-ui 的Tag组件完成实际渲染。基础组件层amis-uiTag 组件 是一个无状态展示组件接收displayMode、color、icon、closable、style等 props通过themeable接入主题系统并负责拼装语义化 class。样式层SCSS标签样式 定义各模式的视觉细节全部颜色、间距、字号都抽取为 CSS 变量--Tag-*支持主题定制。这一分层结构意味着你既可以在页面 JSON 中开箱即用地消费它也可以在自定义渲染器中直接 import amis-ui 的Tag组件复用同一套视觉与交互。常见使用场景小结状态展示displayMode: status 预设色 icon自定义图标配合processing的圆点动画表达进行中。分类标注 / 结果回显normal面性标签或rounded线性标签 预设色超长文本自动省略。可交互标签closable开关 close事件做删除确认或 toast 提示checkable/checked实现可点选标签组。动态数据驱动color、label、displayMode支持变量直接绑定业务字段即可随数据变化自动着色。强定制外观style行内样式做品牌化定制className配合全局 CSS 做批量扩展。如需在表单、CRUD、选择类组件中看到 Tag 的实际联动用法可在仓库的 Select、InputTag、CRUD 等渲染器源码中搜索其引用位置本文聚焦的独立 Tag 组件已足以覆盖绝大多数标记与选择场景。【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
