# 引用与参考文献

查找来源，检查其元数据，把它添加到正确的参考文献库，在光标处引用，选择 Typst 引用样式，并在不丢失原件的情况下清理文库。

引用是一条链：论述指向一个键，键指向一条参考文献条目，条目指向一个真实的来源。Oleafly 让这条链始终可见，这样一次快速查找就不会在日后变成一条莫名其妙的参考文献。

![Oleafly 的“参考文献”面板。可在参考文献、引用和符号之间切换；用搜索框筛选当前视图。](https://cdn.oleafly.com/images/screenshots/desktop/docs/references-panel-dark-window-v2.png#view=0,45,344,703)

## 边写边引用

![“从项目引用”会打开参考文献选择器。可按键、作者或标题搜索；“查找并添加新引用”会打开在线查询。](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-citation-picker-dark-window-v2.png#view=415,77,365,467)

在 LaTeX 或 Typst 工具栏中选择**从项目引用**（`@` 图标）。按键、作者或标题搜索当前参考文献库，并选择一个条目。

你也可以从 ⌘K 或 Ctrl+K 命令面板运行**添加引用**。Oleafly 会插入适合当前项目的语法：

- LaTeX 中是 `\cite{key}`；
- Typst 中是 `@key`，如果主文档没有 `#bibliography(...)` 行，会在末尾添加一行；
- Markdown 中是 `[@key]`，需要时会在前置元数据中添加 `bibliography:` 行。

连接 Zotero 后，**添加引用**会先列出来自你的 Zotero 文库的匹配项。

## 从你的 Zotero 文库中引用

[连接 Zotero](/docs/integrations/research-sources/#zotero) 之后，输入 `@` 以及作者姓名的一部分、标题中的一个词、年份或键。你的整个 Zotero 文库就会与项目自己的参考文献一起显示。选择一篇论文，Oleafly 会按文档已有的引用方式插入引用。LaTeX 会得到文档用得最多的命令，例如 `\citep` 或 `\parencite`，Typst 得到 `@key`，Markdown 得到 `[@key]`。在已有的 `\cite{...}` 内输入 `@`，会向其中再添加一个键。

只有那一个条目会写入项目的 `.bib`，放在文件末尾，文件的其余部分保持原样。已在 `.bib` 中的论文，无论是按它的键还是按它的 DOI，都不会被重复添加。条目从不包含你电脑上 PDF 的路径。如果项目还没有参考文献行，Oleafly 会添加一行：LaTeX 中是 `\bibliography` 或 `\addbibresource`，Typst 中是 `#bibliography`，Markdown 前置元数据中是 `bibliography:`。如果有多个 `.bib` 文件，Oleafly 会询问一次新参考文献放进哪个文件，并记住你的回答。

第一次在手动用 `thebibliography` 环境列出参考文献的 LaTeX 论文中从 Zotero 引用时，Oleafly 会提议把这份列表移入 `.bib`。之后所有参考文献共用同一个编号列表。

### 让 .bib 与 Zotero 保持同步

如果某个被引用的键不在 `.bib` 中但在 Zotero 里，会提供**从 Zotero 添加**。从 ⌘K 面板运行**从 Zotero 添加缺失的引用**，可以一次检查所有被引用的键。它会添加 Zotero 中有的那些，列出没有的那些，并指出那些引用了你的参考文献中已有论文的键。

当一篇论文在 Zotero 中发生变化时，它在 `.bib` 中的条目会提供**从 Zotero 更新**。面板中的**从 Zotero 更新 .bib 条目**会审阅每一个发生变化的条目。你手动编辑过的条目，只有在你确认之后才会被替换。**同步 Zotero 库**会重新读取文库。Oleafly 绝不会自行从 `.bib` 中删除任何内容。

![粘贴论文标题的一部分，并把它的 BibTeX 条目保存到 refs.bib。](https://cdn.oleafly.com/images/gifs/desktop/add-citation.gif?v=2)

## 查找并添加新的参考文献

从选择器中选择**查找并添加新引用**。可以从下面任何一种开始：

- DOI，例如 `10.1145/3592979`；
- arXiv ID，例如 `1706.03762`；
- ISBN-10 或 ISBN-13；
- PubMed ID（PMID）；
- 包含上述某个标识符的 URL；
- 论文标题。

DOI、arXiv、ISBN 和 PubMed 查询使用它们的公开目录。标题搜索会返回可能的匹配项，附有作者、年份和发表场所，让你自己选择，而不是接受猜测。

检查返回的 BibTeX，然后选择**添加到 .bib 并引用**。Oleafly 会：

1. 在当前参考文献库中添加一个不冲突的键；
2. 当 DOI 已存在时复用已有条目；
3. 在当前光标处插入引用；
4. 立即刷新文件树和“参考文献”面板。

元数据是可编辑的。在它成为稿件的一部分之前，请先更正记录。

当文档声明了多个参考文献库时，对话框会显示一个**参考文献**菜单。条目会进入你选择的文件，Oleafly 会为该项目记住这个选择。

## Oleafly 如何选择参考文献库

LaTeX 项目遵循有效主文档中的声明：

- `biblatex` 使用 `\addbibresource{references.bib}`；
- BibTeX 工作流使用 `\bibliography{references}`。

路径的解析方式，与 TeX 工具链所期望的扩展名和相对路径行为一致。指向缺失文件的声明会在其源码行处报告，而不是悄悄写到别处。

Typst 项目遵循 `#bibliography(...)` 调用，无论它指定的是一个文件还是一个列表，也无论文件是 BibTeX `.bib` 还是 Hayagriva `.yml` 和 `.yaml`。新的引用会写入文档声明的文件。如果该文件是 Hayagriva，Oleafly 会在写入之前转换 BibTeX 条目。当调用指定了多个文件时，请在对话框的**参考文献**菜单中选择目标。

Markdown 项目遵循前置元数据中的 `bibliography:` 字段。

当没有声明任何参考文献库时，Oleafly 会使用项目中的第一个 `.bib`。如果不存在，它会创建 `references.bib`，并让它出现在文件树和引用选择器中。

对于有多个库的项目，请在添加记录之前检查所选的目标。

## 选择 Typst 引用样式

当 Typst 文档有 `#bibliography(...)` 调用时，“参考文献”面板的**引用**视图底部会显示一个**引用样式**菜单。它列出该项目的 Typst 版本内置的样式，以及项目中的所有 `.csl` 文件。选择一个样式会把它写入该调用的 `style:` 参数。没有设置时，Typst 使用 `ieee`。

对于 LaTeX，请在源码中设置样式。`\bibliographystyle{` 会补全常用的 BibTeX 样式；使用 `biblatex` 时，请用它的 `style=` 选项。

## 导入整个参考文献库

在“参考文献”面板中选择**导入参考文献库**。你可以导入文件，也可以导入你的 Zotero 文库。

**从文件**导入时，选择一个导出的库：

| 来源格式 | 文件 |
| --- | --- |
| BibTeX | `.bib` |
| RIS | `.ris` |
| EndNote XML | `.xml` |
| Zotero RDF | `.rdf` |

**从 Zotero** 导入时，先在**设置 → 集成 → Zotero** 中连接一次你的 zotero.org 账户，然后在 Zotero 卡片上选择**导入 Zotero 库**。Oleafly 最多导入 5,000 个条目。[连接研究来源](/docs/integrations/research-sources/#zotero)会带你完成设置。

Oleafly 会把这些记录映射为 BibTeX，并跳过 DOI 已在目标库中或已在同一批较早位置出现的参考文献。它会创建不冲突的键，并一次写入追加结果。消息会说明添加了多少条参考文献，以及已有多少条。导入文库不会在光标处插入引用。

导入之后，在引用选择器中搜索新条目，并对照原始目录核对一个样本。

## 清理参考文献库

“参考文献”面板可以在更改文件之前预览清理结果。

1. 打开项目，在“参考文献”面板中选择**清理参考文献库**。
2. 当项目有多个 `.bib` 文件时，选择其中一个。
3. 阅读操作列表和前后对比差异。
4. 检查每一项建议的键重命名、移除的 DOI 重复项和提示。
5. 只有在预览符合你的意图之后才应用。

清理器会把键重命名为统一的“作者-年份-标题”模式，并更新整个项目源文件中的引用。只有当保留的条目保留了被移除条目的每个字段时，它才会移除 DOI 重复项。互相冲突的 DOI 记录和相似的标题会被标记出来供审阅，而不是凭猜测合并。

注释和 BibTeX 字符串定义会被保留。应用时会检查库是否仍与预览一致，并在更改文件之前写入备份。较大的差异在预览中显示前 500 行；应用更改时仍使用完整的文件。

:::caution[应用前检查]
两个版次、译本、预印本和期刊版本，或标题相似的论文，可能本来就是各自独立的。在手动合并任何内容之前，请阅读提示并比较实际的来源。
:::

## 补全并浏览参考文献

在 `\cite{}`、`\citep{}`、`\citet{}`、`\parencite{}` 和 `\textcite{}` 等 LaTeX 引用命令内，自动补全会搜索项目中的每个 `.bib` 文件。在 Typst 中，`@` 会补全来自 `.bib` 和 Hayagriva 文件的键。连接 Zotero 后，列表中也会包括你的 Zotero 文库。

如果某条引用指向的条目是在该 `.bib` 未打开时添加的，例如由助手添加或来自 Zotero，它会立即解析，你不必先在文档中输入内容。

- F12 或按住修饰键点击，从引用键跳转到它的条目。
- ⇧F12 列出某个来源的所有用法。
- F2 在源文件和参考文献文件中重命名一个键。
- 悬停会显示目标；未解析或有歧义的键会在编译之前被标出。

[代码智能](/docs/code-intelligence/)介绍了完整的导航模型。

## 引用 Oleafly

如果 Oleafly 帮助了一篇论文，请从命令面板，或从“参考文献”面板**引用**视图的底部，运行**在本文中引用 Oleafly**。Oleafly 会向文档声明的参考文献库添加一个键为 `oleafly` 的条目，使用 BibTeX 格式，对于 Hayagriva 文件则使用 Hayagriva 格式。一条消息会指出文件和要使用的语法，例如 `\cite{oleafly}` 或 `@oleafly`，旁边有**撤销**。如果条目已经存在，你会收到一个关于该键的提醒。

没有参考文献文件的项目不会被更改，而是会弹出一个显示该条目的对话框供你复制。同一条目始终可以在[设置 → 帮助与关于](/docs/settings/help/#cite-oleafly-in-a-paper)中找到。

## 参考文献构建与 Biber

对于 `biblatex`，当编译器没有生成可用的 `.bbl` 时，Oleafly 会重新运行与之匹配的 Biber 步骤。Biber 的消息，包括缺失 `.bib` 路径的消息，会出现在编译日志和编辑器诊断中。

当 Biber 本身失败时，编译日志会说明原因。它会指出缺少的系统库，并建议用 `\usepackage[backend=bibtex]{biblatex}` 在不使用 Biber 的情况下构建。在 Fedora 上，Oleafly 的 `.rpm` 会推荐安装 Biber 所需的两个库。

如果参考文献仍未定义：

1. 检查参考文献声明和路径。
2. 打开**日志**，找到第一条 Biber 或参考文献消息。
3. 确认该引用键恰好存在一次。
4. 在 `.bib` 文件保存后重新编译。

有关各引擎的恢复方法，请参阅[编译与日志](/docs/compiling/)和 [LaTeX 引擎与宏包](/docs/latex-engines/)。

## 独立的参考文献工具

不打开项目也可以准备参考文献：

- [引用生成器](/docs/tools/citation-generator/)接受标识符、标题、结构化字段或 BibTeX。
- [参考文献生成器](/docs/tools/bibliography-generator/)构建并验证列表。
- [按样式分类的引用生成器](/docs/tools/citation-styles/)比较八种样式。
- 专门的工具处理 [DOI](/docs/tools/doi-to-bibtex/)、[ISBN](/docs/tools/isbn-to-bibtex/)、[PubMed ID](/docs/tools/pubmed-to-bibtex/)、[arXiv](/docs/tools/arxiv-citation-generator/) 和[网址](/docs/tools/url-to-bibtex/)。

手动编辑和引用格式化都在本地进行。标识符和标题查询需要联网。[离线模式](/docs/settings/general/#offline-mode)会阻止这些查询，而已有的参考文献补全和导航继续可用。

## 找到证据，然后核实

[查找引用](/docs/tools/find-citations/)会搜索学术索引，或扫描打开的草稿，找出可能需要支持的段落。引用一篇论文之前请先阅读它，并让每条论述保持在其方法和结果所能证明的范围内。
