الأدوات: الكتالوج

يوفّر العنصر <devsite-catalog> المخصّص محتوى ديناميكيًا قابل للفلترة يتضمّن واجهة مستخدم للفلترة على مستوى النظام الأساسي. تطلب الأداة محتوى يملكه تطبيق DevSite لتحميل الموارد ذات الصلة بموضوع معيّن على صفحة على DevSite. يمكن لهذا العنصر المخصّص تحميل موارد من أي مستأجر على DevSite بالإضافة إلى الموارد الخارجية التي تمت إضافتها إلى مجموعة المحتوى الخارجي على DevSite.

الاستخدام

لبدء استخدام العنصر المخصّص <devsite-catalog>، عليك اتّباع الخطوات التالية:

  1. إضافة العنصر المخصّص إلى صفحتك:
  2. اعزل مجموعة البيانات باستخدام طلب بحث ديناميكي.
  3. إضافة فلاتر
  4. تحديد خيارات العرض
  5. الإشارة إلى المنتجات في المحتوى
  6. ضبط التنسيق:

إضافة العنصر المخصص

أضف عنصر <devsite-catalog> المخصص إلى صفحتك في المكان المطلوب.

HTML

بالنسبة إلى صفحات HTML، يمكن إضافة العنصر المخصّص تمامًا مثل أي عنصر HTML آخر:

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

YAML

بالنسبة إلى صف الصفحة المقصودة الذي يتضمن محتوى إضافيًا مرتبطًا بالعنصر المخصّص، استخدِم صف عنصر واحد مع خيار الوصف 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>

ويمكنك أيضًا استخدام الحقل custom_html إذا لم تكن بحاجة إلى أيّ حقول أخرى على مستوى العنصر، مثل heading أو description:

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> لضمان صحة واجهة مستخدم الفلتر التي تم إنشاؤها.

أضِف عنصر <option> لكل قيمة فلتر في السمة المحدّدة على عنصر <select> الرئيسي. حدِّد القيمة القابلة للفلترة في سمة القيمة لكلّ <option>. أضِف تصنيفات فلاتر قابلة للقراءة بين علامات <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 لتحديد البيانات التي تريد عرضها على بطاقة الكتالوج. بالإضافة إلى fields الموثَّقة للنطاق <devsite-dynamic-content>، يمكنك تحديد أي من مساحات أسماء الكلمات الرئيسية المنظَّمة الموثَّقة لعرض العلامات المطبّقة على كل مستند في مساحة الاسم هذه. على سبيل المثال، عند تحديد product، سيتم عرض جميع علامات المنتجات على كل صفحة على البطاقة في تلك الصفحة. يمكنك أيضًا تحديد tags لعرض جميع علامات Nomenclature التي تم تطبيقها على المستند.

يضبط الرمز البرمجي التالي المثال أعلاه لتقديم 1,000 نتيجة كحد أقصى مرتّبة حسب مدى الحداثة مع واجهة مستخدم للتقسيم على صفحات رقمية تبدأ بـ 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)، يمكنك إنشاء نموذج مخصّص لبطاقات الكتالوج عن طريق إضافة نموذج فول الصويا الجديد إلى العنصر المخصّص وتحديد النموذج الجديد باستخدام سمة النموذج في الكتالوج الخاص بك.

الإشارة إلى المنتجات في المحتوى

لا يمكن فلترة المحتوى إلا إذا تم وضع علامة عليه وفقًا للفلاتر التي اخترتها. يمكنك إضافة فلاتر باستخدام السمات التالية:

الكلمات الرئيسية المنظَّمة التي تمّ وضع علامات عليها بشكلٍ صريح الكلمات الرئيسية (غير المنظَّمة) page_type الكلمات الرئيسية المنظَّمة المستنتَجة من الرسم البياني للتسمية وستعمل معظم فلاتر مربع الاختيار ونمط التحديد على تصفية المحتوى وفقًا للكلمات الرئيسية المنظمة، حيث يجب أن يطابق بُعد الفلتر مساحة اسم الكلمة الرئيسية المنظمة ويجب أن تتطابق قيمة الفلتر مع باقي الكلمة الرئيسية المنظمة. اطّلِع على مستندات Nomenclature للحصول على مزيد من المعلومات حول الكلمات الرئيسية المنظَّمة ومساحات الاسم المتوافقة.

ولإخفاء صفحة من كل الكتالوجات، اضبط علامة البيانات الوصفية light_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> المخصّص ووظائفها.

مركز بنية Google Cloud

في ما يلي مثال على الكتالوج المستخدَم في Cloud structure Center. بالإضافة إلى title وsummary، تحدد السمة product وapi في السمة fields لإضافة علامات لمساحات الاسم هذه إلى البطاقات.

عرض توضيحي

عرض بالحجم الكامل

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

كتالوج Codelabs

في ما يلي مثال على كتالوج الدروس التطبيقية حول الترميز باستخدام كلمات رئيسية مسطحة، والتقسيم على صفحات غير مرقّمة، وعدم إدخال فلاتر نصوص.

عرض توضيحي

عرض بالحجم الكامل

الفلاتر المطبَّقة مسبقًا

يتتبّع تطبيق "الكتالوج" المصغّر حالة الفلاتر التي يطبّقها المستخدم في عنوان URL الخاص بالصفحة، ما يتيح وضع إشارات مرجعية على إعدادات فلاتر معيّنة أو مشاركتها. يتم تمثيل كل سمة فلتر بمَعلمة عنوان URL. يتم تنظيم مَعلمات عناوين URL على النحو التالي:

بالنسبة إلى عناصر التحكّم في الفلاتر التي تحتوي على قيمة واحدة مثل فلاتر نمط الاختيار، تكون قيمة مَعلمة عنوان URL هي قيمة الفلتر التي تمّت تسويتها. بالنسبة إلى عناصر التحكّم في الفلاتر التي تتيح قيمًا متعدّدة مثل مربّعات الاختيار، تكون قيمة مَعلمة عنوان URL هي قائمة مفصولة بفواصل لقيم الفلاتر التي تمّت تسويتها. ولن تتأثر جميع معلمات عناوين URL الأخرى (التي لا تستخدم أي فلاتر) بأداة "الكتالوج". على سبيل المثال، إذا أدخل المستخدم "البيانات الضخمة" في فلتر النص وتحديد Python وJavaScript من مربعات اختيار اللغة، سيظهر عنوان URL للصفحة هذه الفلاتر من خلال سلسلة طلب البحث "text=Big%20Data&language=python,javascript".

عند تحميل صفحة تحتوي على التطبيق المصغَّر للكتالوج مع معلَمات فلاتر في عنوان URL، تملأ أداة "الكتالوج" مسبقًا عناصر التحكم في الفلتر المقابلة وتفلتر النتائج بشكل مناسب.

على سبيل المثال، في ما يلي عنوان URL للعرض التوضيحي لمركز بنية Cloud:

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

في ما يلي بعض الأمثلة على سلاسل طلبات البحث التي يمكنك إلحاقها بعنوان URL هذا:

تضع ?doctype=bestpractices علامة في مربّع الاختيار أفضل الممارسات في قسم اختيار نوع المحتوى الذي يتوافق مع سمة الفلتر doctype. تتحقق ?doctype=bestpractices,blueprint من كل من مربعي الاختيار أفضل الممارسات والمخطط في القسم نفسه. تتم تعبئة إدخال فلتر النص بـ "Cloud SQL" من خلال ?text=Cloud%20SQL.

يمكن أيضًا دمج سمات مَعلمات الفلتر. يحتوي عنوان URL التالي على المعلمة doctype والمعلمة النصية:

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

يحدِّد عنوان URL هذا مربّعات الاختيار المناسبة ويعبئ إدخال النص، كما هو موضَّح في العرض التوضيحي التالي.

عرض بالحجم الكامل