---
title: "ModeChip 模式芯片"
description: "表示当前模式、切换时原地变身的按钮"
category: AiChat
status: beta
since: 0.6.0
tags: [chip, mode, toggle, morph, ai]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
:::TuffDemoWrapper{demo="ModeChipModeChipDemo" code-lang="vue"}
---
code: |
  <template>
    <TxModeChip
      :icon="unrestricted ? 'i-carbon-unlocked' : 'i-carbon-touch-1'"
      :label="unrestricted ? '无限制访问' : '请求批准'"
      :tone="unrestricted ? 'danger' : 'muted'"
      @click="unrestricted = !unrestricted"
    />
  </template>
---
:::

### 色调
`muted` 没有底色；其余色调以该色相的 `-light-9` 为底色，`info` 取主色色相。
:::TuffDemoWrapper{demo="ModeChipTonesDemo" code-lang="vue"}
---
code: |
  <template>
    <TxModeChip tone="muted" icon="i-carbon-touch-1" label="请求批准" />
    <TxModeChip tone="info" icon="i-carbon-earth" label="联网搜索" />
    <TxModeChip tone="success" icon="i-carbon-checkmark-outline" label="自动接受编辑" />
    <TxModeChip tone="warning" icon="i-carbon-warning-alt" label="计划模式" />
    <TxModeChip tone="danger" icon="i-carbon-unlocked" label="无限制访问" />
  </template>
---
:::

### 最佳实践

- 文字随模式变化的芯片不加 `aria-pressed`；它只用于文字固定、开关某个模式的芯片。点击打开模式菜单时加 `aria-haspopup`。
- 用色调表示风险：默认或安全的模式用 `muted`，放开保护的模式用 `danger`；文字与图标也要说明模式。
- 文字控制在两到四个词。
- 放进 [ChatComposer](/docs/dev/components/chat-composer) 时用 `toolbar-left` 插槽；托盘里用 `muted` 色调。
- 只在用户操作或语境变化时切换，不要自动高频切换。

## API 参考

### 属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `label` | `string` | - | 显示的文字，也是按钮的可访问名称；必填。 |
| `icon` | `string` | `''` | 前置图标 class；为空时不占图标位。 |
| `tone` | `'muted' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'muted'` | 色调，复用 `StatusTone`。 |
| `disabled` | `boolean` | `false` | 禁用按钮。 |

### CSS 变量

| 变量 | 说明 |
|------|------|
| `--tx-mode-chip-ink` | 文字颜色，每个色调各自设置。 |
| `--tx-mode-chip-ink-hover` | 悬停时的文字颜色，只有 `muted` 设置。 |
| `--tx-mode-chip-fill` | 底色。 |
| `--tx-mode-chip-fill-hover` | 悬停时的底色。 |

## 概述

- 渲染为原生 `<button type="button">`；`label` 是可访问名称，图标不参与命名。`click` 等原生事件与其余属性透传到根元素。
- `label`、`icon`、`tone` 任一变化都会变身：图标缩放互换，50ms 后文字模糊交叉，宽度跟随新文字；中途再变会重新计时。
- 颜色过渡只存在于变身期间（`.is-morphing`）；悬停立即换色，`muted` 变为主墨色，其余色调加深底色。
- 各色调文字在四套主题的静止与悬停态下对比度均不低于 4.5:1。
- 减少动态效果时直接落到终态；没有 Web Animations API 时宽度直接跳到新值。
- 禁用时半透明，光标为 `not-allowed`，没有悬停变化。

## 技术实现

- 文字动效复用 `TxTextTransformer` 的 fade 模式，因此文字只来自 `label`，不提供插槽。
- 动效参考：[@flohoeller 的 Chatbox 组件视频](https://x.com/flohoeller/status/2102660458658582913)。
- 源码：`packages/tuffex/packages/components/src/mode-chip/`。

<TuffDocSourceLink />