每个文档包含一组称为文档属性的名值对。 这些属性提供了一种配置AsciiDoc处理器的方法，声明文档元数据，以及定义可重用的内容。本页介绍了文档属性，并回答了一些关于提及它们时使用的术语的问题。

文档属性是什么？

文档属性实际上是AsciiDoc语言的文档范围变量。AsciiDoc语言定义了一系列内置属性，并且允许作者（或扩展）定义额外的文档属性，这些属性在允许的情况下可以替换内置属性。

内置属性要么提供对文档及其环境的只读信息的访问，要么允许作者配置 AsciiDoc 处理器对整个文档或选定区域的行为。内置属性在效果上是无序的。用户定义的属性作为一个强大的文本替换工具。用户定义的属性按照它们被定义的顺序进行存储。

这是一些文档属性用途的总结：

  • 提供文档信息的访问权限

  • 定义文档元数据

  • 打开或关闭内置功能

  • 配置内置功能

  • 声明资产（如图像）的位置

  • 在文档中存储内容以便重复使用

让我们仔细了解一下不同类型的文档属性。

文档属性的类型

文档属性分为以下几组。

内置属性

内置属性用于添加、配置以及控制文档中的常见特性。许多内置属性只有在文档头部通过属性条目定义时才会生效。

布尔属性是内置属性的一个子集。如果定义了一个布尔属性，但没有赋值（即设置），它就处于“开”状态。如果属性没有定义（即没有设置），它就处于“关”状态。在这方面，这些属性的作用就像一个开关。它们的唯一功能是打开或关闭一个功能。

用户定义的属性

用户定义的属性是作者设置的任何不被AsciiDoc语言或扩展保留的属性。大多数情况下，用户定义的属性被用作文本替换工具。这些属性允许作者定义命名的、可重用的内容。因此，作者不必在文档中重复文字，例如产品名称，可以在属性中定义这些文本，并通过其名称引用。这种技巧有助于保持文档的DRY，即“不要重复自己”。

定义文档属性是什么意思？

  • 在内置属性的情况下具有默认值

  • 在布尔属性和具有默认值的内置属性的情况下没有价值。

  • 只有一行数值

  • 拥有一个值，该值跨越多个连续行

  • 具有一个值，其中包括基本的内联AsciiDoc语法，例如：

    • 属性引用

    • 文本格式化（如果包裹在pass宏中）

    • 如果包裹在pass宏中的内联宏（inline macros）

但是有一些局限性需要注意。文档属性不能：

  • 拥有一个包括AsciiDoc块内容的值，例如：

    • 列表

    • 多个段落

    • 区块（表格、侧边栏、示例等）

    • 其他依赖空白的标记

设置文档属性是什么意思？

  • 被设置（打开）

取消设置文档属性是什么意思？

  • 通过在名称前面（更推荐）或后面加上一个`!`来取消设置（关闭）。

文档属性在哪里定义、设置和取消设置？

文档属性可以在以下位置声明：

  • 将文档头作为一个属性条目

  • 将文档主体作为 属性条目

  • 通过 :attributes 选项使用API

  • 通过`-a`选项使用CLI

  • 覆盖从命令行分配的锁定属性

引用文档属性是什么意思？

引用文档属性意味着用属性的值来替换属性名。一个文档属性可以在文档中使用语法 {name} 来引用，其中 name 是属性的名称。

文档属性可以在哪里被引用？

一个文档属性可以在文档中的任何地方被引用，只要属性替换被应用到那里。一般来说，属性替换被应用于属性条目的值、标题、段落文本、列表文本、元素属性的值，以及宏的目标上。

一个文档属性只有在它被定义之后才能被引用。