chrome.omnibox

說明

網址列 API 可讓您在 Google Chrome 的網址列 (又稱為網址列) 登錄關鍵字。

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

使用者輸入擴充功能的關鍵字時，使用者只會開始與額外資訊互動。每個按鍵行為都會傳送至你的擴充功能，你也可以提供建議。

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

資訊清單

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

"omnibox"

您必須在資訊清單中加入 "omnibox.keyword" 欄位，才能使用網址列 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 範例。

類型

DefaultSuggestResult

建議結果。

屬性

  • description

    字串

    網址下拉式選單中顯示的文字。可包含設定樣式的 XML 樣式標記。支援的標記為「url」(如文字網址)、「match」(以醒目顯示符合使用者查詢內容的文字) 和「dim」(用於暗淡輔助文字)。樣式可以是巢狀結構，例如暗灰色。

DescriptionStyleType

Chrome 44 以上版本

樣式類型。

列舉

"match"

"dim"

OnInputEnteredDisposition

Chrome 44 以上版本

網址列查詢的視窗配置。這是顯示結果的建議情境。舉例來說，如果網址列指令可前往特定網址，「newForegroundTab」代表導覽會在新分頁中生效。

列舉

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

建議結果。

屬性

  • 內容

    字串

    使用者選擇這個項目時，網址列中顯示的文字。

  • 可刪除

    布林值 (選用)

    Chrome 63 以上版本

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

  • description

    字串

    網址下拉式選單中顯示的文字。可包含設定樣式的 XML 樣式標記。支援的標記為「url」(如文字網址)、「match」(以醒目顯示符合使用者查詢內容的文字) 和「dim」(用於暗淡輔助文字)。樣式可以是巢狀結構，例如暗灰色。您必須逸出五個預先定義的實體，才能以文字顯示：Stackoverflow.com/a/1091953/89484

方法

setDefaultSuggestion()

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

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

參數

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

  • 回呼

    函式選用

    Chrome 100 以上版本

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 100 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

onDeleteSuggestion

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

使用者已刪除建議的結果。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (text: string)=>void

    • text

      字串

onInputCancelled

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

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

參數

  • 回呼

    功能

    callback 參數如下所示： 

    ()=>void

onInputChanged

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

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

參數

  • 回呼

    功能

    callback 參數如下所示： 

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

    • text

      字串

    • suggest

      功能

      suggest 參數如下所示： 

      (suggestResults: SuggestResult[])=>void

onInputEntered

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

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

參數

onInputStarted

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

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

參數

  • 回呼

    功能

    callback 參數如下所示： 

    ()=>void