这个页面详细分解了元素上位置属性和命名属性之间的区别，以及解析属性列表的规则。

定位属性

在属性列表中，只包含值的条目被称为位置属性。位置是一旦移除所有命名属性后条目的1-based索引（因此它们可能会间隔分布）。

位置属性可以分配给隐式属性名称，如果块或宏为位置属性定义了映射。以下是一些映射示例:

  • icon:` 1 ⇒ size

  • image:` 和 image:: 1 ⇒ alt (文字说明), 2 ⇒ 宽度, 3 ⇒ 高度

  • 定界块：1 ⇒ 块样式和属性简写

  • 其他内联引用文本：1 ⇒ 属性简写

  • link:` 和 xref:`` 1 ⇒ 文本

  • 自定义块和宏也可以指定位置属性。

例如，下面这两个图像宏是等价的。

image::sunset.jpg[Sunset,300,400]

image::sunset.jpg[alt=Sunset,width=300,height=400]

第二个宏与第一个相同，但以完整形式写出。

区块样式和属性简写

所有块（包括节）上的第一个位置属性是特殊的。它用于定义block style。它还支持定义ID、角色和选项属性的简写语法。即使格式化文本技术上不支持属性，这种简写语法也可以用在格式化文本上。

属性简写的灵感来自于HAML和Slim模板语言，作为一种减少作者输入的方式。不必使用 name 属性的冗长形式，可以将赋值压缩到一个由特殊标记前缀的值。标记的映射如下：

  • #` - ID

  • .` - 角色

  • %` - 选项

每个简写条目都直接放置在前一个条目的紧邻处，紧跟在可选的块风格之后开始。条目的顺序并不重要，除了风格必须放在第一位。

这是一个示例，展示了如何使用这种简写语法给章节设置一个ID。

[#custom-id]
== 带有自定义ID的章节

速记条目必须遵循块样式（如果存在的话）。这里有一个示例，展示了如何使用这种速记语法为附录部分设置ID：

[appendix#custom-id]
== 附录带有自定义ID

这里有一个块的例子，它使用简写语法来设置ID、角色和列表选项。具体来说，这个语法将ID设置为`rules`，添加角色`prominent`，并设置选项`incremental`。

[#rules.prominent%incremental]
* 努力工作
* 尽情玩乐
* 保持快乐

一个区块可以有多个角色和选项，因此这些简写条目可能会重复。这里有一个示例，展示了如何在表格上设置多个选项。具体来说，这种语法设置了`header`、`footer`和`autowidth`选项。

|===
[%header%footer%autowidth]
|Header A |Header B
|Footer A |Footer B
|===

这种简写语法也出现在格式化文本中。 下面是一个例子，展示了如何设置ID并为加粗短语添加一个角色。 具体来说，这种语法将ID设置为 free-world 并添加了 goals 角色。

[#free-world.goals]*free the world*

格式化文本不支持样式，因此第一个也是唯一的位置属性始终是速记语法。

命名属性

一个命名属性由一个名称和一个值组成，这两者之间用一个等号`=字符来分隔（例如，`name=value）。

如果值包含空格、逗号或引号字符，则必须用双引号或单引号括起来（例如，name="value with space"）。在所有其他情况下，外围的引号是可选的。

如果值中包含用于封闭该值的*相同*引号字符，那么值中的引号字符必须通过在其前面加上反斜杠来转义（例如，value="the song \"Dark Horse\""）。

如果使用了引号来包围文本，那么在解析值时会去掉这些引号，并且会删除任何被转义引号前的反斜杠。

未设置 === 取消设置一个命名属性

要取消定义一个命名属性，将其值设置为`None`（大小写敏感）。// end::name[]

属性列表解析

用于定义元素属性的源文本被称为 属性列表（attrlist）。属性列表总是包含在一对方括号内。这适用于块属性以及块或行内宏的属性。处理器将属性列表分割为单独的属性条目，确定每个条目是位置属性还是命名属性，相应地解析条目，并将结果作为属性分配到节点上。

定义一个属性的边界，以及该属性是位置属性还是命名属性的规则在下面定义。在这些规则中，name 由一个单词字符（字母或数字）组成，后面可以跟任意数量的单词字符或 - 字符（例如，see-also）。

  • 属性引用会在属性列表解析之前展开（也就是说，属性的替换已经被应用了）。 * 解析一个属性会从属性列表字符串的开头或一个先前识别的分隔符（,）后开始。 属性列表的第一个字符不能是制表符或空格。对于后续的属性，任何前导的空格或制表符都会被跳过。 * 如果找到了一个有效的属性名，并且它后面跟着等号（=），那么解析器将其识别为一个具名属性。等号（=）之后的文本，直到下一个逗号或列表末尾，被认为是属性值。等号（=）周围以及值末尾的空格和制表符会被忽略。 * 否则，这将是一个位置属性，其值在下一个分隔符或列表末尾结束。值边界处的任何空格或制表符都会被忽略。 * 要解析属性值： 如果第一个字符不是引号，字符串会一直读取到下一个分隔符或字符串末尾。 如果第一个字符是双引号（也就是 "），那么字符串会一直读到下一个未转义的双引号，或者，如果没有关闭的双引号，下一个分隔符。如果有一个闭合的双引号，包住双引号的字符会被移除，并且转义的双引号字符会被反转义；如果没有，最初的双引号会被保留。 如果下一个字符是单引号（即 '），那么字符串将一直读到下一个未转义的单引号，或者，如果没有闭合的单引号，下一个分隔符。如果有一个闭合的单引号，包含单引号的字符将被移除，转义的单引号字符将被反转义；如果没有，最初的单引号将被保留。如果有一个闭合的单引号，并且第一个字符不是转义的单引号，则按照 [Substitutions] 中描述的对值进行替换。

当需要转义闭合方括号时 ** 由于attrlist的终端是闭合方括号，如果在属性的值中出现闭合方括号，有时需要转义闭合方括号。

在面向行的语法中，如块属性列表、块宏和包含指令，您不必转义在attrlist本身中出现的闭合方括号。这是因为解析器已经知道要在行末寻找闭合的方括号。

如果在内联元素的attrlist中出现闭合的方括号，例如内联宏，通常需要使用反斜杠转义，或者使用字符引用 ] 来转义。这个规则有一些例外，例如脚注中的链接宏，这些例外受到替换顺序的影响。

替代品

请记住，在解析attrlist之前，属性引用就已经展开了。因此，如果你只感兴趣于应用属性替代，那么没有必要强制应用替代到值上。在这一点上，属性替代已经被应用过了。

如果属性名（在位置属性的情况下）或值（在命名属性的情况下）被单引号（例如，citetitle='Processed by https://asciidoctor.org'）包围，并且该属性在块上的attrlist中定义，那么在赋值时将对值应用normal substitution group的正常替换组。如果值没有被引号包围，或者被双引号包围，则不进行特殊处理，除了属性引用的扩展。

如果值中包含用于封闭该值的相同引号字符，请通过在其前面添加反斜杠来转义值中的引号字符（例如，citetitle='一个‘用例’图，由https://plantuml.com生成'）。// end::subs[]