דף זה תורגם על ידי 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 לדף האינטרנט שלכם, יחד עם הסברים על רכיבים שניתנים להגדרה ו-API גמיש של JavaScript.

היקף

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

תאימות דפדפן

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

קהל

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

רכיבי חיפוש ניתנים לתכנות

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

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

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

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

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

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

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

<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` 'תיבת חיפוש בלבד0' ובשנייה `gname` 'seachbox-only1', וכן הלאה. חשוב לשים לב שהשדה `gname` שנוצר באופן אוטומטי לרכיב ב- פריסת שתי עמודות תהיה `two-column`. הדוגמה הבאה משתמש בשם השם `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`, היא מפעילה את ניהול ההיסטוריה בדפדפן הקודם ו'הבא'. לצפייה בהדגמה	תיבת חיפוש תיבת חיפוש בלבד
`queryParameterName`	מחרוזת	שם הפרמטר של השאילתה, לדוגמה `q` (ברירת המחדל) או `query`. הוא יוטמע בכתובת ה-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>`	תוצאות חיפוש searchresults-only
`mobileLayout`	מחרוזת	ההגדרה קובעת אם אפשר להשתמש בסגנונות הפריסה לנייד במכשירים ניידים. הפונקציה `enabled` משתמשת בפריסה לנייד בלבד. `disabled` לא משתמשת בפריסה לנייד באף מכשיר. `forced` עושה שימוש בפריסה לנייד בכל המכשירים. ברירת מחדל: `enabled` שימוש לדוגמה: `<div class="gcse-search" data-mobileLayout="disabled"></div>`	הכול
השלמה אוטומטית
`enableAutoComplete`	בוליאני	האפשרות הזו זמינה רק אם הופעלה השלמה אוטומטית בלוח הבקרה של Programmable Search Engine. `true` מפעיל השלמה אוטומטית.	הכול
`autoCompleteMaxCompletions`	מספר שלם	המספר המקסימלי של השלמות אוטומטיות להצגה.	תיבת חיפוש תיבת חיפוש בלבד
`autoCompleteMaxPromotions`	מספר שלם	המספר המקסימלי של קידומי מכירות שיוצגו בהשלמה האוטומטית.	תיבת חיפוש תיבת חיפוש בלבד
`autoCompleteValidLanguages`	מחרוזת	רשימה מופרדת בפסיקים של השפות שעבורן צריכה להיות השלמה אוטומטית מופעל. שפות נתמכות.	תיבת חיפוש תיבת חיפוש בלבד
חידודים
`defaultToRefinement`	מחרוזת	זמין רק אם חידודים נוצרו לוח הבקרה של Programmable Search Engine. ציון תווית החידוד שמוגדרת כברירת מחדל ל- הערה: המאפיין הזה לא נתמך בפריסה באירוח Google.	הכול
`refinementStyle`	מחרוזת	הערכים הקבילים הם `tab` (ברירת מחדל) ו-`link`. יש תמיכה ב-`link` רק אם החיפוש באמצעות תמונות מושבת, או אם חיפוש תמונות מופעל אך החיפוש באינטרנט מושבת.	תוצאות חיפוש searchresults-only
חיפוש לפי תמונה
`enableImageSearch`	בוליאני	זמין רק אם חיפוש תמונות הופעל בלוח הבקרה של Programmable Search Engine. אם הערך הוא `true`, יופעל חיפוש תמונות. תוצאות של תמונות יוצגו טאב נפרד.	תוצאות חיפוש searchresults-only
`defaultToImageSearch`	בוליאני	זמין רק אם חיפוש תמונות הופעל בלוח הבקרה של Programmable Search Engine. אם הערך שלו הוא `true`, יוצגו תוצאות חיפוש עם תמונות בדף תוצאות החיפוש כברירת מחדל. תוצאות מהאינטרנט יהיו זמינות בכרטיסייה נפרדת.	הכול
`imageSearchLayout`	מחרוזת	זמין רק אם חיפוש תמונות הופעל בלוח הבקרה של Programmable Search Engine. מציינת את הפריסה של דף תוצאות החיפוש של התמונות. ערכים קבילים הם `classic`, `column` או `popup`.	תוצאות חיפוש 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. סינון תוצאות החיפוש באמצעות Logical 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.	תוצאות חיפוש 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 הוא מופעל לתוצאות websearch. הערכים הקבילים הם `off` ו-`active`.	הכול
`as_filetype`	מחרוזת	הגבלת התוצאות לקבצים עם סיומת מסוימת. במרכז העזרה של Search Console ניתן למצוא רשימה של סוגי קבצים ש-Google יכולה להוסיף לאינדקס.	הכול
`as_oq`	מחרוזת	סינון תוצאות החיפוש באמצעות Logical 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-only
`noResultsString`	מחרוזת	ציון טקסט ברירת המחדל שיוצג כשאין תוצאות שתואמות לשאילתה. ניתן להשתמש במחרוזת התוצאה המוגדרת כברירת מחדל כדי להציג מחרוזת מותאמת לשוק המקומי בכל בעוד שהשפה המותאמת אישית לא תומכת בהם.	תוצאות חיפוש searchresults-only
`resultSetSize`	מספר שלם, מחרוזת	הגודל המקסימלי של קבוצת התוצאות. לדוגמה, `large`, `small`, `filtered_cse`, `10`. תלוי בפריסה ובהגדרת המנוע לחיפוש את כל האינטרנט או רק אתרים שצוינו.	הכול
`safeSearch`	מחרוזת	מציין אם החיפוש הבטוח מופעל גם לחיפוש באינטרנט וגם לחיפוש באמצעות תמונות. הערכים הקבילים הם: `off` ו-`active`.	הכול

התקשרות חזרה

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

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

רישום קריאה חוזרת (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 משאיר את עיבוד רכיבי החיפוש קריאה חוזרת (callback) של אתחול (כפי שמוצג בקטע רישום התקשרות חזרה). משמש לבחירת רכיבים לעיבוד, או לדחייה של רכיבי רינדור עד שהם הדרושים. הוא יכול גם לשנות את המאפיינים של הרכיבים; למשל, הוא יכול להפוך תיבת חיפוש שמוגדרת באמצעות מאפייני 'לוח הבקרה' או 'HTML' כברירת מחדל של 'אינטרנט' לחפש בתיבת חיפוש באמצעות תמונות, או לציין ששאילתות שנשלחות באמצעות טופס של Programmable Search Engine הן בוצעה ברכיב Searchresults בלבד. להדגמה.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

searchStartingCallback(gname, query)

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

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

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

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

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

חיפוש לדוגמה שמתחיל ב- קריאה חוזרת לדוגמה בחיפוש Google מוסיפה morning או afternoon לשאילתה, בהתאם לשעה ביום.

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

    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>

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

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

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

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

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

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

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

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

דוגמה לקריאה חוזרת (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) שמוסיפה תוכן של תוצאות שהחיפוש לא מוצג בהם רכיב, כמו תיבת הסימון Save this או מידע מעובדת באופן אוטומטי, או קריאה חוזרת (callback) שמוסיפה לחצני למידע נוסף.

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

callback(gname, query, promoElts, resultElts);

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

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

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

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

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

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

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

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

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

מאפייני קידום ותוצאה

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

פעולה תיאור

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

.getElement(gname)

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

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

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

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

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

.getAllElements() מחזירה מפה של כל אובייקטי הרכיב שנוצרו בהצלחה, עם קידוד של gname.