WebToApp CSS 模块开发指南站点主题化、夜间模式与纯样式覆盖本文基于 WebToApp 的扩展体系讲解 CSS 模块纯样式覆盖模块的完整开发方式如何用module.jsonstyle.css为指定站点做主题化、重设样式或夜间模式。读完你可以掌握 CSS 模块的文件布局、清单字段、DOCUMENT_START时机选择、CSS 在 WebView 中的注入原理含源码级证据并能参照内置web-tint模块产出一个可发布的样式扩展。什么是 CSS 模块WebToApp 提供四类扩展JS 模块、CSS 模块、油猴脚本、Chrome MV3它们都由同一个ExtensionManager管理并由 WebView 在页面生命周期钩子处注入见 扩展开发总览。CSS 模块是其中的纯样式子类——它为某个站点做主题化、重设样式或夜间模式。它使用与 JS 模块 相同的module.json清单但实质是一个样式表逻辑代码退化为一个最小桩真正的功能全部写在style.css里。文件布局一个 CSS 模块的目录结构如下my-theme/ ├── module.json # 必需 —— 清单 ├── main.js # 必需 —— 可以是近乎为空的桩 ├── style.css # 实际样式 └── icon.png # 可选注意一个容易踩的坑即便是纯 CSS 模块main.js也是必需的它不能省略可以是最小的桩。把runAt设为DOCUMENT_START让样式尽早生效避免未设样式内容的闪现FOUC。module.json清单一个完整的 CSS 模块清单示例夜间主题{ id: dark-reader-lite, name: Dark Reader Lite, description: 一个简单的夜间主题, category: THEME, runAt: DOCUMENT_START, urlMatches: [ { pattern: *://news.ycombinator.com/* } ], permissions: [CSS_INJECT] }关键字段说明categoryCSS 模块应使用STYLE_MODIFIER或THEME之一。全系统允许的category取值还包括CONTENT_FILTER、CONTENT_ENHANCE、FUNCTION_ENHANCE、AUTOMATION、READING、ACCESSIBILITY等二十余个见 modules/README.md未知取值不会破坏安装只会让模块从分类筛选中隐藏。runAtDOCUMENT_START、DOCUMENT_END默认、DOCUMENT_IDLE、CONTEXT_MENU、BEFORE_UNLOAD。对 CSS 模块DOCUMENT_START是最优选择因为样式需要尽早落地。urlMatches[]每条规则形如{pattern, isRegexfalse, excludefalse}。isRegex: false默认是 Chrome 风格 glob*匹配任意字符*://展开为(https?|ftp|file)://*或all_urls匹配一切 URL若 glob 无法匹配则回退为子串包含判断。isRegex: true时按 Java 正则求值带 200ms 超时超时算作不匹配。exclude: true表示该规则从结果集中扣除匹配的 URL。permissions对样式模块声明CSS_INJECT即可。权限列表在安装页仅作展示运行时不据此沙箱化主要用于审核时识别危险能力。此外还有一个发布侧的约束在市场registry.json中hasCss标志必须为true且目录中必须存在style.css——校验器会检查两者一致不匹配时 CI 直接报错见 modules/README.md 的校验规则一节。App 端的数据模型也对应声明了该字段见 ModuleMarketModels.kt安装流程会依据它决定是否下载style.css见 ModuleMarketRepository.kt。CSS 如何注入源码级原理文档给出的注入时机是当模块携带 CSScssCode/style.css时它会在main.js运行之前以style idext-module-id元素的形式注入页面。这一行为可以直接在 ExtensionModule.kt 的注入模板中得到印证。运行时把模块代码拼装成一段完整的脚本顺序为定义__MODULE_INFO__、__MODULE_UI_CONFIG__等全局若cssCode非空先注入一个自执行函数document.createElement(style)设置style.id ext-module-${id}写入 CSS 内容再appendChild到document.head或document.documentElement之后才在try/catch中执行你的main.js用户代码异常只写入console.error不会中断页面。// CSS 注入cssCode 非空时生成 (function() { const style document.createElement(style); style.id ext-module-${id}; style.textContent ${cssCode}; (document.head || document.documentElement).appendChild(style); })();这段结构意味着两件事对写 CSS 模块的人很关键CSS 先于 JS 生效。如果你的main.js里还保留 DOM 操作例如动态插入一个覆盖层节点该节点出现时样式已经就位不会出现先裸后着色的闪现。样式节点有确定的 id 规则ext-module-模块id。你可以在自己的main.js中用document.getElementById(ext-module- __MODULE_INFO__.id)找到并操作它——内置web-tint模块的开关逻辑就依赖对注入节点的直接操纵。同时你的main.js仍可在需要时操作 DOM对纯 CSS 模块而言它通常只是个空桩但如上文所述不可省略。style.css示例一个最小可用的夜间主题样式继承自 css-module.md 原文档示例:root { color-scheme: dark; } body { background: #111 !important; color: #ddd !important; } a { color: #60a5fa !important; }几点实践说明!important在这里是常态。页面自身样式表会持续参与层叠主题覆盖通常需要靠!important或更精确的选择器 :where()降低特异性才能稳定压过站点自身规则。color-scheme: dark声明会让表单控件、滚动条等浏览器原生 UI 跟随暗色外观是夜间主题中容易被忽略的一笔。若你用了DOCUMENT_START注入时document.head可能尚未完全构建——这正是源码中(document.head || document.documentElement)回退写法的原因你无需在 CSS 层面处理但 JS 桩里不应假设document.body存在。完整参考实现内置web-tint模块仓库modules/目录即 WebToApp 的模块市场App 直接拉取该目录内容渲染市场列表其中的 web-tint 是一个可工作的DOCUMENT_START样式模块同时展示了CSS 打底 最小 JS 交互的协作模式清单 modules/web-tint/module.jsonrunAt: DOCUMENT_START、urlMatches全匹配*、权限[CSS_INJECT, DOM_ACCESS]并声明了 5 个configItems滤镜模式SELECT、强度NUMBER、色温SELECT、自定义颜色COLOR、对比度NUMBER。样式 modules/web-tint/style.css定义全屏覆盖层#wta-tint-overlayposition: fixed; inset: 0; pointer-events: none; z-index: 2147483647night/custom 模式用mix-blend-mode: multiply灰度/反色模式改用根元素filter并对img/video/canvas/iframe单独反向补偿滤镜避免媒体内容被二次过滤。脚本 modules/web-tint/main.js用getConfig(key, defaultValue)读配置按模式插入覆盖层或切换html上的类关键细节是它先判断document.documentElement是否就绪未就绪则挂DOMContentLoaded回调最后通过__WTA_MODULE_UI__.register({...})注册浮动面板按钮——点击按钮即可在开/关滤镜间切换切换实现就是对注入节点的opacity取反。它证明了 CSS 模块不必是完全零逻辑的style.css负责静态样式契约main.js桩负责把用户配置翻译为节点状态两者通过覆盖层 id 与类名约定衔接。发布与校验发布到市场时除模块目录外还要在 modules/registry.json 中登记一条记录保持id、name、version、runAt、permissions与module.json一致并把hasCss置为true前提是style.css确实存在。CI 校验脚本python3 .github/scripts/ci/validate_modules.py会检查hasCss标志与style.css是否存在不一致对 CSS 模块这是最常见的打回原因registry.json与module.json的字段不匹配id/name/version/runAt/漏报权限缺失必需文件module.json、main.js——再次强调 CSS 模块也需要main.js桩main.js顶层return注入时被包在 IIFE 内顶层return是语法错误。完整规则与审核清单见 modules/README.md字段级参考见 JS 模块文档两者共用同一套module.jsonschema。runAt 时机对照CSS 模块对时机的要求最严格完整对照引自 扩展开发总览运行时机触发于DOCUMENT_STARTonPageStartedDOCUMENT_ENDonPageFinishedDOMContentLoadedDOCUMENT_IDLE加载后默认CONTEXT_MENU上下文菜单时BEFORE_UNLOAD卸载前对主题/夜间模式类 CSS 模块结论直接DOCUMENT_START是唯一正确选择——样式必须抢在任何内容渲染前落地否则用户会先看到一帧原始浅色页面。小结CSS 模块 module.jsoncategory: THEME/STYLE_MODIFIERrunAt: DOCUMENT_START 最小main.js桩 承载全部逻辑的style.css 市场侧hasCss: true。运行时保证style idext-module-id先于 JS 注入你可以放心地把覆盖层、类名等约定写在 CSS 里由桩代码负责把用户配置接到 DOM 上。仓库内置的web-tint是可直接模仿的完整样例。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考