本頁面由 Cloud Translation API 翻譯而成。

小工具：目錄

<devsite-catalog> 自訂元素提供可篩選的動態內容，其中包含一個平台的篩選 UI。這會在 DevSite 頁面上查詢 DevSite 擁有的內容，以載入與特定主題相關的資源。這項自訂元素可載入任何 DevSite 用戶群的資源，以及已新增至 DevSite 外部內容語料庫的外部資源。

用量

如要開始使用 <devsite-catalog> 自訂元素，請按照下列指示操作：

新增自訂元素

在網頁中的目標位置新增 <devsite-catalog> 自訂元素。

HTML

針對 HTML 網頁，新增自訂元素的方式和任何其他 HTML 元素一樣：

<devsite-catalog query="project_url:/devsite"></devsite-catalog>

YAML

如要在到達網頁列中加入自訂元素相關額外內容，請使用單一項目列，並提供到達網頁列選項中的 description-100 選項。

rows:
- options:
  - description-100
  heading: Row-level heading
  description: >
    Row-level description with an overview of the catalog.
  items:
  - heading: Catalog heading
    description: >
      <p>Additional lead-in copy.</p>
      <devsite-catalog query="project_url:/devsite"></devsite-catalog>

如果您不需要任何其他項目層級欄位 (例如 heading 或 description)，也可以使用 custom_html 欄位：

rows:
- custom_html: >
    <devsite-catalog query="project_url:/devsite"></devsite-catalog>

Markdown

若是 Markdown 檔案，自訂元素必須納入在 <div> 或 <section> 元素中：

<div>
  <devsite-catalog query="project_url:/devsite"></devsite-catalog>
</div>

區隔資料集

決定一個動態內容查詢，將您想提供給目錄的完整資料集區隔開來，並新增至新目錄中的查詢屬性。

舉例來說，如要將 developers.google.com 列出的所有產品新增至你的網頁，請在網頁中加入下列目錄。

<devsite-catalog query="type:product"></devsite-catalog>

新增篩選器

如要在目錄中加入篩選器，請針對下列每個選項分別按照下列指示操作：

「文字輸入」方塊側邊核取方塊篩選器專區

文字輸入篩選器

新增輸入框，在使用者輸入文字時篩選結果。篩選方塊會比對每筆結果的標題、說明和關鍵字中的使用者文字。

<devsite-catalog query="type:product">
  <input type="text" placeholder="Filter results">
</devsite-catalog>

核取方塊篩選器

在 <devsite-catalog> 元素中，為每個可篩選維度 (例如文件類型、產品和程式設計語言) 加入 <select> 元素。name 屬性會決定篩選維度，對應於結構化關鍵字命名空間或 DevSite 欄位名稱 (例如 keywords)。使用標籤屬性為讀者指定維度標籤。此外，請務必為每個 <select> 元素指定多個屬性，確保產生的篩選器 UI 正確無誤。

在父項 <select> 元素的指定維度中，為每個篩選器值新增 <option> 元素。在每個 <option> 的值屬性中指定可篩選的值。在 <option> 標記之間加入可理解的篩選器標籤。而這些內容都會經過本地化

下列程式碼會在搜尋結果側邊的篩選 UI 中，加入一部分的文件類型篩選器和關鍵字篩選器：

<devsite-catalog query="project_url:/devsite">
  <select name="doctype" label="Choose a content type" multiple>
    <option value="BestPractices">Best Practices</option>
    <option value="Blueprint">Blueprint</option>
    <option value="Concept">Concept</option>
    <option value="Pattern">Pattern</option>
    <option value="ReferenceArchitecture">Reference Architecture</option>
    <option value="Tutorial">Tutorial</option>
  </select>
  <select name="keywords" label="Choose a keyword" multiple>
    <option value="BestPractices">Best Practices</option>
    <option value="Blueprint">Blueprint</option>
    <option value="Concept">Concept</option>
    <option value="Pattern">Pattern</option>
    <option value="ReferenceArchitecture">Reference Architecture</option>
    <option value="Tutorial">Tutorial</option>
  </select>
</devsite-catalog>

初始核取方塊篩選器

initial-checkbox-filters 屬性決定了初始載入時顯示的數字核取方塊篩選器。預設值為 3。

<devsite-catalog query="project_url:/devsite" initial-checkbox-filters="5">
  ...
</devsite-catalog>

選取轉譯選項

<devsite-catalog> 支援動態內容小工具的所有轉譯選項和自訂元素屬性。

使用 fields 屬性指定要在目錄資訊卡中顯示的資料。除了 <devsite-dynamic-content> 記錄的 fields 外，您還可以指定任何記載的結構化關鍵字命名空間，來轉譯套用至該命名空間中每份文件的標記。舉例來說，如果指定 product，系統就會將該網頁資訊卡上的所有產品標記套用至該網頁。您也可以指定 tags，查看套用至文件的所有 Nomenclature 標記。

下列程式碼會設定上述範例，最多提供 1000 筆結果，這些結果包含數值的分頁 UI，以數字分頁 UI 排序，從 9 筆結果開始排序，每頁再增加 9 筆結果。系統會將結果設為資訊卡，其中包含標題、摘要和標籤為「瞭解詳情」的按鈕以及 product 和 api 的標記。

<devsite-catalog query="project_url:/devsite"
                 maxresults="1000"
                 sortorder="recency"
                 items-per-page="9"
                 fields="title summary product api"
                 pagination-type="numeric"
                 link-type="button"
                 button-label="Learn more"
                 template="card">
  <select name="doctype" label="Choose a content type" multiple>
    <option value="BestPractices">Best Practices</option>
    <option value="Blueprint">Blueprint</option>
    <option value="Concept">Concept</option>
    <option value="Pattern">Pattern</option>
    <option value="ReferenceArchitecture">Reference Architecture</option>
    <option value="Tutorial">Tutorial</option>
  </select>
  <select name="keywords" label="Choose a keyword" multiple>
    <option value="BestPractices">Best Practices</option>
    <option value="Blueprint">Blueprint</option>
    <option value="Concept">Concept</option>
    <option value="Pattern">Pattern</option>
    <option value="ReferenceArchitecture">Reference Architecture</option>
    <option value="Tutorial">Tutorial</option>
  </select>
</devsite-catalog>

如果您的團隊支援 UXE，您就可以為目錄資訊卡建立自訂範本，方法是在自訂元素中新增 Soy 範本，然後使用目錄上的範本屬性指定新的範本。

標記內容

內容必須根據篩選條件加上標記，才可進行篩選。您可以使用下列維度新增篩選器：

明確標記的結構化關鍵字 (非結構化) 關鍵字 page_type 根據 Nomenclature 圖表推斷出的結構化關鍵字大部分的核取方塊和選取樣式篩選器都會根據結構化關鍵字篩選內容，因為篩選器維度必須與結構化關鍵字命名空間相符，且篩選器值必須與結構化關鍵字的其餘部分相符。如要進一步瞭解結構化關鍵字和支援的命名空間，請參閱 Nomenclature 說明文件。

如要將網頁從所有目錄中隱藏，請在該頁面上將 hide_from_catalogs 中繼資料標記設為 true。

調整版面配置

如要變更預設欄版面配置 (template="activity" 項目的兩欄或三個欄)，請在屬性中加入 1、2、3 或 4 值。

<devsite-catalog items-across="2" query="type:product"></devsite-catalog>

隨著可視區域變窄，項目的版面配置也會隨之調整，確保內容仍可存取如果 items-across 值為 3 或 4，平板電腦的版面配置會切換為兩欄，且在行動裝置上，所有版面配置都會切換為單欄。

範例

以下範例呈現 <devsite-catalog> 自訂元素的基本功能外觀和功能。

雲端架構中心

以下是用於雲端架構中心的目錄範例。除了 title 和 summary 以外，它還在 fields 屬性中指定 product 和 api，以便為資訊卡新增這些命名空間的標記。

示範

查看原尺寸

<span class="devsite-heading" role="heading" aria-level="4">Source</span>

程式碼研究室目錄

以下的程式碼研究室目錄範例使用平面關鍵字、無編號的分頁，且不含文字篩選器輸入內容。

示範

查看原尺寸

預先套用的篩選器

Catalog 小工具會在網頁網址中追蹤使用者套用篩選器的狀態，方便您將特定篩選器設定加入書籤或分享。每個篩選器維度會以網址參數表示。網址參數的結構如下：

若是篩選器控制項含有單一值 (例如選取樣式篩選器)，網址參數值則是正規化的篩選器值。如果篩選器控制項支援核取方塊等多個值，網址參數值是以半形逗號分隔的標準化篩選器值清單。所有其他 (非篩選器) 網址參數則不受目錄小工具影響。舉例來說，如果使用者輸入「Big Data」接著，在文字篩選器中選取「Python」和「JavaScript」，網頁網址便會透過查詢字串「text=Big%20Data&language=python,javascript」反映這些篩選器。

當系統載入含有目錄小工具的網頁，並在網址中加入篩選器參數時，目錄小工具會預先填入相應的篩選器控制項及篩選結果。

舉例來說，Cloud 架構中心示範的網址如下：

https://developers.google.com/devsite/reference/widgets/catalog/architecture

以下是您可以附加至該網址的查詢字串範例：

?doctype=bestpractices 會勾選與 doctype 篩選器維度對應的「選擇內容類型」部分中的「最佳做法」核取方塊。 ?doctype=bestpractices,blueprint 會檢查同一部分中的「Best Practices」和「Blueprint」核取方塊。 ?text=Cloud%20SQL 在文字篩選器輸入內容中填入「Cloud SQL」。

您也可以合併篩選器參數維度。下列網址同時包含 doctype 和文字參數：

https://developers.google.com/devsite/reference/widgets/catalog/architecture?doctype=bestpractices%2Cblueprint&text=Cloud%20SQL

這個網址會選取適當的核取方塊並填入文字輸入內容，如以下示範所示。

查看原尺寸