使用键和键引用
Arbortext Editor 支持在 OASIS 的
DITA Architectural Specification 的
Key based (indirect) addressing 部分定义的基于键的引用。
Arbortext Editor 用户界面提供了许多功能来帮助您在 DITA 映射中指定键定义以及在映射和主题中插入键引用。此外，
Arbortext Editor 还提供了仅包含键定义的专用 DITA 映射，即
DITA 键定义映射。此映射可用于为键定义提供其他信息。
存储键定义的最佳方法是创建一个专门用来保存键定义的 DITA 映射。随后，便可根据需要使用 mapref 元素将包含键定义的映射加入任何其他 DITA 映射中。建议您使用 DITA 键定义映射来存储键定义。
键引用的用户界面
Arbortext Editor 用户界面的以下部分支持键引用：
• 插入菜单具有以下选项：
◦ 键定义 - 打开资源管理器，其中键定义选项卡处于激活状态。
◦ 键引用 – 打开插入键引用对话框。
• 工具菜单具有以下选项：
◦ 键和键引用 – 打开键和键引用对话框。
◦ 查找键引用 – 打开键和键引用对话框，其中仅显示包含光标的标记中的键。
也可通过 Arbortext Editor 的快捷菜单使用此选项。
◦ 键引用信息 – 打开键引用信息对话框。
也可通过 Arbortext Editor 的快捷菜单使用此选项。
• “标注”工具栏具有
插入键引用按钮
，使用该按钮可打开
插入键引用对话框。
• 资源管理器的以下功能支持键引用：
◦ DITA 映射中提供了
键定义选项卡，用于帮助您指定键定义。
此选项卡版本用于修改键定义且可在修改属性对话框、文档结构图和列视图中获得。
◦ 资源管理器的所有选项卡和对话框 (针对内容引用的选项卡和对话框除外) 中均提供了 Keyref 选项，使用该选项可以为所创建或修改的引用输入或选择要插入到 keyref 属性中的键名称。
◦ 资源管理器中针对内容引用的选项卡和对话框提供了 Conkeyref 选项，使用该选项可为所创建或修改的引用输入要插入到 conkeyref 属性中的键名称。
◦ 使用链接/Xref、内容引用及主题选项卡和对话框可浏览到包含键定义的 DITA 映射并为所插入或修改的引用使用所选的键定义。
• 以下对话框支持键引用：
◦ 插入键引用 - 使您可以将键引用插入到文档中。
◦ 添加/删除映射 - 使您可以在为
插入键引用对话框提供键定义的映射列表中添加或删除映射。
◦ 选择引用 - 使您可以选择在引用元素具有多个定义的引用目标时，要打开哪个文档。
◦ 键引用信息 - 显示有关与键引用关联的键定义的信息。
◦ 键和键引用 - 显示当前文档以及从当前文档引用的任何文档中所包含的键定义和键引用。
隐藏键引用的用户界面
默认情况下，键引用的用户界面在 Arbortext Editor 中可用。如果在 DITA 文档中未使用键引用，则可将键引用功能从用户界面中删除。
键引用的用户界面是否可用，取决于 ditakeyrefui 高级首选项。将此首选项的值设置为 off 可以删除键引用的用户界面。
建立键上下文
如果 Arbortext Editor 要查找与键引用关联的键定义，它必须知道当前文档的键上下文。键上下文是包含相关键定义的 DITA 映射。如果包含定义的映射是 DITA 键定义映射，则可向显示在键引用的用户界面中的键定义添加其他信息。文档的键上下文取决于 ditakeycontext 设置选项的具体设置。
在当前会话期间，ditakeycontext 选项被设置为单个映射，并为当前文档定义主键上下文。如果文档已建立键上下文，它将影响 Arbortext Editor 处理引用的方式。例如，如果图像标记同时定义了 href 属性和 keyref 属性，Arbortext Editor 将显示 keyref 属性的键定义中的图像。如果某个已建立的键上下文包含匹配的键定义，则 Arbortext Editor 将为键引用或内容键引用指定优先权。
您可以显式设置 ditakeycontext，在某些情况下，Arbortext Editor会自动设置该选项。例如，如果通过双击交叉引用、主题引用等打开一个文档，则原始文档的键上下文会应用到新打开的文档。同样，如果通过 Arbortext Editor 的与 DITA 相关的对话框打开文档，则当前文档的键上下文将应用到打开的文档。如果原始文档是不具有键上下文的 DITA 映射，该映射将成为已打开文档的键上下文。
另一种确定键定义是否可插入到文档中的方法是使用 ditakeybaselist 设置选项。ditakeybaselist 选项主要是用来建立供插入键引用对话框和资源管理器的 Keyref 选项中显示的键定义使用的映射列表。与 ditakeycontext 不同，ditakeybaselist 是高级首选项，它可包含多个映射并且可在 Arbortext Editor 会话之间保持不变。如果为 ditakeybaselist 分配了值，并且映射是当前 ditakeycontext 且不在该列表中，则键上下文映射将添加到当前会话中 ditakeybaselist 映射列表的开头。
使用 DITA 键定义映射
Arbortext Editor 提供了称为 DITA 键定义映射的专用 DITA 映射。此映射包含可让您在键定义中提供更多信息的其他元素，并且仅用于存储键定义。额外的键定义信息显示在键引用的用户界面中的不同位置处。DITA 键定义映射位于新建对话框的 DITA Technical Content 类别中。
键定义映射在 topicmeta 元素中添加可提供有关键定义的详细信息的额外元素。要使用这些元素，需要将 keydef 元素插入到映射中、将 topicmeta 元素插入到 keydef 元素中并将 keyinfo 元素插入到 topicmeta 元素中。随后，便可插入任何要在 keyinfo 内部使用的新元数据元素。您也可以使用键定义映射中资源管理器的键定义选项卡来将这类额外的信息添加到键定义中。
对于常规的键引用，可在 topicmeta 中使用以下附加元素：
• keyinfo - 括上其他元素。
• keydescription - 包含键的文本说明。
• keysubelementid - 指定 (在 value 属性中) 此键应该应用到哪个特定元素 ID。
• keyreftags - 包含 (在 value 属性中) 应用来引用此键的一个或多个元素名称的列表。
使用内容键引用
在 Arbortext Editor 中，要替换键引用中的内容，可以使用元素的 conkeyref 属性来设置内容键引用。与常规的键引用一样，如果内容键引用在文档的键上下文中具有关联定义，并且元素同时定义了 conref 属性和 conkeyref 属性，则 Arbortext Editor 将显示与 conkeyref 关联的内容，并且通常会为键内容引用指定优先权。
您可以使用常规的键定义来为内容键引用设置键。然而，DITA 键定义映射提供了一些附加元素来帮助您定义内容引用的键定义。另外，要在插入键引用对话框中包含内容键引用，您必须在 DITA 键定义映射中定义关联键定义。对于内容键引用，可以使用以下附加元素：
• keyconrefs - 使您可以专门为内容键引用指定键定义。
该元素是 keydef 元素的专门化。如果主题或映射引用以 keyconrefs 定义的键名称，则该主题或映射内具有 ID 的元素将在插入键引用对话框中显示为 conkeyref 引用的目标。此元素的 scope 属性将被设置为 local。format 属性被设置为 dita (默认值) 或 ditamap。
此元素还将包含新的 keyinfo 元素及其全部子元素。如果在 keyconrefs 定义中为 keysubelementid 元素分配值，则只有具有该特定 ID 的元素才能用于采用该定义的内容键引用。否则，所有具有 ID 的元素均可用。
• keyforconrefs - 表示键定义用于内容键引用。
此元素包含在 keyinfo 元素中。如果 keyforconrefs 元素的 value 属性设置为 true (默认值)，则表明此键定义用于内容键引用，并且在插入键引用对话框中也是如此。这使得您可以使用 keydef 和映射中的其他元素来为内容键引用指定键定义。
使用 DITA 键定义映射时，您可以将内容键定义设置为使单个元素可用于内容键引用或者所有具有 ID 的元素均可用。为了使单个元素可在插入键引用对话框中用于 conkeyref 引用，您必须使用以下标注在 DITA 键定义映射中对此进行定义：
• 键定义的 href 属性必须指向包含该元素的主题或映射。
href 中不得包含元素的 ID。
• keysubelementid 元素的 value 属性必须指定元素的 ID。
• keyreftags 元素的 value 属性必须包含具有指定 ID 的元素的名称，且以字符串 conkeyref: 作为前缀。
例如，以下键定义将主题 strings.dita 中具有 ID custom 的 ph 元素作为 conkeyref 目标添加到插入键引用对话框中。
<keydef keys=”strings” href=”strings.dita”>
<topicmeta>
<keyinfo>
<keydescription>Description of the “custom” element</keydescription>
<keysubelementid value=”custom”/>
<keyreftags value=”conkeyref:ph”/>
</keyinfo>
</topicmeta>
</keydef>
为了使映射或主题中所有具有 ID 的元素均可在插入键引用对话框中用于 conkeyref 引用，您还必须在 DITA 键定义映射中对此进行定义。您可以采用下列方法来定义该标注：
• 使用 keyconrefs 元素生成键定义。
例如：
<keyconrefs href=”strings.dita” keys=”strings”/>
• 将任何可用于指定键定义的元素与 topicmeta 元素中 keyinfo 元素内部的 keyforconrefs 元素结合使用。
例如：
<keydef href=”strings.dita” keys=”strings”>
<topicmeta>
<keyinfo>
<keyforconrefs/>
</keyinfo>
</topicmeta>
</keydef>
使用键引用插入文本
也可以使用常规的键引用在文档中插入文本。许多 DITA 元素均具有 keyref 属性。当元素为空并具有键引用集时，可以在键定义中包括文本以插入到这些元素中。元素必须为空才能用于文本插入。例如，文档中可以包括以下元素：
<ph keyref="product-name"></ph>
键引用以下键定义：
<keydef keys="product-name">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
当发布文档时，在 ph 元素内插入以下文本：
<ph>Acme Product</ph>
也可以包括带有您要插入的文本的标注。例如，当键引用以下键定义时：
<keydef keys="product-name">
<topicmeta>
<keywords>
<keyword><i>Acme Product</i></keyword>
</keywords>
</topicmeta>
</keydef>
在文档中插入以下文本：
<ph><i>Acme Product</i></ph>
除插入文本之外，通过在键定义中包括 href 属性，也可以将非链接元素变为链接元素或将链接元素变为非链接元素。例如，考虑以下键定义：
<keydef keys="product-name" href="acme.dita">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
<keydef keys="product-name-no-link">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
这些键定义由文档中的以下元素引用：
当发布文档时，在文档中插入以下文本：
请注意，当键定义分配有 href 时，插入文本的元素将成为链接元素。如果未分配有 href，即使链接元素 (例如 xref) 也不包含链接。虽然引用键定义的元素包含内容并且不能用于文本插入，此链接行为也适用。例如，当以下元素引用以上键定义时，请考虑：
<ph keyref="product-name">New Acme Product</ph>
在这种情况下，当发布文档时，键引用仅使元素成为链接元素但并不在键定义中插入文本：
<ph>
<xref href="acme.dita">New Acme Product</xref>
</ph>
要从键定义插入的文本按以下优先顺序：
1. 在键定义的 topicmeta 元素的 keywords 元素中的第一个 keyword 元素的内容
2. 在键定义的 topicmeta 元素的 keywords 元素中的第一个 term 元素的内容
3. 在键定义的 topicmeta 元素中的 linktext 元素的内容
4. 在键定义的 topicmeta 元素中的 navtitle 元素的内容
5. 键定义的 navtitle 属性的内容
例如，以下键定义包含多个可能的文本插入区域中的文本：
<keydef keys="product-name" navtitle="New Acme Product">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
在这种情况下，为键引用所插入的文本是 keyword 元素的内容，因为它比 navtitle 属性的内容具有更高的优先权。
以下元素是文本插入的特殊情况：
• link
link 元素不直接包含文本。但它的确包含可包含文本的可选 linktext 和 desc 元素。在这种情况下，如果键定义的 topicmeta 元素中存在 linktext 和 desc 元素，则当发布文档时，会将这些元素插入到 link 元素中。
• image
image 元素包含提供图像文本说明的 alt 元素。如果空 image 元素具有对键定义的键引用，而键定义包含要插入的文本，则在发布过程中文本将作为 alt 元素插入到 image 中。
• 不允许文本内容的元素
一些 DITA 元素 (例如 longdescref)，包含 keyref 属性，但不允许文本内容。这些元素不能通过键引用用于文本插入。
Arbortext Editor 用户界面提供以下功能支持通过键引用插入文本：
• 键引用信息对话框提供显示文本内容 (包括键定义中提供的任何标注) 的
文本选项。
• 插入键引用对话框显示键定义的文本内容，包括
资源列中的标注。
另外，当将 ditatextkeyrefs 高级首选项设置为 on 时，允许键引用的非链接元素显示在插入下拉列表中。
• 当编辑 DITA 文档时，分配有键引用的空元素显示以括号括起的键引用名称：
请注意，仅 DITA 文档的默认样式表中的非链接元素对此支持。仅当在 Arbortext Editor 中编辑文档时，键引用名称才出现。发布文档时其不会出现。
通过主题引用使用键引用
当主题引用包含键引用时，topicmeta 元素中的某些信息与键定义中的相似信息可能冲突。topicref 元素包含 topicmeta 元素作为键定义。当将 topicref 的 topicmeta 内容与键引用和引用的键定义合并时，遵照以下规则：
• topicref 元素的 locktitle 属性遵循键定义的 locktitle 属性。
• 键定义中的其他元数据覆盖 topicref 元素中的相同元数据。
• 保留 topicref 元素中与键定义中元数据不匹配的所有元数据。
