דף זה תורגם על ידי Cloud Translation API.

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.

קהל

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

רכיבי Programmable Search

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

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

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

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

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

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

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

אפשרות	רכיבים
רוחב מלא	`<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">` (או רכיבים אחרים) בדף השני.
תוצאות בלבד חיפוש באמצעות כתובת URL חיפוש באמצעות תיבת החיפוש	`<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`	מחרוזת	(אופציונלי) שם לאובייקט של רכיב החיפוש. שם משמש לאחזור רכיב משויך לפי שם, או כדי להתאים רכיב `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 תיבת חיפוש בלבד
`queryParameterName`	מחרוזת	שם הפרמטר של השאילתה — לדוגמה `q` (ברירת מחדל) או `query`. כתובת ה-URL הזו תוטמע בכתובת ה-URL (לדוגמה, http://www.example.com?q=lady+gaga). חשוב לזכור שציון השם של פרמטר השאילתה לבדו לא יפעיל חיפוש אוטומטי בזמן הטעינה. מחרוזת שאילתה חייבת להופיע בכתובת ה-URL כדי להפעיל את החיפוש האוטומטי.	ללא הגבלה
`resultsUrl`	כתובת URL	כתובת ה-URL של דף התוצאות. (ברירת המחדל היא הדף שמתארח ב-Google).	תיבת חיפוש בלבד
`newWindow`	בוליאני	מציינת אם דף התוצאות נפתח בחלון חדש. ברירת המחדל: `false`.	תיבת חיפוש בלבד
`ivt`	בוליאני	הפרמטר הזה מאפשר להזין ערך בוליאני שמודיע ל-Google שברצונך לאפשר להציג מודעות שנעשה בהן שימוש בקובץ cookie לא חוקי לתנועה בלבד ובאחסון מקומי, גם בתנועה של משתמשים שהביעו הסכמה וגם בתנועה ללא הסכמה. `true` אם הפרמטר הזה לא קיים או אם הוא מוגדר כ-"true", אנחנו מגדירים קובץ cookie לא חוקי לתנועה בלבד ונשתמש באחסון מקומי רק לתנועה שהתקבלה הסכמה. `false` אם הערך שמוגדר לפרמטר הזה הוא 'FALSE', נגדיר קובץ cookie לא חוקי שמיועד לתנועה בלבד ונשתמש באחסון מקומי גם בתנועה של משתמשים שהביעו הסכמה וגם בתנועה של משתמשים שלא הסכימו לאיסוף נתונים. ברירת מחדל: `false` שימוש לדוגמה: `<div class="gcse-search" data-ivt="true"></div>`	תוצאות חיפוש תוצאות חיפוש בלבד
`mobileLayout`	מחרוזת	מציינת אם יש להשתמש בסגנונות הפריסה לנייד במכשירים ניידים. `enabled` משתמש בפריסה לנייד למכשירים ניידים בלבד. `disabled` לא משתמש בפריסה לנייד עבור אף מכשיר. `forced` עושה שימוש בפריסה לנייד עבור כל המכשירים. ברירת מחדל: `enabled` שימוש לדוגמה: `<div class="gcse-search" data-mobileLayout="disabled"></div>`	ללא הגבלה
השלמה אוטומטית
`enableAutoComplete`	בוליאני	האפשרות הזו זמינה רק אם ההשלמה האוטומטית הופעלה בלוח הבקרה של Programmable Search Engine. `true` מפעיל השלמה אוטומטית.	ללא הגבלה
`autoCompleteMaxCompletions`	מספר שלם	המספר המקסימלי של השלמות אוטומטיות להצגה.	searchbox תיבת חיפוש בלבד
`autoCompleteMaxPromotions`	מספר שלם	המספר המקסימלי של קידומי מכירות להצגה בהשלמה האוטומטית.	searchbox תיבת חיפוש בלבד
`autoCompleteValidLanguages`	מחרוזת	רשימה מופרדת בפסיקים של שפות שבהן יש להפעיל את ההשלמה האוטומטית. שפות נתמכות.	searchbox תיבת חיפוש בלבד
חידודים
`defaultToRefinement`	מחרוזת	האפשרות הזו זמינה רק אם נוצרו חידודים בלוח הבקרה של Programmable Search Engine. מציין את תווית החידוד שמוגדרת כברירת מחדל להצגה.הערה: המאפיין הזה לא נתמך לפריסה באירוח Google.	ללא הגבלה
`refinementStyle`	מחרוזת	הערכים הקבילים הם `tab` (ברירת מחדל) ו-`link`. יש תמיכה ב-`link` רק אם חיפוש באמצעות תמונות מושבת, או אם החיפוש באמצעות תמונות מופעל אבל החיפוש באינטרנט מושבת.	תוצאות חיפוש תוצאות חיפוש בלבד
חיפוש לפי תמונה
`enableImageSearch`	בוליאני	האפשרות הזו זמינה רק אם חיפוש באמצעות תמונות הופעל בלוח הבקרה של Programmable Search Engine. אם `true`, מפעיל חיפוש תמונות. תוצאות של תמונות יוצגו בכרטיסייה נפרדת.	תוצאות חיפוש תוצאות חיפוש בלבד
`defaultToImageSearch`	בוליאני	האפשרות הזו זמינה רק אם חיפוש באמצעות תמונות הופעל בלוח הבקרה של Programmable Search Engine. אם בוחרים באפשרות `true`, כברירת מחדל יוצגו בדף תוצאות החיפוש תוצאות של חיפוש תמונות. תוצאות האינטרנט יהיו זמינות בכרטיסייה נפרדת.	ללא הגבלה
`imageSearchLayout`	מחרוזת	האפשרות הזו זמינה רק אם חיפוש באמצעות תמונות הופעל בלוח הבקרה של Programmable Search Engine. מציין את הפריסה של דף התוצאות של חיפוש תמונות. הערכים הקבילים הם `classic`, `column` או `popup`.	תוצאות חיפוש תוצאות חיפוש בלבד
`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 מונפשים).	ללא הגבלה
חיפוש Google
`disableWebSearch`	בוליאני	אם `true`, השבתת החיפוש באינטרנט. בדרך כלל נעשה שימוש רק אם חיפוש באמצעות תמונות הופעל בלוח הבקרה של Programmable Search Engine.	תוצאות חיפוש תוצאות חיפוש בלבד
`webSearchQueryAddition`	מחרוזת	מונחים נוספים נוספו לשאילתת החיפוש באמצעות האופרטור הלוגי OR. שימוש לדוגמה: `<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 מופעל לתוצאות של websearch. הערכים הקבילים הם `off` ו-`active`.	ללא הגבלה
`as_filetype`	מחרוזת	הגבלת התוצאות לקבצים של תוסף שצוין. במרכז העזרה של Search Console תוכלו למצוא רשימה של סוגי קבצים ש-Google יכולה להוסיף לאינדקס.	ללא הגבלה
`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`	מחרוזת	קידום תוצאות חיפוש שמדינת המקור שלהן תואמת לערך הפרמטר. האפשרות הזו תפעל רק בשילוב עם ההגדרה language value. ערכים נתמכים שימוש לדוגמה: `<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`.	תוצאות חיפוש תוצאות חיפוש בלבד
`noResultsString`	מחרוזת	ציון טקסט ברירת המחדל שיוצג כשאין תוצאות שמתאימות לשאילתה. מחרוזת ברירת המחדל של התוצאה יכולה לשמש להצגת מחרוזת מותאמת לשוק המקומי בכל השפות הנתמכות, והמחרוזת המותאמת אישית לא מוצגת.	תוצאות חיפוש תוצאות חיפוש בלבד
`resultSetSize`	מספר שלם, מחרוזת	הגודל המרבי של קבוצת התוצאות. לדוגמה, `large`, `small`, `filtered_cse`, `10`. ברירת המחדל תלויה בפריסה ובשאלה אם המנוע מוגדר לחיפוש בכל האינטרנט או רק באתרים שצוינו.	ללא הגבלה
`safeSearch`	מחרוזת	מציינת אם החיפוש הבטוח מופעל לחיפוש באינטרנט וגם לחיפוש באמצעות תמונות. הערכים הקבילים הם `off` ו-`active`.	ללא הגבלה

התקשרות חזרה

תרשים רצף של קריאות חוזרות (callback) מרכיב החיפוש JavaScript — **תרשים רצף קריאה חוזרת**

בהתקשרות חזרה יש תמיכה מפורטת בניהול של אתחול רכיב החיפוש ותהליכי החיפוש. הם רשומים ב-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,
      },
    },
  };

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

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

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

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

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

הערה: דוגמאות הרצה בדף הזה פועלות באתר JSFiddle. חפש את לחצן jsfiddle,

, בפינה השמאלית העליונה של בלוק הקוד. לחיצה עליו תפתח דף JSFiddle שבו הדוגמה מוצגת בחלוניות HTML, JavaScript, css ו-run. ההפעלה מתחילה 'alive', לכן יש להזין שאילתה בתיבת החיפוש שמוצגת בחלונית ההרצה, והקריאה החוזרת תפעל.

הדוגמאות במסמך הזה מחולקות לחלקים בהתאם לסוג ולפונקציה שלהן, אבל:

כל החלקים של הדוגמה נשלחים אל JSFiddle יחד
לכל חלק בדוגמה יש לחצן JSFiddle. כולן עושות את אותו הדבר.

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

דוגמה לקריאה חוזרת (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 הזה כדי להתחיל לטעון את Search Element. מחליפים את הערך cx בסעיף src בערך cx שלכם.

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

חיפוש קריאות חוזרות (callback)

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

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

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

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

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

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

התחלת קריאה חוזרת (callback) לפי תמונה/חיפוש Google

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

searchStartingCallback(gname, query)

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

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

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

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

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

החיפוש לדוגמה שמתחיל בקריאה חוזרת (callback) בחיפוש לדוגמה מתחיל קריאה חוזרת (callback) מוסיף את 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>

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

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

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

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

הערה: הקריאה החוזרת עשויה לשנות באופן חופשי את ערכי הפרמטרים. שינויים ב-gname, query, promos, וב-results לא משפיעים על ההתנהגות של JavaScript של רכיב החיפוש, אבל אם הקריאה החוזרת (callback) מחזירה TRUE, מוצג עץ ה-DOM שיוצר ב-div.

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

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

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

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

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

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

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

callback(gname, query, promoElts, resultElts);

gname: מחרוזת הזיהוי של רכיב החיפוש
query: מחרוזת חיפוש.
promoElts: מערך של רכיבי DOM שמכילים קידומי מכירות.
resultElts: מערך של רכיבי DOM שמכילים תוצאות.

אין ערך מוחזר.

הערה: שינוי הערך של gname ושל query לא ישנה את ההתנהגות של ה-JavaScript של רכיב החיפוש, אבל שינויים בערכים ב-promoElts וב-resultElts הם שינויים ב-DOM.

הערה: רק רכיבי DOM שעברו רינדור על ידי ה-JavaScript של רכיב החיפוש עצמו מועברים לקריאה החוזרת של resultsRendered.

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

הדוגמה של התקשרות חזרה מסוג resultsRendered בקריאה חוזרת של תוצאות לדוגמה, מוסיפה תיבת סימון 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);
    }
  };

התקנת הקריאה החוזרת הזו ב-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). הדוגמה הבאה מראה דרך אחת ממגוון הדרכים שבהן אפשר להעביר ערך דירוג מ-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};
};

יש להתקין את הקריאה החוזרת (callback) באמצעות קוד כמו זה במהלך ההגדרה של __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>

דוגמאות נוספות להתקשרות חזרה

דוגמאות נוספות לקריאה חוזרת מופיעות במסמך דוגמאות נוספות לקריאה חוזרת.

מאפיינים של מבצעים ותוצאות

אם משתמשים בסימון JSDoc, אלה המאפיינים של אובייקטים של promotion ו-result. כאן אנו מפרטים את כל המאפיינים שעשויים להיות קיימים. הנוכחות של רבים מהנכסים תלויה בפרטים של המבצע או תוצאת החיפוש.

מאפייני קידום מכירות

{
  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 מפרסם את הפונקציות הסטטיות הבאות:

פעולה תיאור

.render(componentConfig, opt_componentConfig)

מעבד רכיב חיפוש.

פרמטרים

שם תיאור

componentConfig

התצורה של רכיב רכיב Programmable Search Element. מציינים את הפרטים הבאים:

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

opt_componentConfig

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

div (מחרוזת): ה-id של הרכיב <div> או של הרכיב div שבו הרכיב עובר.
tag (מחרוזת): סוג הרכיבים שיש לעבד. אם opt_componentConfig מסופק, הערך של המאפיין tag חייב להיות searchresults. בנוסף, הערך של המאפיין tag של componentConfig חייב להיות searchbox.
gname (מחרוזת): (אופציונלי) שם ייחודי לרכיב הזה. אם לא תספקו אותו, Programmable Search Engine ייצור gname לרכיב הזה באופן אוטומטי. אם הוא סופק, עליו להתאים ל-gname ב-componentConfig.
attributes (אובייקט): מאפיינים אופציונליים בצורת צמד מפתח/ערך. מאפיינים נתמכים.

.go(opt_container)

עיבוד כל התגים/המחלקות של רכיב החיפוש במאגר התגים שצוין.

פרמטרים

שם	תיאור
`opt_container`	המאגר שמכיל את רכיבי Search Element לעיבוד. מציינים את המזהה של המאגר (מחרוזת) או של הרכיב עצמו. אם המאפיין יושמט, יתבצע עיבוד של כל רכיבי 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.