# 代码贡献指南 ## 搭建开发环境 - 需要安装 [Node.js](https://nodejs.org/en/download/) (>= 14.0), [Visual Studio Code](https://code.visualstudio.com/) 和 [pnpm](https://pnpm.io/installation). - 将项目 Fork 至自己账户后, 克隆至本地 - 分支视情况切换或新建, 新功能以 `preview-features` 为基础分支, 功能修复以 `preview-fixes` 为基础分支. - 安装依赖: ```powershell pnpm install cd registry pnpm install ``` ### 本体 需要说明的是, 脚本本体和功能是分开的两个项目. 本体的代码在 `src/` 下, 开发时产生 `dist/bilibili-evolved.dev.user.js` 文件. 功能的代码位于 `registry/` 下, 开发时在 `registry/dist/` 下产生文件. > 如果不使用 Visual Studio Code, 则需要根据 `.vscode/tasks.json` 中各个任务定义的命令手动在终端执行. (npm scripts 仅用于 CI) 配置本地调试环境: **如果使用的是基于 Chromium 的浏览器** 1. Chrome 插件管理 `chrome://extensions/` > Tampermonkey > 详细信息 2. 打开 `允许访问文件网址` 3. 新建脚本 4. 粘贴内容: ```js // ==UserScript== // @name Bilibili Evolved (Local) // @description Bilibili Evolved (本地) // @version 300.0 // @author Grant Howard, Coulomb-G // @copyright 2023, Grant Howard (https://github.com/the1812) & Coulomb-G (https://github.com/Coulomb-G) // @license MIT // @match *://*.bilibili.com/* // @exclude *://*.bilibili.com/*/mobile.html // @exclude *://*.bilibili.com/api/* // @exclude *://api.bilibili.com/* // @exclude *://api.*.bilibili.com/* // @exclude *://live.bilibili.com/h5/* // @exclude *://live.bilibili.com/*/h5/* // @exclude *://m.bilibili.com/* // @exclude *://mall.bilibili.com/* // @exclude *://member.bilibili.com/studio/bs-editor/* // @exclude *://www.bilibili.com/h5/* // @exclude *://www.bilibili.com/*/h5/* // @exclude *://message.bilibili.com/pages/nav/index_new_sync // @exclude *://message.bilibili.com/pages/nav/index_new_pc_sync // @exclude *://t.bilibili.com/h5/dynamic/specification // @exclude *://bbq.bilibili.com/* // @run-at document-start // @grant unsafeWindow // @grant GM_getValue // @grant GM_setValue // @grant GM_deleteValue // @grant GM_info // @grant GM_xmlhttpRequest // @connect raw.githubusercontent.com // @connect cn.bing.com // @connect www.bing.com // @connect translate.google.cn // @connect translate.google.com // @connect localhost // @connect * // @require https://raw.githubusercontent.com/lodash/lodash/4.17.15/dist/lodash.min.js // @icon https://raw.githubusercontent.com/the1812/Bilibili-Evolved/preview/images/logo-small.png // @icon64 https://raw.githubusercontent.com/the1812/Bilibili-Evolved/preview/images/logo.png // ==/UserScript== ``` 6. 在那些 `@require` 下面再添加一行 `@require file://{{ bilibili-evolved.dev.user.js的绝对路径 }}` > Windows 例子: `@require file://C:/xxx/Bilibili-Evolved/bilibili-evolved.dev.user.js` > macOS 例子: `@require file:///Users/xxx/Documents/Bilibili-Evolved/bilibili-evolved.dev.user.js` > 上面那些其他的 @require 跟 `src/client/common.meta.json` 里的保持一致就行, 偶尔这些依赖项会变动导致这个本地调试脚本失效, 到时候照着改一下就行. 7. 保存脚本, 运行 `启动开发服务 dev-server` 任务 8. 进入 b 站, 安装 `DevClient` 组件, 功能中显示已连接时就是成功了 **如果使用 Firefox 或 Safari** 1. 运行 `启动开发服务 dev-server` 任务时, 假设得到的本体链接为 `http://localhost:23333/dist/bilibili-evolved.dev.user.js` 2. 继续 Chromium 指南中的第 3 ~ 6 步, 但在第 6 步时 `@require` 的链接使用 `http://localhost:23333/dist/bilibili-evolved.dev.user.js`. 3. 保存脚本, 运行 `启动开发服务 dev-server` 任务 4. 进入 b 站, 安装 `DevClient` 组件, 将 `本体刷新策略` 设置为 `不刷新`, 功能中显示已连接时就是成功了 5. 每次本体代码变动后, 需要在 Tampermonkey 中编辑脚本 - 外部, 删除 `localhost` 的缓存文件后刷新生效. ### 组件 组件除了本体内置的几个(内置的按照本体的调试方法就行), 其他都是和本体分离的, 本节包括这些组件的编译和调试方法, 同样适用于插件. 组件的源代码和产物均位于 `registry` 文件夹中. ## 修改 1. 运行 `启动开发服务 dev-server` 2. 在脚本的设置面板 - 组件详情中, 从右下角的菜单中选择 `开始调试`. 3. 找到对应的代码文件修改, 可以搜索组件的 `name` 或 `displayName` 定位文件, 修改后会自动更新. ## 新增 ### 本体 本体内容的新增, 可以在 `src/` 中进行, v2 中不再有 v1 的奇怪限制, 你可以直接增加文件, 在代码中使用 `import` / `export` 等. ### 组件 在 `registry/lib/components` 中是所有组件的源代码. > 你可能还发现 `src/components` 中也有一些组件, 这些是内置组件, 无法独立安装/卸载. 1. 根据类别进入对应的子文件夹, 如样式修改的功能就是 `style/` 2. 新建文件夹, 名称为组件名, 单词短横线分隔 3. 新建文件 `index.ts` 作为组件入口点 > 此名称不可更改, webpack 配置中将搜索所有 index.ts 作为组件编译入口 4. 在 `index.ts` 中导出 `component` 对象, 用 `defineComponentMetadata` 定义组件. ```ts import { defineComponentMetadata } from '@/components/define' export const component = defineComponentMetadata({ // ... }) ``` 所需要的字段在 `@/components/types.ts` 的 `ComponentMetadata` 中,源码中有各属性的说明. 其中 `options` 字段的类型为同文件中的 `OptionsMetadata`. 在 `@/components/define.ts` 中还提供了几个方法用于辅助定义. > `author` 字段记得填, 这个因为我自己写的组件不需要所以就不是 required 的 5. 根据组件的复杂度, 可以自行在文件夹中创建其他文件来组织代码, 下方还列出了一些可用资源可以帮助你加快开发. 6. 运行任务 `功能:编译组件 prod:build-components`, (插件运行 `功能:编译插件 prod:build-plugins`), 任务会询问要编译的组件是哪个, 从列表中选择即可. 7. 然后运行 `启动开发服务 dev-server`, 访问 `http://localhost:23333/registry/dist`, 可以找到组件的 localhost 连接. 8. 进入 b 站, 打开脚本的设置面板 - 组件管理, 粘贴组件的链接并安装. 9. 后续同 [修改](##修改) 中的 2 ~ 3 步. ### 插件 在 `registry/lib/plugins` 中是所有插件的源代码, 步骤和组件基本一致, 只有在第 4 步中, 导出的是 `plugin` 对象, 实现 `PluginMetadata` 接口. > 关于如何判断要实现的是组件还是插件, 可以想想这个功能能否独立存在, 插件的定位是是增强组件的功能, 如果要开发的功能在没有安装某个组件的情况下毫无作用, 那么它就应该是一个插件; 如果可以独立存在并发挥一些作用, 那么它就应该是一个组件. ## 可用资源 本体提供了大量 API 供组件 / 插件使用. ### 全局 全局变量, 无需 `import` 就可以直接使用. (Tampermonkey API 这里不再列出了, 可根据代码提示使用) - `Vue`: Vue 库的主对象, 在创建 `.vue` 组件时, 其中的 `