香草布丁🌿🍮 用户脚本加载器和管理器

简体中文 | English

名称由来

• JavaScript 又被大家称为 vanilla-js
• 而脚本管理器类似于 JavaScript 的 “补丁”
• 因此本项目被我称为 《香草布丁》 vanilla pudding。

插件安装与环境要求

• 从 ChromeWebStore 安装
• 适用于现代浏览器的简约 JavaScript 用户脚本加载器和管理器。
• 为了使用此扩展程序，您需要 Chrome 120 或更高版本，并启用开发者模式。

你什么时候需要这个？

• 一个现代的脚本管理器，默认支持ESM 的脚本加载器
• 一个类似 Tampermonkey ，但不支持 GM_* API的脚本管理器
• 内置 MonacoEditor
• 一个强大的管理器，支持来自插件的高级API能力 服务源码
  • Cookie chrome.cookies
  • Tabs chrome.tabs
  • Storage (chrome.storage.sync、chrome.storage.local、chrome.storage.session) 提供插件级存储能力。
  • NamespaceStorage 基于 indexDB, 由 Dexie 驱动，提供带有命名空间的插件级存储能力。
  • RuleDNRTool chrome.declarativeNetRequest
  • 插件请求, 基于 quick-fy
    • 请求跨域
    • 修改请求头
    • 使用示例模版，通过 vite 构建用户脚本（此部分下面有详细介绍）。

MataData

您需要将元数据以注释的形式写在脚本的开头，格式请参考示例。

type StrOrStrArr = string | string[]

// 1、支持驼峰和短横线风格
// 2、虽然这里的ts类型主要是为vite 插件提供类型提示, 但是命名仍然和注释语法保持一致，这与谷歌插件实际值略有出入
interface ScriptMeta {
  // 用户脚本的名称
  'name': string
  // 用户脚本的更新URL,这是可选的，点击更新按钮，插件将会访问该 URL 以使用户脚本保持最新。
  // 您可以通过多个指定多个更新URL,插件将按顺序逐一检查它们，直到找到可用的用户脚本
  'update-url'?: StrOrStrArr
  'updateUrl'?: StrOrStrArr
  // 下面的属性来自 chrome.userScripts.RegisteredUserScrip, 仅在支持的值为 StrOrStrArr 的属性名上略有出入
  'world'?: chrome.userScripts.ExecutionWorld
  'runAt'?: chrome.userScripts.RunAt
  'run-at'?: chrome.userScripts.RunAt
  'allFrames'?: boolean
  'all-frames'?: boolean
  'match'?: StrOrStrArr
  'exclude-match'?: StrOrStrArr
  'excludeMatch'?: StrOrStrArr
  'exclude-glob'?: StrOrStrArr
  'excludeGlob'?: StrOrStrArr
  'include-glob'?: StrOrStrArr
  'includeGlob'?: StrOrStrArr
  // 用户脚本注入的方式, 默认: esm
  'run-with'?: 'esm' | 'raw'
  'runWith'?: 'esm' | 'raw'
}

案例一

// @name allow-temu-translate
// @match https://www.temu.com/*
// @runAt document_start
(function () {
  document.documentElement.setAttribute('translate', '')
})()

案例二 ESM 支持， 来自 eternity

// @name Hello World
// @match <all_urls>
import { addStyleSheet } from 'https://esm.sh/userstyle@0.2.1'

addStyleSheet(`
  *:before {
    content: 'Hello'
  }

  *:after {
    content: 'World'
  }
`)

更多高级使用，推荐使用示例模板 create-vpu

• create-vpu 源码
• 创建你的第一个 vanilla-pudding 用户脚本项目。 npm create vpu@latest
• 示例模板使用 vite 构建你的用户脚本,
• build 后可以直接复制到用户脚本管理器中。也可以打包发布到 npm 就像这个工具。
• 香草布丁-通信包 提供了轻松使用插件的高级API。
• 香草布丁-vite-plugin
  • 自动按照配置生成注释，轻松设置MataData。
  • 支持 esm，减少打包体积。

技术分享

• wxt 用于快速构建浏览器扩展。
• vite 我常用的前端构建工具
• @webext-core/proxy-service 用于 popup、content 和 background 之间的服务调用。
• message 为了用户脚本或浏览器页面与插件进行通信，我创建了这个库，它提供了调用插件的高级API。
  • 通过 @webext-core/proxy-service 使 content.js 具有 background.js 服务调用能力, message 将会与 content.js 建立连接, 进行服务调用。
  • 借鉴 @webext-core/proxy-service 的 Proxy, 为用户提供友好的 简单、类型安全的调用方案。测试用例、 ts类型

致谢

• 受到 eternity 的启发，创建了香草布丁。

许可证

• 取自开源, 回馈开源, 本项目使用 MIT License
• 本项目包含了 eternity 的部分代码 MIT License
• 第三方许可证