chrome.omnibox

說明

網址列 API 可讓您透過 Google Chrome 的網址列 (又稱為網址列) 註冊關鍵字。

這張螢幕截圖顯示與關鍵字「Chromium 搜尋」相關的建議

使用者輸入擴充功能的關鍵字時，使用者只會開始與 。每個按鍵動作都會傳送至擴充功能，您可以提供回應建議。

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

資訊清單

您必須在資訊清單中宣告下列金鑰，才能使用這個 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 提供的網址列 API 範例。 Cloud Storage 也提供目錄同步處理功能

類型

DefaultSuggestResult

建議結果。

屬性

  • 說明

    字串

    網址下拉式選單中顯示的文字。可包含用於樣式的 XML 樣式標記。支援的標記為「url」(如果是常值網址)，「match」(用於醒目顯示符合使用者查詢的文字) 以及「dim」(適用於將說明文字調暗)。樣式可採用巢狀結構，例如設定為廣泛比對。

DescriptionStyleType

Chrome 44 以上版本

樣式類型。

列舉

"url"

"相符"

"dim"

OnInputEnteredDisposition

Chrome 44 以上版本

網址列查詢的視窗配置。這是顯示結果的建議結構定義。舉例來說，如果網址列指令是要前往特定網址，系統會將「newForegroundTab」做為配置方式表示導覽應在新的所選分頁中進行。

列舉

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

建議結果。

屬性

  • 內容

    字串

    會顯示在網址列的文字，在使用者選擇這個項目時傳送至擴充功能。

  • 可卸除

    布林值 選填

    Chrome 63 以上版本

    使用者能否刪除建議結果。

  • 說明

    字串

    網址下拉式選單中顯示的文字。可包含用於樣式的 XML 樣式標記。支援的標記為「url」(如果是常值網址)，「match」(用於醒目顯示符合使用者查詢的文字) 以及「dim」(適用於將說明文字調暗)。樣式可採用巢狀結構，例如設定為廣泛比對。您必須逸出以下五個預先定義的實體，才能將其顯示為文字：Stackoverflow.com/a/1091953/89484

方法

setDefaultSuggestion()

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

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

參數

  • 部分 SuggestResult 物件，不含「content」參數。

  • 回呼

    函式 選用

    Chrome 100 以上版本

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 100 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

活動

onDeleteSuggestion

Chrome 63 以上版本 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

使用者已刪除建議結果。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (text: string) => void

    • 文字

      字串

onInputCancelled

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    () => void

onInputChanged

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

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

    • 文字

      字串

    • suggest

      函式

      suggest 參數如下所示： 

      (suggestResults: SuggestResult[]) => void

onInputEntered

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

使用者已接受網址列輸入的內容。

參數

onInputStarted

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

使用者輸入擴充功能的關鍵字後，啟動了關鍵字輸入工作階段。保證每個輸入工作階段只會傳送一次，以及在任何 onInputChanged 事件之前傳送。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    () => void