Skip to content

Commit 4b23727

Browse files
RJiazhenRJiazhen
committed
Initial commit
1 parent d1ec628 commit 4b23727

32 files changed

+17807
-0
lines changed

‎.eslintrc.js

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
module.exports = {
2+
env: {
3+
browser: true,
4+
es2021: true,
5+
node: true,
6+
},
7+
parser: 'vue-eslint-parser',
8+
extends: [
9+
'eslint:recommended',
10+
'airbnb',
11+
'./.eslintrc-auto-import.json',
12+
'plugin:@typescript-eslint/recommended',
13+
'plugin:vue/vue3-recommended',
14+
],
15+
parserOptions: {
16+
ecmaVersion: 'latest',
17+
parser: '@typescript-eslint/parser',
18+
sourceType: 'module',
19+
},
20+
plugins: [
21+
'@typescript-eslint',
22+
'vue',
23+
],
24+
settings: {
25+
'import/resolver': {
26+
typescript: {},
27+
},
28+
},
29+
globals: {
30+
uni: true,
31+
wx: true,
32+
},
33+
rules: {
34+
// 从不添加分号
35+
semi: ['error', 'never'],
36+
// 箭头函数可以使用空函数
37+
'@typescript-eslint/no-empty-function': ['error', {
38+
allow: ['arrowFunctions'],
39+
},
40+
],
41+
// 允许vue文件名使用单个单词
42+
'vue/multi-word-component-names': 'off',
43+
// 部分文件引入忽略后缀名
44+
'import/extensions': [
45+
'error',
46+
'ignorePackages',
47+
{
48+
js: 'never',
49+
jsx: 'never',
50+
ts: 'never',
51+
tsx: 'never',
52+
},
53+
],
54+
// 可以引入开发环境模块
55+
'import/no-extraneous-dependencies': ['error', {
56+
devDependencies: true,
57+
}],
58+
},
59+
}

‎.gitignore

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
pnpm-debug.log*
8+
lerna-debug.log*
9+
10+
node_modules
11+
.DS_Store
12+
dist
13+
*.local
14+
15+
# Editor directories and files
16+
.idea
17+
*.suo
18+
*.ntvs*
19+
*.njsproj
20+
*.sln
21+
*.sw?
22+
.eslintrc-auto-import.json
23+
src/types/auto-imports.d.ts

‎.stylelintrc.js

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
module.exports = {
2+
extends: [
3+
'stylelint-config-standard-scss',
4+
'stylelint-config-standard-vue/scss',
5+
'stylelint-config-recess-order-rjz',
6+
],
7+
rules: {
8+
indentation: [2, {
9+
baseIndentLevel: 0
10+
}],
11+
'declaration-empty-line-before': null,
12+
},
13+
};

‎.vscode/extensions.json

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"recommendations": [
3+
"vue.vscode-typescript-vue-plugin",
4+
"vue.volar",
5+
"mrmaoddxxaa.create-uniapp-view",
6+
"uni-helper.uni-app-schemas-vscode",
7+
"dbaeumer.vscode-eslint",
8+
"formulahendry.auto-rename-tag",
9+
"uni-helper.uni-ui-snippets-vscode",
10+
"uni-helper.uni-app-snippets-vscode",
11+
"stylelint.vscode-stylelint",
12+
"christian-kohler.path-intellisense",
13+
]
14+
}

‎.vscode/settings.json

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"stylelint.validate": [
3+
"css",
4+
"less",
5+
"postcss",
6+
"scss",
7+
"vue"
8+
],
9+
"path-intellisense.mappings": {
10+
"@": "${workspaceFolder}/src",
11+
},
12+
"[vue]": {
13+
"editor.formatOnSave": false,
14+
"editor.codeActionsOnSave": {
15+
"source.fixAll.stylelint": true,
16+
"source.fixAll.eslint": true
17+
}
18+
},
19+
"files.eol": "\n",
20+
"[javascript]": {
21+
"editor.defaultFormatter": "dbaeumer.vscode-eslint",
22+
},
23+
"[typescript]": {
24+
"editor.defaultFormatter": "dbaeumer.vscode-eslint",
25+
}
26+
}

‎README.md

+226
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# uniapp-vue3-ts-template
2+
基于官方模板自定义的uniapp+vue3+ts模板，预先添加了常用的pinia、sass、uni-ui等常用npm包，且在预设编译环境下编译为微信小程序时，没有因为不同版本的包导致的兼容性问题，开箱即用。
3+
4+
## ⏬ 运行
5+
6+
### 编译环境
7+
8+
本模板在`node.js 18.14.2`和`npm 9.5.0`环境下进行编译，其他环境下未测试
9+
10+
### 运行
11+
12+
#### 安装npm包：
13+
```
14+
npm install
15+
```
16+
注意，不要运行`npm audit fix --force`命令，可能会因为npm版本过高导致无法正常编译。
17+
同时本模板在package.json中限制了pinia、sass、sass-loader的版本，请谨慎更新这几个库的版本，可能出现版本不兼容的问题。
18+
19+
#### 编译为开发环境的微信小程序：
20+
```
21+
npm run dev:mp-weixin
22+
```
23+
编译完成后，在微信开发者工具中导入运行，其他编译命令参考[uniapp官方文档](https://uniapp.dcloud.net.cn/quickstart-cli.html#%E8%BF%90%E8%A1%8C%E3%80%81%E5%8F%91%E5%B8%83uni-app)。
24+
25+
#### 编译为本地测试环境微信小程序：
26+
```
27+
npm run dev-local:mp-weixin
28+
```
29+
自定义环境配置参考[Vite官方文档](https://cn.vitejs.dev/guide/env-and-mode.html#modes)
30+
31+
#### 编译为生产环境的微信小程序：
32+
```
33+
npm run build:mp-weixin
34+
```
35+
该版本用于正式发行
36+
37+
38+
## 💻 开发
39+
40+
### npm包
41+
42+
除原官方模板已自带的，本模板还添加了以下npm包：
43+
* @dcloudio/uni-ui：uniapp官方ui库；
44+
* @types/XXX：typescript类型包；
45+
* @typescript-eslint/XXX：typescript的eslint插件；
46+
* @uni-helper/XXX：uni-helper团队制作的uniapp的api的ts类型包；
47+
* @vue/tsconfig: Vue官方提供的Vue3项目的ts配置；
48+
* eslint、eslint-XXX：eslint及相关的配置扩展和插件，用于规范ts代码检查和风格规范；
49+
* pinia：Vue官方推荐状态管理包；
50+
* postcss-html：css样式转换器，用于stylelint；
51+
* sass、sass-loader：scss语法支持，uni-ui必备；
52+
* stylelint、stylelint-XXX：stylelint及相关配置扩展，用于样式代码的检查与风格规范；
53+
* typescript：ts支持；
54+
* unplugin-auto-import：自动引入vue、pinia、uniapp等的API；
55+
* vite、vue-tsc：vite项目自带包；
56+
57+
### 开发环境和插件
58+
59+
推荐使用VScode进行开发，在插件搜索栏中输入`@recommended`可以查看本项目推荐使用的扩展。
60+
61+
**本项目推荐**的插件：
62+
63+
* [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar)：Vue官方推荐插件，拥有语法检测、代码提示等适配Vue的功能，但注意使用时需要[开启Takeover模式](https://cn.vuejs.org/guide/typescript/overview.html#volar-takeover-mode)；
64+
* [Eslint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)：实时检测js/ts代码是否符合eslint配置，以及根据配置进行修复；
65+
* [Auto Rename Tag](https://marketplace.visualstudio.com/items?itemName=formulahendry.auto-rename-tag)：自动重命名配对的HTML标签；
66+
* [uni-create-view](https://marketplace.visualstudio.com/items?itemName=mrmaoddxxaa.create-uniapp-view)：快速创建uniapp视图；
67+
* [uni-app-schemas](https://marketplace.visualstudio.com/items?itemName=uni-helper.uni-app-schemas-vscode)：校验 uni-app 中的 androidPrivacy.json、pages.json 和 manifest.json 格式；
68+
* [uni-app-snippets](https://marketplace.visualstudio.com/items?itemName=uni-helper.uni-app-snippets-vscode)：uniapp代码片段；
69+
* [uni-ui-snippets](https://marketplace.visualstudio.com/items?itemName=uni-helper.uni-ui-snippets-vscode)：uni-ui代码片段；
70+
* [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint)：实时检测样式代码是否符合stylelint配置，以及根据配置进行修复；
71+
* [Path Intellisense](https://marketplace.visualstudio.com/items?itemName=christian-kohler.path-intellisense)：路径提示。
72+
73+
Eslint、Stylelint、Path Intellisense插件已在`.vscode\setting.json`中进行相关配置；
74+
75+
**其他推荐**插件：
76+
77+
* [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)：单词拼写检查；
78+
* [Error Lens](https://marketplace.visualstudio.com/items?itemName=usernamehw.errorlens)：行内显示报错信息；
79+
* [Todo Tree](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree)：显示TODO、FIXME等特殊注释；
80+
81+
## 📖项目结构
82+
83+
```
84+
uniapp-vue3-ts-template
85+
├─ .eslintrc-auto-import.json unplugin-auto-import自动生成文件，推荐添加到忽略列表
86+
├─ .eslintrc.js eslint配置文件
87+
├─ .stylelintrc.js stylelint配置文件
88+
├─ .vscode VScode项目配置
89+
├─ index.html
90+
├─ package-lock.json
91+
├─ package.json
92+
├─ README.md
93+
├─ src
94+
│ ├─ api 接口
95+
│ │ ├─ request.ts 封装的请求方法
96+
│ │ └─ user-api.ts 接口示例文件
97+
│ ├─ App.vue
98+
│ ├─ components 组件
99+
│ │ └─ MyPopup.vue 组件示例文件
100+
│ ├─ env 环境变量文件夹
101+
│ │ ├─ .env.development 开发环境变量文件
102+
│ │ ├─ .env.devLocal 本地开发环境变量文件
103+
│ │ └─ .env.production 生产环境变量文件
104+
│ ├─ main.ts
105+
│ ├─ manifest.json uniapp配置文件
106+
│ ├─ pages 页面
107+
│ │ └─ index.vue 示例页面文件
108+
│ ├─ pages.json 项目页面配置文件
109+
│ ├─ static 静态文件夹
110+
│ │ ├─ constants 常量
111+
│ │ │ └─ view-constants.ts 常量示例文件
112+
│ │ ├─ icons 图标
113+
│ │ │ └─ common 通用图标
114+
│ │ ├─ images 图片
115+
│ │ │ └─ common 通用图片
116+
│ │ └─ styles 样式
117+
│ │ └─ common.scss 通用样式文件
118+
│ ├─ stores store文件夹
119+
│ │ └─ user-store.ts store示例文件
120+
│ ├─ subpkg 分包文件夹
121+
│ │ └─ subpkg-example.vue 分包示例文件
122+
│ ├─ types 类型
123+
│ │ ├─ auto-imports.d.ts unplugin-auto-import自动生成文件，推荐添加到忽略列表
124+
│ │ ├─ env.d.ts 全局类型示例文件
125+
│ │ └─ shime-uni.d.ts uniapp原模板自带声明文件
126+
│ └─ utils 通用方法
127+
├─ tsconfig.json ts配置文件
128+
├─ vite.config.ts vite配置文件
129+
└─ vue.config.js vue配置文件
130+
```
131+
132+
## 🦒代码风格
133+
本项目推荐代码遵循[vue3官方的风格指南](https://v2.cn.vuejs.org/v2/style-guide/)和[Vue3组合式API风格指南（英文）](https://cn.vuejs.org/style-guide/)，js/ts代码风格已使用eslint进行限制，css/scss代码已使用stylelint进行限制。
134+
135+
以下是部分无法通过工具约束，但有希望遵循的规则
136+
137+
### 必要的
138+
139+
#### 优先使用`async/await`
140+
141+
除非是要将回调函数Promise化，否则优先使用`async/await`的形式代替`Promise.then()`，以免`Promise.then()`过度使用导致代码阅读难度增加。
142+
143+
#### 页面文件和组件文件的命名
144+
145+
页面文件使用短横线命名法（kebab-case），组件文件使用大驼峰命名法（PascalCase）。
146+
147+
除了uni-ui组件因为要使用easycom功能而使用短横线命名法，个人组件请使用大驼峰命名法，以便和Vue官方指南以及其他常见Vue组件库保持统一，而页面使用短横线命名法和组件文件进行区别。
148+
149+
#### 文件头部添加基本说明
150+
151+
在所有代码文件中添加类似以下的注释，以方便快速分辨文件作用：
152+
```
153+
<!-- 首页 -->
154+
155+
// 页面展示相关的常量
156+
157+
```
158+
159+
#### 给函数、变量添加注释
160+
161+
所有在外部使用的函数或变量均需要编写TSDoc风格的注释。
162+
163+
通过给函数或变量添加如下TSDoc风格注释，可以直接通过鼠标悬停就查看代码相关注释，以方便开发：
164+
``` ts
165+
/**
166+
* 显示弹窗
167+
* @param title 弹窗标题
168+
* @param icon 弹窗图标
169+
* @param duration 弹窗持续时间
170+
* @param mask 是否显示透明蒙层，防止触摸穿透
171+
* @param image 自定义图标的本地路径，image 的优先级高于 icon
172+
* @param success 成功回调
173+
* @param fail 失败回调
174+
* @param complete 完成回调
175+
* @returns void
176+
*/
177+
export const showToast = (
178+
title: string,
179+
icon: 'none' | 'success' | 'loading' | 'error' | undefined = 'none',
180+
duration = 1500,
181+
mask = false,
182+
image = '',
183+
success = () => { },
184+
fail = () => { },
185+
complete = () => { },
186+
) => {
187+
uni.showToast({
188+
title,
189+
icon,
190+
duration,
191+
mask,
192+
image,
193+
success,
194+
fail,
195+
complete,
196+
})
197+
}
198+
```
199+
200+
详细编写方法可以参考[TSDoc官方文档](https://tsdoc.org/)。
201+
202+
203+
#### 常量的命名和保存
204+
205+
对于菜单列表、数据模板这类不进行任何操作的常量，请保存在`src/static/constants`文件夹下对应的文件中，并且使用全大写下划线命名法，例如：
206+
``` ts
207+
// view-constants.ts
208+
209+
/** 首页按钮列表 */
210+
export const HOME_BUTTON_LIST = [
211+
{
212+
name: '弹窗按钮一',
213+
},
214+
{
215+
name: '弹窗按钮二',
216+
},
217+
{
218+
name: '弹窗按钮三',
219+
},
220+
]
221+
```
222+
223+
## ✅TODO
224+
225+
- [ ] 编写完整的风格指南
226+
- [ ] 编写项目开发建议

‎index.html

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset="UTF-8" />
5+
<script>
6+
var coverSupport = 'CSS' in window && typeof CSS.supports === 'function' && (CSS.supports('top: env(a)') ||
7+
CSS.supports('top: constant(a)'))
8+
document.write(
9+
'<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0' +
10+
(coverSupport ? ', viewport-fit=cover' : '') + '" />')
11+
</script>
12+
<title></title>
13+
<!--preload-links-->
14+
<!--app-context-->
15+
</head>
16+
<body>
17+
<div id="app"><!--app-html--></div>
18+
<script type="module" src="/src/main.ts"></script>
19+
</body>
20+
</html>

0 commit comments

Comments
 (0)