嵌入其它文件

Quarto 1.4 Feature

This feature is new in Quarto 1.4. Download the latest version of Quarto at https://quarto.org/docs/download/.

Overview|概述

可以使用 embed 快捷代码包含另一个 Quarto 文档（.qmd 或 .ipynb）的输出。要嵌入代码块或notebook单元格的输出，请提供文档路径以及代码块或单元格的标识符。例如，这个名为 penguins.ipynb 的 Jupyter notebook就有一个标有 fig-bill-scatter 的单元格：

A screenshot of a Jupyter Notebook with the name 'penguins.ipynb', with a cell highlighted that has the code chunk option label set to fig-bill-scatter. Below the cell is the resulting plot.

您可以使用以下简码嵌入该单元格的输出：

{{< embed penguins.ipynb#fig-bill-scatter >}}

嵌入如下图所示：

图 1: A scatterplot of bill dimensions for penguins, made with Altair.
记事本: Palmer Penguins (.ipynb)

绘图下方会自动提供指向源notebook的链接。点击链接后，用户将进入notebook的渲染版本，无需下载并在本地运行，即可浏览notebook。例如，点击 “penguins.ipynb”的链接会进入如下页面：

A screenshot of webpage with the title 'penguins.ipynb', a large blue button labelled 'Download Notebook', followed by the notebook contents.

你可以将输出嵌入 Jupyter Notebooks (.ipynb) 和 Quarto 文档 (.qmd)。在本文中，我们将源文件统称为 Notebooks。

除了这些基本用法外，您还可以

Specifying Cells|指定单元

embed简短代码使用单元格或代码块标识符（如 penguins.ipynb#fig-bill-scatter）后的相对路径指定源notebooks。如果省略标识符，notebooks中的所有单元格或代码块都将嵌入文档。

Quarto Documents|Quarto文档

如果源文件是 Quarto 文档 (.qmd)，则使用代码块的 “标签”作为标识符。例如，如果源文件 penguins.qmd 包含以下代码块：

penguins.qmd
```{r}
#| label: fig-size-scatter
ggplot(penguins, aes(body_mass_g, flipper_length_mm)) +
  geom_point(aes(color = species)) +
  scale_color_manual(values = colors) +
  theme_minimal()
```

用以下方式嵌入程序块的输出：

{{< embed penguins.qmd#fig-size-scatter >}}

结果输出如下:

记事本: Palmer Penguins (.qmd)

Jupyter Notebooks

当数据源是 Jupyter Notebook 时，用于定位适当的单元格的标识符会遵循这些启发式方法：

  1. ** CellID***
    首先，将检查单元格元数据中是否有匹配的 id。单元格 ID是 Jupyter Notebook 的一项较新功能，Jupyter 前端还不能很好地支持该功能，但 id 会首先被检查，以便在将来更常见时实现兼容性）。
  2. Label   | Label标签 如果找不到与 id 匹配的单元格，Quarto 将使用代码元数据中有与单元格标识符匹配的 label 的单元格。
  3. Tags | Tag标签 如果没有找到单元格，Quarto 将使用标签与单元格标识符匹配的一个或多个单元格。

Cell Tags|单元格 Tags

例如，要在 Jupyter Lab 中嵌入您赋予标签 bill-ratio 的单元格的输出，请执行以下操作

Screenshot of a code cell in a Jupyter Notebook with the cell tags open in the cell toolbar and displaying the tag 'bill-ratio'.

可以使用以下嵌入代码：

{{< embed penguins.ipynb#bill-ratio >}}

结果输出如下:

A density plot of bill ratio by species.

Code Cell Options|单元格选项

源notebook中的代码单元选项会传播到嵌入它们的文档中。例如，您可以指定 fig-cap, fig-alt and layout-ncol,等代码单元选项，以控制嵌入数字的各个方面。例如，penguins.ipynb 中的这个单元格指定了数字选项，包括标题、副标题、alt 文本和布局：

penguins.ipynb
#| label: fig-bill-marginal
#| fig-cap: "Marginal distributions of bill dimensions"
#| fig-subcap: 
#|   - "Gentoo penguins tend to have thinner bills,"
#|   - "and Adelie penguins tend to have shorter bills."
#| fig-alt:
#|   - "Density plot of bill depth by species."
#|   - "Density plot of bill length by species."
#| layout-ncol: 2

sns.displot(penguins, 
            x = "bill_depth_mm", 
            hue = "species", 
            kind = "kde", fill = True, aspect = 2, height = 3)
plt.show()
sns.displot(penguins, 
            x = "bill_length_mm", 
            hue = "species", 
            kind = "kde", fill = True, aspect = 2, height = 3)
plt.show()

该单元格嵌入时：

{{< embed penguins.ipynb#fig-bill-marginal >}}

结果输出如下:

Density plot of bill depth by species.
(a) Gentoo penguins tend to have thinner bills,
Density plot of bill length by species.
(b) and Adelie penguins tend to have shorter bills.
图 3: Marginal distributions of bill dimensions

Embedding Code|代码嵌入

您可以通过使用 embed shortcode 的 echo=true 选项，将单元格或块中的代码与输出结果一起嵌入。例如，若要包含来自 penguins.ipynb 中标有 species-counts 的单元格的代码和绘图，嵌入代码应为：

{{< embed penguins.ipynb#species-counts echo=true >}}

文档中的结果既是单元格的代码，也是单元格的输出：

penguins.groupby("species").size().reset_index(name = "count")
species count
0 Adelie 152
1 Chinstrap 68
2 Gentoo 124

与图表选项一样，显示代码的选项也会从源代码notebook.中传入。例如，要折叠该单元格的代码，可以在 species-counts 单元格的选项中添加 code-fold: true ：

penguins.ipynb
#| label: species-counts
#| code-fold: true
penguins.groupby("species").size().reset_index(name = "count")

在嵌入这些单元格的文档的 YAML 标头中设置的选项也将控制这些代码单元格。例如，要折叠所有代码，包括从 penguins.ipynb 嵌入的代码，可以在文档 YAML 中添加 code-fold: true：

sample.qmd
title: Exploration of penguin characteristics
author: Norah Jones
toc: true
format:
  html:
    code-fold: true

Linked source notebooks|链接到源Notebooks

在 Quarto 文档中嵌入笔记本内容并将文档渲染为 HTML 时，Quarto 会自动包含指向提供嵌入内容的源notebooks的链接。默认情况下，这些链接将同时出现在嵌入内容的内嵌内容下方和目录下方。例如，以下文档嵌入了来自notebook penguins.ipynb 的内容。你可以在下面渲染的 HTML 文档中看到这些链接：

Screenshot of a rendered page with an embedded plot. A link to the Source 'penguins.ipynb' is shown directly below the plot. A similar link is shown below the table of contents under the heading 'Notebooks'.

Notebook Views|Notebook 视图

默认情况下，指向源notebook的链接会跳转到自动生成的notebook HTML 渲染窗口。这样，用户就可以更方便地查看notebook内容，而无需下载notebook并在本地运行。该notebook视图显示笔记本内容，并包含一个下载notebook的按钮。例如：

A screenshot of webpage with the title 'penguins.ipynb', a large blue button labelled 'Download Notebook', followed by the notebook contents.

例如，您可以查看本文档中使用的 penguins.ipynb notebook 和 penguins.qmd notebook 的实时预览。

View Options|视图选项

可以使用 notebook-view 来控制笔记本视图的行为。你可以为每个源notebook提供一个 title 和一个 url 。标题 “将用作指向源notebook的任何链接的文本，也将出现在渲染的notebook视图的顶部。url”（如果提供）将用作指向源notebook链接的 “href”。如果您已将源notebook的副本部署到 Github、Google Colab 或 Kaggle 等网站，并希望链接到该网站，这将非常有用。

例如：

notebook-view:
  - notebook: penguins.ipynb
    title: "Plots and Computations"
    url: https://colab.research.google.com/drive/12GsIPQ644SI4vkEEHiZn-Qqfbr-bD1__

将产生指向源笔记本的链接，如图所示：

Screenshot of a rendered page with an embedded plot. A link to the Source 'Plots and Computations' is shown directly below the plot. A similar link is shown below the table of contents under the heading 'Notebooks'.

T要禁用notebook视图并直接链接到notebook（这样用户就可以下载notebook而无需中间视图），请将 notebook-view 设置为 false。