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' (לכתובת URL מילולית), 'match' (להדגשת טקסט שתואם לשאילתה של המשתמש) ו-'dim' (לטקסט עזר עמום). הסגנונות יכולים להיות מקוננים, למשל התאמה מעומעמת.

DescriptionStyleType

Chrome 44 ואילך

סוג הסגנון.

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

"url"

"dim"

OnInputEnteredDisposition

Chrome 44 ואילך

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

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

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

תוצאה מוצעת.

תכונות

  • רווחי

    מחרוזת

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

  • ניתן למחיקה

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

    Chrome מגרסה 63 ואילך

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

  • תיאור

    מחרוזת

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

שיטות

setDefaultSuggestion()

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

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

פרמטרים

  • הצעה מ-Android

    DefaultSuggestResult

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

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

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

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

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

    ()=>void

החזרות

  • Promise<void>

    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