chrome.omnibox

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

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

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

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

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

מניפסט

כדי להשתמש ב-Omnibox 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 ואילך

סוג הסגנון.

ספירה

‫"url"

'התאמה'

‫"dim"

OnInputEnteredDisposition

‫Chrome 44 ואילך

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

ספירה

‫currentTab

‪"newForegroundTab"

"newBackgroundTab"

SuggestResult

תוצאה של הצעה.

מאפיינים

  • תוכן

    מחרוזת

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

  • ניתן למחיקה

    ‫boolean אופציונלי

    ‫Chrome 63 ואילך

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

  • תיאור

    מחרוזת

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

Methods

setDefaultSuggestion()

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

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

פרמטרים

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

  • callback

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

    ‫Chrome 100 ואילך

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 100 ואילך

    התמיכה ב-Promises קיימת רק ב-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