# @citestyle/types 中文文档

规范地址：https://npmcn.com/package/%40citestyle/types/

版本：1\.0\.1
npm 元数据更新时间：2026-04-26T19:15:31.597Z
中文译文更新时间：2026-11-09T22:02:06.869Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40citestyle/types
原文对照：https://npmcn.com/package/%40citestyle/types/?lang=original
项目主页：https://github.com/uniweb/csl/tree/main/packages/types
源码仓库：https://github.com/uniweb/csl

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

- 包体积（解压后）：20.8 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-03-12T22:13:44.999Z
- 最新版本发布：2026-04-26T19:15:31.459Z
- 近 30 天下载量：1864（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

TypeScript 为 DSL-JSON 定义, 编译样式和注册

## 安装

```sh
npm install @citestyle/types
```

也可以使用：`pnpm add @citestyle/types`、`yarn add @citestyle/types`、`bun add @citestyle/types`

## README

# @ citetyle/ 类型

Citestyle生态系统的TypeScript类型定义. 覆盖了CSL-JSON数据结构,编译了样式模块,引用注册,以及所有公共API.

当使用任意类型时自动获得这些类型 `@citestyle/*` 软件包——每个软件包 `exports` 地图包括 `types` 条件在这里。 直接安装此软件包, 只当您需要导入类型而无需拖入运行时的软件包 .

## 安装

```bash
npm install -D @citestyle/types
```

## 类型

### CSL- JSON 数据

| 类型 | 说明 |
| --- | --- |
| `CslItem` | 包含所有标准 SSL- JSON 字段( 70+) 的引用项, 加 `year-suffix` 和扩展字段的索引签名 |
| `CslName` | 名称对象 : `family`, (中文(简体) ), `given`, (中文(简体) ), `non-dropping-particle`, (中文(简体) ), `dropping-particle`, (中文(简体) ), `suffix`, (中文(简体) ), `literal` |
| `CslDate` | 日期对象 : `date-parts`, (中文(简体) ), `literal`, (中文(简体) ), `raw`, (中文(简体) ), `season`, (中文(简体) ), `circa` |
| `CslItemType` | 40+ CPL 项目类型字符串的结合 |

### 编译样式模块

| 类型 | 说明 |
| --- | --- |
| `CompiledStyle` | 编译的样式模块 : `meta`, (中文(简体) ), `bibliography()`, (中文(简体) ), `citation()`, (中文(简体) ), `bibliographySort()` |
| `StyleMeta` | 样式元数据 : `id`, (中文(简体) ), `title`, (中文(简体) ), `class`,解析设置,崩溃模式,分隔符 |
| `FormattedEntry` | 文献目录产出: `{ text, html, parts, links }` |
| `FormattedCitation` | 引用输出 : `{ text, html }` |

### 书记官处

| 类型 | 说明 |
| --- | --- |
| `Registry` | 登记册接口 : `addItems()`, (中文(简体) ), `getItem()`, (中文(简体) ), `cite()`, (中文(简体) ), `getBibliography()`, (中文(简体) ), `size` |
| `RegistryOptions` | 备选方案 `createRegistry()`数字 : `subsequentAuthorSubstitute` |
| `CiteRef` | 引文参考: `id`, (中文(简体) ), `item`, (中文(简体) ), `locator`, (中文(简体) ), `label`, (中文(简体) ), `prefix`, (中文(简体) ), `suffix` |
| `FormatContext` | 运行时背景传递到样式函数 : `_secOpts`, (中文(简体) ), `_disambig` |
| `DisambiguationContext` | 平地分解状态 : `addNames`, (中文(简体) ), `addGivenname`, (中文(简体) ), `givenname` |

### 编译器

| 类型 | 说明 |
| --- | --- |
| `CompileOptions` | 备选方案 `compile()`数字 : `locale`, (中文(简体) ), `format` |
| `CompileResult` | 编译器输出 : `{ code, meta }` |

### 格式化帮助

| 类型 | 说明 |
| --- | --- |
| `NameFormatConfig` | 配置用于 `formatNames()`: et-al,粒子,排序顺序,初始化 |
| `DateFormatConfig` | 配置用于 `formatDate()`: 日期、月份、范围 |
| `ValidationResult` | 产出 `validateItem()`数字 : `{ valid, warnings }` |

## 使用量

```typescript
import type { CslItem, CslName, FormattedEntry, CompiledStyle } from '@citestyle/types'

const item: CslItem = {
  id: '1',
  type: 'article-journal',
  title: 'A groundbreaking study',
  author: [{ family: 'Smith', given: 'Jane' }],
  issued: { 'date-parts': [[2024, 6]] },
  'container-title': 'Nature',
  DOI: '10.1038/example',
}

function formatBibliography(style: CompiledStyle, items: CslItem[]): FormattedEntry[] {
  return items.map(item => style.bibliography!(item))
}
```

```typescript
import type { Registry, CiteRef, FormattedCitation } from '@citestyle/types'

function citeItems(registry: Registry, ids: string[]): FormattedCitation {
  const cites: CiteRef[] = ids.map(id => ({ id }))
  return registry.cite(cites)
}
```

## 常见问题

### @citestyle/types 是什么？

TypeScript 为 DSL-JSON 定义, 编译样式和注册

### 如何安装 @citestyle/types？

在项目目录运行 npm install @citestyle/types，或使用 pnpm add / yarn add / bun add。

### @citestyle/types 支持 TypeScript 吗？

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

### @citestyle/types 支持 ESM 还是 CommonJS？

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

### @citestyle/types 可以商用吗？

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

### @citestyle/types 的下载量有多少？

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

### @citestyle/types 还在维护吗？

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