chrome.omnibox

说明

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

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

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

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

清单

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

"omnibox"

您必须在清单中添加 "omnibox.keyword" 字段才能使用多功能框 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 代码库安装多功能框 API 示例。

类型

DefaultSuggestResult

建议结果。

属性

  • 说明

    string

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

DescriptionStyleType

Chrome 44 及更高版本

样式类型。

枚举

"url"

OnInputEnteredDisposition

Chrome 44 及更高版本

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

枚举

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

建议结果。

属性

  • 内容

    string

    放置在网址栏中的文本，当用户选择此条目时，系统会将该文本发送到扩展程序。

  • 可删除

    布尔值 选填

    Chrome 63 及更高版本

    用户是否可以将建议结果删除。

  • 说明

    string

    网址下拉菜单中显示的文字。可以包含用于样式设置的 XML 样式标记。支持的标记包括“url”（用于文字网址）、“match”（用于突出显示与用户查询的内容匹配的文本）和“dim”（用于暗淡的帮助文本）。样式可以嵌套，例如采用暗匹配。您必须转义五个预定义实体才能将其显示为文本：stackoverflow.com/a/1091953/89484

方法

setDefaultSuggestion()

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

为默认建议设置说明和样式。默认建议是显示在网址栏下方第一个建议行的文本。

参数

  • 部分 SuggestedResult 对象，不含“content”参数。

  • callback

    函数（可选）

    Chrome 100 及更高版本

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 100 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

活动

onDeleteSuggestion

Chrome 63 及更高版本 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

用户删除了建议的结果。

参数

  • callback

    功能

    callback 参数如下所示：

    (text: string)=>void

    • text

      string

onInputCancelled

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

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

参数

  • callback

    功能

    callback 参数如下所示：

    ()=>void

onInputChanged

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

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

参数

  • callback

    功能

    callback 参数如下所示：

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

    • text

      string

    • suggest

      功能

      suggest 参数如下所示：

      (suggestResults: SuggestResult[])=>void

onInputEntered

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

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

参数

onInputStarted

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

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

参数

  • callback

    功能

    callback 参数如下所示：

    ()=>void