此页面由 Cloud Translation API 翻译。

微件：目录

<devsite-catalog> 自定义元素提供可过滤的动态内容，其中包括整个平台的过滤界面。它会查询 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> 元素指定多个属性，以确保生成的过滤器界面正确无误。

在父 <select> 元素上，为指定维度中的每个过滤条件值添加 <option> 元素。在每个 <option> 的 value 属性中指定可过滤值。在 <option> 标记之间添加可读的过滤条件标签；如果您的网页已本地化，这些内容将会翻译。

以下代码在过滤界面中的结果一侧添加了文档类型过滤条件和关键字过滤条件部分：

<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 个按新近度排序的结果，并采用数字分页界面，每页以 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 根据命名法图表推断出的结构化关键字大多数复选框和 select-style 过滤器都会根据结构化关键字过滤内容，其中过滤器维度必须与结构化关键字命名空间匹配，并且过滤值必须与结构化关键字的其余部分匹配。如需详细了解结构化关键字和支持的命名空间，请参阅“命名法”文档。

若要在所有目录中隐藏某个网页，请将该网页上的 hide_from_catalogs 元数据标记设为 true。

调整布局

如需更改默认列布局（template="activity" 项为两列，否则为三列），请添加 items-cross 属性，并将其值设为 1、2、3 或 4。

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

当视口变窄时，系统会调整列表项的布局，以确保列表项的仍然可供访问如果 items-across 值为 3 或 4，则布局会在平板电脑上切换为两列，而所有布局在移动设备上会切换为单列。

示例

以下示例展示了 <devsite-catalog> 自定义元素基本功能的外观和功能。

云架构中心

以下是用于 Cloud Architecture Center 的目录示例。除了 title 和 summary 之外，它还在 fields 属性中指定了 product 和 api，以将这些命名空间的标记添加到卡片中。

演示

查看完整尺寸

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

Codelab 目录

以下示例展示了使用平面关键字、无编号分页和无文本过滤条件输入的 Codelab 目录。

演示

查看完整尺寸

预先应用的过滤条件

目录微件可跟踪页面网址中用户应用的过滤条件的状态，允许将特定过滤条件配置添加为书签或进行共享。每个过滤器维度都由一个网址参数表示。网址参数的结构如下所示：

对于选择样式过滤器等具有单个值的过滤器控件，网址参数值是标准化过滤器值。对于支持复选框等多个值的过滤器控件，网址参数值是一系列以英文逗号分隔的标准化过滤器值。所有其他（非过滤器）网址参数不受目录微件的影响。例如，如果用户输入“Big Data”输入文本过滤器，并从“语言”复选框中选中了 Python 和 JavaScript，则页面网址会反映这些带有查询字符串“text=Big%20Data&language=python,javascript”的过滤器。

如果通过网址中的过滤器参数加载了包含 Catalogs 微件的页面，Catalogs 微件会相应地预先填充相应的过滤器控件并过滤结果。

例如，以下是 Cloud Architecture Center 演示的网址：

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

以下是一些您可以附加到该网址的查询字符串示例：

?doctype=bestpractices 勾选了选择内容类型部分中的最佳实践复选框，该部分与 doctype 过滤条件维度相对应。 ?doctype=bestpractices,blueprint 会在同一部分中同时勾选最佳实践和 Blueprint 复选框。 ?text=Cloud%20SQL 会使用“Cloud SQL”填充文本过滤条件输入。

您还可以组合使用过滤器参数的维度。以下网址包含 doctype 和 text 参数：

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

此网址会选中适当的复选框并填充文本输入，如以下演示所示。

查看完整尺寸