地址栏 omnibox

29-1 omnibox 是什么

omnibox 让你接管地址栏的一部分：用户输入你注册的关键词后，就进入你的逻辑。

典型用法是“快捷搜索”：输一个词，后面跟查询内容，回车就去搜。

它运行在后台服务工作者（Service Worker）里，所有事件都在那里注册。

用之前要在清单申请 omnibox 权限，并写死一个 keyword。

{
  "manifest_version": 3,
  "permissions": ["omnibox"],
  "omnibox": {
    "keyword": "myext"
  }
}

omnibox 是扩展里“存在感”很强的一个入口，用户不必打开任何页面就能用。

它和右键菜单都挂在后台，但触发方式不同：右键菜单绑定右键内容，omnibox 绑定地址栏输入。如果你的功能本质是“用户主动输入一个查询词”，omnibox 比弹出页更顺手。

29-2 声明关键词 keyword

keyword 写在 omnibox 字段下，是用户触发你扩展的“暗号”。

比如 keyword 设成 “myext”，用户就在地址栏输入 myext 加空格开始。

之后输入的任何内容，都会作为文本传给你的事件回调。

建议选一个短、好记、不和常见命令撞车的词，避免用户混淆。

因为整个浏览器只有一个地址栏，多个扩展、书签、内置命令都在抢这块地方。你的词越独特，用户越不容易误触到别的东西。

keyword 必须是纯小写、不含空格的单词。如果你写成 “MyExt” 或 “my ext”，扩展不会生效，也不会报错提示，调试时容易一脸懵。

29-3 监听输入变化

用户每敲一个字符，onInputChanged 就会触发，拿到当前文本和 suggest 回调。

chrome.omnibox.onInputChanged.addListener((text, suggest) => {
  if (!text) return;
  suggest([
    { content: text, description: "搜索：" + text },
    { content: "site:" + text, description: "站内搜索：" + text }
  ]);
});

suggest 接收一个建议数组，浏览器会把它们列在地址栏下拉里。

除了 onInputChanged，还有 onInputStarted（开始输入）和 onInputCancelled（取消输入）可用。

chrome.omnibox.onInputStarted.addListener(() => {
  console.log("用户开始用 omnibox");
});

onInputStarted 适合在这里做一些初始化，比如预加载数据；onInputCancelled 适合做清理。这两个事件在轻量扩展里用得不多，但了解一下没坏处。

29-4 构造建议列表

每个建议是个对象，至少有 content 和 description 两个字段。

content 是用户回车时真正提交的值，description 是展示在下拉里的文字。

chrome.omnibox.setDefaultSuggestion({
  description: "输入关键词开始搜索"
});

description 支持几个 XML 样式标签来高亮： 标重点， 标次要。

suggest([
  { content: "dog", description: "搜索 <match>dog</match> 相关图片" }
]);

deletable 设为 true 的话，用户还能在下拉里把这条建议删掉。

setDefaultSuggestion 设置的是用户还没输入时的占位提示，它会出现在下拉第一行。注意它的 description 同样支持 等标签。

description 里的标签要成对标对，写错（比如少了闭合）会导致这一行建议显示异常。如果不确定，先用纯文本跑通，再加高亮标签。

29-5 处理回车 onInputEntered

用户选定某条建议并回车，onInputEntered 触发，拿到 text 和 disposition。

chrome.omnibox.onInputEntered.addListener((text, disposition) => {
  const url = "https://example.com/search?q=" + encodeURIComponent(text);
  if (disposition === "currentTab") {
    chrome.tabs.update({ url });
  } else if (disposition === "newForegroundTab") {
    chrome.tabs.create({ url });
  } else {
    chrome.tabs.create({ url, active: false });
  }
});

disposition 告诉你用户想在哪打开：当前标签、新前台标签、还是新后台标签。

通常你根据它调用 tabs.update 或 tabs.create 把结果页打开。

这里的 text 是选中的那条建议的 content，不是用户原始输入。所以如果你在 suggest 里把 content 设成加工过的值（比如带了 site: 前缀），回车时拿到的就是加工后的值。

disposition 的取值：currentTab（当前标签）、newForegroundTab（新前台标签）、newBackgroundTab（新后台标签）。按 Ctrl+回车或 Alt+回车时，浏览器会自动切换为相应的新标签方式。

29-6 与后台联动

omnibox 的后台逻辑可以很轻：把输入组装成 URL，再打开对应标签。

chrome.omnibox.onInputEntered.addListener((text, disposition) => {
  const url = "https://example.com/search?q=" + encodeURIComponent(text);
  if (disposition === "currentTab") {
    chrome.tabs.update({ url });
  } else if (disposition === "newForegroundTab") {
    chrome.tabs.create({ url });
  } else {
    chrome.tabs.create({ url, active: false });
  }
});

如果你要做更复杂的动作，比如把数据存起来或发给内容脚本，同样用存储和消息 API。

比如你做了一个书签搜索扩展：onInputChanged 时去 chrome.bookmarks 里匹配标题，生成建议；onInputEntered 时 chrome.tabs.update 跳到那个书签地址。全程都在后台完成，不需要任何可见页面。

29-7 调试与限制

改了 keyword 或事件逻辑，一定去扩展管理页点“重新加载”再试。

地址栏输入 keyword 后必须跟一个空格，扩展的建议才会接管下拉。

一个常见的“看起来没反应”：用户在地址栏输了 keyword 但没敲空格。浏览器只有在 keyword 后面跟一个空格、进入“扩展输入模式”后，才会把后续输入交给你的 onInputChanged。所以提示用户“加空格”很关键。

此外，omnibox 的 keyword 在地址栏是大小写不敏感的：用户输 “MYEXT” 也能触发，但清单里必须写小写。

29-8 小结

omnibox 的链路是：清单里定 keyword，onInputChanged 给建议，onInputEntered 拿回车去执行。

它和右键菜单一样，事件都挂在后台服务工作者上，所以逻辑也得写在后台脚本里。

建议列表不要贪多，几条最相关的就够。description 里用 高亮关键词，能明显提升可读性。

当你把“输入—建议—回车—打开”这条链路跑顺，扩展就多了一个不抢界面的轻量入口。

29-9 描述文案与异步建议

description 里的 XML 标签不止 ，还有 用来弱化次要信息， 专门高亮网址片段。

合理使用这些标签，下拉里的建议会更易读，用户一眼就能抓住重点。

如果建议来自网络请求，onInputChanged 里要做好异步。先发请求，回来后调用 suggest 把结果补进下拉即可。

注意请求可能慢于用户输入，最好做一个简单的防抖或取消上一次请求，避免旧结果覆盖新输入。

举个例子，异步取建议时维护一个“最新请求序号”，每次 onInputChanged 都自增序号；请求回来后比对序号，只有最新的那个才调用 suggest。这样旧请求的结果就不会覆盖新输入了。

29-10 常见误区

第一个坑：地址栏输完 keyword 没跟空格。扩展的建议只有在一个空格之后才开始接管下拉，别忘了提醒用户。

第二个坑：keyword 不是小写或含空格。清单里写 “MyExt” 或 “my ext” 都不会生效，必须是纯小写、无空格的单词。

第三个坑：onInputEntered 里没按 disposition 处理。用户按 Ctrl+回车想开新标签，你却只更新了当前页，会不符合预期。

还有一个隐藏点：keyword 全局唯一，且和浏览器内置命令、其他扩展都共用地址栏。选词时尽量带品牌标识，减少冲突。