# @github/tab-container-element 中文文档

规范地址：https://npmcn.com/package/%40github/tab-container-element/

版本：4\.9\.0
npm 元数据更新时间：2026-10-15T16:21:15.221Z
中文译文更新时间：2026-11-16T10:49:57.096Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：59.9 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2018-12-12T11:12:49.769Z
- 最新版本发布：2026-08-03T23:49:20.092Z
- 近 30 天下载量：232386（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 1 个）

## 中文简介

标签容器元素

## 安装

```sh
npm install @github/tab-container-element
```

也可以使用：`pnpm add @github/tab-container-element`、`yarn add @github/tab-container-element`、`bun add @github/tab-container-element`

## README

# <tab-容器>元素

带有键盘支持的可访问标签容器元素 。 跟着 [ARIA 标签最佳做法指南](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/)。 。 。 .

## 安装

```
$ npm install @github/tab-container-element
```

## 使用量

```js
import '@github/tab-container-element'
```

```html
<tab-container>
  <button type="button" id="tab-one" role="tab" aria-selected="true">Tab one</button>
  <button type="button" id="tab-two" role="tab" tabindex="-1">Tab two</button>
  <button type="button" id="tab-three" role="tab" tabindex="-1">Tab three</button>
  <div role="tabpanel" aria-labelledby="tab-one">
    Panel 1
  </div>
  <div role="tabpanel" aria-labelledby="tab-two" hidden>
    Panel 2
  </div>
  <div role="tabpanel" aria-labelledby="tab-three" hidden>
    Panel 3
  </div>
</tab-container>
```

如果没有标签 `aria-selected=true`,然后自动选择第一个标签。 您还可以添加 `default-tab=N` 属性以避免设置 `aria-selected=true` 选项卡上 `N` 是基于 0 的标签索引 :

```html
<!-- The _second_ tab will be selected -->
<tab-container default-tab="1">
  <button type="button" id="tab-one" role="tab">Tab one</button>
  <button type="button" id="tab-two" role="tab">Tab two</button>
  <button type="button" id="tab-three" role="tab">Tab three</button>
  <!-- ... -->
</tab-container>
```

### 活动

-   `tab-container-change` (泡泡,可取消):发射 `<tab-container>` 在选择新标签和更新能见度之前. `event.tab` 是将被聚焦的标签, `event.tabIndex` 是基于 0 的索引 `tab` 财务报告和审定财务报表 `tab.panel` 如果事件未取消, 将会显示的面板 .
-   `tab-container-changed` (泡泡):开火 `<tab-container>` 在选择新标签并更新能见度后. `event.tab` 是当前正在运行的标签(并且将在此事件之后集中), `event.tabIndex` 是基于 0 的索引 `tab` 财务报告和审定财务报表 `event.panel` 是新可见的标签面板.

### 方法

-   `selectTab(tabIndex, options: {focus?: boolean} = {})`: 程序上用给定的以0为基础的索引选择标签并显示其面板。 点燃上述事件。 默认情况下,将焦点设置到选定的标签;调用 `{focus: false}` 为了防止这种情况.

### 部件

-   `::part(tablist-wrapper)` 是包含 `before-tabs`, (中文(简体) ), `tablist` 财务报告和审定财务报表 `after-tabs`。 。 。 .
-   `::part(tablist)` 是包装所有标签的容器。 这个元素在ATs中现出 `role=tablist`。 。 。 .
-   `::part(panel)` 是当前活动小板的容器.
-   `::part(before-tabs)` 容器中包含任何在第一个 `role=tab`。这也可以直接与 `slot=before-tabs`该容器位于元素外,其作用=列表以遵守ARIA准则.
-   `::part(after-tabs)` 容器中包含任何在上一页之后出现的元素 `role=tab`。这也可以直接与 `slot=after-tabs`该容器位于元素外,其作用=列表以遵守ARIA准则.
-   `::part(after-panels)` 容器中包含任何在上一页之后出现的元素 `role=tabpanel`。如果想要在容器中添加视觉处理,但内容总是显示在活动面板下.

### 当标签面板内容为控件时

启动后,整个标签面板将获得焦点. 如果标签面板本身由交互式元素组成,例如动作列表或收音机按钮,这可能不可取.

在这些情况下,适用 `data-tab-container-no-tabstop` 页:1 `tabpanel` 键.

```html
<tab-container>
  <button type="button" id="tab-one" role="tab" aria-selected="true">Tab one</button>
  <button type="button" id="tab-two" role="tab" tabindex="-1">Tab two</button>
  <div role="tabpanel" aria-labelledby="tab-one" data-tab-container-no-tabstop>
    <ul role="menu" aria-label="Branches">
      <li tabindex="0">branch-one</li>
      <li tabindex="0">branch-two</li>
    </ul>
  </div>
  <div role="tabpanel" aria-labelledby="tab-two" data-tab-container-no-tabstop hidden>
    <ul role="menu" aria-label="Commits">
      <li tabindex="0">Commit One</li>
      <li tabindex="0">Commit Two</li>
    </ul>
  </div>
</tab-container>
```

### 垂直标签

若为 `<tab-container>` 给出 `vertical` 属性将应用 `aria-orientation=vertical` 属性到标签列表。 这将以垂直制表列表的形式呈现给ATs,您可以据此使用属性来样式制表符.

在这些情况下,适用 `data-tab-container-no-tabstop` 页:1 `tabpanel` 键.

```html
<tab-container vertical>
  <button type="button" id="tab-one" role="tab" aria-selected="true">Tab one</button>
  <button type="button" id="tab-two" role="tab" tabindex="-1">Tab two</button>
  <div role="tabpanel" aria-labelledby="tab-one" data-tab-container-no-tabstop>
    <ul role="menu" aria-label="Branches">
      <li tabindex="0">branch-one</li>
      <li tabindex="0">branch-two</li>
    </ul>
  </div>
  <div role="tabpanel" aria-labelledby="tab-two" data-tab-container-no-tabstop hidden>
    <ul role="menu" aria-label="Commits">
      <li tabindex="0">Commit One</li>
      <li tabindex="0">Commit Two</li>
    </ul>
  </div>
</tab-container>
```

### 未管理槽

`<tab-container>` 旨在简化 ShadowDOM 中复杂的标记,从而使您最终编写的 HTML 总体上减少。 然而,有时,如果 _满_ 控制标记。 每一个 `::part` 选择器也是 `<slot>`s,这表示你可以参与任何角色并进行分档,凌驾于内置的ShadowDOM之上.

#### 未管理 `tablist`

你可以自己提供 `role=tablist` 财务报告和审定财务报表 `<tab-container>` 将容纳。 如果您在标签列表中需要额外的演示标记, 这将会有所帮助 。 但记住:

-   您必须确保所有的孩子元素 `role=tab` 或者说 `role=presentational`。 。 。 .
-   该元素仍然会在此元素前后放置内容档,以便正确显示标签列表.

```html
<tab-container>
  <div role="tablist">
      <my-icon name="tabs" role="presentational"></my-icon>
      <button type="button" role="tab">Tab one</button>
      <button type="button" role="tab">Tab two</button>
  </div>
  <div role="tabpanel"></div>
  <div role="tabpanel"></div>
</tab-container>
```

#### 未管理 `tablist-tab-wrapper`

你可以把时间档 `tablist-tab-wrapper` 页:1 此槽管理标签, 但不管理元素的前后 。 这样,您可以将自定义的 HTML 设置在标签列表中. 记住,如果你提供这个元素:

-   您还必须提供 `role=tablist` 小时候.
-   您必须确保所有的孩子元素 `role=tab` 或者说 `role=presentational`。 。 。 .
-   该元素仍然会在此元素前后放置内容档,以便正确显示标签列表.

```html
<tab-container>
  <div slot="tablist-tab-wrapper">
    <div role="tablist">
        <button type="button" role="tab">Tab one</button>
        <button type="button" role="tab">Tab two</button>
    </div>
  </div>
  <div role="tabpanel"></div>
  <div role="tabpanel"></div>
</tab-container>
```

#### 未管理 `tablist-wrapper`

如果您想完全控制整个制表区域,包括管理制表前和制表后的内容,那么您可以将制表符排入 `tablist-wrapper` 键。 记住,如果你提供这个元素:

-   `<tab-container>` 将仅管理 `role=panel`它不会在标签或面板之前或之后管理元素.
-   你连时间都打不开 `tablist-tab-wrapper`。您可以选择省略此元素.
-   您还必须提供 `role=tablist` 作为后人.
-   您必须确保列表中的所有儿童元素 `role=tab` 或者说 `role=presentational`。 。 。 .
-   该元素仍然会在此元素前后放置内容档,以便正确显示标签列表.

```html
<tab-container>
  <div slot="tablist-wrapper">
    <div role="tablist">
        <button type="button" role="tab">Tab one</button>
        <button type="button" role="tab">Tab two</button>
    </div>
  </div>
  <div role="tabpanel"></div>
  <div role="tabpanel"></div>
</tab-container>
```

## 浏览器支持

浏览器, 不本地 [自定义元素支持](https://caniuse.com/#feat=custom-elementsv1) 需要一个 [多边填充](https://github.com/webcomponents/polyfills/tree/master/packages/custom-elements)。 。 。 .

-   颜色
-   火花
-   萨法里
-   微软边缘

## 发展

```
npm install
npm test
```

## 许可证

以麻省理工学院许可证分发。 详情见LICENSE.

## 常见问题

### @github/tab-container-element 是什么？

标签容器元素

### 如何安装 @github/tab-container-element？

在项目目录运行 npm install @github/tab-container-element，或使用 pnpm add / yarn add / bun add。

### @github/tab-container-element 支持 TypeScript 吗？

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

### @github/tab-container-element 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @github/tab-container-element 可以商用吗？

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

### @github/tab-container-element 的下载量有多少？

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

### @github/tab-container-element 还在维护吗？

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

