API کنترل عنصر جستجوی قابل برنامه ریزی

می توانید اجزای موتور جستجوی قابل برنامه ریزی (جعبه های جستجو و صفحات نتایج جستجو) را با استفاده از نشانه گذاری HTML در صفحات وب خود و سایر برنامه های کاربردی وب جاسازی کنید. این عناصر موتور جستجوی قابل برنامه ریزی شامل اجزایی هستند که بر اساس تنظیمات ذخیره شده توسط سرور جستجوی قابل برنامه ریزی همراه با هر گونه سفارشی سازی که انجام می دهید ارائه می شوند.

��مه جاوا اسکریپت به صورت ناهمزمان بارگیری می شود، که به صفحه وب شما اجازه می دهد تا زمانی که مرورگر جاوا اسکریپت موتور جستجوی قابل برنامه ریزی را واکشی می کند، به بارگیری ادامه دهد.

مقدمه

این سند یک مدل پایه برای افزودن عناصر موتور جستجوی قابل برنامه ریزی به صفحه وب شما به همراه توضیحاتی در مورد اجزای قابل تنظیم عنصر و API انعطاف پذیر جاوا اسکریپت ارائه می دهد.

دامنه

این سند نحوه استفاده از توابع و ویژگی های خاص API کنترل موتور جستجوی برنامه پذیر را شرح می دهد.

سازگاری با مرورگر

لیست مرورگرهای پشتیبانی شده توسط موتور جستجوی برنامه پذیر را می توانید در اینجا بیابید.

مخاطب

این مستندات برای توسعه دهندگانی در نظر گرفته شده است که مایلند قابلیت جستجوی قابل برنامه ریزی Google را به صفحات خود اضافه کنند.

عناصر جستجوی قابل برنامه ریزی

می توانید از نشانه گذاری 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>

با استفاده از عناصر جستجوی قابل برنامه ریزی گزینه های طرح بندی مختلف را بنویسید

گزینه های طرح بندی زیر در صفحه ظاهر و احساس صفحه کنترل قابل برنامه ریزی موتور جستجو در دسترس هستند. در اینجا چند دستورالعمل کلی در مورد ترکیب گزینه‌های طرح‌بندی با استفاده از عناصر جستجوی برنامه‌پذیر آمده است. برای مشاهده نسخه نمایشی هر یک از این گزینه ها، روی پیوند کلیک کنید.

اطلاعات بیشتر در مورد گزینه های طرح بندی.

سفارشی کردن عناصر جستجوی قابل برنامه ریزی

برای سفارشی کردن رنگ ها، فونت یا سبک پیوند، به صفحه Look and Feel موتور جستجوی قابل برنامه ریزی خود بروید.

می‌توانید از ویژگی‌های اختیاری برای بازنویسی پیکربندی‌های ایجاد شده در پانل کنترل موتور جستجوی قابل برنامه‌ریزی استفاده کنید. این به شما امکان می دهد تا یک تجربه جستجوی خاص برای صفحه ایجاد کنید. به عنوان مثال، کد زیر یک کادر جستجو ایجاد می کند که یک صفحه نتیجه (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>

تماس های تلفنی

Callbacks از کنترل دقیق اولیه سازی عنصر جستجو و فرآیندهای جستجو پشتیبانی می کند. آنها با جستجوی عنصر جاوا اسکریپت از طریق شیء جهانی __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,
      },
    },
  };
  

پاسخ به تماس اولیه

فراخوانی اولیه قبل از اینکه عنصر جستجو جاوا اسکریپت عناصر جستجو را در DOM ارائه کند فراخوانی می شود. اگر parsetags به explicit در __gcse تنظیم شده باشد، عنصر جستجو جاوا اسکریپت رندر عناصر جستجو را به بازگشت به تماس اولیه می‌گذارد (همانطور که در Register Callbacks نشان داده شده است). این ممکن است برای انتخاب عناصر برای رندر یا به تعویق انداختن عناصر رندر تا زمانی که آنها مورد نیاز هستند استفاده شود. همچنین می تواند ویژگی های عناصر را نادیده بگیرد. برای مثال، می‌تواند یک جعبه جستجو را که از طریق کنترل پنل یا ویژگی‌های HTML به صورت پیش‌فرض برای جستجوی وب پیکربندی شده است، به کادر جستجوی تصویر تبدیل کند، یا مشخص کند که درخواست‌های ارسال شده از طریق یک فرم موتور جستجوی قابل برنامه‌ریزی در یک عنصر فقط نتایج جستجو اجرا شوند. دمو را ببینید.

نقش بازخوانی اولیه توسط مقدار ویژگی parsetags __gcse کنترل می شود.

• اگر مقدار آن onload باشد، جاوا اسکریپت عنصر جستجو همه عناصر جستجو را در صفحه به طور خودکار نمایش می دهد. فراخوانی اولیه هنوز فراخوانی می شود، اما مسئولیتی برای ارائه عناصر جستجو ندارد.
• اگر مقدار آن explicit باشد، جاوا اسکریپت عنصر جستجو عناصر جستجو را نمایش نمی دهد. پاسخ تماس ممکن است آنها را به صورت انتخابی با استفاده از تابع render() رندر کند یا تمام عناصر جستجو را با تابع go() رندر کند.

کد زیر نشان می دهد که چگونه می توان یک جعبه جستجو را همراه با نتایج جستجو در یک div با استفاده از تگ parset 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>

جستجوی تماس ها

جاوا اسکریپت عنصر جستجو از شش تماس برگشتی پشتیبانی می کند که در جریان کنترل جستجو عمل می کنند. تماس‌های جستجو به صورت جفت، یک تماس جستجوی وب و پاسخ به تماس جستجوی تصویر مطابقت دارند:

• شروع جستجو
  • برای جستجوی تصویر
  • برای جستجوی وب
• نتایج آماده است
  • برای جستجوی تصویر
  • برای جستجوی وب
• نتایج ارائه شده
  • برای جستجوی تصویر
  • برای جستجوی وب

مانند پاسخ تماس اولیه، تماس های جستجو با استفاده از ورودی های شی __gcse پیکربندی می شوند. این با شروع جاوا اسکریپت عنصر جستجو اتفاق می افتد. تغییرات __gcse پس از راه‌اندازی نادیده گرفته می‌شوند.

به هر یک از این فراخوان ها gName برای عنصر جستجو به عنوان آرگومان ارسال می شود. gname زمانی مفید است که یک صفحه دارای بیش از یک جستجو باشد. با استفاده از ویژگی data-gname به عنصر جستجو مقادیر gname بدهید:

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

اگر HTML gname را شناسایی نکند، عنصر جستجو جاوا اسکریپت مقداری ایجاد می کند که تا زمانی که HTML اصلاح نشود، ثابت می ماند.

تصویر/جستجوی وب-شروع پاسخ به تماس

تماس‌های شروع جستجو بلافاصله قبل از درخواست جستجوی عنصر جاوا اسکریپت از سرور خود، فراخوانی می‌شوند. یک مثال مورد استفاده، استفاده از زمان محلی روز برای کنترل تغییرات در پرس و جو است.

searchStartingCallback(gname, query)

gname

جستجوی رشته شناسایی عنصر

query

مقدار وارد شده توسط کاربر (احتمالاً توسط عنصر جستجو جاوا اسکریپت اصلاح شده است.)

تماس برگشتی مقداری را که باید به عنوان پرس و جو برای این جستجو استفاده شود برمی گرداند. اگر یک رشته خالی برگرداند، مقدار بازگشتی نادیده گرفته می شود و تماس گیرنده از پرس و جوی اصلاح نشده استفاده می کند.

همچنین، می‌توانید تابع callback را در شی __gcse قرار دهید یا به صورت پویا با جاوا اسکریپت پاسخ تماس را به شی اضافه کنید:

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;

این callback را در 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>

نتایج جستجوی تصویر/وب - پاسخ به تماس آماده

این تماس‌ها بلافاصله قبل از اینکه عنصر جستجوی جاوا اسکریپت تبلیغات و نتایج را ارائه کند، فراخوانی می‌شوند. یک مثال استفاده از یک callback است که تبلیغات را ارائه می دهد و به سبکی منجر می شود که با سفارشی سازی معمولی قابل تعیین نیست.

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

gname

جستجوی رشته شناسایی عنصر

query

جستجویی که این نتایج را ایجاد کرد

promos

آرایه ای از اشیاء تبلیغاتی، که با تبلیغات منطبق برای درخواست کاربر مطابقت دارد. تعریف شی تبلیغاتی را ببینید.

results

آرایه ای از اشیاء نتیجه تعریف شی نتیجه را ببینید.

div

یک div HTML در DOM که عنصر جستجو معمولاً تبلیغات و نتایج جستجو را در آن قرار می دهد. به طور معمول، جاوا اسکریپت عنصر جستجو، پر کردن این div را انجام می‌دهد، اما این فراخوان ممکن است رندر خودکار نتایج را متوقف کند و از این div برای ارائه خود نتایج استفاده کند.

اگر این فراخوانی مقدار true را برگرداند، جاوا اسکریپت عنصر جستجو به کار پاورقی صفحه خود می‌رود.

نتایج نمونه پاسخ به تماس آماده

مثال resultsReady callback در Example Results Ready Callback ارائه پیش‌فرض تبلیغات و نتایج را با یک جایگزین بسیار ساده لغو ��ی‌کند.

    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>

تصویر/نتایج جستجوی وب - پاسخ به تماس ارائه شده

این تماس‌ها بلافاصله قبل از اینکه عنصر جستجوی جاوا اسکریپت پاورقی صفحه را ارائه کند، فراخوانی می‌شوند. موارد استفاده مثال شامل پاسخ به تماسی است که محتوای نتیجه‌ای را اضافه می‌کند که عنصر جستجو نمایش نمی‌دهد، مانند ذخیره این کادر انتخاب یا اطلاعاتی که به‌طور خودکار ارائه نمی‌شوند، یا پاسخ به تماسی که دکمه‌های اطلاعات بیشتر را اضافه می‌کند.

اگر یک نتیجه رندر شده به اطلاعاتی نیاز داشته باشد که در promos و پارامترهای results پاسخ به تماس آماده نتایج وجود داشته باشد، می تواند آن را بین آنها ارسال کند، مانند این:

callback(gname, query, promoElts, resultElts);

gname

جستجوی رشته شناسایی عنصر

query

رشته جستجو

promoElts

آرایه ای از عناصر DOM حاوی تبلیغات.

resultElts

آرایه ای از عناصر DOM حاوی نتایج.

هیچ ارزش بازگشتی وجود ندارد.

نتایج نمونه پاسخ به تماس ارائه شده

مثال resultsRendered callback در Example Results Rendered Callback یک چک باکس 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>

نمونه های بیشتر برای پاسخ به تماس

نمونه‌های پاسخ به تماس اضافی را می‌توانید در سند More Callback Examples پیدا کنید.

ویژگی های ارتقا و نتیجه

با استفاده از نماد JSDoc ، اینها ویژگی های اشیاء تبلیغاتی و نتیجه هستند. در اینجا، ما تمام ویژگی هایی را که ممکن است وجود داشته باشند، فهرست می کنیم. وجود بسیاری از خواص به جزئیات تبلیغات یا نتیجه جستجو بستگی دارد.

{
  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',
},

API کنترل عنصر جستجوی قابل برنامه ریزی (V2)

شی google.search.cse.element توابع ثابت زیر را منتشر می کند:

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