# @clean-jsdoc-theme/utils 中文文档

规范地址：https://npmcn.com/package/%40clean-jsdoc-theme/utils/

版本：5\.2\.1
npm 元数据更新时间：2026-10-24T11:26:04.060Z
中文译文更新时间：2026-11-10T00:46:32.398Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：601 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-06-10T15:31:47.164Z
- 最新版本发布：2026-10-24T11:26:03.423Z
- 近 30 天下载量：21801（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

共同类型和计划

## 安装

```sh
npm install @clean-jsdoc-theme/utils
```

也可以使用：`pnpm add @clean-jsdoc-theme/utils`、`yarn add @clean-jsdoc-theme/utils`、`bun add @clean-jsdoc-theme/utils`

## README

# @ clean-jsdoc-主题/用途

每种其他包装进口的共享核心:界定 战地边界和双方使用的弹道规则,加上 **纯** 运行时逻辑——选择验证,构建报告和诊断 脊椎骨 脊椎骨 脊椎骨 它保持浏览器安全( 刚导入到浏览器中) : **注射**数字 : 网络`fetch`)和 `node:zlib` gzip 尺寸器由呼叫者传递, 从来没有进口到这里.

## 里面的东西

```
src/
├── doclet-schema.ts   # JSDoc doclet shape (TDoclet, kinds, params, meta, …)
├── salty.ts           # salty (taffy) collection helpers + types
├── site/              # the setu↔dwar contract (types-first)
│   ├── page.ts        # Page (+ PageKind, 'source' body), Frontmatter, Heading
│   ├── manifest.ts    # SiteManifest, NavNode, SearchEntry, ExtractManifest, BuildSpec
│   ├── render.ts      # OutputFile, RenderOptions, RenderResult, RenderError, RenderWarning
│   ├── theme.ts       # ThemeTokens, ThemeColors, ThemeConfig, ComponentOverrides
│   ├── site-name.ts   # SiteName (text | logo set) + siteNameText / resolveSiteLogo
│   ├── islands.ts     # IslandName union + IslandPropsMap
│   └── slug-rules.ts  # slugifyHeading / slugifyPath / slugifySourcePath
└── config/            # PURE opts validation + build report (network/zlib injected)
    ├── diagnostics.ts # Diagnostic model + DiagnosticBag + formatDiagnostics
    ├── opts-schema.ts # zod schemas + THEME_OPT_KEYS
    ├── validate-opts.ts # validateThemeOpts → { value, diagnostics }
    ├── site-name.ts   # validateSiteName (shape only)
    ├── fonts.ts       # validateFonts (heading/body existence-checked; per-locale keys)
    ├── locales.ts     # validateLocales (opts.locales/defaultLocale → ValidatedLocales)
    ├── google-fonts.ts# createGoogleFontResolver (injectable fetch; fail-open)
    ├── suggest.ts     # near-miss "did you mean X?" key suggestions
    ├── report.ts      # formatBuildReport (per-route sizes + optional gzip)
    └── format.ts      # humanFileSize, byteLength, ANSI helpers
```

## 公共 API

包件为型号一等;从管子再出出:

```ts
import type {
  SiteManifest,
  Page,
  PageKind,
  NavNode,
  SearchEntry,
  Frontmatter,
  Heading,
  OutputFile,
  RenderOptions,
  RenderResult,
  RenderError,
  ThemeConfig,
  ThemeTokens,
  ThemeColors,
  ComponentOverrides,
  SiteName,
  IslandName,
  IslandPropsMap,
  TDoclet,
} from '@clean-jsdoc-theme/utils';

import {
  // slug rules (shared by setu + dwar)
  slugifyHeading,
  slugifyPath,
  slugifySourcePath,
  // opts validation + build report (the bridges call these)
  validateThemeOpts,
  formatBuildReport,
  DiagnosticBag,
  formatDiagnostics,
  // the i18n contract (setu emits, aadesh reads)
  toExtractManifest,
} from '@clean-jsdoc-theme/utils';
```

### 阻塞帮助

-   `slugifyHeading(text, registry?)` ——标题正文 锚地编号. 通过共享 `Map` 以解析页面上的 ids 相撞(`-1`, (中文(简体) ), `-2`) (中文(简体) ).
-   `slugifyPath(parts)` 长名部件 URL 路径段 .
-   `slugifySourcePath(path)` 源文件路径 – 其 `source/<file>` slug.

### 选择验证+报告`config/`(中文(简体) )

-   `validateThemeOpts(input)` → `{ value, diagnostics }` ——正常化+验证 主题选项(zod schemas,一个活的 Google-Font 存在检查,未知密钥) "你的意思是?"建议). 桥很早就叫这个, 字体/ typo 不好 警告,除非 `strict` 升级.
-   `formatBuildReport(input)` – Next.js 风格的每行大小表(gzip 缩放器) 注入,因此本模块保持浏览器安全.
-   `DiagnosticBag` 编号 : `formatDiagnostics` 诊断脊椎被setu重用, 和bhasha的验证原始.

### I18n/建筑合同

`ExtractManifest` + 键 `toExtractManifest(manifest)` (aadish在摘录中的内容) 模式)和 `BuildSpec` (每个地方都会变光) 住在这里 所以setu,the 桥,和aadish都同意的形状.

## 为什么它存在

Setu-ddwar合同就住在这里一次 所以双方都一样 形状和永远不能漂移。 弹道规则共享的原因相同: setu 生成导航/TOC锚地,并释放导出的标题代号——使用一个 执行保证双方同意。 这个 `config/` 逻辑住在这里( 而非 因此 JSDoc 和 TypeDoc 验证选项并打印报告 同样的.

## 贡献者

感谢所有帮助建立干净的jsdoc主题的人.

[![Contributors](https://contrib.rocks/image?repo=ankitskvmdam/clean-jsdoc-theme)](https://github.com/ankitskvmdam/clean-jsdoc-theme/graphs/contributors)

## 许可证

麻省理工学院.

## 常见问题

### @clean-jsdoc-theme/utils 是什么？

共同类型和计划

### 如何安装 @clean-jsdoc-theme/utils？

在项目目录运行 npm install @clean-jsdoc-theme/utils，或使用 pnpm add / yarn add / bun add。

### @clean-jsdoc-theme/utils 支持 TypeScript 吗？

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

### @clean-jsdoc-theme/utils 支持 ESM 还是 CommonJS？

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

### @clean-jsdoc-theme/utils 可以商用吗？

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

### @clean-jsdoc-theme/utils 的下载量有多少？

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

### @clean-jsdoc-theme/utils 还在维护吗？

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