browser.omnibox

תיאור

‫omnibox API מאפשר לכם לרשום מילת מפתח בסרגל הכתובות של Google Chrome, שנקרא גם סרגל הכתובות המשולב.

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

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

מניפסט

כדי להשתמש ב-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"]
  }
}

הערה: דפדפן Chrome יוצר באופן אוטומטי גרסה בגווני אפור של הסמל בגודל 16x16 פיקסלים. כדאי לספק גרסה בצבע מלא כדי שאפשר יהיה להשתמש בה גם במצבים אחרים שבהם נדרש צבע. לדוגמה, ה-API של תפריטי ההקשר משתמש גם בסמל בגודל 16x16 פיקסלים, אבל הוא מוצג בצבע.

דוגמאות

כדי לנסות את ה-API הזה, מתקינים את הדוגמה ל-omnibox API ממאגר chrome-extension-samples.

סוגים

DefaultSuggestResult

תוצאה מוצעת.

מאפיינים

• תיאור

  מחרוזת

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

DescriptionStyleType

Chrome 44 ואילך browser.* ‎ מ-Chrome 148

סוג הסגנון.

טיפוסים בני מנייה (enum)

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44 ואילך browser.* ‎ מ-Chrome 148

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

טיפוסים בני מנייה (enum)

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

תוצאה מוצעת.

מאפיינים

• תוכן

  מחרוזת

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

• ניתן למחיקה

  בוליאני אופציונלי

  ‫Chrome 63 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

• תיאור

  מחרוזת

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

Methods

setDefaultSuggestion()

browser.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
): Promise<void>

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

פרמטרים

• הצעה

  DefaultSuggestResult

  אובייקט SuggestResult חלקי, בלי הפרמטר content.

החזרות

• Promise<void>

  ‫Chrome 100+‎ browser.* ‎ מגרסה Chrome 148

אירועים

onDeleteSuggestion

‫Chrome 63 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

browser.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

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

פרמטרים

• callback

  פונקציה

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

  (text: string) => void

  • text

    מחרוזת

onInputCancelled

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

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

פרמטרים

• callback

  פונקציה

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

  () => void

onInputChanged

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

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

פרמטרים

• callback

  פונקציה

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

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

  • text

    מחרוזת

  • הצעה

    פונקציה

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

    (suggestResults: SuggestResult[]) => void

    • suggestResults

      SuggestResult[]

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

onInputEntered

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

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

פרמטרים

• callback

  פונקציה

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

  (text: string, disposition: OnInputEnteredDisposition) => void

  • text

    מחרוזת

  • מחיקה

    OnInputEnteredDisposition

onInputStarted

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

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

פרמטרים

• callback

  פונקציה

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

  () => void