标签片（Chips） · Bootstrap 6.0 中文文档

概览

Chips 是表示实体的小型交互元素。它们可以用于在表单或其他交互环境中对值进行分组和选择。它们类似于早期的徽章组件，但有一些重要的区别。

Chips 是交互元素，而不是像徽章那样静态的。
Chips 只有一种尺寸——不像徽章那样会随父元素 font-size 缩放。
Chips 可以有图标、头像和关闭按钮。
Chips 可以设置主题，单独设置或在父容器作为一组设置。默认情况下，chips 使用 subtle 和 text 主题令牌，而活跃状态使用 bg 和 contrast 令牌。
Chips 可以处于活跃或禁用状态。
Chips 在被点击进入活跃状态时会自动获得焦点。
Chips 在其自定义 .chip-input 容器中支持键盘导航和选择。

在下面查看所有这些的实际示例。

薯片

对于独立的芯片使用 .chip。添加 .chip-icon 用于前置图标，.chip-img 用于类似头像的图像，.chip-dismiss 用于移除按钮。请注意，我们为关闭按钮图标使用了内联 SVG——你可以根据需要修改它。JavaScript 用户可以使用 dismissIcon 选项来传递自定义 SVG。

基础芯片

带头像带图标可解雇的

HTML

<span class="chip">Basic chip</span>

<span class="chip">
  <img src="/assets/img/avatar.png" class="chip-img" width="16" height="16" alt="">
  With avatar
</span>

<span class="chip">
  <span class="chip-icon">
    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
      <path d="M3 14s-1 0-1-1 1-4 6-4 6 3 6 4-1 1-1 1zm5-6a3 3 0 1 0 0-6 3 3 0 0 0 0 6"/>
    </svg>
  </span>
  With icon
</span>

<span class="chip">
  Dismissible
  <button type="button" class="chip-dismiss" aria-label="Remove">
    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="4" y1="4" x2="12" y2="12"/><line x1="12" y1="4" x2="4" y2="12"/></svg>
  </button>
</span>

主题芯片

应用 .theme-* 类来为你的芯片上色。芯片默认是微妙的，因为这允许有一个清晰的主题活动状态。

默认主要口音成功危险警告信息反向次要

HTML

<span class="chip">Default</span>
<span class="chip theme-primary">Primary</span>
<span class="chip theme-accent">Accent</span>
<span class="chip theme-success">Success</span>
<span class="chip theme-danger">Danger</span>
<span class="chip theme-warning">Warning</span>
<span class="chip theme-info">Info</span>
<span class="chip theme-inverse">Inverse</span>
<span class="chip theme-secondary">Secondary</span>

活动状态

添加 .active 以使芯片使用实心外观（背景/对比度）。这对于切换式芯片选择非常有用。

默认活跃默认活跃

HTML

<span class="chip theme-primary">Default</span>
<span class="chip theme-primary active">Active</span>
<span class="chip theme-success">Default</span>
<span class="chip theme-success active">Active</span>

芯片输入

将芯片和一个隐藏输入包裹在.chip-input中以创建标签输入字段。添加data-bs-chips以启用JavaScript行为。芯片默认为灰色，激活状态为主要蓝色，但你可以为容器应用任何主题颜色，使其中的芯片继承你选择的颜色。

在下面的输入框中输入内容，然后按 Enter 或 , 来添加新的芯片。使用 Backspace 或 Delete 键来移除芯片。有关更多详细信息，请参阅键盘行为部分。

技能： JavaScript TypeScript

HTML

<div class="chip-input" data-bs-chips>
  <label class="chip-input-label" for="skillsInput">Skills:</label>
  <span class="chip">
    JavaScript
  </span>
  <span class="chip">
    TypeScript
  </span>
  <input type="text" class="form-ghost" id="skillsInput" placeholder="Add more…" />
</div>

主题变体

添加一个 .theme-* 到……的课程 .chip-input 容器用于将主题颜色应用于其中的所有芯片。

已批准已验证

虫子关键的

HTML

<div class="chip-input theme-primary" data-bs-chips>
  <span class="chip">Approved</span>
  <span class="chip">Verified</span>
  <input type="text" class="form-ghost" placeholder="Add status...">
</div>

<div class="chip-input theme-danger" data-bs-chips>
  <span class="chip">Bug</span>
  <span class="chip">Critical</span>
  <input type="text" class="form-ghost" placeholder="Add issue">
</div>

你也可以通过向 chip 元素添加 .theme-* 类来单独应用主题颜色。

虫子关键的

HTML

<div class="chip-input theme-primary" data-bs-chips>
  <span class="chip theme-warning">Bug</span>
  <span class="chip theme-danger">Critical</span>
  <input type="text" class="form-ghost" placeholder="Add issue">
</div>

空状态

从仅仅是幽灵输入开始——随着用户输入，芯片被创建。

HTML

<div class="chip-input theme-primary" data-bs-chips>
  <input type="text" class="form-ghost" placeholder="Type and press Enter">
</div>

带标签

使用表单标签以提高可访问性。

技能

反应

按回车键或逗号添加技能。

HTML

<div class="form-field">
  <label class="form-label" for="skillsInputLabel">Skills</label>
  <div class="chip-input theme-primary" data-bs-chips>
    <span class="chip">
      React
      <button type="button" class="chip-dismiss" aria-label="Remove">
        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="4" y1="4" x2="12" y2="12"/><line x1="12" y1="4" x2="4" y2="12"/></svg>
      </button>
    </span>
    <input type="text" class="form-ghost" id="skillsInputLabel" placeholder="Add skill...">
  </div>
  <div class="form-text">Press Enter or comma to add a skill.</div>
</div>

残疾

禁用幽灵输入以防止添加新芯片，并禁用现有芯片上的关闭按钮。现有芯片将变为不可交互。

只读 [!代码高亮]

HTML

<div class="chip-input theme-primary" data-bs-chips>
  <span class="chip">
    Read only
    <button type="button" class="chip-dismiss" aria-label="Remove" disabled>
      <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="4" y1="4" x2="12" y2="12"/><line x1="12" y1="4" x2="4" y2="12"/></svg>
    </button>
  </span>
  <input type="text" class="form-ghost" placeholder="Disabled..." disabled>
</div>

用法

通过数据属性

将 data-bs-chips 添加到你的容器元素以自动初始化芯片输入行为。选项可以作为数据属性传递。

属性	描述
`data-bs-chips`	在容器元素上初始化芯片输入。
`data-bs-separator`	输入该字符时创建一个新芯片（或 `null` 禁用）。
`data-bs-allow-duplicates`	是否允许重复的芯片值。
`data-bs-max-chips`	最大芯片数量（`null` 表示无限制）。
`data-bs-create-on-blur`	当焦点离开字段时，从输入值创建一个芯片。

HTML

          <div class="chip-input theme-primary" data-bs-chips data-bs-separator="," data-bs-allow-duplicates="false">
  <input type="text" class="form-ghost" placeholder="Add tags...">
</div>

通过 JavaScript

使用 JavaScript 手动初始化：

JavaScript

          const chipInputElement = document.querySelector('.chip-input')
const chips = new bootstrap.Chips(chipInputElement, {
  separator: ',',
  maxChips: 5
})

依赖项

如果你从源代码构建 Bootstrap 的 JS，chips 插件需要以下 JavaScript 文件：

文件	描述
`js/src/chips.ts`	主要芯片组件
`js/src/base-component.ts`	基础组件类
`js/src/dom/data.ts`	元素数据存储
`js/src/dom/event-handler.ts`	事件处理工具
`js/src/dom/manipulator.ts`	数据属性操作
`js/src/dom/selector-engine.ts`	DOM选择器工具
`js/src/util/config.ts`	配置基类
`js/src/util/index.ts`	核心实用功能
`js/src/util/sanitizer.ts`	HTML 内容净化器

选项

选项可以通过数据属性或 JavaScript 传递：

名称	类型	默认	描述
`separator`	字符串 \| 空	`','`	输入时触发芯片创建的字符。设置为 `null` 禁用。
`allowDuplicates`	boolean	`false`	允许重复的芯片值。
`maxChips`	数字 \| 空	`null`	允许的最大筹码数量。 `null` 无限制
`placeholder`	string	`''`	用于动态创建输入的占位符文本。
`dismissible`	boolean	`true`	在创建的芯片上添加关闭按钮。
`dismissIcon`	string	`'<svg>...</svg>'`	用于关闭按钮图标的 HTML 字符串。通过传递给图标内容清理器插入之前。
`createOnBlur`	boolean	`true`	当输入框失去焦点时，根据输入值创建标签。

方法

方法	描述
`add(value)`	添加一个具有给定值的筹码。返回筹码元素或 `null` 如果被拒绝。
`remove(chipOrValue)`	通过元素引用或值字符串移除芯片。返回 `true` 如果被移除。
`removeSelected()`	移除所有当前选中的芯片。
`getValues()`	返回所有芯片值的数组。
`getSelectedValues()`	返回一个所选芯片值的数组。
`clear()`	移除所有芯片。
`clearSelection()`	取消选择所有芯片但不将其移除。
`selectChip(chip, options)`	选择一个芯片。选项： `addToSelection`, `rangeSelect`.
`focus()`	聚焦幽灵输入。
`dispose()`	销毁组件实例。

JavaScript

          const chipInputElement = document.querySelector('.chip-input')
const chips = bootstrap.Chips.getOrCreateInstance(chipInputElement)

// Add chips programmatically
chips.add('JavaScript')
chips.add('TypeScript')

// Get all values
console.log(chips.getValues()) // ['JavaScript', 'TypeScript']

// Remove a specific chip
chips.remove('JavaScript')

// Clear all chips
chips.clear()

事件

事件	描述
`add.bs.chips`	在添加芯片之前触发。调用 `event.preventDefault()` 以取消。
`remove.bs.chips`	在移除芯片之前触发。调用 `event.preventDefault()` 以取消。
`change.bs.chips`	在添加或移除任意芯片后触发。包含 `values` 数组。
`select.bs.chips`	当芯片选择发生变化时触发。包含 `selected` 值数组。

JavaScript

          const chipInputElement = document.querySelector('.chip-input')

chipInputElement.addEventListener('add.bs.chips', event => {
  console.log('Adding chip:', event.value)

  // Validate and optionally prevent
  if (event.value.length < 2) {
    event.preventDefault()
  }
})

chipInputElement.addEventListener('remove.bs.chips', event => {
  console.log('Removing chip:', event.value)
})

chipInputElement.addEventListener('change.bs.chips', event => {
  console.log('Current values:', event.values)
  // Sync with hidden input or state
})

chipInputElement.addEventListener('select.bs.chips', event => {
  console.log('Selected:', event.selected)
})

键盘行为

芯片输入支持类似 Mail.app 的键盘导航和芯片选择。

当输入框获取焦点时

键	操作
`Enter`	从当前输入值创建标签
`,`（或分隔符）	从当前输入值创建标签
`Backspace` / `Delete`	当输入为空时，选择并聚焦最后一个标签（首次按下）；再次按下将删除它
`←`	当光标在开头时，将焦点移到最后一个标签
`Shift+←`	选择最后一个标签并扩展选择
`Escape`	清除选择，清除输入，并失焦

当一个芯片被聚焦时

键	操作
`Backspace` / `Delete`	移除选中的芯片，然后选择并聚焦下一个最近的芯片
`←`	移动到上一个芯片
`→`	移动到下一个芯片（如果在末尾则输入）
`Shift+←` / `Shift+→`	在该方向上扩展选择
`Home`	移动到第一个芯片
`End`	移动到输入
`Cmd/Ctrl+A`	选择所有芯片
`Escape`	清除选择并聚焦输入

鼠标选择

操作	效果
点击芯片	选择芯片（取消选择其他芯片）
`Cmd/Ctrl+Click`	切换芯片选择状态
`Shift+Click`	从起点到点击的芯片进行范围选择

无障碍访问

为屏幕阅读器使用与芯片输入相关联的<label>元素
芯片可以聚焦，并支持完整的键盘导航
每个.chip-dismiss按钮都有aria-label="Remove"
已选芯片具有.active类以提供视觉提示
添加或移除芯片时会进行提示

CSS

芯片变量

Chip 在 .chip 上使用本地 CSS 变量以实现实时自定义。CSS 变量的值由每个组件独有的 Sass map生成，并应用于上述类。

scss/_chip.scss

// stylelint-disable-next-line scss/dollar-variable-default
$chip-tokens: defaults(
  (
    --chip-height: 1.75rem,
    --chip-padding-x: .625rem,
    --chip-gap: .3125rem,
    --chip-border-radius: var(--radius-pill),
    --chip-img-size: 1.25rem,
    --chip-icon-size: 1rem,
    --chip-dismiss-size: 1rem,
    --chip-dismiss-opacity: .65,
    --chip-dismiss-hover-opacity: 1,
    --chip-color: var(--theme-fg, var(--fg-body)),
    --chip-bg: var(--theme-bg-subtle, var(--bg-2)),
    --chip-border-color: transparent,
    --chip-selected-color: var(--theme-contrast, var(--primary-contrast)),
    --chip-selected-bg: var(--theme-bg, var(--primary-bg)),
    --chip-selected-border-color: var(--theme-bg, var(--primary-bg)),
  ),
  $chip-tokens
);

芯片输入变量

这些变量的作用域是 .chip-input 容器。

scss/表单/_芯片输入.scss

// stylelint-disable-next-line scss/dollar-variable-default
$chip-input-tokens: defaults(
  (
    --chip-input-padding-y: .75rem,
    --chip-input-padding-x: .75rem,
    --chip-input-gap: .375rem,
    --chip-input-ghost-min-width: 5rem,
    --control-fg: var(--btn-input-fg),
    --control-bg: var(--btn-input-bg),
    --control-border-width: var(--border-width),
    --control-border-color: var(--border-color),
    --control-border-radius: var(--radius-5),
  ),
  $chip-input-tokens
);