# @data-slot/tabs 中文文档

规范地址：https://npmcn.com/package/%40data-slot/tabs/

版本：1\.1\.3
npm 元数据更新时间：2026-11-05T12:30:55.174Z
中文译文更新时间：2026-11-11T13:13:25.165Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40data-slot/tabs
原文对照：https://npmcn.com/package/%40data-slot/tabs/?lang=original
项目主页：https://github.com/bejamas/data-slot#readme
源码仓库：https://github.com/bejamas/data-slot

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：23.5 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-01-09T14:58:25.510Z
- 最新版本发布：2026-11-05T12:30:54.785Z
- 近 30 天下载量：6855（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：164（近 12 个月 164 个）

## 中文简介

香草JavaScript的无头标签组件. 无障碍而无作相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.

## 安装

```sh
npm install @data-slot/tabs
```

也可以使用：`pnpm add @data-slot/tabs`、`yarn add @data-slot/tabs`、`bun add @data-slot/tabs`

## README

# @ data- slot/ tabs

香草JavaScript的无头标签组件. 无障碍而无作相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.

## 安装

```bash
npm install @data-slot/tabs
```

## 快速启动

```html
<div data-slot="tabs" data-default-value="one">
  <div data-slot="tabs-list">
    <button data-slot="tabs-trigger" data-value="one">Tab One</button>
    <button data-slot="tabs-trigger" data-value="two">Tab Two</button>
    <button data-slot="tabs-trigger" data-value="three">Tab Three</button>
    <div data-slot="tabs-indicator"></div>
  </div>
  <div data-slot="tabs-content" data-value="one">Content One</div>
  <div data-slot="tabs-content" data-value="two">Content Two</div>
  <div data-slot="tabs-content" data-value="three">Content Three</div>
</div>

<script type="module">
  import { create } from "@data-slot/tabs";
  
  const controllers = create();
</script>
```

## API 密码

### 初始化

#### `create(scope?)`

自动发现并绑定范围中的所有标签实例(默认为 `document`) (中文(简体) ).

```typescript
import { create } from "@data-slot/tabs";

const controllers = create(); // Returns TabsController[]
```

#### `createTabs(root, options?)`

为特定元素创建控制器.

```typescript
import { createTabs } from "@data-slot/tabs";

const tabs = createTabs(element, {
  defaultValue: "one",
  orientation: "horizontal",
  onValueChange: (value) => console.log(value),
});
```

### 槽数

#### 运行时间槽

-   `tabs` - 管理所选标签和激活模式的根元素.
-   `tabs-list` - 需要接收列表语义和取向的标签列表容器.
-   `tabs-trigger` - 标签按钮 `data-value`; 接收选定的状态和键盘导航。 需要至少一个触发器.
-   `tabs-content` - 与触发装置相匹配的小组 `data-value`; 接收表单语义,并在选中时显示.
-   `tabs-indicator` - 可选动画突出显示其位置和大小随所选触发器而来.

#### 标记

```html
<div data-slot="tabs" data-default-value="initial-tab">
  <div data-slot="tabs-list">
    <button data-slot="tabs-trigger" data-value="unique-id">Label</button>
    <!-- Optional animated indicator -->
    <div data-slot="tabs-indicator"></div>
  </div>
  <div data-slot="tabs-content" data-value="unique-id">Panel content</div>
</div>
```

### 数据属性

也可以通过根元素上的数据属性来设定选项. 联合来文的选择优先.

| 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `data-default-value` | 字符串 | 第一个启用的标签 | 初始选中标签 |
| `data-orientation` | 字符串 | `"horizontal"` | 分页方向:水平、垂直 |
| `data-activation-mode` | 字符串 | `"auto"` | 激活模式:自动、手动 |

```html
<!-- Vertical tabs with manual activation -->
<div data-slot="tabs" data-orientation="vertical" data-activation-mode="manual">
  ...
</div>
```

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `defaultValue` | `string` | 第一个启用的触发值 | 初始选中标签 |
| `orientation` | `"horizontal" | "vertical"` | `"horizontal"` | 键盘导航的标签取向 |
| `activationMode` | `"auto" | "manual"` | `"auto"` | 如何用键盘激活标签 |
| `onValueChange` | `(value: string) => void` | `undefined` | 选定标签更改时召回 |

### 主计长

| 方法/财产 | 说明 |
| --- | --- |
| `select(value)` | 按值选择标签 |
| `value` | 目前选中的值( 只读) `string`(中文(简体) ) |
| `updateIndicator()` | 在布局变化后重新计算指标位置 |
| `destroy()` | 清理所有事件听众 |

### 活动

#### 境外事件

通过自定义事件聆听更改 :

```javascript
element.addEventListener("tabs:change", (e) => {
  console.log("Selected tab:", e.detail.value);
});
```

#### 入境事件

通过事件控制标签 :

| 活动 | 细节 | 说明 |
| --- | --- | --- |
| `tabs:set` | `{ value: string }` | 在程序上选择标签 |

```javascript
// Select a tab
element.dispatchEvent(
  new CustomEvent("tabs:set", { detail: { value: "two" } })
);
```

#### 折旧事件

下列事件已贬值,将在v1.0中删除:

```javascript
// Deprecated: tabs:select event
element.dispatchEvent(
  new CustomEvent("tabs:select", { detail: { value: "two" } })
);

// Deprecated: string detail
element.dispatchEvent(
  new CustomEvent("tabs:select", { detail: "two" })
);
```

使用 `tabs:set` 与 `{ value: string }` 换句话说.

### 样式

#### 基本结构

```css
/* Hidden panels */
[data-slot="tabs-content"][hidden] {
  display: none;
}

/* Active trigger */
[data-slot="tabs-trigger"][aria-selected="true"] {
  font-weight: bold;
  border-bottom: 2px solid currentColor;
}

/* Or use data-state */
[data-slot="tabs-trigger"][data-state="active"] {
  color: blue;
}

[data-slot="tabs-trigger"][data-state="inactive"] {
  color: gray;
}
```

#### 面板激活方向

小组收到 `data-activation-direction` 在制表符更改后( 初始挂载时没有) :

-   水平 : `left`, (中文(简体) ), `right`
-   垂直数 : `up`, (中文(简体) ), `down`

用于方向内容动画 :

```css
[data-slot="tabs-content"][data-activation-direction="right"] {
  animation: slide-in-from-right 200ms ease;
}

[data-slot="tabs-content"][data-activation-direction="left"] {
  animation: slide-in-from-left 200ms ease;
}
```

#### 动画指标

该指标收到用于定位的CSS变量:

```css
[data-slot="tabs-indicator"] {
  position: absolute;
  left: var(--active-tab-left);
  width: var(--active-tab-width);
  height: 2px;
  background: currentColor;
  transition: left 0.2s, width 0.2s;
}

/* Vertical orientation */
[data-slot="tabs-list"][aria-orientation="vertical"] [data-slot="tabs-indicator"] {
  top: var(--active-tab-top);
  height: var(--active-tab-height);
  width: 2px;
}
```

#### CSS 变量

| 变量 | 说明 |
| --- | --- |
| `--active-tab-left` | 活动触发的左偏移 |
| `--active-tab-width` | 活动触发的宽度 |
| `--active-tab-top` | 主动触发的顶部抵消 |
| `--active-tab-height` | 活动触发高度 |

#### 尾风示例

```html
<div data-slot="tabs">
  <div data-slot="tabs-list" class="relative flex border-b">
    <button 
      data-slot="tabs-trigger" 
      data-value="one"
      class="px-4 py-2 aria-selected:text-blue-600"
    >
      Tab One
    </button>
    <div 
      data-slot="tabs-indicator" 
      class="absolute bottom-0 h-0.5 bg-blue-600 transition-all"
      style="left: var(--active-tab-left); width: var(--active-tab-width)"
    ></div>
  </div>
  <div data-slot="tabs-content" data-value="one" class="p-4">
    Content
  </div>
</div>
```

### 键盘导航

下表说明 `activationMode: "auto"` (默认). 单位 `"manual"` 模式,箭头键, `Home`,以及 `End` 仅移动焦点; `Enter` 或者说 `Space` 选择焦点标签。 已禁用触发器被跳过 .

#### 水平方向

| 密钥 | 行动 |
| --- | --- |
| `ArrowLeft` | 选择上一个标签 |
| `ArrowRight` | 选择下一个标签 |
| `Home` | 选择第一个标签 |
| `End` | 选择最后一个标签 |

#### 垂直方向

| 密钥 | 行动 |
| --- | --- |
| `ArrowUp` | 选择上一个标签 |
| `ArrowDown` | 选择下一个标签 |
| `Home` | 选择第一个标签 |
| `End` | 选择最后一个标签 |

### 无障碍

该组件自动处理 :

-   `role="tablist"` 列表中
-   `role="tab"` 触发器
-   `role="tabpanel"` 关于内容
-   `aria-orientation` 列表中
-   `aria-selected` 触发器
-   `aria-controls` 将触发器连接到面板
-   `aria-labelledby` 将面板连接到触发器
-   `tabindex` 管理( 只有选中的已启用标签在标签顺序中)

## 许可证

麻省理工学院

## 常见问题

### @data-slot/tabs 是什么？

香草JavaScript的无头标签组件\. 无障碍而无作相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相\.

### 如何安装 @data-slot/tabs？

在项目目录运行 npm install @data-slot/tabs，或使用 pnpm add / yarn add / bun add。

### @data-slot/tabs 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @data-slot/tabs 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @data-slot/tabs 可以商用吗？

@data-slot/tabs 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @data-slot/tabs 的下载量有多少？

根据 npm 官方下载统计，@data-slot/tabs 在 2026/10/12 – 2026/11/10 这 30 天内被下载 6,855 次，日均约 229 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @data-slot/tabs 还在维护吗？

最新版本 1\.1\.3 发布于 2026/11/05（6 天前）；至今共发布 164 个版本，其中过去 12 个月发布了 164 个；首次发布于 2026/01/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。