跳转到主要内容
Extension.js 从两个来源处理 HTML 入口:manifest 字段与特殊文件夹 pages/。Manifest 字段包括 popup、options、side panel、new tab 与 DevTools。对于 manifest 没有直接命名的路由,使用 pages/。 Extension.js 会遍历每个入口的脚本、样式和关联资源。你编写纯 HTML,Extension.js 会自动完成全部配置。

模板示例

new

new template screenshot 带有 HTML 页面入口的最简 new-tab 扩展。
仓库:extension-js/templates/newtab sidebar template screenshot 带有 HTML 页面入口的 side panel 扩展,用于持久性的伴随 UI。
仓库:extension-js/templates/sidebar

HTML 能力

受支持的 HTML 入口

以下 manifest 字段使用 HTML 文件作为入口: 你也可以把独立页面放在 pages/ 下,无需为每个文件都扩展 manifest 入口字段。

HTML 入口示例

Extension.js 如何处理 HTML

对每个 HTML 入口,Extension.js 会:
  1. 把该 HTML 文件加入编译输出。
  2. 从标签中发现本地脚本/样式/静态资源。
  3. 将脚本/样式打包成合适的扩展产物。
  4. 修补 HTML,注入对编译后产物的引用。
  5. 保留 public-root 引用(例如 /icon.png)作为 public 资源。
从 HTML 引用的静态资源会按其相对源码的路径输出,因此运行时引用(例如你同时也会在 JavaScript 里读取的 <img> src)在构建后的扩展里,会和浏览器从源码提供它们时以同样的方式解析。 另一个页面用 <iframe> 加载的页面会作为独立文件输出到 assets/ 下。它的脚本、样式表和图片会以副本形式输出,它的引用会指向这些副本。dev 会监视它们,所以保存后框架内容会更新。构建不会打包这类页面的脚本,所以请用普通的浏览器 JavaScript 编写它们。只通过 <a href> 链接到达的页面不会被复制。请把这类页面放到 pages/ 下。

同一页面上的多个经典脚本

当一个页面列出多个 <script> 标签、且它们都没有使用 type="module" 时,这些脚本在浏览器里共享同一个 sloppy 模式的全局作用域:一个文件里的 var 声明和隐式全局变量对下一个文件可见。Extension.js 通过把全部为经典脚本的列表按标签顺序拼接进同一个共享作用域来保留这个行为,让跨脚本的全局变量在构建后依然有效。只要页面里有至少一个 type="module" 脚本,就仍然按标准的逐脚本打包处理。

开发期行为

  • Extension.js 会把 HTML 与所引用的资源加入文件依赖跟踪,因此编辑会触发重新编译。
  • 在受支持时,脚本变更会在注入的脚本流程中使用热模块替换(HMR)。
  • 如果 HTML 中脚本/样式的入口列表发生变化(新增/删除入口),正在运行的 extension dev 会话会自行重启编译器。你不需要重启命令。
  • manifest 的修改添加、移除或重命名 HTML 入口时,编译器会以同样的方式重启。
  • 从 4.1.41 之后的版本起,没有对应文件的页面脚本或样式表会发出警告。
  • 页面随后会在不含该文件的情况下输出。
  • 这个警告会在启动时、生产构建中以及你删除文件之后出现。
  • 设置 EXTENSION_STRICT_REFS=true 可以把缺失的页面文件变成错误。
  • 缺失的 popup、options、devtools 或 background 页面会让构建失败。浏览器会拒绝这样的扩展。
  • 缺失的 sandbox 或侧边栏页面会发出警告。
  • pages/ 下缺失的页面会警告一次,并给出文件名。
  • 只由脚本打开的缺失页面(例如 devtools 面板)也会以同样方式警告。

路径与环境变量

  • Extension.js 会按 HTML 文件位置解析相对路径。
  • Extension.js 把以 / 开头的路径视为扩展 public-root 路径。
  • <base href> 标签会作用于链接,然后从页面中移除:<a href>、<area href> 与 <form action> 的值会基于它解析并写入输出,而脚本、样式与图片仍然留在扩展内部。
  • 在编译期,Extension.js 会替换 emitted HTML 中的 $EXTENSION_PUBLIC_* 及相关占位符。

使用额外页面

把额外的文件放在 pages/ 下:

常见的扩展表面

大多数渲染 UI 的扩展表面都是 HTML 入口,只是 manifest 字段和运行时期望不同。先选与交互模型相匹配的表面,再让 HTML 页面本身保持精简。 将 popup 用于快速、聚焦的操作:
  • 快速查看状态。
  • 一步式命令。
  • 小型表单或开关。
让 popup 保持小巧而稳健。Popup 经常被打开和关闭,因此不要依赖长时间存活的内存 UI 状态。 manifest 里没有控制 popup 尺寸的字段。浏览器会按你渲染出的 HTML 来决定 popup 大小,并受最小 25x25、最大 800x600 CSS 像素的硬性限制。要控制宽度,请在标记的根元素上设置:
不要在根元素上使用 width: 100vw 或百分比宽度:popup 的视口是由你的内容推导出来的,这种循环的尺寸计算会让 popup 塌缩或抖动。如果 UI 需要超过 800x600,说明它已经超出了 popup 这个表面的适用范围,请改用 side panel 或 new tab 页面。

Options 页面

当你需要配置持久行为时使用 options 页面:
  • 账户或集成设置。
  • 功能开关。
  • 键盘或工作流偏好。
把 options 页面和浏览器存储搭配使用,让设置在重启之间保留,并能被 background 或 content script 读取。

浏览器对话框中的 Options 页面

使用 "options_ui": {"page": "...", "open_in_tab": false} 时,Chromium 浏览器会在其扩展页面上以对话框显示该页面,并根据页面的首次布局决定对话框尺寸。首次渲染为空的页面,例如在 chrome.storage 返回之前一直返回 null 的组件,会以零高度完成布局,让对话框一片空白。 Extension.js 为 Chromium 目标防止了这种情况:它会在开发与生产构建中给该页面加上 html{min-height:32px},这样对话框总能打开。从 4.1.41 之后的版本开始,这条规则以一个小样式表 options/dialog-floor.css 的形式发布,并作为页面 <head> 中的第一个链接。它是文件而不是内联样式,所以当你的 content_security_policy 设置了 style-src 'self' 时也能生效。但仍请立刻用默认值渲染页面,等存储的值到达后再填入。这样对话框一开始就是真实尺寸,而不是过一会儿才长大。

Side panel

当扩展需要在当前页面旁提供一个持久工作区时使用 side panel:
  • 研究或笔记伴侣。
  • 标签页感知的助手。
  • 在你浏览时应保持可见的页面分析结果。
Side panel 的 HTML 仍然是扩展页面入口。区别在于表面语义,而不是构建管线。

DevTools 页面

当扩展为开发者提供工具时使用 devtools_page:
  • 审查面板。
  • 请求或 DOM 诊断。
  • 项目特定的调试辅助。
把它当作一种专门的表面。它通常需要更强的消息通信模式,因为它常常要协调 background 逻辑和被审查的标签页。

New tab 重写

当扩展拥有整个 new-tab 体验时使用 chrome_url_overrides.newtab。 对于 popup 显得太局促的、富应用式的 UI,它通常是最合适的选择。

Sandbox 页面

只有当功能确实需要沙箱模型时才使用 sandbox 页面。它们也是 HTML 入口,但存在的目的是为了应对浏览器扩展中较窄的一组安全与执行约束。

表面编写模式

对任意 HTML 表面,一个不错的默认结构是:
  1. 让 HTML 文件保持最小化。
  2. 挂载一个脚本入口。
  3. 在该脚本中导入样式,或通过 <link> 引用样式表。
  4. 把浏览器 API 协调放进专门的模块。
这个模式适用于 popup、options、side panel、DevTools 和 new-tab 表面。

最佳实践

  • 让入口 HTML 保持最小化,并通过脚本引入应用代码。
  • 对项目资源使用相对路径,仅在确实意指 public 资源时才使用 / 路径。
  • 对于不是主要 manifest UI 入口的额外扩展页面,使用 pages/。
  • 把脚本/链接的新增/删除视为可能需要重启的结构性变更。
  • 先按用户交互模型选择表面,再用一个轻量的 HTML 页面入口去实现它。
  • 把表面特定的状态放在存储或 background 协调中,而不是假设 UI 页面始终挂载。

下一步

视频讲解