browser.omnibox

说明

借助 omnibox API，您可以在 Google Chrome 的地址栏（也称为多功能框）中注册关键字。

显示与关键字“Chromium 搜索”相关的建议的屏幕截图

当用户输入扩展程序的关键字时，用户开始仅与您的扩展程序互动。每次按键都会发送到您的扩展程序，您可以提供建议作为响应。

建议可以采用多种方式进行丰富格式设置。当用户接受建议时，您的扩展程序会收到通知并可以采取行动。

清单

必须在清单中声明以下键，才能使用此 API。

"omnibox"

您必须在清单中添加 "omnibox.keyword" 字段，才能使用 omnibox API。您还应指定一个 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，请从 chrome-extension-samples 代码库中安装 omnibox API 示例。

类型

DefaultSuggestResult

建议结果。

属性

  • 说明

    字符串

    网址下拉菜单中显示的文字。可包含 XML 样式的标记，用于设置样式。支持的标记包括“url”（表示字面量网址）、“match”（表示突出显示与用户查询匹配的文本）和“dim”（表示暗淡的辅助文本）。样式可以嵌套，例如：变暗的匹配项。

DescriptionStyleType

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

样式类型。

枚举

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

多功能框查询的窗口处置。这是显示结果的推荐上下文。例如，如果多功能框命令是导航到某个网址，则“newForegroundTab”处置方式意味着应在选中的新标签页中进行导航。

枚举

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

建议结果。

属性

  • 内容

    字符串

    当用户选择此条目时，系统会将其放入网址栏并发送给扩展程序。

  • deletable

    布尔值 （可选）

    Chrome 63 及更高版本 browser.*（自 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 及更高版本 browser.*（自 Chrome 148 起） 
browser.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

用户已删除建议的结果。

参数

  • callback

    函数

    callback 参数如下所示： 

    (text: string) => void

    • text

      字符串

onInputCancelled

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

用户已结束关键字输入会话，但未接受输入。

参数

  • callback

    函数

    callback 参数如下所示： 

    () => void

onInputChanged

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

用户更改了在多功能框中输入的内容。

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • text

      字符串

    • suggest

      函数

      suggest 参数如下所示： 

      (suggestResults: SuggestResult[]) => void

onInputEntered

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

用户已接受在多功能框中输入的内容。

参数

onInputStarted

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

用户已通过输入扩展程序的关键字启动了关键字输入会话。这可保证在每个输入会话中仅发送一次，并且在任何 onInputChanged 事件之前发送。

参数

  • callback

    函数

    callback 参数如下所示： 

    () => void