chrome.omnibox

תיאור

ממשק ה-API של סרגל הכתובות מאפשר לרשום מילת מפתח באמצעות סרגל הכתובות של Google Chrome, שנקרא גם 'סרגל הכתובות'.

צילום מסך שבו מוצגות הצעות שקשורות למילת המפתח 'חיפוש Chromium'

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

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

מניפסט

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

"omnibox"

כדי להשתמש בממשק API של סרגל הכלים, עליך לכלול את השדה "omnibox.keyword" במניפסט. שלך צריך גם לציין סמל בגודל 16 על 16 פיקסלים, שיוצג בסרגל הכתובות כשתציעו שהמשתמשים עוברים למצב מילות מפתח.

לדוגמה:

{
  "name": "Aaron's omnibox extension",
  "version": "1.0",
  "omnibox": { "keyword" : "aaron" },
  "icons": {
    "16": "16-full-color.png"
  },
  "background": {
    "persistent": false,
    "scripts": ["background.js"]
  }
}

דוגמאות

כדי לנסות את ה-API הזה, צריך להתקין את הדוגמה ל-API של סרגל הכתובות מchrome-extension-samples. של מאגר הנתונים.

סוגים

DefaultSuggestResult

תוצאה מוצעת.

מאפיינים

  • תיאור

    מחרוזת

    הטקסט שמוצג בתפריט הנפתח של כתובת ה-URL. יכול להכיל תגי עיצוב בסגנון XML לצורך עיצוב. התגים הנתמכים הם url (לכתובת אתר מילולית), 'match' (להדגשת טקסט שתאם לשאילתה של המשתמש) ו-'dim' (לטקסט עזרה מעומעם). הסגנונות יכולים להיות מקוננים, למשל התאמה מעומעם.

DescriptionStyleType

Chrome 44 ואילך

סוג הסגנון.

Enum

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44 ואילך

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

Enum

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

תוצאה מוצעת.

מאפיינים

  • תוכן

    מחרוזת

    הטקסט שמועבר בסרגל של כתובת ה-URL, שנשלח לתוסף כשהמשתמש בוחר ברשומה הזו.

  • ניתנת להסרה

    ערך בוליאני אופציונלי

    Chrome 63+

    אם המשתמש יכול למחוק את התוצאה המוצעת.

  • תיאור

    מחרוזת

    הטקסט שמוצג בתפריט הנפתח של כתובת ה-URL. יכול להכיל תגי עיצוב בסגנון XML לצורך עיצוב. התגים הנתמכים הם url (לכתובת אתר מילולית), 'match' (להדגשת טקסט שתאם לשאילתה של המשתמש) ו-'dim' (לטקסט עזרה מעומעם). הסגנונות יכולים להיות מקוננים, למשל התאמה מעומעם. צריך לסמן בתו בריחה (escape) את חמש הישויות המוגדרות מראש כדי שהן יוצגו כטקסט: Stackoverflow.com/a/1091953/89484

שיטות

setDefaultSuggestion()

הבטחה 
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
)

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

פרמטרים

  • הצעה מ-Android

    DefaultSuggestResult

    אובייקט Offer result חלקי, ללא 'content' הפרמטר.

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

    Chrome 100+

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 100+

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

אירועים

onDeleteSuggestion

Chrome 63+ 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

משתמש מחק תוצאה מוצעת.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    (text: string) => void

    • טקסט

      מחרוזת

onInputCancelled

chrome.omnibox.onInputCancelled.addListener(
  callback: function,
)

המשתמש סיים את הסשן של הזנת מילת מפתח בלי לאשר את הקלט.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    () => void

onInputChanged

chrome.omnibox.onInputChanged.addListener(
  callback: function,
)

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    (text: string, suggest: function) => void

    • טקסט

      מחרוזת

    • להציע

      פונקציה

      הפרמטר suggest נראה כך: 

      (suggestResults: SuggestResult[]) => void

      • suggestResults

        SuggestResult[]

        מערך של הצעות לתוצאות

onInputEntered

chrome.omnibox.onInputEntered.addListener(
  callback: function,
)

המשתמש קיבל את הטקסט שמוקלד בסרגל הכתובות.

פרמטרים

onInputStarted

chrome.omnibox.onInputStarted.addListener(
  callback: function,
)

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    () => void