使用鍵與鍵參照
Arbortext Editor 為以鍵為基礎的參照提供支援，如 OASIS
DITA Architectural Specification 的
Key based (indirect) addressing 一節中所定義。
Arbortext Editor 使用者介面提供許多功能來協助您在 DITA 圖中定義金鑰定義，以及在圖與主題中插入金鑰參照。此外，
Arbortext Editor 還提供分項化的 DITA 圖，主要目的是僅包含名為
DITA 金鑰定義 map 的金鑰定義。此圖可讓您為金鑰定義提供額外資訊。
儲存金鑰定義的最佳工作模式，是使用一個 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 選項來建立用於金鑰定義的圖清單，這些金鑰定義顯示在插入金鑰參照對話方塊以及 Resource Manager 的 Keyref 選項中。與 ditakeycontext 不同，ditakeybaselist 是進階偏好設定，可包含多個圖，並持續存在於多個 Arbortext Editor 工作階段中。如果已將某個值指派給 ditakeybaselist，且該清單中沒有是目前 ditakeycontext 的 map，則會將金鑰前後關聯圖新增到目前工作階段的 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 元素的分項。在主題或 map 中具有 ID 的元素 (參照以 keyconrefs 定義的金鑰名稱)，會在插入鍵參照對話方塊中顯示為 conkeyref 參照的目標。此元素的 scope 屬性將被設定為 local。format 屬性將被設定為 dita (預設) 或 ditamap。
此元素也包括新的 keyinfo 元素及其所有子元素。如果您將某個值指派給 keyconrefs 定義中的 keysubelementid 元素，則只有具有該特定 ID 的元素可用於使用該定義的內容金鑰參照。否則，所有具有 ID 的元素都可供使用。
• keyforconrefs - 指示某一金鑰定義屬於某一內容金鑰參照。
此元素包含在 keyinfo 元素中。若 keyforconrefs 元素的 value 屬性設定為 true (預設)，則指示此金鑰定義屬於某一內容金鑰參照，並且會像在插入鍵參照對話方塊中一樣來處理它。這可以讓您使用 keydef 及 圖中的其他元素來定義內容金鑰參照的金鑰定義。
使用 DITA 金鑰定義圖，可對內容金鑰定義進行設定，以使單一元素可用於內容金鑰參照，或具有 ID 的所有元素皆可供使用。若要使單一元素可用於插入鍵參照對話方塊中的 conkeyref 參照，必須在 DITA 金鑰定義圖中使用下列標示定義它：
• 金鑰定義的 href 屬性必須指向包含元素的主題或圖。
元素的 ID 不得包括在 href 中。
• 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 元素擁有包含文字以進行文字插入之鍵定義的鍵參照，則會在發行期間將該文字插入 image 中作為 alt 元素。
• 不允許文字內容的元素
某些 DITA 元素 (例如 longdescref) 包含 keyref 屬性，但不允許文字內容。這些元素無法用於透過鍵參照插入文字。
Arbortext Editor 使用者介面提供下列功能，以支援使用鍵參照插入文字：
• 鍵參照資訊對話方塊提供
文字選項，可顯示鍵定義中提供的文字內容，其中包括任何標示。
• 插入鍵參照對話方塊會在
資源欄中顯示鍵定義的文字內容，其中包括標示。
同時，當將 ditatextkeyrefs 進階偏好設定設為 on 時，允許鍵參照的非連結元素會顯示在插入下拉式清單中。
• 已指派鍵參照的空白元素會在編輯 DITA 文件時顯示括在括弧中之鍵參照的名稱。
請注意，只有 DITA 文件預設樣式表中的非連結元素才支援此功能。鍵參照名稱只會在於 Arbortext Editor 中編輯文件時顯示出來。它不會在發行文件時顯示出來。
同時使用鍵參照與主題參照
當主題參照包含鍵參照時，topicmeta 元素中的某些資訊可能與鍵定義中的相似資訊衝突。topicref 元素包含 topicmeta 元素，鍵定義也是如此。將 topicref 的 topicmeta 內容與鍵參照和參照的鍵定義合併時，會遵循下列規則：
• topicref 元素的 locktitle 屬性重視度高於鍵定義的 locktitle 屬性。
• 鍵定義中的其他中繼資料會取代 topicref 元素中的相同中繼資料。
• 而 topicref 元素中與鍵定義中的中繼資料不符的任何中繼資料都會得到保留。
