Programmable Search Element Control API

يمكنك تضمين مكوّنات محرك البحث المبرمَج (مربّعات البحث وصفحات نتائج البحث) في صفحات الويب الخاصة بك وتطبيقات الويب الأخرى باستخدام ترميز HTML. محرك البحث المبرمج هذا من العناصر تتكون من مكونات يتم عرضها بناءً على الإعدادات المخزنة بواسطة خادم "البحث المبرمَج"، بالإضافة إلى أي عمليات تخصيص تجريها

يتم تحميل كل ملفات JavaScript بشكل غير متزامن، الأمر الذي يتيح لصفحة الويب مواصلة التحميل أثناء استرجاع المتصفِّح لمحتوى JavaScript الخاص بـ "محرك البحث المبرمَج"

Introduction

يعرض هذا المستند نموذجًا أساسيًا لإضافة "محرك البحث المبرمَج". إلى صفحة الويب الخاصة بك، إلى جانب شروحات مكونات قابلة للتهيئة وواجهة برمجة تطبيقات JavaScript مرنة.

المستوى

توضح هذه الوثيقة كيفية استخدام الدوال والخصائص الخاصة واجهة برمجة التطبيقات للتحكّم في محرك البحث المبرمَج

توافُق المتصفّح

يمكن العثور على قائمة المتصفِّحات المتوافقة مع "محرك البحث المبرمَج" هنا.

الجمهور

هذا المستند مخصّص للمطوّرين الذين يريدون إضافة Google Programmable. وظائف البحث على صفحاتهم.

عناصر البحث القابلة للبرمجة

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

• طلب بحث مكتوب في حقل إدخال النص
• سلسلة طلب بحث مضمّنة في عنوان URL
• التنفيذ الآلي

بالإضافة إلى ذلك، يقبل حظر نتائج البحث الإدخال في الطرق التالية:

• سلسلة طلب بحث مضمّنة في عنوان URL
• التنفيذ الآلي

تتوفّر الأنواع التالية من "عناصر البحث المبرمَجة":

يمكنك إضافة أي عدد من "عناصر البحث" الصالحة إلى صفحة الويب. للعمودين وضع، وجميع المكونات المطلوبة (مربع بحث كتلة نتائج) موجودة.

إليك مثال على عنصر بحث بسيط:

<!-- Put the following javascript before the closing </head> tag
and replace 123456 with your own Programmable Search Engine ID. -->
<script async src="https://cse.google.com/cse.js?cx=123456"></script>

<!-- Place this tag where you want both of the search box and the search results to render -->
<div class="gcse-search"></div>

إنشاء خيارات تنسيق مختلفة باستخدام "عناصر البحث المبرمَجة"

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

مزيد من المعلومات حول خيارات التنسيق

تخصيص عناصر البحث القابلة للبرمجة

لتخصيص الألوان أو الخط أو نمط الرابط، انتقِل إلى صفحة الشكل والمظهر في محرك البحث المبرمج.

يمكنك استخدام السمات الاختيارية لاستبدال الإعدادات التي تم إنشاؤها في محرك البحث المبرمَج لوحة التحكم. يتيح لك ذلك إنشاء تجربة بحث خاصة بصفحة معيّنة. على سبيل المثال، تُنشئ التعليمة البرمجية التالية مربع بحث يفتح صفحة نتائج (http://www.example.com?search=lady+gaga) في نافذة جديدة. تحدد قيمة السمة queryParameterName، مع سلسلة طلب بحث المستخدم، المستخدم لإنشاء عنوان URL للنتائج.

يُرجى العِلم أنّ السمة queryParameterName تكون مسبوقة بالرمز data-. هذه البادئة مطلوبة لجميع السمات.

<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">

إذا كنت قد استخدمت لوحة تحكّم "محرك البحث المبرمَج" لتفعيل ميزات مثل الإكمال التلقائي أو التحسينات، يمكنك استخدام السمات تخصيص تلك الميزات. أي عمليات تخصيص تحدّدها باستخدام هذه السمات سيؤدي إلى إلغاء الإعدادات التي تم إجراؤها في لوحة التحكم. ينشئ المثال التالي عنصر بحث مؤلف من عمودين مع الميزات التالية:

• إدارة السجلّ مفعَّلة
• تم ضبط الحد الأقصى لعدد عمليات الإكمال التلقائي المعروضة على 5.
• يتم عرض التحسينات في شكل روابط.

<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5">
<div class="gcse-searchresults" data-refinementStyle="link">

السمات المتوافقة

<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

طلبات معاودة الاتصال

تتيح عمليات معاودة الاتصال التحكم التفصيلي في إعداد عنصر البحث وعمليات البحث. يتم تسجيلها باستخدام JavaScript لعنصر البحث من خلال __gcse الشاملة. الخاص بك. يوضّح تسجيل معاودة الاتصال تسجيل جميع والاستدعاءات المتوافقة.

  window.__gcse = {
    parsetags: 'explicit', // Defaults to 'onload'
    initializationCallback: myInitializationCallback,
    searchCallbacks: {
      image: {
        starting: myImageSearchStartingCallback,
        ready: myImageResultsReadyCallback,
        rendered: myImageResultsRenderedCallback,
      },
      web: {
        starting: myWebSearchStartingCallback,
        ready: myWebResultsReadyCallback,
        rendered: myWebResultsRenderedCallback,
      },
    },
  };
  

معاودة الاتصال للإعداد

يتم استدعاء استدعاء الإعداد قبل عرض JavaScript لعنصر البحث والعناصر في DOM. إذا تم ضبط parsetags على explicit في __gcse، يترك عنصر JavaScript عنصر البحث عرض عناصر البحث على معاودة الاتصال للإعداد (كما هو موضح في تسجيل معاودة الاتصال). ويمكن استخدام هذا لتحديد العناصر لعرضها أو لتأجيل عناصر العرض حتى احتاجت. ويمكنها أيضًا تجاوز سمات العناصر؛ على سبيل المثال، يمكنها تحويل مربع البحث الذي يتم تكوينه من خلال سمات لوحة التحكم أو HTML على الوضع الافتراضي البحث في مربّع بحث صور، أو تحديد أنّ طلبات البحث التي يتم إرسالها من خلال نموذج "محرك البحث المبرمَج" تنفيذه في عنصر searchresults فقط. مشاهدة عرض توضيحي

يتم التحكّم في دور استدعاء الإعداد من خلال قيمة parsetags. الخاصة بـ __gcse.

• إذا كانت قيمتها onload، يتم عرض عنصر البحث يعرض JavaScript جميع عناصر البحث على الصفحة تلقائيًا. استدعاء الإعداد هو حتى الآن، لكنها ليست مسؤولة عن عرض عناصر البحث.
• إذا كانت قيمتها هي explicit، لن يتم عرض JavaScript لعنصر البحث. عناصر البحث قد تعرضها معاودة الاتصال بشكل انتقائي باستخدام render()، أو عرض جميع عناصر البحث باستخدام الدالة go()

توضح التعليمة البرمجية التالية كيفية عرض مربع بحث، مع نتائج البحث، في div، باستخدام علامة التحليل explicit واستدعاء الإعداد:

    <div id="test"></div>

const myInitCallback = function() {
  if (document.readyState == 'complete') {
    // Document is ready when Search Element is initialized.
    // Render an element with both search box and search results in div with id 'test'.
    google.search.cse.element.render(
        {
          div: "test",
          tag: 'search'
         });
  } else {
    // Document is not ready yet, when Search Element is initialized.
    google.setOnLoadCallback(function() {
       // Render an element with both search box and search results in div with id 'test'.
        google.search.cse.element.render(
            {
              div: "test",
              tag: 'search'
            });
    }, true);
  }
};

// Insert it before the Search Element code snippet so the global properties like parsetags and callback
// are available when cse.js runs.
window.__gcse = {
  parsetags: 'explicit',
  initializationCallback: myInitCallback
};

<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>

البحث عن طلبات معاودة الاتصال

يدعم JavaScript عنصر البحث ست استدعاءات تعمل في عملية التحكّم في البحث تأتي استدعاءات البحث على شكل أزواج، ومعاودة اتصال لبحث الويب ومعاودة اتصال مطابقة للبحث بالصور:

• بدء البحث
  • للبحث بالصور
  • لبحث الويب
• النتائج جاهزة
  • للبحث بالصور
  • لبحث الويب
• تمّ عرض النتائج
  • للبحث بالصور
  • لبحث الويب

مثل استدعاء الإعداد، يتم وصف استدعاءات البحث باستخدام إدخالات في الكائن __gcse. ويحدث هذا عندما يتم عرض عنصر البحث بدء تشغيل JavaScript. ويتم تجاهل التعديلات على __gcse بعد بدء التشغيل.

يتم اجتياز كل من عمليات معاودة الاتصال هذه وتجاوز gName عنصر البحث كوسيطة. ويمكن الاستفادة من gname عندما تحتوي الصفحة على أكثر من عملية بحث واحدة. إجراء بحث العنصر gname باستخدام السمة data-gname:

<div class="gcse-searchbox" data-gname="storesearch"></div>

إذا لم يحدد HTML الاسم gname، فإن JavaScript لعنصر البحث تنشئ قيمةً متسقة حتى يتم تعديل HTML.

معاودة الاتصال لبدء بحث الصور/الويب

يتم استدعاء استدعاءات بدء البحث مباشرةً قبل طلبات JavaScript لعنصر البحث نتائج البحث من خادمها. من الأمثلة على حالة الاستخدام هي استخدام التوقيت المحلي من اليوم التحكم في التغييرات على الاستعلام.

searchStartingCallback(gname, query)

gname

سلسلة تعريف عنصر البحث

query

القيمة التي أدخلها المستخدم (ربما تم تعديلها من خلال البحث عنصر JavaScript).

تعرض دالة الاستدعاء القيمة التي يجب استخدامها كطلب البحث لهذا البحث. إذا أرجعت سلسلة فارغة، يتم تجاهل القيمة المعروضة ويستخدم المتصل طلب البحث غير المعدل.

بدلاً من ذلك، يمكنك وضع دالة رد الاتصال في كائن __gcse أو إضافة الاستدعاء ديناميكيًا إلى الكائن باستخدام JavaScript:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};

مثال على بدء معاودة الاتصال بعد البحث

مثال على عملية البحث التي تبدأ معاودة الاتصال في مثال على بدء معاودة الاتصال عند بدء البحث يضيف إما morning أو afternoon إلى طلب البحث اعتمادًا على الوقت من اليوم.

    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

تثبيت معاودة الاتصال هذه في window.__gcse:

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      image: {
        starting: 'myImageSearchStartingCallbackName',
      },
      web: {
        starting: myWebSearchStartingCallback,
      },
    };
  

  <script
  async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

معاودة الاتصال الجاهزة للإعلان عن الصور/نتائج بحث الويب

ويتم استدعاء هذه الاستدعاءات مباشرةً قبل أن يعرض JavaScript عنصر البحث العروض الترويجية نتائجك. من الأمثلة على حالة الاستخدام هذه استدعاء يعرض الإعلانات الترويجية وينتج عنها نمط لا يمكن تحديدها بالتخصيص العادي.

resultsReadyCallback(gname, query, promos, results, div)

gname

سلسلة تعريف عنصر البحث

query

طلب البحث الذي أدّى إلى هذه النتائج

promos

مصفوفة من عناصر الترويج، تتجاوب مع العناصر المتطابقة العروض الترويجية طلب بحث المستخدم. اطّلِع على تعريف عنصر العرض الترويجي.

results

مصفوفة من كائنات النتائج. يمكنك الاطّلاع على تعريف عنصر النتيجة:

div

عنصر div HTML يتم وضعه في DOM حيث عادةً ما يتم وضع عنصر البحث الحملات الترويجية ونتائج البحث عن الأماكن. وعادةً ما تتعامل عناصر JavaScript مع عنصر البحث تعبئة عنصر div هذا، ولكن قد تختار معاودة الاتصال هذه إيقاف العرض التلقائي للنتائج ويمكنك استخدام div هذا لعرض النتائج نفسها.

إذا عرض رد الاستدعاء هذا قيمة true، سيتم تخطي JavaScript لعنصر البحث إلى عمل تذييل الصفحة.

أمثلة على معاودة الاتصال الجاهزة للنتائج

مثال على معاودة الاتصال resultsReady في يؤدي مثال على معاودة الاتصال الجاهزة للنتائج إلى إلغاء العرض التقديمي التلقائي من العروض الترويجية والنتائج مع الاستبدال بسيط للغاية.

    const myResultsReadyCallback = function(name, q, promos, results, resultsDiv) {
      const makePromoElt = (promo) => {
        const anchor = document.createElement('a');
        anchor.href = promo['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs-title');
        const span = document.createElement('span');
        span.innerHTML = 'Promo: ' + promo['title'];
        anchor.appendChild(span);
        return anchor;
      };
      const makeResultParts = (result) => {
        const anchor = document.createElement('a');
        anchor.href = result['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs_title');
        anchor.appendChild(document.createTextNode(result['visibleUrl']));
        const span = document.createElement('span');
        span.innerHTML = ' ' + result['title'];
        return [anchor, span];
      };

      const table = document.createElement('table');
      if (promos) {
        for (const promo of promos) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          cell.appendChild(makePromoElt(promo));
        }
        resultsDiv.appendChild(table);
        resultsDiv.appendChild(document.createElement('br'));
      }
      if (results) {
        const table = document.createElement('table');
        for (const result of results) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          const [anchor, span] = makeResultParts(result);
          cell.appendChild(anchor);
          const cell2 = row.insertCell(-1);
          cell2.appendChild(span);
        }
        resultsDiv.appendChild(table);
      }
      return true;
    };

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      web: {
        ready: myResultsReadyCallback,
      },
    };

  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

معاودة الاتصال معروضة ضمن نتائج بحث الويب أو الصور

يتم استدعاء هذه الاستدعاءات مباشرةً قبل أن يعرض JavaScript لعنصر البحث الصفحة تذييل. قد تتضمن أمثلة حالات الاستخدام معاودة الاتصال التي تضيف محتوى النتيجة الذي يضيفه لا يتم عرضه مثل مربع الاختيار حفظ هذا أو المعلومات غير يتم عرضه تلقائيًا، أو استدعاء يضيف أزرارًا لمزيد من المعلومات.

إذا كانت النتائج المعروضة تحتاج إلى معلومات كانت في promos results مَعلمات دالّة الاتصال الجاهزة للنتائج، يمكنها تمرير تلك المَعلمات بينها، على النحو التالي:

callback(gname, query, promoElts, resultElts);

gname

سلسلة تعريف عنصر البحث

query

سلسلة بحث.

promoElts

مصفوفة من عناصر DOM تحتوي على عمليات ترويجية.

resultElts

مصفوفة من عناصر DOM تحتوي على نتائج.

ما مِن قيمة معروضة.

مثال على معاودة الاتصال المعروضة بالنتائج

مثال على معاودة الاتصال resultsRendered في يضيف مثال على معاودة الاتصال المعروضة بالنتائج Keep وهميًا مربّع اختيار لكل إعلان ترويجي ونتيجة

myWebResultsRenderedCallback = function(name, q, promos, results) {
    for (const div of promos.concat(results)) {
      const innerDiv = document.createElement('div');
      innerDiv.appendChild(document.createTextNode('Keep: '));
      const checkBox = document.createElement('input');
      checkBox.type = 'checkbox';
      checkBox.name = 'save';
      innerDiv.appendChild(checkBox);
      div.insertAdjacentElement('afterbegin', innerDiv);
    }
  };

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: 'myWebResultsRenderedCallback',
  },
};

  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

إذا كانت النتائج المعروضة بحاجة إلى المعلومات التي تم تمريرها إلى استدعاء النتائج الجاهزة، فيمكنها تمرير هذه البيانات بين مع استدعاءات. يوضح المثال التالي إحدى الطرق العديدة لتمرير قيمة تقييم من richSnippet من معاودة الاتصال الجاهزة للنتائج إلى النتائج المعروضة

const makeTwoPartCallback = () => {
  let saveForRenderCallback;
  const readyCallback = (name, q, promos, results, resultsDiv) =>
  {
    saveForRenderCallback = [];
    for (const result of results) {
      const {
        richSnippet: {
          answer = []
        } = {},
      } = result;
      const firstAnswer = answer[0];
      if (firstAnswer) {
        const upVotes = firstAnswer['upvotecount'];
        if (upVotes) {
          saveForRenderCallback.push(
            {upvotes: parseInt(upVotes, 10)}
          );
          continue;
        }
      }
      saveForRenderCallback.push({});
    }
  };
  const renderedCallback = (name, q, promos, results) => {
    for (let i = 0; i < results.length; ++i) {
      const div = results[i];
      const votes = saveForRenderCallback[i]['upvotes'];
      if (votes) {
        const innerDiv = document.createElement('div');
        innerDiv.innerHTML = '<b>Upvotes: ' + votes + '</b>';
         div.insertAdjacentElement('afterbegin', innerDiv);
      }
    }
  };
  return {readyCallback, renderedCallback};
};

const {
  readyCallback: webResultsReadyCallback,
  renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    ready: webResultsReadyCallback,
    rendered: webResultsRenderedCallback,
  },
};

  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:kdroeu4mwju"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

المزيد من أمثلة معاودة الاتصال

يمكن العثور على أمثلة إضافية لمعاودة الاتصال في مستند مزيد من الأمثلة على معاودة الاتصال

خصائص العروض الترويجية والنتائج

باستخدام تدوين JSDoc، تكون هذه خصائص كائن promotion والنتيجة. ندرج هنا جميع الخصائص التي قد تكون موجودة. إنّ توفّر العديد من المواقع تعتمد على تفاصيل العرض الترويجي أو نتيجة البحث.

{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}

{
  content: string,
  contentNoFormatting: string,
  contextUrl: string, // For image search results only
  fileFormat: string,
  image: { // For image search reseults only
    height: number,
    url: string,
    width: number,
  },
  perResultLabels: !Array<{
    anchor: string,
    label: string,
    labelWithOp: string,
  }>,
  richSnippet: !Array<!Object>, // For web search results only
  thumbnailImage: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  titleNoFormatting: string,
  url: string,
  visibleUrl: string,
}

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

'review': {
  'ratingstars': '3.0',
  'ratingcount': '1024',
},

Programmable Search Element Control API (V2)

ينشر الكائن google.search.cse.element ما يلي الدوال الثابتة:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');