drukscode-v2/docs/zh/extensions/js-module.md

JS 模块

JS 模块是能力最强的原生扩展格式:一个清单、一个脚本、可选 CSS、一个配置 UI,以及一个可选的浮动面板 —— 全部打包在一起。

文件布局

my-module/
├── module.json    # 必需 —— 清单
├── main.js        # 必需 —— 在 WebView 中运行
├── style.css      # 可选 —— 当 hasCss / cssCode 存在时自动注入
└── icon.png       # 可选 —— ≤256KB;png/svg/webp/jpg/jpeg

module.json schema

{
  "id": "my-module",
  "name": "My Module",
  "description": "它做什么",
  "icon": "star",
  "category": "CONTENT_ENHANCE",
  "tags": ["demo"],
  "version": { "code": 1, "name": "1.0.0", "changelog": "首次发布" },
  "author": { "name": "You", "url": "https://example.com" },
  "runAt": "DOCUMENT_END",
  "urlMatches": [
    { "pattern": "*://example.com/*", "isRegex": false, "exclude": false }
  ],
  "permissions": ["DOM_ACCESS", "STORAGE"],
  "configItems": [
    {
      "key": "greeting",
      "name": "问候语",
      "type": "TEXT",
      "defaultValue": "Hello",
      "required": true
    }
  ]
}

::: warning version 是一个对象 version 有 code(整数)、name(semver 字符串)和 changelog。不要在 module.json 里把它写成纯字符串。 :::

字段参考

字段	说明
id	全局唯一。
icon	Material Icons 名称(如 star、package)。
category	取值之一:CONTENT_FILTER、CONTENT_ENHANCE、STYLE_MODIFIER、THEME、FUNCTION_ENHANCE、AUTOMATION、NAVIGATION、DATA_EXTRACT、DATA_SAVE、INTERACTION、ACCESSIBILITY、MEDIA、VIDEO、IMAGE、AUDIO、SECURITY、ANTI_TRACKING、SOCIAL、SHOPPING、READING、TRANSLATE、DEVELOPER、OTHER。
runAt	DOCUMENT_START、DOCUMENT_END(默认)、DOCUMENT_IDLE、CONTEXT_MENU、BEFORE_UNLOAD。
urlMatches[]	{pattern, isRegex=false, exclude=false}。见 URL 匹配。
permissions[]	仅展示用;运行时不据此沙箱化。危险项(如 CAMERA、LOCATION、EVAL、FILE_ACCESS)会受到额外审核。
configItems[]	用户可配置字段;见配置项。

URL 匹配

• isRegex: false(默认)—— Chrome 风格 glob。* 匹配任意字符;*:// 展开为 (https?|ftp|file)://;* 或 <all_urls> 匹配一切。若 glob 无法匹配则回退为子串 contains。
• isRegex: true —— Java 正则,带 200ms 超时;超时算作不匹配。
• exclude: true —— 从结果集中移除匹配的 URL。

main.js 契约

你的代码被包在一个带 try/catch 的 IIFE 中(错误写入 console.error,绝不破坏页面)。以下全局可用:

全局	值
__MODULE_INFO__	{id, name, icon, version, uiConfig, runMode}
__MODULE_CONFIG__	解析后的配置对象
__MODULE_UI_CONFIG__	UI 配置
__MODULE_RUN_MODE__	'INTERACTIVE' 或 'AUTO'
__MODULE_PANEL_HTML__	你的 panelHtml(若有)
getConfig(key, defaultValue)	读取配置值的便捷访问器

// main.js
const greeting = getConfig('greeting', 'Hello')
const banner = document.createElement('div')
banner.textContent = greeting
banner.style.cssText = 'position:fixed;top:0;left:0;z-index:99999;padding:8px;background:#2563eb;color:#fff'
document.body.appendChild(banner)

::: warning 禁止顶层 return 因为你的代码被包在 IIFE 里,顶层 return 语句是非法的,会被市场校验器拒绝。 :::

配置项

configItems[] 为用户构建设置 UI。每一项:

{
  "key": "speedLevel",
  "name": "速度",
  "description": "滚动速度倍数",
  "type": "NUMBER",
  "defaultValue": "3",
  "options": [],
  "required": false,
  "placeholder": "",
  "validation": ""
}

支持的 type 取值:TEXT、TEXTAREA、NUMBER、BOOLEAN、SELECT、MULTI_SELECT、RADIO、CHECKBOX、COLOR、URL、EMAIL、PASSWORD、REGEX、CSS_SELECTOR、JAVASCRIPT、JSON、RANGE、DATE、TIME、DATETIME、FILE、IMAGE。

用 getConfig(key, defaultValue) 读取值。

交互面板

要一个浮动 UI,提供 panelHtml 并注册一个面板按钮:

window.__DKC_MODULE_UI__.register({
  id: __MODULE_INFO__.id,
  name: __MODULE_INFO__.name,
  icon: __MODULE_INFO__.icon
})

在 panelHtml 内部,使用绑定到 window.__dkc_module_action_<name> 处理器的 data-dkc-action 属性,并用 var(--dkc-*) 主题变量做样式,使你的面板与应用主题一致。

多文件模块

codeFiles 是一个 Map<文件名, 源码>。入口点从 main.js、index.js、app.js、script.js 或 content.js 自动识别。

打包与分享

• 模块导出扩展名:.dkcmod;模块打包:.dkcpkg。
• 分享码前缀:DKC1:(全量 gzip + Base64)或 DKC2:(差异载荷 + 极限压缩,V1 装不进一个二维码时发射),可通过二维码分享。解码兼容 V2、V1 和远古裸 Base64。

完整可工作的示例见 modules/ 下内置的 hello-world 和 auto-scroll 模块。