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"> (או רכיבים אחרים) בדף השני.
תוצאות בלבד <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) של אתחול:

דוגמה לקריאה חוזרת (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 כדי להציג את התוצאות עצמן.

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

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

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

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