Tiện ích: Danh mục

Phần tử tuỳ chỉnh <devsite-catalog> cung cấp nội dung động có thể lọc, trong đó có giao diện người dùng lọc trên toàn nền tảng. Công cụ này truy vấn nội dung do DevSite sở hữu để tải các tài nguyên có liên quan đến một chủ đề cụ thể trên trang DevSite. Phần tử tuỳ chỉnh này có thể tải tài nguyên từ bất kỳ đối tượng thuê DevSite nào cũng như tài nguyên bên ngoài đã được thêm vào kho nội dung bên ngoài của DevSite.

Cách sử dụng

Để bắt đầu sử dụng phần tử tuỳ chỉnh <devsite-catalog>, hãy làm như sau:

  1. Thêm phần tử tuỳ chỉnh vào trang của bạn.
  2. Tách tập dữ liệu bằng truy vấn Nội dung động.
  3. Thêm bộ lọc.
  4. Chọn chế độ kết xuất.
  5. Gắn thẻ cho nội dung của bạn.
  6. Điều chỉnh bố cục.

Thêm phần tử tuỳ chỉnh

Thêm phần tử tuỳ chỉnh <devsite-catalog> vào trang của bạn ở vị trí bạn muốn.

HTML

Đối với các trang HTML, bạn có thể thêm phần tử tuỳ chỉnh giống như bất kỳ phần tử HTML nào khác:

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

YAML

Đối với hàng trang đích có nội dung bổ sung liên quan đến phần tử tuỳ chỉnh, hãy sử dụng hàng chứa một mặt hàng có lựa chọn description-100 trong tuỳ chọn hàng trên trang đích.

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>

Bạn cũng có thể sử dụng trường custom_html nếu không cần bất kỳ trường nào khác ở cấp mặt hàng như heading hoặc description:

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

Markdown

Đối với các tệp Markdown, phần tử tuỳ chỉnh phải được gói trong một phần tử <div> hoặc <section>:

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

Tách biệt tập dữ liệu

Xác định Truy vấn nội dung động để tách riêng tập dữ liệu đầy đủ mà bạn muốn cung cấp cho danh mục của mình rồi thêm tập dữ liệu đó vào thuộc tính truy vấn trên danh mục mới.

Ví dụ: để thêm danh mục của tất cả các sản phẩm được liệt kê trên developer.google.com vào trang, hãy thêm danh mục sau vào trang.

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

Thêm bộ lọc

Để thêm bộ lọc vào danh mục của bạn, hãy làm theo các hướng dẫn bên dưới cho từng lựa chọn sau:

Ô nhập văn bản Một mục gồm các bộ lọc hộp đánh dấu ở bên cạnh

Bộ lọc nhập văn bản

Thêm một ô nhập dữ liệu để lọc kết quả khi người dùng nhập văn bản. Hộp lọc sẽ khớp với văn bản của người dùng trong tiêu đề, nội dung mô tả và từ khoá của từng kết quả.

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

Bộ lọc hộp đánh dấu

Trong phần tử <devsite-catalog>, hãy thêm một phần tử <select> cho mọi phương diện có thể lọc, chẳng hạn như loại tài liệu, sản phẩm và ngôn ngữ lập trình. Thuộc tính name xác định phương diện lọc, tương ứng với không gian tên từ khoá có cấu trúc hoặc tên trường DevSite (chẳng hạn như keywords). Chỉ định một nhãn kích thước cho độc giả bằng thuộc tính nhãn. Hãy nhớ chỉ định nhiều thuộc tính cho mỗi phần tử <select> để đảm bảo giao diện người dùng của bộ lọc đã tạo là chính xác.

Thêm một phần tử <option> cho mỗi giá trị bộ lọc trong phương diện đã chỉ định trên phần tử <select> mẹ. Hãy chỉ định giá trị có thể lọc trong thuộc tính giá trị trên mỗi <option>. Thêm nhãn bộ lọc có thể đọc được vào giữa các thẻ <option>; những nội dung này sẽ được dịch nếu trang của bạn được bản địa hoá.

Mã sau đây thêm một phần bộ lọc loại tài liệu và bộ lọc từ khoá trong giao diện người dùng lọc vào bên cạnh kết quả:

<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>

Bộ lọc hộp đánh dấu ban đầu

Thuộc tính initial-checkbox-filters xác định các bộ lọc hộp đánh dấu số để hiển thị trong lần tải đầu tiên. Mặc định là 3.

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

Chọn tuỳ chọn kết xuất

<devsite-catalog> hỗ trợ mọi tuỳ chọn kết xuất hình ảnh và thuộc tính phần tử tuỳ chỉnh cho tiện ích Nội dung động.

Dùng thuộc tính fields để chỉ định dữ liệu bạn muốn giới thiệu trên thẻ danh mục. Ngoài fields trong tài liệu về <devsite-dynamic-content>, bạn có thể chỉ định bất kỳ không gian tên từ khoá có cấu trúc nào được lập tài liệu để kết xuất các thẻ áp dụng cho từng tài liệu trong không gian tên đó. Ví dụ: nếu bạn chỉ định product thì tất cả các thẻ sản phẩm áp dụng cho mỗi trang sẽ xuất hiện trên thẻ cho trang đó. Bạn cũng có thể chỉ định tags để xem tất cả các thẻ Danh pháp được áp dụng cho tài liệu.

Mã sau đây định cấu hình ví dụ trên để cung cấp tối đa 1.000 kết quả được sắp xếp theo số ngày gần đây với giao diện người dùng phân trang bằng số bắt đầu bằng 9 kết quả và 9 kết quả bổ sung trên mỗi trang. Tính năng này định cấu hình kết quả hiển thị dưới dạng thẻ có tiêu đề, bản tóm tắt và nút được gắn nhãn "Tìm hiểu thêm" cũng như các thẻ cho product và 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>

Nếu nhóm của bạn có hỗ trợ về trải nghiệm người dùng, bạn có thể tạo một mẫu tuỳ chỉnh cho thẻ danh mục bằng cách thêm mẫu Soy mới vào phần tử tuỳ chỉnh và chỉ định mẫu mới bằng thuộc tính mẫu trong danh mục của mình.

Gắn thẻ cho nội dung của bạn

Chỉ có thể lọc nội dung nếu nội dung đó được gắn thẻ theo bộ lọc của bạn. Bạn có thể thêm bộ lọc bằng cách sử dụng các phương diện sau:

từ khóa có cấu trúc được gắn thẻ rõ ràng từ khóa (không có cấu trúc) page_type từ khoá có cấu trúc được suy ra từ Biểu đồ danh pháp Hầu hết các bộ lọc kiểu chọn lọc và hộp đánh dấu sẽ lọc nội dung theo từ khoá có cấu trúc, trong đó phương diện bộ lọc phải khớp với không gian tên của từ khoá có cấu trúc và giá trị bộ lọc phải khớp với phần còn lại của từ khoá có cấu trúc. Xem tài liệu Danh mục để biết thêm thông tin về từ khoá có cấu trúc và không gian tên được hỗ trợ.

Để ẩn một trang khỏi tất cả các danh mục, hãy đặt thẻ siêu dữ liệu hide_from_catalogs thành true trên trang đó.

Điều chỉnh bố cục

Để thay đổi bố cục cột mặc định (là 2 cột cho template="activity" hoặc 3 cột), hãy thêm thuộc tính items-across có giá trị là 1, 2, 3 hoặc 4.

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

Khi khung nhìn ngày càng thu hẹp, bố cục của các mục sẽ điều chỉnh để đảm bảo mục nội dung vẫn có thể truy cập được. Đối với các giá trị items-across của 3 hoặc 4, bố cục chuyển sang hai cột trên máy tính bảng và tất cả bố cục đều chuyển thành một cột duy nhất trên thiết bị di động.

Ví dụ

Sau đây là ví dụ minh hoạ giao diện và chức năng của các tính năng cơ bản của phần tử tuỳ chỉnh <devsite-catalog>.

Trung tâm kiến trúc đám mây

Sau đây là ví dụ về danh mục được dùng cho Trung tâm kiến trúc đám mây. Ngoài title và summary, thành phần này còn chỉ định product và api trong thuộc tính fields để thêm thẻ cho các không gian tên này vào thẻ.

Bản minh hoạ

Xem kích thước đầy đủ

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

Danh mục của lớp học lập trình

Sau đây là ví dụ về danh mục các lớp học lập trình sử dụng từ khoá phẳng, phân trang không được đánh số và không nhập bộ lọc văn bản.

Bản minh hoạ

Xem kích thước đầy đủ

Bộ lọc được áp dụng trước

Tiện ích Danh mục theo dõi trạng thái của các bộ lọc mà người dùng áp dụng trong URL trang, cho phép đánh dấu hoặc chia sẻ các cấu hình bộ lọc cụ thể. Mỗi phương diện bộ lọc được biểu thị bằng một tham số URL. Các tham số URL có cấu trúc như sau:

Đối với các chế độ kiểm soát bộ lọc có một giá trị như bộ lọc kiểu được chọn, giá trị tham số URL là giá trị bộ lọc chuẩn hoá. Đối với các chế độ kiểm soát bộ lọc hỗ trợ nhiều giá trị như hộp đánh dấu, thì giá trị tham số URL là danh sách các giá trị bộ lọc được chuẩn hoá được phân tách bằng dấu phẩy. Tất cả các tham số URL khác (không phải bộ lọc) không chịu ảnh hưởng của tiện ích Danh mục. Ví dụ: nếu người dùng đã nhập "Dữ liệu lớn" vào bộ lọc văn bản và chọn Python và JavaScript từ hộp đánh dấu Ngôn ngữ, URL trang phản ánh các bộ lọc đó với chuỗi truy vấn 'text=Big%20Data&language=python,javascript'.

Khi một trang có chứa tiện ích Danh mục được tải với các tham số bộ lọc trong URL, tiện ích Danh mục sẽ điền sẵn các chế độ kiểm soát bộ lọc tương ứng và lọc kết quả một cách phù hợp.

Ví dụ: sau đây là URL của bản minh hoạ Trung tâm kiến trúc đám mây:

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

Dưới đây là một số ví dụ về chuỗi truy vấn mà bạn có thể thêm vào URL đó:

?doctype=bestpractices kiểm tra hộp đánh dấu Các phương pháp hay nhất trong phần Chọn loại nội dung, tương ứng với phương diện bộ lọc doctype. ?doctype=bestpractices,blueprint kiểm tra cả hai hộp đánh dấu Các phương pháp hay nhất và Bản vẽ trong cùng một phần. ?text=Cloud%20SQL sẽ điền "Cloud SQL" vào mục nhập bộ lọc văn bản.

Bạn cũng có thể kết hợp các phương diện tham số bộ lọc. URL sau đây chứa cả tham số loại tài liệu và văn bản:

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

URL này chọn các hộp đánh dấu thích hợp và điền sẵn nội dung nhập văn bản, như minh hoạ trong bản minh hoạ sau đây.

Xem kích thước đầy đủ