RStudio IDE

概述

RStudio v2022.07 及更高版本支持编辑和预览 Quarto 文档(以下文档假设您使用的是此版本或更高版本)。

如果您在 RStudio 中使用 Quarto,强烈建议您使用 最新版本 的 RStudio(v2023.12)。

您可以从 https://posit.co/download/rstudio-desktop/ 下载 RStudio v2023.12。

创建文档

使用 文件 : 新建文件 : Quarto 文档… 命令创建新的 Quarto 文档:

RStudio 中的 '新建 Quarto 文档' 对话框菜单。

渲染和预览

使用 渲染 按钮在编辑时预览文档:

RStudio 中显示的 qmd 文件顶部部分。文档上方有一个工具栏,包含各种选项,包括 '渲染'。有一个分段的蓝色箭头指向该词。

如果您希望在保存时自动渲染,可以在编辑器工具栏中勾选 保存时渲染 选项。

预览将显示在编辑器旁边:

一个 RStudio 窗口。页面左侧是 Quarto 文档和打开的 '任务' 窗格。'任务' 窗格中有绿色文本的消息:'正在监视文件更改。浏览地址为 http://localhost:4064'。窗口右侧是左侧文档的 Quarto 输出,由 Knitr 渲染。

每当您重新渲染文档时,预览都会更新。并排预览适用于 HTML 和 PDF 输出。

项目

如果您想为 Quarto 文档或一组文档创建一个新项目,请使用 文件 : 新建项目… 命令,指定 新建目录,然后选择 Quarto 项目

RStudio 的 '新建项目向导' 菜单的一部分。此部分标题为 '创建 Quarto 项目'。左侧显示 Quarto 标志。右侧有 '类型'、'目录名称' 和 '将项目创建为子目录:' 的字段。下面有 '引擎'、'创建 git 仓库' 和 '使用 renv 与此项目' 的选项。'引擎' 选项设置为 'Knitr'。窗口右下角有并排的 '创建项目' 和 '取消' 按钮。左上角有一个 '在新会话中打开' 的选项。

您可以使用此界面创建普通项目以及 网站书籍。还提供了创建 git 仓库并为项目初始化 renv 环境的选项。

可视化编辑器

RStudio IDE 包含一个用于 Quarto Markdown 的可视化编辑器,支持表格、引用、交叉引用、脚注、div/span、定义列表、属性、原始 HTML/TeX 等功能:

在 RStudio 可视化编辑器中打开的 RMarkdown 文件。页面标题为 'Filter joins'。下方是一个包含 R 语法、数学符号和半连接与反连接定义的表格。在此表格下方是一个显示半连接图形表示的 R 代码块。

要了解更多信息,请参阅关于 使用可视化编辑器 的文档。

Knitr 引擎

Quarto 设计为与现有的 R Markdown 文档高度兼容。通常情况下,您应该能够使用 Quarto 渲染任何现有的 Rmd 文档而无需更改。

R Markdown文档与Quarto文档之间的一个重要区别在于,在Quarto中,代码块选项通常包含在代码块顶部的特殊注释中,而不是在开始代码块的那一行内。例如:

```{r}
#| echo: false
#| fig-cap: "Air Quality"

library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess", se = FALSE)
```

Quarto采用这种方法,既可以更好地适应像fig-capfig-subcapfig-alt这样的较长选项,也使得在不具备便捷编辑代码块元数据功能的更结构化的编辑器中(例如大多数传统笔记本用户界面),编辑代码块选项变得简单明了。

Note

请注意,如果你愿意,仍然可以在第一行包含代码块选项(例如```{r, echo = FALSE})。尽管如此,我们建议使用基于注释的语法,以使文档在不同执行引擎之间更具可移植性和一致性。

以这种方式包含的代码块选项使用YAML语法而不是R语法,以与YAML前置内容中提供的选项保持一致。然而,你仍然可以通过在选项值前加上!expr来使用R代码。例如:

#| fig-cap: !expr 'paste("Air", "Quality")'
Caution

!expr语法是YAML“标签”字面量的一个示例,可能不太直观。!expr后面需要跟随一个_单一的YAML“流标量”_:有关双引号、单引号和无引号字符串的工作原理,请参阅YAML规范

Jupyter 引擎

您还可以在 RStudio 中处理以 Jupyter 引擎为目标的 Quarto Markdown 文档。这些文件通常会在 YAML 前文中包含一个 jupyter 选项,指示要使用的内核。例如:

---
title: "Matplotlib 演示"
author: "Norah Smith"
jupyter: python3
---

如果您想在虚拟环境中工作(venv),请使用 文件 : 新建项目… 命令,指定 Jupyter 引擎并使用 venv,并指定您希望用哪些包来初始化 venv:

RStudio 的 '新建项目向导' 菜单的一部分。此部分标题为 '创建 Quarto 项目'。左侧显示 Quarto 标志。右侧有 '类型'、'目录名称' 和 '创建项目为子目录:' 的字段。下方有 '引擎' 和 '内核' 的选项。'引擎' 选项设置为 'Jupyter','内核' 选项设置为 'Python 3'。下方有 '创建 git 仓库' 和 '使用 venv 与此项目' 的选项。'使用 venv...' 按钮被选中,右侧有一个文本框,其中填写了 Python 包名称 'matplotlib' 和 'pandas'。窗口右下角并排排列着 '创建项目' 和 '取消' 按钮。左上角有一个 '在新会话中打开' 的选项。

每当您打开项目时,RStudio 都会自动激活此虚拟环境。您可以使用 RStudio 的 终端 选项卡将其他 Python 包安装到环境中。例如:

一个 RStudio 终端窗口。提示前缀为 '(env)',表示此提示发生在名为 'env' 的 Python 虚拟环境中。第一行为空,第二行包含命令 'python3 -m pip install scikit-learn'。

YAML 智能

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

正在编辑的 Quarto 文档,带有 YAML。光标旁边的代码补全助手打开,显示以光标前字母('to')开头的 YAML 选项。

如果 YAML 有误,文档保存时也会被高亮显示:

带有错误选项的 Quarto 文档 YAML 元数据,错误选项下方有红色下划线。

R 包

如果您不使用 RStudio 或更喜欢从 R 控制台渲染,可以使用 quarto R 包来实现。要安装 R 包:

install.packages("quarto")

然后,要渲染文档:

library(quarto)
quarto_render("document.qmd")

要渲染网站(即:组织为网站的目录中的所有 qmd):

library(quarto)
quarto_render()

要实时预览(自动渲染并在保存时刷新浏览器)您正在处理的文档,请使用 quarto_preview() 函数:

library(quarto)
quarto_preview("document.qmd")

如果您正在处理 网站书籍 项目,您也可以在项目目录上使用 quarto_preview()

library(quarto)
quarto_preview()