为组件版本分配属性

您可以通过在该组件版本的 antora.yml 文件中声明属性，将其应用于该组件版本中的所有页面。

组件版本属性

在组件版本描述符中定义的属性称为组件版本属性。组件版本属性可以是内置属性、自定义属性和页面属性。根据属性优先级规则，将这些属性应用于所有组件版本的页面并使其可用(如果未设置则使其不可用)。如果一个属性以前在站点的剧本中被硬设置或硬取消设置，那么它在组件版本描述符中的声明将不会产生影响。

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

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

剧本是您配置站点、内容源和 UI url 的地方。剧本文件的文件名中通常有剧本这个词，例如: antora-playbook.yml 或 local-antora-playbook.yml 。

组件版本描述符用于配置组件版本的名称、版本、元数据、属性和导航列表。组件版本描述符的文件名总是 antora.yml 。

在 antora.yml 中设置属性

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

Example 1. Example 1. Declare attributes in 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	将属性键嵌套在 `asciidoc` 键的正下方。输入 `attributes` ，后跟冒号( `:` )，然后按 `Enter` 。
3	每个组件版本属性都嵌套在 `attributes` 键下，并在自己的行中定义。键入属性的名称，后面跟着冒号( `:` )。按冒号后的空格键一次，然后键入属性的值。
4	若要将默认值(或布尔属性的情况下为空字符串值)分配给内置属性，请在值字段中键入两个连续的单引号(`''`)。
5	要声明自定义页面属性，请键入 `page-` 和属性名称，后面跟着冒号( `:` )。在冒号后按一次空格键，然后输入属性的值。
6	当一个属性有多个独立的值时，每个值用分号( `;` )分隔。

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

示例1 中的属性都是硬设置的。硬设置的组件版本属性无法从页面中覆盖。默认情况下，当为属性分配了一个值时，该属性是硬设置的。该值不能是用于取消设置属性 (即 false 或 ~) 的保留值，也不能以修饰符（即 @ ）结尾。要允许页面修改或取消设置组件版本属性，您需要对组件版本属性进行软设置。

软设置属性

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

Example 2. Example 2. Assign soft set precedence to attributes

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

1	要软设置被显式赋值的属性，请将 `@` 修饰符附加到其值的末尾。
2	要软设置和分配内置属性的默认值，或者在布尔属性的情况下，为空字符串值，请键入一个开始的单引号，然后是 `@` 修饰符，然后是结束的单引号( `'` )。

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

在属性值中引用组件版本属性

组件版本属性的值可以包含对站点属性的属性引用，也可以包含已在同一控件中设置的其他组件版本属性。使用 AsciiDoc 属性引用语法(例如，Docs ， {page-level} )的 yml 文件。

Example 3. Example 3. Reference a component version attribute in a component version attribute value

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-substitute} )。在这种情况下，属性引用将不会被替换，反斜杠将被省略。

在 antora.yml 中取消设置属性

也可以取消设置属性。当组件版本属性被分配了保留的波浪线符号 ~ 值时，它们被硬取消设置。每个属性都作为一个键值对在 attributes 键下的自己行中输入。

Example 4. Example 4. Hard unset attributes

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

1	要硬取消一个属性，请给它指定一个波浪符号( `~` )。 `~` 是一个保留值，用于硬取消组件版本属性的设置。
2	当分配波浪符号( `~` )时，布尔属性也硬取消设置。

无法从页面覆盖硬取消设置组件版本属性。当组件版本属性是硬取消设置时，它的行为将被关闭，并且它对组件版本的页面不可用。

取消软设置属性

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

Example 5. Example 5. Assign soft unset precedence to attributes

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

1	若要软取消对属性的设置，请将其赋值为 `false` 。
2	当软取消设置赋值为 `false` 时，布尔属性也会软取消设置。

由于示例5中的属性是软未设置的，因此页面可以重置它们。

优先级规则

Antora 首先考虑分配给站点属性的优先级。在 antora.yml 文件中声明的属性不能覆盖相同的属性(如果它在剧本中是硬设置或硬取消设置)。只有当站点属性为软设置或未设置时，组件版本属性才能覆盖站点属性。

在声明组件版本属性时，您可以根据具体情况控制页面是否可以重置或取消每个属性。假设属性是软设置或未设置的，或者以前没有在剧本中定义，那么硬设置或硬未设置的组件版本属性不能被页面更改。但是，可以从页面覆盖软设置和取消设置组件版本属性。

使用没有 @ 修饰符的字符串值(例如，value 或 '' )来硬设置组件版本属性，可以防止页面更改或取消设置该属性。
软设置组件版本属性，使用一个字符串值，后面带 @ 修饰符(例如， value@ 或 '@' )，允许页面更改或取消设置该属性。
使用波浪符号( ~ )硬取消组件版本属性可防止页面设置该属性。
使用 false 值软取消组件版本属性允许页面设置该属性。

要了解更多关于组件版本属性与站点属性和页面属性的交互，请参见指定站点属性和 Antora 中的 AsciiDoc 属性。

内在组件版本属性

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

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

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