browser.omnibox

說明

Omnibox API 可讓您在 Google Chrome 的網址列 (也稱為多功能框) 註冊關鍵字。

螢幕截圖：顯示與關鍵字「Chromium Search」相關的建議

使用者輸入擴充功能的關鍵字後，就只會與擴充功能互動。每次按鍵輸入都會傳送至擴充功能，您可以據此提供建議。

建議可以採用多種格式。使用者接受建議時，擴充功能會收到通知並採取行動。

資訊清單

您必須在資訊清單中宣告下列金鑰，才能使用這個 API。

"omnibox"

您必須在資訊清單中加入 "omnibox.keyword" 欄位，才能使用 Omnibox API。您也應指定 16 x 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，請從 chrome-extension-samples 存放區安裝 omnibox API 範例。

類型

DefaultSuggestResult

建議結果。

屬性

  • 說明

    字串

    網址下拉式選單中顯示的文字。可包含 XML 樣式的標記，用於設定樣式。支援的標記包括「url」(用於常值網址)、「match」(用於醒目顯示與使用者查詢相符的文字) 和「dim」(用於調暗輔助文字)。樣式可以巢狀，例如：暗色比對。

DescriptionStyleType

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

樣式類型。

列舉

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

網址列查詢的視窗配置。建議在這種情境下顯示結果。舉例來說，如果網址列指令是前往特定網址，則「newForegroundTab」處置方式表示應在新的所選分頁中前往該網址。

列舉

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

建議結果。

屬性

  • 內容

    字串

    使用者選擇這個項目時，系統會將這段文字放入網址列，並傳送至擴充功能。

  • deletable

    布林值 選填

    Chrome 63 以上版本 Chrome 148 以上版本的瀏覽器

    使用者是否可以刪除建議結果。

  • 說明

    字串

    網址下拉式選單中顯示的文字。可包含 XML 樣式的標記，用於設定樣式。支援的標記包括「url」(用於常值網址)、「match」(用於醒目顯示與使用者查詢相符的文字) 和「dim」(用於調暗輔助文字)。樣式可以巢狀，例如：暗色比對。您必須逸出五個預先定義的實體，才能將其顯示為文字：stackoverflow.com/a/1091953/89484

方法

setDefaultSuggestion()

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

設定預設建議的說明和樣式。預設建議是指網址列下方第一個建議列中顯示的文字。

參數

傳回

  • 承諾<void>

    Chrome 100+ browser.* (自 Chrome 148 起)

事件

onDeleteSuggestion

Chrome 63 以上版本 Chrome 148 以上版本的瀏覽器 
browser.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

使用者已刪除建議結果。

參數

  • callback

    函式

    callback 參數如下： 

    (text: string) => void

    • 文字

      字串

onInputCancelled

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

使用者已結束關鍵字輸入工作階段，但未接受輸入內容。

參數

  • callback

    函式

    callback 參數如下： 

    () => void

onInputChanged

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

使用者已變更在網址列中輸入的內容。

參數

  • callback

    函式

    callback 參數如下： 

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

    • 文字

      字串

    • suggest

      函式

      suggest 參數如下： 

      (suggestResults: SuggestResult[]) => void

onInputEntered

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

使用者已接受在多功能框中輸入的內容。

參數

onInputStarted

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

使用者輸入擴充功能的關鍵字，開始關鍵字輸入工作階段。這項事件保證在每個輸入工作階段中只會傳送一次，且會在任何 onInputChanged 事件之前傳送。

參數

  • callback

    函式

    callback 參數如下： 

    () => void