# @shelf/table-of-contents 中文文档

规范地址：https://npmcn.com/package/%40shelf/table-of-contents/

版本：1\.4\.6
npm 元数据更新时间：2026-11-02T10:16:37.019Z
中文译文更新时间：2026-11-02T11:36:21.522Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40shelf/table-of-contents
原文对照：https://npmcn.com/package/%40shelf/table-of-contents/?lang=original
项目主页：https://github.com/shelfio/libs-frontend#readme
源码仓库：https://github.com/shelfio/libs-frontend

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

- 包体积（解压后）：14.9 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2021-11-05T13:16:01.091Z
- 最新版本发布：2026-10-08T20:11:22.841Z
- 已发布版本数：23（近 12 个月 11 个）

## 中文简介

node-toc的分支，以减少bundle的大小，并在TypeScript中重写

## 安装

```sh
npm install @shelf/table-of-contents
```

也可以使用：`pnpm add @shelf/table-of-contents`、`yarn add @shelf/table-of-contents`、`bun add @shelf/table-of-contents`

## README

# 目录 [![CircleCI](https://circleci.com/gh/shelfio/table-of-contents/tree/master.svg?style=svg)](https://circleci.com/gh/shelfio/table-of-contents/tree/master)![](https://img.shields.io/badge/code_style-oxfmt-0ea5e9.svg)

> 链接HTML标头并生成TOC。
> 
> 叉形的 [node-toc](https://github.com/cowboy/node-toc)
> 
> 用TypeScript重写并重构以减小包的大小（不使用整个lodash库）

## 安装

```
$ yarn add @shelf/table-of-contents
```

## 使用

```js
const toc = require('@shelf/table-of-contents');
```

### toc.untag

从字符串中剥离HTML标记。

```js
const stripped = toc.untag(html);
```

### toc.anchor

将文本字符串转换为url友好且不太难看的内容。

```js
const anchor = toc.anchor(arbitraryText);
```

### toc.unique

获取唯一名称并将返回的名称存储在名称中，以备将来使用惟一名称获取。

```js
const names = {};
const guaranteedUniqueAnchor1 = toc.unique(names, toc.anchor(arbitraryText));
const guaranteedUniqueAnchor2 = toc.unique(names, toc.anchor(arbitraryText));
```

### toc.process

锚定所有标头并内联生成的TOC，返回处理过的HTML。

```js
const htmlWithAnchorsAndTOC = toc.process(html [, options]);
```

#### 选项

-   **占位符** - `RegExp` -用于匹配TOC占位符。默认为 `/<!--\s*toc\s*-->/gi`.
-   _因为这个方法调用 `toc.anchorize` 和 `toc.toc` 方法，也可以指定它们的选项。_

### toc.anchorize

解析HTML，返回头部对象和锚定HTML的数组。

```js
const obj = toc.anchorize(html [, options]);
```

#### 选项

-   **头** - `RegExp` -用于匹配HTML标头。默认为 `/<h(\d)(\s*[^>]*)>([\s\S]+?)<\/h\1>/gi`.
-   **tocMin** - `Number` -添加到TOC的最小header级别。默认为 `2`.
-   **tocMax** - `Number` -最大头级别添加到TOC。默认为 `6`.
-   **anchorMin** - `Number` -要锚定的最小标头级别。默认为 `2`.
-   **anchorMax** - `Number` -最大头级别锚定。默认为 `6`.
-   **头** - `String` | `Function` - Lodash模板字符串或函数，用于锚定标头。

### toc.toc

从标题对象数组生成TOC HTML。

```js
const obj = toc.toc(headers [, options]);
```

#### 选项

-   **openUL** - `String` | `Function` —Lodash模板用于生成TOC的字符串或函数。
-   **closeUL** - `String` | `Function` —Lodash模板用于生成TOC的字符串或函数。
-   **openLI** - `String` | `Function` —Lodash模板用于生成TOC的字符串或函数。
-   **closeLI** - `String` | `Function` —Lodash模板用于生成TOC的字符串或函数。
-   **TOC** - `String` | `Function` - Lodash模板字符串或函数，用于包装生成的TOC。

## 示例

默认的HTML非常棒，但是您可以自定义生成的HTML，例如：

```js
const processedHTML = toc.process(unprocessedHTML, {
  header: '<h<%= level %><%= attrs %> id="<%= anchor %>"><%= header %></h<%= level %>>',
  TOC: '<div class="toc"><%= toc %></div>',
  openUL: '<ul data-depth="<%= depth %>">',
  closeUL: '</ul>',
  openLI: '<li data-level="H<%= level %>"><a href="#<%= anchor %>"><%= text %></a>',
  closeLI: '</li>',
});
```

## 发布

```sh
$ git checkout master
$ yarn version
$ yarn publish
$ git push origin master --tags
```

## 许可证

麻省理工学院© [架子上](https://shelf.io/)

## 常见问题

### @shelf/table-of-contents 是什么？

node-toc的分支，以减少bundle的大小，并在TypeScript中重写

### 如何安装 @shelf/table-of-contents？

在项目目录运行 npm install @shelf/table-of-contents，或使用 pnpm add / yarn add / bun add。

### @shelf/table-of-contents 支持 TypeScript 吗？

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

### @shelf/table-of-contents 支持 ESM 还是 CommonJS？

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

### @shelf/table-of-contents 可以商用吗？

@shelf/table-of-contents 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @shelf/table-of-contents 还在维护吗？

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