chrome.omnibox

תיאור

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

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

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

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

מניפסט

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

סוג הסגנון.

Enum

"url"

‫"match"

‫"dim"

OnInputEnteredDisposition

‫Chrome 44 ואילך

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

Enum

‫"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.

פרמטרים

  • הצעה מ-Android

    DefaultSuggestResult

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

  • callback

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

    ‫Chrome 100 ואילך

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 100 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

אירועים

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