页面属性

某些 AsciiDoc 文档属性为 Antora 页面提供元数据或控制 Antora 如何处理页面。我们将这些称为页面属性。页面属性有三种类型:自定义、预定义和内在属性。本页解释了每种类型的页面属性的用途，如何重新定义它们，以及如何使用 UI 模型从 UI 模板访问它们。

目的及解剖

页面属性都是关于提供元数据的，无论该元数据是用于 Antora 本身、UI模板、用户还是用于搜索索引。通过定义页面属性，您可以存储关于页面的其它信息，然后可以在整个站点中访问和使用这些信息。

页面属性的定义与任何其它 AsciiDoc 文档属性一样，通常使用文档头中的属性条目。页面属性的不同之处在于属性的名称必须以 page- 开头(例如，page-category )。page- 前缀的存在允许 Antora 将其识别为页面属性。

TIP

如果您想知道是否需要添加 page- 前缀，请询问自己是否需要从 UI 模板访问该属性。如果答案是肯定的，那么就需要前缀。否则，不需要前缀。

下面是一个定义了两个页面属性的页面示例：

= Page Title
:page-category: DevOps
:page-edition: Enterprise

Main content.

page- 前缀旨在向 Antora 和作者提供一个提示，告诉他们哪些属性构成了页面的元数据。通过对 page- 前缀 进行标准化，Antora 能够将页面属性从 AsciiDoc 中或由 AsciiDoc 处理器定义的众多内置和固有属性中分离出来。前缀还将页面属性与用于在页面或站点中存储可重用内容的内部属性(也称为自定义内容属性)隔离开来。

定义一个自定义页面属性

要定义页面属性，您可以在页面标头中添加一个属性条目，并以 page- 开始名称。在头文件中定义属性条目是很重要的。否则，将找不到 page 属性。

下面是定义页面属性的属性条目示例：

= Page Title
:page-name-goes-here: value goes here

这个页面属性的名称是 name-goes-here ( page- 前缀加上自定义名称 name-goes-here )。它的值 value goes here 。

页面属性的名称必须遵守文档属性的 命名规则。该值可以为空，也可以为字符串值。如果该值不为空，则必须与结束冒号( : )至少偏移一个空格。

TIP

由于页面属性只是特殊的 AsciiDoc 文档属性，它们也可以在 Antora 剧本中定义 站点范围 内的属性，或者在组件版本描述符中定义 每个组件版本 。

提升非页面属性

如果希望使现有文档属性中的信息作为页面属性可用，则必须将该属性提升为页面属性。可以使用属性引用将文档属性提升为页面属性。

例如，假设您在页面或站点上定义了属性 product-name 。您可以使用以下属性条目将其提升为页面属性：

= Page Title
:product-name: Name of My Product
:page-product-name: {product-name}

属性引用立即被解析，因此名为 page-product-name 的页面属性现在与名为 product-name 的文档属性共享相同的值。

配置预定义的页面属性

一些页面属性在 Antora 中得到特殊处理。这些页面属性具有保留的名称，但接受用户定义的值，以便将有关页面的信息传递给 Antora 。示例包括 page-aliases , page-layout , 和 page-partial 。

页面别名( page-aliases )属性允许您为当前页面配置备用资源 id 。例如，要声明页面的旧名称，您可以使用：

= Page Title
:page-aliases: old-page-name.adoc

与自定义页面属性不同，页面别名(page-aliases)属性要求值符合特定的语法(即，以逗号分隔的资源 id 列表)。请参阅 页面别名，了解页面别名(page-aliases)属性，以及如何使用它来保留对已重命名、移动或删除的页面的引用。

page-layout 属性允许您指定将哪个 UI 模板应用到当前页面。例如，要将主(home)布局应用于当前页面，可以使用：

= Home Page
:page-layout: home

请参阅 页面布局，了解 page-layout 属性以及如何使用它来定义应用于页面的 UI 布局。

将来可能会添加其他预定义的页面属性，以允许配置类似的功能。

从UI模板访问页面属性

页面属性的主要作用之一是通过 UI 模型将关于页面的元数据传递给 UI 模板。 UI 模板可以以各种方式使用页面属性提供的信息，从在发布的页面中填充元数据到在 UI 中切换或配置行为。

例如，默认 UI 允许您使用名为 toclevels 的页面属性来配置侧边栏 TOC 的深度(即定义时的页面 toclevels )。例如：

= Page Title
:page-toclevels: 3

你也可以在剧本中设置这个属性(添加一个后缀的 @ ，这样它仍然可以在每页被覆盖)：

asciidoc:
  attributes:
    page-toclevels: 3@

在 UI 模型中可以通过页面访问 page.attributes 的属性。此属性的值是属性的映射。

例如，要访问 UI 模板中名为 toclevels 的页面属性，可以使用:

{{page.attributes.toclevels}}

那么 page- 前缀去了哪里？

当页面属性被提升到 UI 模型时，page- 前缀将被删除。这就是为什么我们说页面属性的名称为 toclevels 而不是 page-toclevels 。页面前缀只是一个命名空间，用于将其标识为页面属性。因此，页面属性命名为 page-toclevels 在 UI 模型中变为 toclevels (例如，page.attributes.toclevels )。

属性名称上的 page- 前缀是将其提升到 UI 模型的原因。所有其它文档属性都对 UI 模型有效地隐藏起来。

内置页面属性

Antora 在运行时自动设置一些只读的、固有的页面属性，这些属性来源于关于当前页面的现有元数据。例如，当前组件的名称可以从 page-component-name 属性中读取。

内置页面属性在 内置属性 中列出。这些属性是只读的，因此不应该在页头中重写它们的值。