文档列表
概述
列表功能使你能够根据Quarto文档或自定义数据列表自动生成页面（或页面的一部分）的内容。
列表功能适用于创建博客、为大量文档提供导航，或者在希望页面内容随着文档的添加、更新和删除自动更新的任何其他场景中使用。
你可以在文档的前置部分使用listing选项来启用列表功能。这将指示Quarto在渲染页面时生成额外的内容（即“列表”）。例如，文档前置部分的以下YAML：
---
title: "列表示例"
listing: default
---将生成目录中所有文档的列表（当前文档除外）。它可能看起来像这样：
列表内容
你可以通过使用contents选项来控制哪些文档包含在列表中，该选项允许你提供一组输入文件（或输入文件的通配符），这些文件应包含在列表中。对于每个与列表的contents匹配的输入，将使用文档前置部分的元数据包含一个项目。
要使项目出现在列表中，它必须至少包含“title”元数据。
例如，要包括posts目录中的所有Quarto文档，你可以这样写：
---
title: "列表示例"
listing:
contents: posts
---你可以通过使用通配符并在内容中使用目标列表来编写更复杂的内容包含规则，例如：
---
title: "列表示例"
listing:
contents:
- "reports/*.qmd"
- "lab-notes/*reports.qmd"查看Quarto通配符参考以获取有关支持的通配符语法的更多信息。
如果你提供了一个目录的路径，它将被视为<目录>/** - 该目录将被递归搜索以查找项目输入。
需要注意的是，当提供目标列表时，这些目标将根据列表页面的位置进行识别，而不是项目文件的根目录。例如，如果你的列表页面位于/pages/listings.qmd，指定contents: "reports/*.qmd"将在/pages/reports/而不是/reports/中搜索目标文件。
除了指定文件列表或通配符外，内容还可以包含元数据列表。有关更多信息，请参阅自定义列表。
列表类型
有三种内置的列表类型可供选择。使用type选项来选择列表的外观：
---
listing:
contents: posts
type: default
---类型字段接受以下值：
| 类型 | 描述 |
|---|---|
default |
博客风格的条目列表。 |
table |
列表的表格形式。 |
grid |
列表卡片的网格形式。 |
默认情况下，列表将以全宽行的形式显示项目的元数据（作者和日期）、标题、描述和图像。
网格风格的列表为每个项目显示一张卡片。
表格列表风格提供了传统的表格布局。
默认情况下，从文档创建的列表将按标题排序。使用 sort 选项来控制列表的顺序。例如：
listing:
contents: posts
sort: "date"每个 sort 键可以包含一个字段名称，并可选地包含 asc 或 desc 来控制是按升序还是降序排序。当仅指定名称时，该字段的排序将按升序进行。
排序键还可以包含一个或多个字段进行排序。例如：
listing:
contents: posts
sort:
- "date"
- "title desc"这将首先按日期升序对 posts 目录中的文档进行排序，然后按标题降序排序。
如果你希望完全禁用排序并按指定顺序显示项目，可以传递 sort: false（这将禁用排序并保留项目的原始顺序）。
列表选项
可以使用以下选项来自定义每种列表显示的外观。
默认
| 选项 | 描述 |
|---|---|
max-items |
此列表中包含的最大项目数量。 |
image-align |
是否将图像放置在帖子内容的右侧或左侧。默认为 right。 | |
image-height |
显示的图像高度。宽度会自动确定，图像将填充矩形而不进行缩放（即裁剪以填充）。 | |
image-placeholder |
如果项目没有图像，则使用的默认图像。 |
网格
| 选项 | 描述 |
|---|---|
max-items |
此列表中包含的最大项目数量。 |
image-height |
显示的图像高度。宽度会自动确定，图像将填充矩形而不进行缩放（即裁剪以填充）。 | |
image-placeholder |
如果项目没有图像，则使用的默认图像。 |
grid-columns |
网格显示中的列数。默认为 3。 |
grid-item-border |
是否在项目卡片周围显示边框。默认为 true。 | |
grid-item-align |
卡片内内容的对其方式（left, right, 或 center）。默认为 left。 | |
表格
| 选项 | 描述 | |
|---|---|
max-items |
此列表中包含的最大项目数。 | |
image-height |
显示的图像的高度。图像的宽度会自动选择，图像将填满矩形而不进行缩放（即裁剪以填充）。 | |
image-placeholder |
如果项目没有图像，则使用的默认图像。 | |
table-striped |
以交替的背景颜色显示表格行（true 或 false）。默认为 false | |
table-hover |
当用户将鼠标悬停在表格行上时突出显示它们（true 或 false）。默认为 false。 | |
field-links |
应链接到表格中文档的字段列表（默认为 title）。 | |
高级选项
选项
|
描述 | ==================================================================================================================================================================================================================================+ 提供特定字段的显示名称的映射。例如，要在表格列表中将标题列显示为“报告”，您可以这样写： | | yaml | listing: | field-display-names: | title: "报告" | | |
image-lazy-loading |
当设置为 true 时，列表中的图片仅在进入视图时加载。当设置为 false 时，图片会自动加载。默认值：true | |
max-description-length |
列表中显示的描述的最大长度（以字符为单位）。默认值为 175。 | |
date-format |
显示日期时使用的日期格式（例如 d-M-yyyy）。 | | 您可以提供日期样式（full、long、medium、short 或 iso）或用于格式化日期的格式字符串。 | 日期样式的行为因语言环境而异，但在 en 语言环境中，示例如下： | | 完整 | | : 2022年2月5日，星期六 | | 长格式 | : 2022年2月5日 | | 中等格式 | : 2022年2月5日 | | 短格式 | | : 2/5/22 | | ISO格式 | : 2022-05-22 | | 了解更多关于支持的日期格式化值 在此。 | |
除了上述适用于所有列表的全局选项外，每种列表类型还有多种选项可用于自定义其外观。
分类
除了显示列表内容外，列表还可以自动在它们出现的页面上添加一个分类列表。要启用分类，您可以设置 categories 选项，如下所示：
listing:
categories: true这将导致类别出现在右侧边栏：
当用户点击一个类别时，页面将更新以仅显示与所选类别匹配的列表项目。
类别外观
你可以选择几种不同的类别显示样式：
| 选项 | 描述 |
|---|---|
numbered |
按字母顺序显示类别列表，并在类别名称旁边显示该类别中的项目数量。 | |
unnumbered |
按字母顺序显示类别列表。 |
cloud |
显示类别的“词云”。 |
当页面显示多个列表时，类别将基于第一个列表中设置的选项启用。如果为第一个列表启用了类别，则页面上的所有列表都将贡献其项目类别到类别列表，并且当用户点击类别时，所有列表都将被过滤。
订阅源
你还可以根据列表内容生成一个RSS订阅源。这对于让你的内容被分发或在RSS阅读器中访问非常有用。通过包含feed选项来为你的列表添加订阅源：
listing:
contents: posts
feed: true当为页面上的列表启用了订阅源时，将自动使用文件名生成一个RSS文件。例如，index.qmd将生成一个位于index.xml的订阅源。订阅源的链接也将包含在页面的head中。
生成订阅源需要在_quarto.yml文件中为网站设置site-url。例如：
_quarto.yml
website:
site-url: "https://www.quarto.org"你还可以通过向feed键传递选项来进一步自定义你的订阅源：
listing:
contents: posts
feed:
items: 10以下选项可用：
| 选项 | 描述 |
|---|---|
items |
要在订阅源中包含的项目数量。默认为20。 | |
type |
full、partial或metadata。full，默认情况下，包括订阅源中每个文档的全部内容。 | partial包括描述（如果可用），否则包括订阅源中的第一段。 | metadata仅包括标题、描述和其他文档元数据在订阅源中。 |
标题 |
该提要的标题。默认为 _quarto.yml 文件中提供的站点标题。 |
图片 |
该提要的图片。如果未指定，将使用列表所在页面的图片，否则将使用 _quarto.yml 文件中为站点指定的图片。 |
描述 |
该提要的描述。如果未指定，将使用列表所在页面的描述，否则将使用 _quarto.yml 文件中为站点指定的描述。 |
语言 |
该提要的语言。如果未指定，则省略。有关有效语言代码的列表，请参见 https://www.rssboard.org/rss-language-codes。 |
分类 |
为该类别名称列表中的每个类别生成一个单独的提要。 |
列表字段
在读取列表内容时，Quarto 使用从文档的前言或文档内容本身读取的元数据来填充每个项目的以下字段：
| 字段名称 | 描述 |
|---|---|
标题 |
项目的标题，从前言的 title 字段读取（或文档的第一个 H1）。 | |
副标题 |
项目的副标题，从前言的 subtitle 字段读取。 |
author |
项目的作者，从前言的 author 字段中读取。 | |
description |
项目的描述，从前言的 description 或 abstract 字段中读取，或者从文档的第一段中获取。 | |
date |
项目的日期，从前言的 date 字段中读取。 | |
image |
该项目的图片，从前言的 image 字段中读取，或者自动发现，优先选择类名为 preview-image 的图片，文件名以 feature、cover 或 thumbnail 开头的图片，或者文档中出现的第一个图片。 | |
image-alt |
该项目的图片的替代文本。 | |
word-count |
该项目的字数统计。 | |
reading-time |
该项目阅读时间的估计值，通过计算项目中的单词数并假设每分钟阅读200个单词来估算。 | |
categories |
项目的分类，从前言的 categories 字段中读取。 | |
filename |
输入文件的名称。 |
file-modified |
该输入文件的最后修改日期。 |
根据您使用的列表类型，会自动显示不同的字段：
| 字段 | 类型: 默认 | 类型: 表格 | 类型: 网格 | | |
|---|---|---|---|
title |
x | x | x |
subtitle |
x | ||
author |
x | x | x |
description |
x | x | |
date |
x | x | x |
image |
x | x | |
自定义字段
虽然默认显示特定列，但每种类型都允许您通过使用fields选项显示上述任何列。例如，要在表格中显示更多字段（作为列），您可以写：
listing:
type: table
contents: posts
fields: [image, date, title, author, reading-time]这将产生：
每种列表类型将以不同方式处理字段。
- 默认
-
对于默认类型的列表，各种字段将按逻辑排列，
image在右列，title、subtitle和description在中间列，其他字段在左列。
- 表格
-
对于表格类型的列表，字段列表将按字段在列表中出现的顺序显示为列。
- 网格
-
对于网格列表，
image、title、subtitle、reading-time、categories、description、author和date字段将排列在卡片主体上。filename和file-modified字段将出现在卡片页脚中。其他字段将出现在卡片主体底部的表格中。
包含或排除项目
您可以根据项目的元数据使用include和exclude选项控制包含或排除哪些文档。这些选项允许您指定一个或多个字段名称和值，这些字段名称和值必须存在或不存在，以便包含或排除项目。例如，要仅包含由Harlow或Tristan编写的项目，您可以写：
listing:
contents: posts
type: grid
include:
author: "{Harlow,Tristan}*"要排除由Charles编写的任何项目，您可以写：
listing:
contents: posts
type: grid
exclude:
author: "Charles*"在基于字符串字段值包含或排除项目时，Quarto将使用glob语法进行值比较。任何其他类型的比较将通过测试相等性来进行。 ## 用户工具
列表支持交互式工具，使查看者能够对列表进行排序、筛选或分页浏览。
排序
用户可以使用选择框来选择如何对列表中的项目进行排序（在表格的情况下，通过点击列标题）。默认情况下，排序控件将允许用户按标题、日期或作者进行排序。你可以通过以下选项阻止此UI向用户显示：
listing:
sort-ui: false你可以通过在sort-ui键中提供一个字段名称列表来控制排序列表中包含哪些字段：
listing:
sort-ui: [title, date]筛选
列表在列表内容的右上方包含一个筛选框。筛选框允许读者对列表内容进行“自动提示”搜索。你可以使用以下选项禁用筛选控件：
listing:
filter-ui: false默认情况下，如果启用了筛选控件，列表中显示的所有字段都将可搜索。如果你想将搜索/筛选限制为特定字段，可以通过在filter-ui键中提供一个字段列表来实现：
listing:
filter-ui: [title, date]分页
列表还天然支持项目的分页。每页显示的项目数量取决于列表类型：
| 列表类型 | 每页项目数 |
|---|---|
default |
25 |
table |
30 |
grid |
18 |
你可以使用page-size选项来控制每页显示的项目数量：
listing:
page-size: 36列表位置
默认情况下，列表将简单地附加到页面主内容区域。如果你想控制列表出现的位置，请为该列表设置一个id，并在页面中相应的div上使用该id。例如，将上一个示例中使用的页面更新为此：
---
title: "Listing Example"
listing:
id: sample-listings
contents: posts
sort: "date desc"
type: table
---
你可以查看以下文档以获取更多信息：
::: {#sample-listings}
:::
了解更多关于Quarto的信息[这里](https://www.quarto.com)。结果是一个类似如下的列表页面：
多个列表
你可以在单个页面上放置任意数量的列表。以下示例将在单个页面上填充两个列表：
---
title: Team Documents
listing:
- id: lab-reports
contents: "lab-reports/*.qmd"
type: table
- id: meeting-notes
contents: "meeting-notes/*.qmd"
type: table
---
## 实验室报告
:::{#lab-reports}
:::
## 会议记录
:::{#meeting-notes}
:::YAML列表内容
除了通过匹配一个或多个全局模式填充列表外，你还可以通过YAML文件明确提供项目。例如，以下列表：
---
title: "Listing Example"
listing:
id: sample-listings
contents:
- posts
- archived-items.yaml
sort: "date desc"
type: table
---将包括posts目录中的所有文档，但还将合并archived-items.yaml文件的内容。archived-items.yaml文件的内容应为项目列表，每个项目都是字段名称到值的映射。例如：
- title: "Archived Item 1"
author: Norah Jones
date: 2020-01-01
path: "archived/archived-item-.html"
categories: [archived, technology]这对于将现有内容迁移到Quarto的情况非常有用——你可以开始创建新的Quarto文档，但仍然可以通过提供元数据通过yaml文件在列表中包含现有内容。