什么是属性条目？

在您能够在文档中使用文档属性之前，您必须先声明它。一个[.term]_属性条目_是在AsciiDoc文档中定义文档属性的主要机制。您可以将属性条目视为AsciiDoc的全局变量分配。从那一点开始，它创建的文档属性在文档中变得可用。属性条目也经常用于切换特性。

属性条目包括两个部分：一个是属性*名称*和一个是属性*值*。属性名称位于前面，随后是可选的值。每个属性条目必须单独输入在它自己的行上。一个属性条目以一个开头的冒号(:)开始，紧接着是属性的名称，然后是一个结束的冒号(:)。这种[.term]设置 — 也就是说，打开 — 文档属性，这样你就可以在文档中使用它。

:name-of-an-attribute: (1)

  1. 属性的名称前面直接跟一个开放的冒号(:)，后面直接跟一个闭合的冒号(:)。

在许多情况下，通过在属性条目中的名称后输入信息来显式为文档属性赋值。值必须至少有一个空格与关闭的冒号（:）分开。

:name-of-an-attribute: value of the attribute (1)

  1. 显式赋予的值应该至少用一个空格与关闭冒号(:)隔开。在值的末尾，按下kbd:[Enter]键。

请注意，默认情况下头部替换会自动应用到值中。这意味着您不需要在HTML标签中逃避特殊字符。这也意味着您可以在定义属性值时引用已经定义的属性的值。属性条目值中的属性引用会立即被解析。

:url-org: https://example.org/projects
:url-project: {url-org}/project-name (1)

  1. 你可以重用已经设置的属性的值，通过在值中使用属性引用。

一些内置属性在属性条目中不需要显式赋值，因为它们是布尔属性或具有隐含的值。

:name-of-an-attribute: (1)

  1. 如果您不想明确给属性分配一个值，请在结束冒号(:)之后按下kbd:[Enter]键。

当设置了内置的布尔属性时，其值总是空的（即一个_空字符串_）。如果你设置了一个内置属性并将其值留空，AsciiDoc处理器可能会在处理时推断出一个值。

属性条目可以在哪里声明？

属性条目通常在文档头部声明。对于允许这样做的属性（包括通用属性），属性条目也可以在文档主体的块之间声明（即，文档头部以下的部分）。

Warning
 属性项的声明不应该在限定块的边界内进行。当属性项在限定块内声明时，其行为是未定义的。

当在文档头部使用属性条目定义一个属性时，这被称为头部属性。头部属性在整个文档中都可用，直到它被取消设定。头部属性也可以从文档的元数据中访问，供内置行为、扩展程序以及其他需要查询其值的应用程序使用（例如，source-highlighter）。

当在文档主体中使用属性条目定义属性时，它只是简单地被称为文档属性。对于在主体中定义的任何属性，该属性从设置点可用，直到被取消设置。在主体中定义的属性不能通过文档元数据访问。

除非属性是解锁的，否则可以在文档头部或正文中取消设置或分配一个新值。然而，请注意，取消设置或重新定义控制文档正文中行为的头部属性通常没有影响。参见document-attributes-ref.html，了解每个属性可以在文档的哪个部分被设置。

定义文档属性而不添加属性条目

文档属性也可以通过CLI（命令行接口）和API（应用程序接口）在文档外部被声明（设置一个可选的值或取消设置）。在这些情况下，不使用属性条目语法。相反，它们是通过提供的选项来声明的。对于API，属性是使用`:attributes`选项来声明的（该选项支持各种条目格式）。对于CLI，属性是通过`-a`选项来声明的。

当属性在文档之外被赋予一个值时，该值会按原样存储，这意味着该值不会应用任何替换。这也意味着当引用文档中的该属性时，特殊字符和引号替换不会应用于该属性的值。然而，后续的替换，比如宏替换，是会被应用的。这种行为是因为属性替换是在特殊字符和引号替换之后应用的。为了强制这些替换应用于属性的值，您必须在引用点改变替换顺序。这里有一个使用内联通行宏的例子。

pass:a,q[{attribute-with-formatted-text}]

当一个属性是从命令行或API声明的时候，它隐式地成为一个文档头属性。默认情况下，该属性会变得锁定（即，硬设置或未设置），因此不能被文档更改。这种行为可以通过在属性名称或值的末尾添加`@`（即，软设置修饰符）来改变。更多信息请参见 assignment-precedence.html。

这条规则的唯一例外是`sectnums`属性，它始终可以被修改。