# 代码贡献指南 ## 搭建开发环境 - 需要安装 [Node.js](https://nodejs.org/en/download/) (>= 14.0), [Visual Studio Code](https://code.visualstudio.com/) 和 [yarn](https://yarnpkg.com/getting-started/install#global-install). - 将项目 Fork 至自己账户后, 克隆至本地 ```powershell git clone https://github.com/{{your-name}}/Bilibili-Evolved.git -b preview --single-branch cd Bilibili-Evolved ``` - 安装依赖 ```powershell yarn cd registry yarn ``` ### 本体 需要说明的是, 脚本本体和功能是分开的两个项目, 因此编译时也是分开的. 脚本本体的编译通常使用 `监视开发版 dev:watch` 任务, 会产生 `dist/bilibili-evolved.dev.user.js` 文件. > 如果不使用 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 2021, 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 cdn.jsdelivr.net // @connect cn.bing.com // @connect www.bing.com // @connect translate.google.cn // @connect translate.google.com // @connect localhost // @connect * // @require https://cdn.jsdelivr.net/npm/lodash@4.17.15/lodash.min.js // @icon https://cdn.jsdelivr.net/gh/the1812/Bilibili-Evolved@preview/images/logo-small.png // @icon64 https://cdn.jsdelivr.net/gh/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` 7. 保存脚本, 监视模式下保存文件构建完成后, 刷新即可生效 > 上面那些其他的 @require 跟 `src/client/common.meta.json` 里的保持一致就行, 偶尔这些依赖项会变动导致这个本地调试脚本失效, 到时候照着改一下就行. **如果使用 Firefox 或 Safari** 1. 运行 `启动服务器(本体) dev:serve` 任务, 假设得到的服务链接为`http://localhost:5000/` 2. 继续 Chromium 指南中的第 3~6 步, 但在第 6 步时 `@require` 的链接使用 `http://localhost:5000/bilibili-evolved.dev.user.js`. 3. 保存脚本, 监视模式下保存文件构建完成后, 在 Tampermonkey 中编辑脚本 - 外部, 删除 `localhost` 的缓存文件后生效. ### 组件 组件除了本体内置的几个(内置的按照本体的调试方法就行), 其他都是和本体分离的, 本节包括这些组件的编译和调试方法, 同样适用于插件. 组件的源代码和产物均位于 `registry` 文件夹中. 1. 运行任务 `监视组件 dev:components`, (插件运行 `监视插件 dev:plugins`), 任务会询问要编译的组件是哪个, 从列表中选择即可. 2. 然后运行 `启动服务器(组件) dev:serve components`, 就得到了组件在 `localhost` 下的链接. 3. 进入网站, 打开脚本的设置面板 - 组件管理, (确保`自动更新器`功能开启) 粘贴组件的链接并安装. 4. 监视模式下保存文件构建完成后, 可以在设置里进入组件详情, 从菜单里选择检查更新; 如果开着 `开发者模式` 和 `自动更新器`, 也可以在搜索栏中搜索 `Check Last Update` 来一键更新上一次检查更新的组件. ## 修改 找到对应的代码文件修改, 可以搜索组件的 `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` 对象, 实现 `ComponentMetadata` 接口 ```ts import { ComponentMetadata } from '@/components/types' export const component: ComponentMetadata = { // ... } ``` > 在 `ComponentMetadata` 的源码中有各属性的说明 > `author` 字段记得填, 这个因为我自己写的组件不需要所以就不是 required 的 5. 根据组件的复杂度, 可以自行在文件夹中创建其他文件来组织代码, 下方还列出了一些可用资源可以帮助你加快开发. 6. 编译并调试组件. ### 插件 在 `registry/lib/plugins` 中是所有插件的源代码, 步骤和组件基本一致, 只有在第 4 步中, 导出的是 `plugin` 对象, 实现 `PluginMetadata` 接口. ## 可用资源 本体提供了大量 API 供组件 / 插件使用. ### 全局 全局变量, 无需 `import` 就可以直接使用. (Tampermonkey API 这里不再列出了, 可根据代码提示使用) - `Vue`: Vue 库的主对象, 在创建 `.vue` 组件时, 其中的 `