# @retorquere/bibtex-parser 中文文档

规范地址：https://npmcn.com/package/%40retorquere/bibtex-parser/

版本：13\.0\.11
npm 元数据更新时间：2026-11-02T07:32:55.654Z
中文译文更新时间：2026-11-02T08:08:18.865Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：8.8 MB，56 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：11 个
- 首次发布：2019-08-17T15:33:08.686Z
- 最新版本发布：2026-11-02T07:32:55.363Z
- 已发布版本数：290（近 12 个月 29 个）

## 中文简介

助理型解析器

## 安装

```sh
npm install @retorquere/bibtex-parser
```

也可以使用：`pnpm add @retorquere/bibtex-parser`、`yarn add @retorquere/bibtex-parser`、`bun add @retorquere/bibtex-parser`

## README

# bibtex-parser

一个用于解析bibtex （.bib）文件的node/npm包。这是驱动的解析器 [更好的BibTeX为Zotero](https://retorque.re/zotero-better-bibtex/) 饮酒(la)特克斯进口。

在解析时，解析器将为命令应用标记，例如 `\textbf`， `\textsc`等，以及保护文本不受大小写变化影响的大括号。在可能的情况下，命令将被替换为对应的unicode文本。

## 什么是BibTeX？

BibTeX是一个参考管理程序，它使TeX和LaTeX的用户可以轻松地为书籍和期刊文章生成书目。在可能的情况下，它通常按照TeX和LaTeX的方式使用TeX字体进行样式化。LaTeX最早由Leslie Lamport和Oren Patashnik于1985年创建。

有关文件可于 [https://retorque.re/bibtex-parser/](https://retorque.re/bibtex-parser/).

## 选择解析器

Rust/WebAssembly实现是默认的导出（仅限ESM，见下文）。纯TypeScript实现也不需要初始化，只能作为esm使用 `/js` 子路径:

```js
import { parse } from '@retorquere/bibtex-parser/js'

const library = parse('@article{example, title={A title}}')
```

对于扫描仪级表示，使用 `parseVerbatim`． 它的字段是字符串，没有被规范化或解释为LaTeX：

```js
import { parseVerbatim } from '@retorquere/bibtex-parser/js'

const library = parseVerbatim('@article{example, title={A title}}')
```

生成的API文档涵盖了规范化的TypeScript API (`/js`),其 `parseVerbatim` 导出，以及从默认入口点可用的WASM导出。

所有解析器结果公开 `preambles: string[]`，保留倍数 `@preamble` 指令的源顺序。规范化的结果属性先前已命名 `preamble`;呼叫者应使用 `preambles` 代替。

WebAssembly实现是仅限esb的默认入口点。在调用解析器之前初始化它。在浏览器中， `init()` 加载相对于模块的二进制文件：

```js
import init, { parse } from '@retorquere/bibtex-parser'

await init()
const library = parse('@article{example, title={A title}}')
```

在Node.js中，显式加载导出的二进制文件：

```js
import { readFile } from 'node:fs/promises'
import init, { parse } from '@retorquere/bibtex-parser'

const binary = new URL(import.meta.resolve('@retorquere/bibtex-parser/bibtex_parser_bg.wasm'))
await init({ module_or_path: await readFile(binary) })
const library = parse('@article{example, title={A title}}')
```

两个入口点都包含TypeScript声明。从源代码构建包也会构建WebAssembly，并且需要Rust `wasm32-unknown-unknown` 目标和 `wasm-pack`;消费者并不需要这些工具。

### Zotero插件

在插件的构建中包含默认的JavaScript入口点，并将WASM二进制文件打包为插件资源。在插件的特权Zotero上下文中，在启动任何解析调用之前初始化解析器：

```js
import init, { parse } from '@retorquere/bibtex-parser'

await init({ module_or_path: 'chrome://zotero-better-bibtex/content/resource/bibtex/bibtex_parser_bg.wasm' })

const library = parse('@article{example, title={A title}}')
```

在启动过程中等待初始化一次；后续 `parse` 或者 `parseAsync` 调用重用初始化的模块。

## URL命令

两个解析器都接受 `richURL`，默认为的布尔值 `true`． 与 `richURL: true`， `\href{http://example.org/{id}}{url}` 显示为 `<a href="http://example.org/{id}">url</a>` 没有案件保护的范围。与 `richURL: false`，它呈现为 `<span class="nocase">http://example.org/{id}</span>`，丢弃标签并保留目的地的外壳，而不考虑 `caseProtection` 设置。该选项也适用于 `\url`.

## 未知的TeX命令

两个 `parse` 和 `parseAsync` 接受一个 `unsupported` 选择:

-   `ignore`：将未知命令替换为空。
-   `keep` （默认）：保留文本TeX，包括反斜杠，并在 `errors`.
-   `throw`抛出一个错误，标识不支持的TeX命令(`parse` 把和 `parseAsync` 拒绝)。它绕过了法线 `errors` 收集。

这些策略也适用于不受支持的环境。不再支持自定义处理程序函数。

## TypeScript自 `v11`

-   `Options.unsupported` 不再接受回调 `(node, tex, entry) => string` 用于自定义替换文本。使用 `ignore`， `keep`，或者 `throw`． 默认值保持不变 `keep`,匹配 `master`;传递任何其他值都会抛出 `TypeError` 在解析器设置期间。
-   新 `unsupported: 'throw'` 模式将不受支持的命令/环境错误传播到 `parse` (或拒绝 `parseAsync`)，而不是将它们添加到条目中 `errors` 和继续。
-   合并后的 `keywords` 现在保留相遇顺序和精确重复字符串。以前，删除完全重复的值，并对剩余值进行不区分大小写的排序。Case变体之前也没有重复数据删除。

# 从8.x迁移到9.0

-   移动 `sentenceCase.langids` 到顶层 `english` 选择。它仍然接受语言数组或布尔值；包括 `''` 在自定义数组中匹配带有no的项 `langid`.
-   移动 `sentenceCase.language` 到顶层 `languageAsLangid` 选择。它仍然控制是否 `language` 字段用作回退 `langid` 和 `hyphenation` 缺席。

这个 `Entry` 和 `ParseError` 形状，包括逐字解析器的条目形状，在8.0.23和9.0.0之间没有改变。默认情况下，绑定的非缩写仍然是启用的。

## 常见问题

### @retorquere/bibtex-parser 是什么？

助理型解析器

### 如何安装 @retorquere/bibtex-parser？

在项目目录运行 npm install @retorquere/bibtex-parser，或使用 pnpm add / yarn add / bun add。

### @retorquere/bibtex-parser 支持 TypeScript 吗？

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

### @retorquere/bibtex-parser 支持 ESM 还是 CommonJS？

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

### @retorquere/bibtex-parser 可以商用吗？

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

### @retorquere/bibtex-parser 还在维护吗？

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