VS Code

概述

Quarto 可以渲染表示为纯文本（.qmd）或普通笔记本文件（.ipynb）的 Jupyter 笔记本。Quarto VS Code 扩展包含许多增强这些文档工作的工具，包括：

  • Quarto 文档的集成渲染和预览。
  • Markdown 和嵌入语言的语法高亮。
  • YAML 选项的补全和诊断。
  • 嵌入语言（如 Python、R、Julia 等）的补全。
  • 运行单元格和选中行的命令和快捷键。
  • LaTeX 数学公式以及 Mermaid 和 Graphviz 图表的实时预览。

Quarto 扩展直接与 Jupyter、R 和 Julia 扩展集成。例如，这里 Quarto 扩展运行一个 Python 单元格并显示 Python 函数的上下文帮助：

VS Code 编辑器的屏幕截图，分为三个垂直部分。最左边包括文件资源管理器和 Quarto 帮助。第二个窗格是包含 Python 代码的 Quarto 文件的源代码。第三个是交互式的，显示 Python 运行和代码单元格的输出。

你可以从 VS Code 扩展市场 或 Open VSX 注册表 安装 Quarto 扩展。

VS Code 编辑器

根据你的偏好和当前任务，你可以使用 VS Code 中的三种不同编辑器来编写 Quarto 渲染的文档：

  1. 用于以文本形式编辑 .qmd 文档的源代码编辑器。

  2. 用于 .qmd 文档所见即所得编辑的 可视化编辑器。

  3. 用于编辑 .ipynb 笔记本的 笔记本编辑器。

我们将在下面介绍源代码编辑器，但你可能还想在你熟悉了基础知识后查阅 可视化编辑器 或 笔记本编辑器 的文档。

渲染和预览

Quarto VS Code 扩展包含渲染 Quarto 文档（无论是独立的还是在网站或书籍中）的命令和键盘快捷键。渲染后，quarto preview 在幕后使用，以在 VS Code 中提供一个预览窗格，与你的文档并排显示：

两个窗口并排排列。左边的窗口是一个在 VSCode 中打开的 qmd 文件。该文档的内容与本网站的入门：欢迎部分的第一部分相同。该文档的内容由 Quarto 在右边的窗口中渲染。

要渲染和预览，执行 Quarto: 预览 命令。你也可以使用 Ctrl+Shift+K 键盘快捷键，或者编辑器右上角的 预览 按钮（预览图标）：

Visual Studio 代码编辑器的顶部。编辑器标签区域的右侧包含一个预览按钮。

注意，在 Mac 上，你应该使用 Cmd 而不是 Ctrl 作为所有 Quarto 键盘快捷键的前缀。

其他格式

Quarto: 预览 命令渲染当前活动文档的默认格式。如果你想预览其他格式，使用 Quarto: 预览格式 命令：

Visual Studio 代码编辑器的顶部。编辑器标题菜单已展开，菜单中提供了预览格式命令。

当你执行 预览格式 时，你会看到一个格式选择列表（文档中声明的任何格式以及一些标准格式，如 PDF 和 MS Word）：

Visual Studio 代码编辑器的顶部。命令面板显示了一个可预览格式的快速选择列表。

预览不同格式后，Quarto: 预览 命令和 Ctrl+Shift+K 键盘快捷键将自动重新绑定到新选择的格式，直到当前预览结束。要切换回预览原始格式，请再次使用 Quarto: 预览格式 命令。

嵌入式预览目前支持基于 HTML 和 PDF 的格式（包括 revealjs 和 beamer 幻灯片）。然而，对于 Word 和其他格式，你需要使用适当的外部程序来预览输出。

渲染命令

Quarto: 预览命令是你在撰写文档时最常用的命令。如果你只有一种格式（例如HTML或PDF），那么预览也会渲染你的文档，这样一旦你对输出满意，它就可以立即分发。然而，如果你有多种格式，你需要明确地渲染它们（因为预览一次只能渲染一种格式）。你可以使用Quarto: 渲染文档命令来完成这个操作：

Visual Studio Code编辑器的顶部。命令面板显示了一个快速选择列表，列出了可渲染的格式。

如果你声明了多种格式，你可以渲染所有格式。你也可以选择性地渲染任何声明的格式或其他标准格式，如PDF和MS Word。

保存时渲染

默认情况下，Quarto不会在你保存.qmd或.ipynb文件时自动渲染它们。这是因为渲染可能非常耗时（例如，它可能包括长时间运行的计算），并且最好能够在不进行完整渲染的情况下定期保存。

然而，你可以配置Quarto扩展，使其在你每次保存时自动渲染。你可以在VS Code设置中或在你的项目或文档的YAML选项中进行此配置。要配置VS Code设置，请在设置中搜索quarto.render，你会找到保存时渲染选项：

Visual Studio Code Quarto渲染设置。保存时渲染选项已勾选。

你可能还希望在每个文档或每个项目的基础上控制此行为。如果你在文档或项目的YAML中包含editor: render-on-save选项，它将覆盖你的VS Code设置。例如：

editor:
  render-on-save: true

外部预览

如果你更喜欢使用外部浏览器进行预览（或者渲染时根本不触发预览），你可以使用预览类型选项来指定替代行为：

VS Code设置界面，搜索栏中输入了'quarto preview type'。用户设置显示了Quarto > 渲染: 预览类型，有一个下拉菜单可以选择渲染后文档预览的位置。默认的内部选项已选中，使用VS Code中的并排面板进行预览。下拉菜单中的其他两个选项是外部和无。

代码单元格

有多种工具可以使编辑和执行代码单元格变得更加容易。编辑工具包括语法高亮、代码折叠、代码补全和签名提示：

VS Code中的一个Quarto文档，包含一个python代码单元格。python单元格中有一个代码补全助手处于活动状态。

对于Python、R和Julia单元格，可以使用命令来执行当前单元格、之前的单元格或当前选中的行。单元格输出会在Jupyter交互式控制台中并排显示：

VS Code中打开了两个窗格，右侧是vscode.qmd源代码，左侧是该代码的交互式输出。

以下是所有可用于执行单元格的命令和键盘快捷键：

Quarto 命令 键盘快捷键
运行当前单元格 ⇧⌘ Enter
运行选中的行 ⌘ Enter
运行下一个单元格 ⌥⌘ N
运行上一个单元格 ⌥⌘ P
运行所有单元格 ⌥⌘ R
运行上方所有单元格 ⇧⌥⌘ P
运行下方所有单元格 ⇧⌥⌘ N

你可以使用Ctrl+Shift+I键盘快捷键快速插入一个新的代码单元格。

通过安装这些扩展的最新版本，可以启用嵌入语言的增强功能（例如补全、代码执行）：

执行目录

嵌入语言扩展以不同的方式处理执行的工作目录：

  1. Python扩展在执行代码的源文件的目录中运行代码。你可以使用jupyter.notebookFileRoot选项自定义此行为。

  2. R扩展在R交互式终端中运行的R会话的工作目录中运行代码。你可以使用setwd()手动更改此目录。

  3. Julia扩展在Julia REPL终端中运行的Julia会话的工作目录中运行代码。你可以使用cd()手动更改此目录。 ## 上下文帮助

执行 Quarto: 显示帮助面板 命令，在侧边栏显示一个面板，根据当前光标位置显示上下文帮助：

  1. 编辑代码时显示帮助/文档
  2. 编辑 LaTeX 数学公式时显示实时预览
  3. 光标位于 Markdown 图片上时显示缩略图预览

例如，当光标位于 matplotlib 的 plot() 函数上时，会自动显示该函数的帮助信息：

VS Code 编辑器的截图，分为三个垂直部分。最左边包括文件资源管理器和 Quarto 帮助。第二个窗格是包含 Python 代码的 Quarto 文件的源代码。第三个窗格是交互式的，显示正在运行的 Python 和代码单元的输出。

实时预览

在编辑 LaTeX 数学公式或 Mermaid 和 Graphviz 图表时，点击代码上方的 预览 按钮（或使用 Ctrl+Shift+L 快捷键）打开一个实时预览，该预览会随着你的编辑自动更新。

这里我们看到当前编辑的 LaTeX 方程在 Quarto 帮助面板中显示的预览：

在 VS Code 中打开的 Quarto 文档，左侧面板的 'Quarto Equation' 部分显示了 LaTeX 方程。

这里我们看到 Graphviz 图表预览在我们编辑时自动更新：

在 Visual Studio Code 中编辑的 Quarto 文档，右侧窗格显示当前编辑图表的实时预览。

YAML 智能提示

项目文件、YAML 前言和可执行单元选项的 YAML 代码补全功能可用：

正在编辑的 Quarto 文档，包含 YAML。光标旁边的代码补全助手显示以光标前字母（'co'）开头的 YAML 选项。

如果 YAML 有错误，文档保存时也会被高亮显示：

Quarto 文档的 YAML 元数据，错误的选项被红色下划线标出。

代码片段

代码片段是模板，便于输入重复的代码模式（例如代码块、标注、div 等）。在 Quarto 文档中执行 插入片段 命令以插入 Markdown 片段：

Quarto 文档，显示 '选择一个片段' 下拉菜单，第一个项目（加粗 - 插入加粗文本）被选中。

IntelliSense

VSCode 使用 IntelliSense 在输入时建议代码片段或特定函数的可用值。默认情况下，代码片段的建议是关闭的，但值的建议是开启的。要在输入时或在选择文本片段并按下 ctrl+space 时启用代码片段的 IntelliSense 建议，需要将设置 editor.snippetSuggestions 设置为非 none 的值（例如 inline）。

  • 按 F1 并搜索 Preferences: Open Settings (UI) 或 File > Preferences > Settings
  • 搜索以下术语 @lang:quarto editor.snippetSuggestions。Editor: Snippet Suggestions 应该会出现。
  • 将值更改为非 none 的值。

文档导航

如果你有一个大型文档，使用大纲视图可以快速在各部分之间导航：

Quarto 文档，左侧面板显示大纲视图。大纲显示了 Quarto 文档的章节标题。

你也可以使用 在编辑器中转到符号 命令或快捷键 Ctrl+Shift+O 进行当前文档大纲的类型前导航。

使用 转到文件 命令 Ctrl+P 导航到其他文件，使用 在工作区中转到符号 命令 Ctrl+T 进行工作区中所有标题的类型前导航：

VS Code 中的 Quarto 文档，命令面板打开，显示项目中的文件，输入的术语为 'margin'。

了解更多

除了上述传统的源代码编辑器外，你还可以根据个人偏好和当前任务使用以下其他编辑器之一：

  1. 可视化编辑器 用于 WYSIWYG 编辑 .qmd 文档。

  2. Notebook 编辑器 用于编辑 .ipynb 笔记本。