Assign Attributes to a Component Version

组件版本属性

在组件版本描述符中定义的属性被称为组件版本属性。组件版本属性可以是内置的、自定义的和页面属性。这些属性根据属性优先级规则应用并可用（或根据情况设置为不可用）于组件版本的所有页面。如果属性先前在站点的playbook中被硬设置或硬取消，在组件版本描述符中声明将不会产生影响。

Playbook文件与组件版本描述符文件

属性在playbook文件和组件版本描述符文件中使用相同的结构和语法进行声明。

Playbook是您配置站点、内容源和UI URL的地方。Playbook文件通常在文件名中包含单词playbook，例如antora-playbook.yml或local-antora-playbook.yml。

组件版本描述符是您配置组件版本的名称、版本、元数据、属性和导航列表的地方。组件版本的组件版本描述符文件名始终为antora.yml。

对于扩展程序编写者。如果在组件描述符中未定义AsciiDoc属性，则组件版本对象上的asciidoc属性将引用站点范围内的AsciiDoc配置对象（即siteAsciiDocConfig）。如果您计划修改组件版本属性，请首先检查asciidoc属性的值是否匹配（===）站点范围对象，如果是，则进行深度复制。

在antora.yml中设置属性

组件版本属性在组件版本的antora.yml文件中设置。首先，必须设置asciidoc和attributes键。然后，每个组件版本属性作为键值对输入到attributes下的自己的一行中。

示例1. 在antora.yml中声明属性

name: light
title: Data Light
version: '2.3'
asciidoc: (1)
  attributes: (2)
    table-caption: Data Set (3)
    hide-uri-scheme: '' (4)
    page-level: Advanced (5)
    page-category: Statistics; Cloud Infrastructure (6)
nav:
- modules/ROOT/nav.adoc

1	在新行上，键入`asciidoc`，后跟冒号（`:`），然后按`Enter`。
2	将`attributes`键嵌套在`asciidoc`键的正下方的行上。键入`attributes`，后跟冒号（`:`），然后按`Enter`。
3	每个组件版本属性都嵌套在`attributes`键下，并在自己的一行上定义。键入属性的名称，后跟冒号（`:`）。在冒号后按一次`空格`，然后键入属性的值。
4	要设置一个属性而不指定显式值，请在值部分输入两个连续的单引号（`''`）。对于某些内置属性，空值等效于默认值，尽管这取决于属性。尽管在这种情况下通常使用布尔值`true`，但AsciiDoc中的属性值是字符串，因此它可能会被强制转换为字符串值`'true'`。
5	要声明自定义页面属性，请键入`page-`和您的属性名称，后跟冒号（`:`）。在冒号后按一次`空格`，然后输入属性的值。
6	当属性具有多个独立值时，使用分号（`;`）分隔每个值。

设置的组件版本属性应用并可用于属于组件版本的每个页面。自定义属性的值，例如page-level，可以在页面中使用属性引用语法显示（例如，{page-level}）。

示例1中的所有属性都是硬设置的。 硬设置的组件版本属性无法从页面中覆盖。默认情况下，当为属性分配一个不用于取消属性的值（即false或~）并且不以修饰符结尾（即@）时，属性被视为硬设置。要允许页面修改或取消组件版本属性，您需要软设置组件版本属性。

软设置属性

软设置的组件版本属性可以从页面中覆盖。通过在值的末尾附加@修饰符来软设置属性。

示例2. 为属性分配软设置优先级

asciidoc:
  attributes:
    table-caption: Data Set@ (1)
    hide-uri-scheme: '@' (2)

1	要软设置分配了显式值的属性，请在其值的末尾附加`@`修饰符。
2	要软设置并分配内置属性的默认值，或者在布尔属性的情况下，空字符串值，请键入一个开头的单引号，后跟`@`修饰符，然后是一个闭合的单引号（`'`）。

由于示例2中的组件版本属性是软设置的，页面可以修改它们的值或取消它们。

插入另一个属性的值

在同一antora.yml文件中设置的任何组件版本属性的值或任何站点属性的值可以通过AsciiDoc属性引用（例如，{site-title}，{page-level}）插入到组件版本属性的值中。

示例3. 引用另一个组件版本属性值的组件版本属性

name: light
title: Data Light
version: '2.3'
asciidoc:
  attributes:
    table-caption: Data Set
    url-plugins: https://example.com/plugins
    url-data-plugin: {url-plugins}/data-light
nav:
- modules/ROOT/nav.adoc

组件版本属性的值也可以在页面属性的值中引用。

要防止属性引用替换在属性值中，插入一个反斜杠在引用前面（例如，\{not-substituted}）。在这种情况下，属性引用将不会被替换，反斜杠将被省略。

在antora.yml中取消设置属性

属性也可以被取消设置。当组件版本属性被分配为保留的波浪符号（~）值时，组件版本属性将被硬取消设置。每个属性都作为键值对在attributes键下的单独行中输入。

示例4. 硬取消设置属性

asciidoc:
  attributes:
    table-caption: ~ (1)
    hide-uri-scheme: ~ (2)

1	要硬取消设置属性，请将其分配为波浪符号（`~`）。在YAML中，`~`是`nil`的简写，`nil`是硬取消设置站点属性的保留值。
2	当分配波浪符号（`~`）时，布尔属性也会被硬取消设置。

硬取消设置组件版本属性无法从页面中被覆盖。当组件版本属性被硬取消设置时，其行为被关闭，不可用于组件版本的页面。

软取消设置属性

软取消设置的组件版本属性可以从页面中被覆盖。通过将其分配为保留值false来软取消设置属性。

示例5. 为属性分配软取消设置优先级

asciidoc:
  attributes:
    table-caption: false (1)
    hide-uri-scheme: false (2)

1	要软取消设置属性，请将其分配为值`false`。
2	当分配`false`时，布尔属性也会被软取消设置。

由于在示例5中的属性是软取消设置的，页面可以重置它们。

优先规则

Antora首先考虑分配给站点属性的优先级。在antora.yml文件中声明的属性无法覆盖如果在playbook中被硬设置或硬取消设置的相同属性。组件版本属性只有在站点属性被软设置或取消设置时才能覆盖站点属性。

当声明组件版本属性时，您可以控制页面是否可以逐个案例地重置或取消设置每个属性。假设属性是软设置或取消设置的，或者之前在playbook中未定义过，则组件版本属性被硬设置或硬取消设置的属性无法被页面更改。然而，软设置和取消设置的组件版本属性可以从页面中被覆盖。

硬设置组件版本属性使用没有尾随@修饰符的字符串值（例如，value或''）会阻止页面更改或取消设置属性。
软设置组件版本属性使用带有尾随@修饰符的字符串值（例如，value@或'@'）允许页面更改或取消设置属性。
硬取消设置组件版本属性使用波浪符号（~）阻止页面设置属性。
软取消设置组件版本属性使用false值允许页面设置属性。

要了解组件版本属性如何与站点属性和页面属性交互的更多信息，请参阅为站点分配属性和Antora中的AsciiDoc属性。

内在组件版本属性

Antora从组件版本描述符文件中的大多数键中定义内在页面属性。例如，Antora设置内置属性page-component-title并将其分配为由title键指定的值。请参阅内在页面属性以获取Antora自动声明的页面属性的完整列表。

Antora还默认设置一些内置的AsciiDoc属性，例如sectanchors。有关更多信息，请参阅站点和配置属性。

一些内置的AsciiDoc属性在Antora环境中不适用。这些属性包括data-uri、allow-uri-read、docinfo、linkcss、noheader、nofooter、webfonts和outfilesuffix。设置这些属性要么没有效果，要么可能导致Antora发生故障。其他属性，如imagesdir，由Antora自动设置，无法被覆盖。

为组件版本分配属性