Programmable Search Element Control API

אתם יכולים להטמיע רכיבים של Programmable Search Engine (תיבות חיפוש ודפי תוצאות חיפוש) בדפי האינטרנט ובאפליקציות אינטרנט אחרות באמצעות תגי HTML. רכיבי Programmable Search Engine מורכבים מרכיבים שעוברים עיבוד על סמך הגדרות שמאוחסנות בשרת של Programmable Search, וגם על סמך התאמות אישיות שאתם מבצעים.

כל ה-JavaScript נטען באופן אסינכרוני, כך שדף האינטרנט יכול להמשיך להיטען בזמן שהדפדפן מאחזר את ה-JavaScript של Programmable Search Engine.

מבוא

במסמך הזה מוסבר איך להוסיף רכיבים של Programmable Search Engine לדף אינטרנט, ומוצג מודל בסיסי לכך. בנוסף, מוסבר על הרכיבים הניתנים להגדרה של האלמנט ועל JavaScript API הגמיש.

היקף

במסמך הזה מוסבר איך להשתמש בפונקציות ובמאפיינים שספציפיים ל-Programmable Search Engine Control API.

תאימות לדפדפנים

רשימת הדפדפנים שנתמכים ב-Programmable Search Engine מופיעה כאן.

קהל

התיעוד הזה מיועד למפתחים שרוצים להוסיף פונקציונליות של Programmable Search של Google לדפים שלהם.

Programmable Search Elements

אפשר להשתמש בתגי HTML כדי להוסיף רכיב של Programmable Search לדף. כל רכיב מורכב לפחות מרכיב אחד: תיבת חיפוש, בלוק של תוצאות חיפוש או שניהם. תיבת החיפוש מקבלת קלט מהמשתמש באחת מהדרכים הבאות:

  • שאילתת חיפוש שהוקלדה בשדה להזנת טקסט
  • מחרוזת שאילתה שמוטמעת בכתובת URL
  • ביצוע פרוגרמטי

בנוסף, אפשר להזין נתונים לבלוק של תוצאות החיפוש בדרכים הבאות:

  • מחרוזת שאילתה שמוטמעת בכתובת URL
  • ביצוע פרוגרמטי

אלה סוגי הרכיבים של Programmable Search שזמינים:

סוג הרכיב רכיבים תיאור
רגיל <div class="gcse-search"> תיבת חיפוש ותוצאות חיפוש, שמוצגות באותו <div>.
שתי עמודות <div class="gcse-searchbox"> וגם <div class="gcse-searchresults"> פריסה של שתי עמודות עם תוצאות חיפוש בצד אחד ותיבת חיפוש בצד השני. אם אתם מתכננים להוסיף כמה רכיבים במצב של שתי עמודות בדף האינטרנט, אתם יכולים להשתמש במאפיין gname כדי לשייך תיבת חיפוש לבלוק של תוצאות חיפוש.
searchbox-only <div class="gcse-searchbox-only"> תיבת חיפוש עצמאית.
searchresults-only <div class="gcse-searchresults-only"> בלוק נפרד של תוצאות חיפוש.

אפשר להוסיף לדף האינטרנט מספר בלתי מוגבל של רכיבי חיפוש תקינים. במצב שתי עמודות, כל הרכיבים הנדרשים (תיבת חיפוש ובלוק של תוצאות חיפוש) חייבים להיות נוכחים.

הנה דוגמה לרכיב חיפוש פשוט:

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

יצירת אפשרויות שונות של פריסה באמצעות רכיבי Programmable Search

אפשרויות הפריסה הבאות זמינות בדף 'מראה ותחושה' בלוח הבקרה של Programmable Search Engine. הנה כמה הנחיות כלליות לגבי יצירת אפשרויות פריסה באמצעות רכיבי Programmable Search. כדי לראות הדגמה של אחת מהאפשרויות האלה, לוחצים על הקישור.

אפשרות רכיבים
רוחב מלא <div class="gcse-search">
קומפקטית <div class="gcse-search">
שתי עמודות <div class="gcse-searchbox">, <div class="gcse-searchresults">
שני עמודים <div class="gcse-searchbox-only"> בדף הראשון, <div class="gcse-searchresults-only"> (או רכיבים אחרים) בדף השני.
תוצאות בלבד <div class="gcse-searchresults-only">
באירוח של Google <div class="gcse-searchbox-only">

מידע נוסף על אפשרויות הפריסה

התאמה אישית של רכיבי Programmable Search

כדי להתאים אישית את הצבעים, הגופן או סגנון הקישור, עוברים לדף 'מראה ותחושה' של מנוע החיפוש הניתן לתכנות.

אפשר להשתמש במאפיינים אופציונליים כדי לשכתב הגדרות שנוצרו בלוח הבקרה של Programmable Search Engine. כך תוכלו ליצור חוויית חיפוש ספציפית לדף. לדוגמה, הקוד הבא יוצר תיבת חיפוש שפותחת דף תוצאות (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">

אם השתמשתם בלוח הבקרה של Programmable Search Engine כדי להפעיל תכונות כמו השלמה אוטומטית או הגדרות מדויקות יותר, אתם יכולים להשתמש במאפיינים כדי להתאים אישית את התכונות האלה. כל התאמה אישית שתציינו באמצעות המאפיינים האלה תבטל את ההגדרות שנקבעו בלוח הבקרה. בדוגמה הבאה נוצר רכיב חיפוש עם שתי עמודות והתכונות הבאות:

  • הניהול של ההיסטוריה מופעל
  • מספר ההשלמות האוטומטיות שיוצגו מוגדר ל-5
  • ההצעות לשיפור מוצגות כקישורים.

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

מאפיינים נתמכים

מאפיין סוג תיאור רכיב
כללי
gname מחרוזת (אופציונלי) שם לאובייקט Search Element. השם משמש לאחזור רכיב משויך לפי שם, או לשיוך רכיב searchbox לרכיב searchresults. אם לא מספקים, ‫Programmable Search Engine ייצור באופן אוטומטי gname, על סמך סדר הרכיבים בדף האינטרנט. לדוגמה, ל-searchbox-only הראשון ללא שם יש את gname searchbox-only0, לשני יש את gname seachbox-only1 וכן הלאה. שימו לב: ה-gname שנוצר באופן אוטומטי לרכיב בפריסה של שתי עמודות יהיה two-column. בדוגמה הבאה נעשה שימוש ב-gname storesearch כדי לקשר בין רכיב searchbox לרכיב searchresults:
<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

כשמאחזרים אובייקט, אם ליותר מרכיב אחד יש את אותו gname, Programmable Search Engine ישתמש ברכיב האחרון בדף.

הכול
autoSearchOnLoad בוליאני מציין אם לבצע חיפוש לפי השאילתה שמוטמעת בכתובת ה-URL של הדף שנמצא בטעינה. שימו לב: כדי להפעיל את החיפוש האוטומטי, צריך להוסיף מחרוזת שאילתה לכתובת ה-URL. ברירת מחדל: true. הכול
enableHistory בוליאני אם הערך הוא true, מופעל ניהול ההיסטוריה של הלחצנים 'הקודם' ו'הבא' בדפדפן. לצפייה בהדגמה

תיבת חיפוש

searchbox-only

queryParameterName מחרוזת השם של פרמטר השאילתה – לדוגמה, q (ברירת מחדל) או query. היא תוטמע בכתובת ה-URL (לדוגמה, http://www.example.com?q=lady+gaga). שימו לב: ציון שם הפרמטר של השאילתה בלבד לא מפעיל חיפוש אוטומטי בזמן הטעינה. מחרוזת שאילתה צריכה להיות נוכחת בכתובת ה-URL כדי להפעיל את החיפוש האוטומטי. הכול
resultsUrl כתובת URL כתובת ה-URL של דף התוצאות. (ברירת המחדל היא הדף שמתארח ב-Google). searchbox-only
newWindow בוליאני מציין אם דף התוצאות נפתח בחלון חדש. ברירת מחדל: false. searchbox-only
ivt בוליאני

הפרמטר הזה מאפשר לכם לספק ערך בוליאני שמודיע ל-Google שאתם רוצים לאפשר הצגת מודעות שמשתמשות באחסון מקומי ובקובצי Cookie לזיהוי תנועה פסולה בלבד, גם למשתמשים שהביעו הסכמה לשימוש בקובצי Cookie וגם למשתמשים שלא הביעו הסכמה.

true אם הפרמטר הזה לא מופיע או אם מגדירים אותו כ-true, אנחנו נגדיר קובץ Cookie לזיהוי תנועה פסולה בלבד ונשתמש באחסון מקומי רק בקרב תנועת משתמשים שהביעו הסכמה.

false אם מגדירים את הפרמטר הזה לערך false, המערכת תגדיר קובץ Cookie לזיהוי תנועה פסולה בלבד ותשתמש באחסון מקומי גם בקרב תנועת משתמשים שהביעו הסכמה וגם בקרב תנועת משתמשים שלא הביעו הסכמה.

ברירת מחדל: false

דוגמאות לשימוש: <div class="gcse-search" data-ivt="true"></div>

searchresults

searchresults-only

mobileLayout מחרוזת

המדיניות קובעת אם להשתמש בסגנונות הפריסה לניידים במכשירים ניידים.

enabled משתמש בפריסה לנייד רק במכשירים ניידים.

disabled לא משתמש בפריסה לנייד באף מכשיר.

forced משתמש בפריסה לניידים בכל המכשירים.

ברירת מחדל: enabled

דוגמאות לשימוש: <div class="gcse-search" data-mobileLayout="disabled"></div>

הכול
השלמה אוטומטית
enableAutoComplete בוליאני האפשרות הזו זמינה רק אם הפעלתם את ההשלמה האוטומטית בלוח הבקרה של Programmable Search Engine. true מפעיל את ההשלמה האוטומטית. הכול
autoCompleteMaxCompletions מספר שלם המספר המקסימלי של השלמות אוטומטיות שיוצגו.

תיבת חיפוש

searchbox-only

autoCompleteMaxPromotions מספר שלם המספר המקסימלי של מבצעים שיוצגו בהשלמה האוטומטית.

תיבת חיפוש

searchbox-only

autoCompleteValidLanguages מחרוזת רשימה של שפות מופרדות בפסיקים שבהן צריך להפעיל את ההשלמה האוטומטית. שפות נתמכות.

תיבת חיפוש

searchbox-only

שיפורים
defaultToRefinement מחרוזת האפשרות הזו זמינה רק אם יצרתם הצעות לשיפור החיפוש בלוח הבקרה של Programmable Search Engine. מציין את התווית של ברירת המחדל לסינון התוצאות שתוצג.הערה: המאפיין הזה לא נתמך בפריסה שמתארחת ב-Google. הכול
refinementStyle מחרוזת הערכים הקבילים הם tab (ברירת מחדל) ו-link. יש תמיכה ב-link רק אם חיפוש התמונות מושבת, או אם חיפוש התמונות מופעל אבל חיפוש האינטרנט מושבת.

searchresults

searchresults-only

חיפוש לפי תמונה
enableImageSearch בוליאני האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

אם הערך הוא true, החיפוש לפי תמונות מופעל. תוצאות החיפוש של תמונות יוצגו בכרטיסייה נפרדת.

searchresults

searchresults-only

defaultToImageSearch בוליאני האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

אם true, תוצאות החיפוש של התמונות יוצגו בדף תוצאות החיפוש כברירת מחדל. תוצאות החיפוש באינטרנט יהיו זמינות בכרטיסייה נפרדת.

הכול
imageSearchLayout מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

מציינת את הפריסה של דף תוצאות החיפוש של תמונות. הערכים הקבילים הם classic,‏ column או popup.

searchresults

searchresults-only

imageSearchResultSetSize מספר שלם, מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

מציין את הגודל המקסימלי של קבוצת תוצאות החיפוש בחיפוש תמונות. לדוגמה, large, ‏ small, ‏ filtered_cse, ‏ 10.

הכול
image_as_filetype מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

הגבלת התוצאות לקבצים עם סיומת שצוינה.

הסיומות הנתמכות הן jpg, ‏ gif, ‏ png, ‏ bmp, ‏ svg, ‏ webp, ‏ ico, ‏ raw.

הכול

image_as_oq מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

סינון של תוצאות החיפוש באמצעות האופרטור הלוגי OR.

דוגמה לשימוש אם רוצים תוצאות חיפוש שכוללות את המונח term1 או את המונח term2:<div class="gcse-search" data-image_as_oq="term1 term2"></div>

הכול

image_as_rights מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

מסננים לפי רישוי.

הערכים הנתמכים הם cc_publicdomain,‏ cc_attribute,‏ cc_sharealike,‏ cc_noncommercial,‏ cc_nonderived וצירופים שלהם.

שילובי ערוצים אופייניים

הכול

image_as_sitesearch מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

הגבלת התוצאות לדפים מאתר ספציפי.

דוגמאות לשימוש: <div class="gcse-search" data-image_as_sitesearch="example.com"></div>

הכול

image_colortype מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

הגבלת החיפוש לתמונות בשחור-לבן (מונו), בגווני אפור או בצבע. הערכים הנתמכים הם mono, ‏ gray, ‏ color.

הכול

image_cr מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

הגבלת תוצאות החיפוש למסמכים שמקורם במדינה מסוימת.

ערכים נתמכים

הכול

image_dominantcolor מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

הגבלת החיפוש לתמונות בצבע דומיננטי ספציפי. הערכים הנתמכים הם red, ‏ orange, ‏ yellow, ‏ green, ‏ teal, ‏ blue, ‏ purple, ‏ pink, ‏ white, ‏ gray, ‏ black, ‏ brown.

הכול

image_filter מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

סינון אוטומטי של תוצאות החיפוש.

ערכים נתמכים: 0/1

דוגמאות לשימוש: <div class="gcse-search" data-image_filter="0"></div>

הכול

image_gl מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine. הגברת תוצאות החיפוש שמדינת המקור שלהן תואמת לערך הפרמטר.

ערכים נתמכים

הכול

image_size מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

הפונקציה מחזירה תמונות בגודל שצוין, כאשר הגודל יכול להיות אחד מהערכים הבאים: icon,‏ small,‏ medium,‏ large,‏ xlarge,‏ xxlarge או huge.

הכול

image_sort_by מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

אפשר למיין את התוצאות לפי תאריך או לפי תוכן מובנה אחר.

כדי למיין לפי רלוונטיות, משתמשים במחרוזת ריקה (image_sort_by="").

דוגמאות לשימוש: <div class="gcse-search" data-image_sort_by="date"></div>

הכול

image_type מחרוזת האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

הגבלת החיפוש לתמונות מסוג מסוים. הערכים הנתמכים הם clipart (קליפ ארט), face (פנים של אנשים), lineart (ציורי קווים), stock (תמונות ממאגר), photo (תמונות) ו-animated (קובצי GIF).

הכול

חיפוש באינטרנט
disableWebSearch בוליאני אם הערך הוא true, החיפוש באינטרנט מושבת. המאפיין הזה משמש בדרך כלל רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.

searchresults

searchresults-only

webSearchQueryAddition מחרוזת הוספת עוד מונחים לשאילתת החיפוש באמצעות האופרטור הלוגי 'או'.

דוגמאות לשימוש: <div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

הכול
webSearchResultSetSize מספר שלם, מחרוזת הגודל המקסימלי של קבוצת התוצאות. רלוונטי גם לחיפוש תמונות וגם לחיפוש באינטרנט. ברירת המחדל תלויה בפריסה ובשאלה אם ה-Programmable Search Engine מוגדר לחפש בכל האינטרנט או רק באתרים ספציפיים. ערכים קבילים:
  • מספר שלם בין 1 ל-20
  • small: בקשה לקבוצת תוצאות קטנה, בדרך כלל 4 תוצאות בכל דף.
  • large: בקשה לקבוצת תוצאות גדולה, בדרך כלל 8 תוצאות בכל דף.
  • filtered_cse: בקשות של עד 10 תוצאות לכל דף, למקסימום של 10 דפים או 100 תוצאות.
הכול
webSearchSafesearch מחרוזת קובעת אם SafeSearch מופעל בתוצאות של חיפוש באינטרנט. הערכים הקבילים הם off ו-active. הכול
as_filetype מחרוזת הגבלת התוצאות לקבצים עם סיומת שצוינה. רשימה של סוגי קבצים ש-Google יכולה להוסיף לאינדקס זמינה במרכז העזרה של Search Console.

הכול

as_oq מחרוזת סינון של תוצאות החיפוש באמצעות האופרטור הלוגי OR.

דוגמה לשימוש אם רוצים תוצאות חיפוש שכוללות את המונח term1 או את המונח term2:<div class="gcse-search" data-as_oq="term1 term2"></div>

הכול
as_rights מחרוזת מסננים לפי רישוי.

הערכים הנתמכים הם cc_publicdomain,‏ cc_attribute,‏ cc_sharealike,‏ cc_noncommercial,‏ cc_nonderived וצירופים שלהם.

מידע על שילובים אופייניים זמין בכתובת https://wiki.creativecommons.org/wiki/CC_Search_integration.

הכול

as_sitesearch מחרוזת הגבלת התוצאות לדפים מאתר ספציפי.

דוגמאות לשימוש: <div class="gcse-search" data-as_sitesearch="example.com"></div>

הכול
cr מחרוזת הגבלת תוצאות החיפוש למסמכים שמקורם במדינה מסוימת.

ערכים נתמכים

דוגמאות לשימוש: <div class="gcse-search" data-cr="countryFR"></div>

הכול
filter מחרוזת סינון אוטומטי של תוצאות החיפוש.

ערכים נתמכים: 0/1

דוגמאות לשימוש: <div class="gcse-search" data-filter="0"></div>

הכול
gl מחרוזת הגברת תוצאות החיפוש שמדינת המקור שלהן תואמת לערך הפרמטר.

האפשרות הזו פועלת רק בשילוב עם ההגדרה ערך השפה.

ערכים נתמכים

דוגמאות לשימוש: <div class="gcse-search" data-gl="fr"></div>

הכול
lr מחרוזת הגבלת תוצאות החיפוש למסמכים שכתובים בשפה מסוימת.

ערכים נתמכים

דוגמאות לשימוש: <div class="gcse-search" data-lr="lang_fr"></div>

הכול
sort_by מחרוזת אפשר למיין את התוצאות לפי תאריך או לפי תוכן מובנה אחר. ערך המאפיין צריך להיות אחת מהאפשרויות שמופיעות בהגדרות מיון תוצאות של מנוע החיפוש הניתן לתכנות.

כדי למיין לפי רלוונטיות, משתמשים במחרוזת ריקה (sort_by="").

דוגמאות לשימוש: <div class="gcse-search" data-sort_by="date"></div>

הכול
תוצאות חיפוש
enableOrderBy בוליאני מאפשר מיון של התוצאות לפי רלוונטיות, תאריך או תווית. הכול
linkTarget מחרוזת הגדרת יעד הקישור. ברירת מחדל: _blank.

searchresults

searchresults-only

noResultsString מחרוזת ציון הטקסט שיוצג כברירת מחדל כשאין תוצאות שתואמות לשאילתה. אפשר להשתמש במחרוזת התוצאה שמוגדרת כברירת מחדל כדי להציג מחרוזת מותאמת לשפה בכל השפות הנתמכות, אבל אי אפשר לעשות את זה עם מחרוזת מותאמת אישית.

searchresults

searchresults-only

resultSetSize מספר שלם, מחרוזת הגודל המקסימלי של קבוצת התוצאות. לדוגמה, large, small, filtered_cse, 10. ברירת המחדל תלויה בפריסה ובשאלה אם מנוע החיפוש מוגדר לחפש בכל האינטרנט או רק באתרים ספציפיים. הכול
safeSearch מחרוזת מציין אם החיפוש הבטוח מופעל גם בחיפוש באינטרנט וגם בחיפוש תמונות. הערכים הקבילים הם off ו-active. הכול

התקשרות חזרה

תרשים של רצף שיחות חוזרות
דיאגרמת רצף של קריאות חוזרות (callbacks) מ-JavaScript של רכיב החיפוש

הפונקציות לביצוע חוזר מאפשרות שליטה מפורטת בתהליכי האתחול והחיפוש של רכיב החיפוש. הם רשומים ב-JavaScript של רכיב החיפוש דרך האובייקט הגלובלי __gcse. במאמר Register Callbacks מוסבר איך לרשום את כל ה-callbacks הנתמכים.

Register Callbacks

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

התקשרות חזרה לאתחול

הקריאה החוזרת (callback) של האתחול מופעלת לפני שסקריפט ה-JavaScript של רכיב החיפוש מעבד רכיבי חיפוש ב-DOM. אם הערך של parsetags מוגדר ל-explicit ב-__gcse, קוד ה-JavaScript של אלמנט החיפוש משאיר את העיבוד של אלמנט החיפוש לפונקציית הקריאה החוזרת של ההפעלה (כפי שמוצג ברישום פונקציות קריאה חוזרות). יכול להיות שהמאפיין הזה ישמש לבחירת רכיבים לעיבוד, או לדחיית עיבוד רכיבים עד שיהיה צורך בהם. הוא יכול גם לשנות את מאפייני הרכיבים. לדוגמה, הוא יכול לשנות תיבת חיפוש שהוגדרה דרך לוח הבקרה או מאפייני HTML כך שברירת המחדל שלה תהיה חיפוש באינטרנט, ולהפוך אותה לתיבת חיפוש תמונות. הוא יכול גם לציין ששאילתות שנשלחות דרך טופס של מנוע חיפוש שניתן לתכנות יופעלו ברכיב של תוצאות חיפוש בלבד. לצפייה בהדגמה

התפקיד של קריאת החזרה לאתחול נקבע לפי הערך של המאפיין parsetags של __gcse.

  • אם הערך שלו הוא onload, קוד ה-JavaScript של רכיב החיפוש מעבד את כל רכיבי החיפוש בדף באופן אוטומטי. הקריאה החוזרת לאתחול עדיין מופעלת, אבל היא לא אחראית לעיבוד של רכיבי החיפוש.
  • אם הערך הוא explicit, קוד ה-JavaScript של רכיב החיפוש לא מעבד את רכיבי החיפוש. פונקציית ה-callback יכולה להציג אותם באופן סלקטיבי באמצעות הפונקציה render(), או להציג את כל רכיבי החיפוש באמצעות הפונקציה go().

בדוגמת הקוד הבאה מוצג איך להציג תיבת חיפוש יחד עם תוצאות חיפוש ב-div באמצעות התג explicit וקריאה חוזרת (callback) לאתחול:

דוגמה לשיחה חוזרת לאתחול

צריך לכלול <div> עם ערך מזהה במקום שבו רוצים להציב את קוד רכיב החיפוש:

    <div id="test"></div>
מוסיפים את קוד ה-JavaScript הזה אחרי התג <div>. שימו לב שהיא מפנה אל test, id שבו השתמשנו כדי לזהות את <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
};

כדי להתחיל לטעון את רכיב החיפוש, צריך לכלול את קוד ה-HTML הזה. מחליפים את הערך cx בסעיף src בערך cx שלכם.

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

חיפוש שיחות חוזרות

קוד ה-JavaScript של רכיב החיפוש תומך בשש פונקציות קריאה חוזרת (callback) שפועלות בתהליך העבודה של החיפוש. התקשרויות החזרה של החיפוש מגיעות בזוגות, התקשרות חזרה של חיפוש באינטרנט והתקשרות חזרה תואמת של חיפוש תמונות:

  • חיפוש התחלתי
    • חיפוש תמונות
    • לחיפוש באינטרנט
  • התוצאות מוכנות
    • חיפוש תמונות
    • לחיפוש באינטרנט
  • תוצאות שנוצרו
    • חיפוש תמונות
    • לחיפוש באינטרנט

בדומה לפונקציית הקריאה החוזרת (callback) של ההפעלה,פונקציות הקריאה החוזרת של החיפוש מוגדרות באמצעות רשומות באובייקט __gcse. המצב הזה קורה כשה-JavaScript של רכיב החיפוש מתחיל. המערכת מתעלמת משינויים ב-__gcse אחרי ההפעלה.

כל אחת מהקריאות החוזרות האלה מקבלת את gName של רכיב החיפוש כארגומנט. התכונה gname שימושית כשהדף מכיל יותר מחיפוש אחד. נותנים לרכיב search ערכים של gname באמצעות המאפיין data-gname:

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

אם לא מצוין gname ב-HTML, קוד ה-JavaScript של רכיב החיפוש יוצר ערך שיישאר עקבי עד שיבוצע שינוי ב-HTML.

קריאה חוזרת (callback) להפעלת חיפוש תמונות או חיפוש באינטרנט

הקריאות החוזרות (callback) להפעלת החיפוש מופעלות מיד לפני שרכיב החיפוש JavaScript מבקש תוצאות חיפוש מהשרת שלו. תרחיש לדוגמה לשימוש: שימוש בשעה המקומית ביום כדי לשלוט בשינויים בשאילתה.

searchStartingCallback(gname, query)
gname
המחרוזת המזהה של רכיב החיפוש
query
הערך שהמשתמש הזין (יכול להיות ששונה על ידי JavaScript של רכיב החיפוש).

פונקציית ההתקשרות חזרה מחזירה את הערך שצריך לשמש כשאילתה לחיפוש הזה. אם הפונקציה מחזירה מחרוזת ריקה, המערכת מתעלמת מהערך המוחזר והקריאה לפונקציה משתמשת בשאילתה ללא שינוי.

אפשר גם להוסיף את פונקציית הקריאה החוזרת לאובייקט __gcse או להוסיף אותה לאובייקט באופן דינמי באמצעות JavaScript:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
דוגמה לקריאה חוזרת (callback) של התחלת חיפוש

הדוגמה של פונקציית הקריאה החוזרת (callback) שמופעלת בתחילת החיפוש ב-Example Search Starting Callback מוסיפה את המחרוזת 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) שמוכנה לתוצאות חיפוש תמונות או חיפוש באינטרנט

הקריאות החוזרות האלה מופעלות מיד לפני שקוד ה-JavaScript של רכיב החיפוש מעבד את המבצעים ואת התוצאות. דוגמה לתרחיש שימוש היא קריאה חוזרת (callback) שמעבדת מבצעים ומובילה לסגנון שלא ניתן לציין באמצעות התאמה אישית רגילה.

resultsReadyCallback(gname, query, promos, results, div)
gname
המחרוזת המזהה של רכיב החיפוש
query
השאילתה שהניבה את התוצאות האלה
promos
מערך של אובייקטים של מבצעים, שמתאימים למבצעים שתואמים לשאילתת המשתמש. הגדרת אובייקט קידום המכירות
results
מערך של אובייקטים של תוצאות. אפשר לעיין בהגדרת אובייקט התוצאה.
div
HTML div שממוקם ב-DOM במקום שבו רכיב החיפוש בדרך כלל מציב מבצעים ותוצאות חיפוש. בדרך כלל, קוד ה-JavaScript של רכיב החיפוש מטפל באכלוס של ה-div הזה, אבל פונקציית הקריאה החוזרת הזו יכולה להפסיק את העיבוד האוטומטי של התוצאות ולהשתמש ב-div כדי לעבד את התוצאות בעצמה.

אם פונקציית ההתקשרות חזרה הזו מחזירה ערך של true, קוד ה-JavaScript של רכיב החיפוש מדלג לעבודה שלו בכותרת התחתונה של הדף.

דוגמה לקריאה חוזרת (callback) של התוצאות מוכנות

הקריאה החוזרת resultsReady בדוגמה Example Results Ready Callback מחליפה את הצגת ברירת המחדל של המבצעים והתוצאות בהחלפה פשוטה מאוד.

דוגמה לקריאה חוזרת (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;
    };

התקנת פונקציית ה-callback הזו ב-window.__gcse:

  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>

בדומה לקריאה החוזרת של התחלת החיפוש, הקוד שלמעלה הוא אחת מתוך הרבה דרכים להציב את הקריאה החוזרת באובייקט __gcse.

קריאה חוזרת (callback) של עיבוד תוצאות חיפוש תמונות או חיפוש באינטרנט

הקריאות החוזרות האלה מופעלות מיד לפני שקוד ה-JavaScript של רכיב החיפוש מעבד את הכותרת התחתונה של הדף. דוגמאות למקרים לשימוש כוללות קריאה חוזרת שמוסיפה תוכן לתוצאה שלא מוצג ברכיב החיפוש, כמו תיבת סימון של שמירת התוצאה או מידע שלא מוצג באופן אוטומטי, או קריאה חוזרת שמוסיפה לחצנים של מידע נוסף.

אם קריאה חוזרת (callback) של תוצאות שעברו עיבוד צריכה מידע שהיה בפרמטרים promos ו-results של קריאה חוזרת (callback) של תוצאות מוכנות, היא יכולה להעביר את המידע הזה ביניהן, באופן הבא:

callback(gname, query, promoElts, resultElts);
gname
המחרוזת המזהה של רכיב החיפוש
query
מחרוזת החיפוש.
promoElts
מערך של רכיבי DOM שמכילים מבצעים.
resultElts
מערך של רכיבי DOM שמכילים תוצאות.

אין ערך להחזרה.

דוגמה לקריאה חוזרת (callback) של תוצאות שעברו רינדור

הקריאה החוזרת resultsRendered בדוגמה Example Results Rendered Callback מוסיפה לכל מבצע ולכל תוצאה תיבת סימון פיקטיבית Keep.

דוגמה לשיחת Callback להצגת תוצאות
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);
    }
  };

התקנת פונקציית ה-callback הזו ב-window.__gcse:

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 מתוך הקריאה החוזרת (callback) של התוצאות שמוכנות אל הקריאה החוזרת (callback) של התוצאות שמוצגות.

דוגמה לשיחת Callback של Results Ready שפועלת בשיתוף עם שיחת Callback של Results Rendered
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};
};
כדי להגדיר את __gcse, צריך להתקין את הקריאה החוזרת הזו באמצעות קוד כמו זה:
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>
דוגמה לקריאה חוזרת (callback) של עיבוד תוצאות: פתיחת סוגים ספציפיים של קבצים בכרטיסייה או בחלון חדשים

בדוגמה הבאה של קריאה חוזרת אפשר לשנות קישורים לתוצאות חיפוש אחרי שהם מוצגים, כדי לפתוח קובץ ספציפי בכרטיסייה או בדף חדשים במקום בחלון הנוכחי (לדוגמה: PDF,‏ Excel או Word). כך משפרים את חוויית הגלישה כשמשתמשים לא רוצים לפתוח קובץ באותו חלון ולעבור מדף התוצאות.

בדוגמה הזו של קריאה חוזרת, מזוהים קישורים לקובצי PDF בתוצאות החיפוש, ומוגדר מאפיין target="_blank" בקישורים לקובצי PDF כך שהם ייפתחו בכרטיסייה חדשה. התוצאות החדשות מטופלות באופן דינמי באמצעות MutationObserver אם הדף מתעדכן. הערה: אפשר להחליף את .pdf ב-handleSearchResults בכל סוג קובץ אחר לפי הצורך.

דוגמת הקריאה החוזרת הזו לא פועלת בפריסות של Google Hosted ו-Overlay.

פתיחת סוגים ספציפיים של קבצים בכרטיסייה או בחלון חדשים
function handleSearchResults() {
  const links = document.querySelectorAll('.gsc-results .gs-title');
  links.forEach(link => {
    const url = link.href;
    if (url?.toLowerCase().endsWith('.pdf')) {
      link.setAttribute('target', '_blank');
    }
  });
}

const myWebResultsRenderedCallback = () => {
  // Call handleSearchResults when results are rendered
  handleSearchResults();
  // Set up a MutationObserver to handle subsequent updates to the results
  const observer = new MutationObserver(handleSearchResults);
  const searchResultsContainer = document.querySelector('.gsc-results');
  if (searchResultsContainer) {
    observer.observe(searchResultsContainer, {
      childList: true,
      subtree: true
    });
  } else {
    console.log('No Results.');
  }
};

התקנת פונקציית ה-callback הזו ב-window.__gcse:

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>

דוגמאות נוספות לקריאה חוזרת (callback)

דוגמאות נוספות לקריאות חוזרות (callback) זמינות במסמך דוגמאות נוספות לקריאות חוזרות.

מאפייני מבצע ותוצאה

אלה המאפיינים של האובייקטים promotion ו-result באמצעות הסימון של 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 ב-results הוא סוג חופשי של מערך אובייקטים. הערכים של הרשומות במערך הזה נקבעים על ידי הנתונים המובְנים שנמצאים בדף האינטרנט של כל תוצאת חיפוש. לדוגמה, אתר עם ביקורות יכול לכלול נתונים מובְנים שמוסיפים את רשומת המערך הזו ל-richSnippet:

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

Programmable Search Element Control API (V2)

אובייקט google.search.cse.element מפרסם את הפונקציות הסטטיות הבאות:

פונקציה תיאור
.render(componentConfig, opt_componentConfig) רכיב Search מוצג.

פרמטרים

שם תיאור
componentConfig ההגדרה של רכיב Programmable Search Element. מציינים את הפרטים הבאים:
  • div (string|Element): ה-id של <div> או רכיב div שבו רכיב Programmable Search יוצג.
  • tag (string): סוג הרכיבים שיוצגו. (אם מספקים את המאפיין opt_componentConfig, הערך של המאפיין tag חייב להיות searchbox). הערכים המותרים הם:
    • search: תיבת חיפוש ותוצאות חיפוש שמוצגות יחד
    • searchbox: רכיב של תיבת חיפוש ב-Programmable Search Element.
    • searchbox-only: תיבת חיפוש עצמאית, שתצורף לבלוק של תוצאות חיפוש שצוין על ידי opt_componentConfig בפריסה של שתי עמודות.
    • searchresults-only: בלוק עצמאי של תוצאות חיפוש. החיפושים מופעלים על ידי פרמטר שאילתה שמוטמע בכתובת URL, או על ידי הפעלה תוכניתית.
  • gname (string): (אופציונלי) שם ייחודי לרכיב הזה. אם לא מספקים את הערך הזה, Programmable Search Engine יוצר באופן אוטומטי gname.
  • attributes (Object): מאפיינים אופציונליים בצורה של צמד מפתח:ערך. מאפיינים נתמכים.
opt_componentConfig אופציונלי. ארגומנט התצורה של רכיב השניות. משמש במצב TWO_COLUMN כדי לספק את הרכיב searchresults. מציינים את הפרטים הבאים:
  • div (מחרוזת): הערך id של <div> או של הרכיב div שבו הרכיב אמור לעבור עיבוד.
  • tag (string): סוג הרכיבים שיוצגו. כשמספקים את המאפיין opt_componentConfig, הערך של המאפיין tag חייב להיות searchresults. בנוסף, הערך של מאפיין tag של componentConfig חייב להיות searchbox.
  • gname (string): (אופציונלי) שם ייחודי לרכיב הזה. אם לא מספקים ערך, Programmable Search Engine יוצר באופן אוטומטי gname לרכיב הזה. אם מספקים את המאפיין הזה, הוא חייב להיות זהה לערך של gname ב-componentConfig.
  • attributes (Object): מאפיינים אופציונליים בצורה של צמד מפתח:ערך. מאפיינים נתמכים.
.go(opt_container) הפונקציה מעבדת את כל התגים או המחלקות של רכיב החיפוש במאגר שצוין.

פרמטרים

שם תיאור
opt_container המאגר שמכיל את הרכיבים של רכיב החיפוש שרוצים לעבד. מציינים את המזהה של מאגר התגים (מחרוזת) או את הרכיב עצמו. אם לא מציינים את התג הזה, כל הרכיבים של Programmable Search Element בתוך התג body של הדף יעברו עיבוד.
.getElement(gname) הפונקציה מחזירה את אובייקט הרכיב לפי gname. אם לא נמצא, מחזירים null.

לאובייקט element שמוחזר יש את המאפיינים הבאים:

  • gname: השם של אובייקט האלמנט. אם לא מספקים ערך, Programmable Search Engine ייצור באופן אוטומטי gname לאובייקט. מידע נוסף
  • type: סוג הרכיב.
  • uiOptions: המאפיינים הסופיים שמשמשים לעיבוד הרכיב.
  • execute - function(string): מריץ שאילתה פרוגרמטית.
  • prefillQuery – function(string): מאכלס מראש את תיבת החיפוש במחרוזת שאילתה בלי להריץ את השאילתה.
  • getInputQuery - function(): מחזירה את הערך הנוכחי שמוצג בתיבת הקלט.
  • clearAllResults - function(): מנקה את האמצעי להצגת תוצאות החיפוש על ידי הסתרת כל מה שמוצג בו, למעט תיבת החיפוש, אם יש כזו.

הקוד הבא מריץ את השאילתה 'news' ברכיב החיפוש 'element1':

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() הפונקציה מחזירה מפה של כל אובייקטי האלמנטים שנוצרו בהצלחה, עם מפתח gname.