chrome.omnibox

refresh date: 2026-09-25 robots: noindex

תיאור

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

צילום מסך שבו רואים הצעות שקשורות למילת המפתח "חיפוש ב-Chromium"

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

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

מניפסט

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

לדוגמה:

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

דוגמאות

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

סוגים

DefaultSuggestResult

תוצאה מוצעת.

מאפיינים

  • תיאור

    מחרוזת

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

Methods

setDefaultSuggestion()

Promise 
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
): Promise<void>

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

פרמטרים

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

  • callback

    function optional

    ‫Chrome מגרסה 100 ואילך

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 100 ואילך

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

אירועים

onDeleteSuggestion

Chrome 63 ואילך 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

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

פרמטרים

  • callback

    פונקציה

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

    (text: string) => void

    • text

      מחרוזת

onInputCancelled

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

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

פרמטרים

  • callback

    פונקציה

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

    () => void

onInputChanged

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

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

פרמטרים

  • callback

    פונקציה

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

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

    • text

      מחרוזת

    • הצעה

      פונקציה

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

      (suggestResults: SuggestResult[]) => void

      • suggestResults

        SuggestResult[]

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

onInputEntered

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

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

פרמטרים

onInputStarted

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

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

פרמטרים

  • callback

    פונקציה

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

    () => void