Skip to content

Commit 87ee606

Browse files
committed
docs: 优化README.md的排版与布局
1. 调整标题层级,增加视觉分隔线\n2. 美化列表项,提高重点内容可读性\n3. 使用引用块突出重要提示\n4. 改进整体文档结构,降低阅读疲劳
1 parent 1a30c78 commit 87ee606

File tree

1 file changed

+62
-42
lines changed

1 file changed

+62
-42
lines changed

README.md

Lines changed: 62 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,34 @@
1-
# UserScript Template
1+
# TypeScript UserScript Template
22

3-
简体中文| [English](./README_en.md)
3+
简体中文 | [English](./README_en.md)
44

5-
# 一、这是什么
5+
## 一、这是什么
66

7-
使用`Node.js`+`Webpack`模块化开发油猴脚本的方案,用于提升油猴开发体验,降低开发时的心智负担,让油猴脚本也能当做一个普通的模块化的前端项目来开发,要不然一个`JavaScript`文件几千行来回改本人真的有点顶不住......
7+
使用 `Node.js` + `Webpack` 模块化开发油猴脚本的方案,用于提升油猴开发体验,降低开发时的心智负担,让油猴脚本也能当做一个普通的模块化的前端项目来开发,要不然一个 `JavaScript` 文件几千行来回改本人真的有点顶不住......
88

9-
# 二、优势
9+
---
1010

11-
- 模块化开发油猴项目,开发体验与效率都能够得到大幅提升,再也不需要头疼怎么在单个`JavaScript`文件中组织代码了(油猴商店上架的脚本得是单文件无混淆无压缩,模块化开发打包出来的JS也是符合上架要求的)
12-
- 开发时热加载提高开发效率,采用推荐的开发模式,油猴中指向打包结果本地文件地址,`JavaScript`代码有变化时自动编译打包加载,开发时修改代码测试更高效(写过油猴脚本的应该都有过这种糟糕的体验,来来回回修改代码测试非常花费时间简直要了老命)
13-
- 发布时打包后的为高可读性的单`JavaScript`文件,符合油猴商店的上架政策,打包出来就能上架不再需要什么手工处理的工作,简单方便不麻烦
11+
## 二、优势
1412

15-
# 三、快速开始
13+
- **模块化开发** - 开发体验与效率都能够得到大幅提升,再也不需要头疼怎么在单个 `JavaScript` 文件中组织代码了(油猴商店上架的脚本得是单文件无混淆无压缩,模块化开发打包出来的JS也是符合上架要求的)
14+
15+
- **开发时热加载** - 采用推荐的开发模式,油猴中指向打包结果本地文件地址,`JavaScript` 代码有变化时自动编译打包加载,开发时修改代码测试更高效(写过油猴脚本的应该都有过这种糟糕的体验,来来回回修改代码测试非常花费时间简直要了老命)
16+
17+
- **生产环境单文件输出** - 发布时打包后的为高可读性的单 `JavaScript` 文件,符合油猴商店的上架政策,打包出来就能上架不再需要什么手工处理的工作,简单方便不麻烦
1618

17-
在当前仓库(https://github.com/JSREI/userscript-template)选择"`Use this template`" --> "`Create a new repository`",从这个模板仓库创建一个新的仓库:
19+
---
1820

19-
![image-20230816233501101](README.assets/image-20230816233501101.png)
21+
## 三、快速开始
22+
23+
在当前仓库(https://github.com/JSREI/userscript-template)选择 "`Use this template`" --> "`Create a new repository`",从这个模板仓库创建一个新的仓库:
24+
25+
![创建新仓库](README.assets/image-20230816233501101.png)
2026

2127
选择新仓库存放的位置以及设置仓库名字等等,通常把新仓库挂在自己的账号下边即可:
2228

23-
![image-20230816235634094](README.assets/image-20230816235634094.png)
29+
![设置新仓库](README.assets/image-20230816235634094.png)
30+
31+
### 安装依赖
2432

2533
新仓库创建好了克隆到本地,然后在克隆到的项目根目录下执行命令安装项目所需依赖:
2634

@@ -30,11 +38,13 @@ npm install
3038

3139
安装依赖可能会花点时间,稍微耐心等待一会儿:
3240

33-
![image-20230817003339266](README.assets/image-20230817003339266.png)
41+
![安装依赖](README.assets/image-20230817003339266.png)
3442

35-
如果依赖安装过慢或者下载不下来,可以为`npm`配置国内镜像源或者使用`cnpm`(自行谷歌)。
43+
> 如果依赖安装过慢或者下载不下来,可以为 `npm` 配置国内镜像源或者使用 `cnpm`(自行谷歌)。
3644
37-
然后修改`package.json`文件,把相关字段替换为你自己的,比如名字、作者、仓库地址等等:
45+
### 配置项目
46+
47+
然后修改 `package.json` 文件,把相关字段替换为你自己的,比如名字、作者、仓库地址等等:
3848

3949
```js
4050
{
@@ -53,7 +63,7 @@ npm install
5363
}
5464
```
5565

56-
在项目根目录下的`userscript-headers.js`文件中存放的是默认的油猴头文件,在`webpack`编译的时候会把这个文件放到编译后的文件的头部作为油猴的插件声明:
66+
在项目根目录下的 `userscript-headers.js` 文件中存放的是默认的油猴头文件,在 `webpack` 编译的时候会把这个文件放到编译后的文件的头部作为油猴的插件声明:
5767

5868
```js
5969
// ==UserScript==
@@ -68,7 +78,9 @@ npm install
6878
// ==/UserScript==
6979
```
7080

71-
`${name}``${version}`这种是本油猴脚手架支持的一些变量,原理就是在编译的时候会从`package.json`中获取对应的值把变量替换掉(这就是所谓的变量渲染),这样对于这些可能会重复或者一直变的内容我们就可以从一个源引用使用而不用重复设置或者反复修改了,如果默认的配置不能满足你的要求,你可以直接修改这个头文件,比如为其增加权限:
81+
`${name}``${version}` 这种是本油猴脚手架支持的一些变量,原理就是在编译的时候会从 `package.json` 中获取对应的值把变量替换掉(这就是所谓的变量渲染),这样对于这些可能会重复或者一直变的内容我们就可以从一个源引用使用而不用重复设置或者反复修改了。
82+
83+
如果默认的配置不能满足你的要求,你可以直接修改这个头文件,比如为其增加权限:
7284

7385
```js
7486
// ==UserScript==
@@ -91,37 +103,41 @@ npm install
91103

92104
除了变量替换其他内容都会被原样保留,这是编译后的样子:
93105

94-
![image-20230817004653299](README.assets/image-20230817004653299.png)
106+
![编译后的文件](README.assets/image-20230817004653299.png)
95107

96-
然后就可以开心的写代码了,在编写代码的时候你可以使用`npm`命令为项目添加依赖,对于一个稍微复杂点的脚本而言很可能会引用外部的依赖:
108+
### 开发流程
109+
110+
然后就可以开心的写代码了,在编写代码的时候你可以使用 `npm` 命令为项目添加依赖,对于一个稍微复杂点的脚本而言很可能会引用外部的依赖:
97111

98112
```bash
99113
npm add xxx
100114
```
101115

102-
但是需要注意,这些依赖最终会被打包进`./dist/index.ts`,而这个文件是不适合太大的,所以尽可能不要引用太多的第三方库。
116+
> **注意**:这些依赖最终会被打包进 `./dist/index.ts`,而这个文件是不适合太大的,所以尽可能不要引用太多的第三方库。
117+
118+
同时你现在可以在 `src` 目录下以模块化的方式组织你的代码,而不必像之前那样来回上下拉扯一个几千行的 `JavaScript` 文件(单文件开发那简直是一种对脑力的摧残...):
103119

104-
同时你现在可以在`src`目录下以模块化的方式组织你的代码,而不必像之前那样来回上下拉扯一个几千行的`JavaScript`文件(单文件开发那简直是一种对脑力的摧残...):
120+
![模块化开发](README.assets/image-20230817003923075.png)
105121

106-
![image-20230817003923075](README.assets/image-20230817003923075.png)
122+
### 测试与调试
107123

108124
当你需要测试的时候,执行:
109125

110126
```bash
111127
npm run watch
112128
```
113129

114-
然后把`./dist/index.ts`中的文件头复制到你的油猴中:
130+
然后把 `./dist/index.ts` 中的文件头复制到你的油猴中:
115131

116-
![image-20230817000716664](README.assets/image-20230817000716664.png)
132+
![油猴脚本头](README.assets/image-20230817000716664.png)
117133

118-
并在最后添加一行引入编译后的文件,注意这个`file://`后面的地址是指向你的编译后的`./dist/index.ts`的绝对路径:
134+
并在最后添加一行引入编译后的文件,注意这个 `file://` 后面的地址是指向你的编译后的 `./dist/index.ts` 的绝对路径:
119135

120136
```js
121137
// @require file://D:/workspace/userscript-template/dist/index.ts
122138
```
123139

124-
比如下面是一个开发时使用的油猴脚本的实际例子,油猴中没有实际代码,而是使用`require`指向我们`build`后的文件,这样当修改完代码`webpack`自动热编译的时候浏览器中引用的`./dist/index.ts`也是最新的:
140+
比如下面是一个开发时使用的油猴脚本的实际例子,油猴中没有实际代码,而是使用 `require` 指向我们 `build` 后的文件,这样当修改完代码 `webpack` 自动热编译的时候浏览器中引用的 `./dist/index.ts` 也是最新的:
125141

126142
```js
127143
// ==UserScript==
@@ -138,33 +154,37 @@ npm run watch
138154
(() => {})();
139155
```
140156

141-
注意,当你使用`// @require file://D:/workspace/userscript-template/dist/index.ts`这种方式来调试的时候,你的油猴插件应该配置了允许访问文件网址(默认情况下是不允许的),在浏览器插件图标上右键,选择"管理扩展程序":
142-
143-
![image-20240723005213833](./README.assets/image-20240723005213833.png)
157+
> **重要提示**:当你使用 `// @require file://D:/workspace/userscript-template/dist/index.ts` 这种方式来调试的时候,你的油猴插件应该配置了允许访问文件网址(默认情况下是不允许的),在浏览器插件图标上右键,选择"管理扩展程序":
158+
>
159+
> ![管理扩展程序](./README.assets/image-20240723005213833.png)
160+
>
161+
> 确保这个"允许访问文件网址"开关是打开的,否则的话 `@require` 将无法引用本地文件:
162+
>
163+
> ![允许访问文件网址](./README.assets/image-20240723005321887.png)
144164
145-
确保这个"允许访问文件网址"开关是打开的,否则的话`@require`将无法引用本地文件:
165+
也许你会注意到,当你使用 `npm run watch` 运行的时候,命令执行时编译完代码了也并没有退出而是进入了等待状态,是的,就像它的名字一样,它是启动了一个 `watch` 模式,当你改动源代码文件的时候 `webpack` 都会帮你重新编译你的代码,而你需要做的就是直接修改你的源代码文件,修改完然后切换到浏览器刷新页面即可生效!(这里没有引入浏览器自动刷新,是否有这个必要呢?说实话有必要我也不大会弄凑活着用吧....)
146166

147-
![image-20240723005321887](./README.assets/image-20240723005321887.png)
148-
149-
也许你会注意到,当你使用`npm run watch`运行的时候,命令执行时编译完代码了也并没有退出而是进入了等待状态,是的,就像它的名字一样,它是启动了一个`watch`模式,当你改动源代码文件的时候`webpack`都会帮你重新编译你的代码,而你需要做的就是直接修改你的源代码文件,修改完然后切换到浏览器刷新页面即可生效!(这里没有引入浏览器自动刷新,是否有这个必要呢?说实话有必要我也不大会弄凑活着用吧....)
167+
### 发布
150168

151169
当你需要发布的时候:
152170

153171
```bash
154172
npm run build
155173
```
156174

157-
然后把`./dist/index.ts`文件拿去发布即可。
175+
然后把 `./dist/index.ts` 文件拿去发布即可。
176+
177+
---
158178

159-
# 四、TypeScript支持
179+
## 四、TypeScript支持
160180

161181
本项目已经集成了TypeScript支持,包括油猴API的类型定义。这使得在开发过程中可以获得完整的类型检查和智能提示。
162182

163-
## 油猴API类型定义
183+
### 油猴API类型定义
164184

165-
项目使用`@types/tampermonkey`包提供油猴API的类型定义,并在`src/types`目录下提供了额外的类型扩展。
185+
项目使用 `@types/tampermonkey` 包提供油猴API的类型定义,并在 `src/types` 目录下提供了额外的类型扩展。
166186

167-
### 如何使用
187+
#### 如何使用
168188

169189
1. 直接在代码中使用油猴API,TypeScript将自动识别这些API的类型:
170190

@@ -176,13 +196,13 @@ GM_setValue('key', 'value');
176196
const value = GM_getValue('key', 'default');
177197
```
178198

179-
2. 查看`src/gm_api_example/gm_api_usage.ts`文件,了解更多油猴API的使用示例。
199+
2. 查看 `src/gm_api_example/gm_api_usage.ts` 文件,了解更多油猴API的使用示例。
180200

181-
3. 详细的使用说明请参考`src/types/README.md`文件。
201+
3. 详细的使用说明请参考 `src/types/README.md` 文件。
182202

183-
### 注意事项
203+
#### 注意事项
184204

185-
确保在`userscript-headers.js`文件中添加了所需的`@grant`声明,否则相应的API将不可用。例如:
205+
确保在 `userscript-headers.js` 文件中添加了所需的 `@grant` 声明,否则相应的API将不可用。例如:
186206

187207
```js
188208
// @grant GM_getValue

0 commit comments

Comments
 (0)