Uniapp (新版V2.*)
注意
- 1、从
v2.0.0版本开始,对uniapp进行了重写,并且更换了UI框架。 - 2、原来
v1.*采用的UI框架是vk-uview。 - 3、现在
v2.*采用的UI框架是wot-design-uni。 - 4、
v1.*采用js进行开发,v2.*采用ts进行开发。 - 5、在
v2.*中还引入了tailwindcss写页面样式更方便了。
- 问:
v1.x可以升级到v2.x吗? - 答: 不支持,改动较大无法升级,建议在新项目使用。
前期准备
| 运行环境 | 要求版本 | 推荐版本 |
|---|---|---|
| node | >=20.19.3 | 20.19.3 |
| npm | >=10.8.2 | 10.8.2 |
| HBuilder X | >=4.85 | >=4.87 |
前置知识
使用前请了解以下内容
TypeScript: https://www.runoob.com/typescript/ts-tutorial.htmlTailwindcss: https://tailwindcss.comWotUI: https://wot-ui.cn
目录结构
├─📂 uniapp
│ ├─📂 dist # 构建输出目录
│ │ ├─ 📂 dev # 开发环境打包结果
│ │ └──📂 build # 生产环境打包结果
│ │
│ ├─📂 node_modules # Node.js 依赖包(通过 `npm install` 生成)
│ │ └──📂 ... # 第三方库(如 uniapp 框架、UI 组件库等)
│ │
│ ├─📂 src # 源代码目录
│ │ ├──📂 api # API 接口请求封装(如封装 `axios` 或 `uni.request`)
│ │ ├──📂 assets # 静态资源(图片、字体、全局样式等)
│ │ ├──📂 bundle # 分包加载的页面(优化首屏加载速度)
│ │ ├──📂 components # 全局公用组件(如按钮、弹窗等)
│ │ ├──📂 config # 项目配置(如全局常量、环境变量配置)
│ │ ├──📂 enums # 全局枚举类型(如状态码、类型定义)
│ │ ├──📂 lang # 国际化多语言文件(i18n 配置)
│ │ ├──📂 mixins # Vue 混入逻辑(复用组件选项,如生命周期、方法)
│ │ ├──📂 hooks # Composition API 逻辑钩子(Vue 3 组合式函数)
│ │ ├──📂 pages # 主包页面(默认分包,高频访问页面建议放此处)
│ │ ├──📂 stores # 状态管理(如 Pinia/Vuex 配置)
│ │ ├──📂 typings # TypeScript 类型声明文件(扩展全局类型)
│ │ ├──📂 uni_modules # 从 uniapp 插件市场安装的扩展(如 `uView`)
│ │ ├──📂 utils # 工具函数(如日期格式化、存储封装等)
│ │ ├── App.vue # 应用入口组件(挂载全局样式、插件)
│ │ ├── main.ts # 项目入口文件(初始化 Vue 实例、注册插件)
│ │ ├── manifest.json # uniapp 多端配置(如 App 图标、权限等)
│ │ ├── pages.json # 页面路由及窗口样式配置(类似小程序 `app.json`)
│ │ ├── env.d.ts # 环境变量类型声明(TypeScript 支持)
│ │ ├── shims-uni.d.ts # 补充 uniapp 全局 API 的 TypeScript 类型
│ │ └── uni.scss # uniapp 全局 SCSS 变量(如主题色、间距)
│ │
│ ├── .env.development # 开发环境变量
│ ├── .env.production # 生产环境变量
│ ├── .eslintrc.js # ESLint 代码规范配置
│ ├── .gitignore # Git 忽略文件规则
│ ├── .stylelintrc.cjs # Stylelint CSS 规范配置
│ ├── index.html # H5 端入口 HTML 模板
│ ├── package.json # 项目依赖及脚本命令定义
│ ├── tailwind.config.ts # Tailwind CSS 配置(如启用 uniapp 支持)
│ ├── tsconfig.json # TypeScript 编译配置
│ └── vite.config.ts # Vite 构建工具配置(如别名、代理、分包优化)
平台兼容性
- UniApp端支持很多平台,每个平台都有差异,兼容更多平台请自行测试。
| H5 | 微信小程序 | 支付宝小程序 | Android | IOS |
|---|---|---|---|---|
| √ | √ | √ | √ | √ |
代码规范
- 采用了 Eslint 控制vue和js等代码规范
- 采用了 Stylelint 控制css的代码规范
- 规范配置文件所在位置:
- Eslint:
eslint.config.ts - Stylelint:
.stylelintrc.cjs
- Eslint:
页面配置
页面配置文件位置:uniapp/src/pages.json
如何配置请参考此:https://uniapp.dcloud.net.cn/collocation/pages.html
{
"login": true,
"theme": true,
"path": "pages/user/home",
"style": {
"navigationBarTitleText": "个人中心",
"navigationBarTextStyle": "white",
"navigationBarBackgroundColor": "#2979ff"
}
}
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| login | boolean | false | 自定义参数,控制是否需要登录才可访问 |
| theme | boolean | false | 自定义参数,顶部导航栏是否设置主题色 |
| path | string | null | uni官方参数,页面的路径,"必须存在" |
| style | object | null | uni官方参数,配置页面的样式 |
| - | - | - | 更多参数请看uni官方文档,自定就两个 |
开发工具
【Visual Studio Code】开发工具
1、打开项目终端:
- 使用vscode打开uniapp目录,在vscode左上角菜单中点击
终端 > 新建终端
2、复制env文件:
- 1、复制
.env.development.example,将复制的文件名修改为.env.development - 2、复制
.env.production.example,将复制的文件名修改为.env.production - 3、打开
.env.development文件,修改VITE_APP_BASE_URL变量的值为项目安装部署的服务端地址 - 4、示例:
VITE_APP_BASE_URL=https://www.waitadmin.cn
3、安装依赖:
你可以使用 pnpm、npm、yarn 等工具作为您的包管理工具
# 方法一: 使用 npm 进行安装
npm install
# 方法二: 使用 pnpm 进行安装
pnpm install
# 说明: 安装成功后,您的项目会多出一个 node_modules 目录
# 注意: 依赖安装只需要执行一次即可,建议你使用 pnpm 安装速度更快。
4、开发运行 (Dev):
注意: dev是开发打包, 打包的内容都放在
dist/dev目录下
# 1、运行到 H5端
pnpm run dev:h5
# 2、运行到 微信小程序
pnpm run dev:mp-weixin
# 3、运行到 支付宝小程序
pnpm run dev:mp-alipay
5、生产打包 (Build):
注意: build是生产打包, 打包的内容都放在
dist/build目录下
# 1、运行到 H5端
pnpm run build:h5
# 2、运行到 微信小程序
pnpm run build:mp-weixin
# 3、运行到 支付宝小程序
pnpm run build:mp-alipay
# 4、您也可以使用打包脚本按提示操作
pnpm run dev
6、运行成功示例:
#【H5端】运行成功示例
vite v5.2.8 dev server running at:
➜ Local: http://localhost:5173/mobile/
➜ Network: use --host to expose
ready in 1035ms.
#【微信小程序端】运行成功示例
✔ 当前使用 Tailwind CSS 版本为: 4.1.18
DONE Build complete. Watching for changes...
运行方式:打开 微信开发者工具, 导入 dist/dev/mp-weixin 运行。
ready in 7000ms.
7、Vscode配置建议:
- 安装
Eslint插件 - 安装
Stylelint插件
{
// 设网页缩放级别
"window.zoomLevel": 2,
// 文件树视图缩进
"workbench.tree.indent": 18,
// 关闭类型切TabSize
"editor.detectIndentation": false,
// 编辑器字体大小
"editor.fontSize": 15,
// 重设定缩进TabSize
"editor.tabSize": 4,
// 每保存时自动格式化
"editor.formatOnSave": true,
// 启用Eslint规范校验
"eslint.enable": true,
// 启用Styles规范校验
"stylelint.enable": true,
// 启用TypeScript校验
"typescript.validate.enable": true,
// 每保存时自动修复规则
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "explicit",
"source.fixAll.stylelint": "explicit"
},
// 每保存时Styles修复
"stylelint.validate": [
"css",
"less",
"sass",
"scss",
"postcss",
"vue"
],
// 确定校验准则ES
"eslint.validate": [
"typescript",
"javascript",
"javascriptreact",
"typescriptreact",
"vue"
],
// 禁用对中文字符的高亮警告
"editor.unicodeHighlight.allowedLocales": {
"zh-hant": true,
"zh-hans": true
},
// 自定义CSS规则
"css.customData": [
".vscode/tailwind.json"
],
// JSON文件注释
"files.associations": {
"*.json": "jsonc"
}
}
【HBuilderX】开发工具
1、导入项目:
- 点击HBuilderX 左上角 菜单文件 > 导入 > 从本地目录导入,目录选择uniapp
2、复制env文件:
- 1、复制
.env.development.example,将复制的文件名修改为.env.development - 2、复制
.env.production.example,将复制的文件名修改为.env.production - 3、打开
.env.development文件,修改VITE_APP_BASE_URL变量的值为项目安装部署的服务端地址 - 4、示例:
VITE_APP_BASE_URL=https://www.waitadmin.cn
3、安装并运行:
- 选中当前项目,点击HBuilderX左上角菜单工具 > 外部命令 >
npm install安装依赖 - 运行到H5,点击HBuilderX左上角菜单
运行>运行到浏览器>Chrome - 运行到微信小程序,点击HBuilderX左上角菜单
运行>运行到小程序模拟器>微信开发者工具-(uniapp)
注意
运行到微信小程序前,先配置好小程序的appid:
- 点击uniapp/src/manifest.json,选择微信小程序配置>微信小程序AppID,输入appid即可
一般运行到微信小程序,会自动打开微信开发者工具,(如打开失败):
- 手动打开工具 -> 设置 -> 安全设置,将服务端口开启。
- 也有可能是你配置的小程序appid中,你登录的账号不是这个小程序的开发者。
- 只需要去微信小程序后台将该账号添加到开发者,重新运行即可。
接口请求
基本描述
- 系统中统一使用
src/utils/request发起请求 (基于 uni.request 的二次封装)- 请求拦截:自动拼接 baseUrl、urlPrefix,并注入 Token / Terminal
- 响应拦截:按后端约定的 code/msg/data 做统一处理与错误提示
- 取消重复请求、GET 超时重试 等能力
- 如果你需要调整 HTTP 请求基础参数:
- 在
src/config/index.ts中调整 (如baseUrl/urlPrefix/timeout/retryCount)
- 在
- 如果你需要对响应数据进行统一处理:
- 在
src/utils/request/index.ts的responseInterceptorsHook中调整
- 在
工具结构
├── src/utils
│ ├── request
│ │ ├── index.ts # 统一配置 + 请求/响应拦截(对外导出 request 实例)
│ │ ├── http.ts # 基于 uni.request 的封装(GET/POST/retry/cancel 等)
│ │ ├── type.d.ts # RequestOptions/RequestConfigs/Hook 类型声明
│ │ ├── cancel.ts # 重复请求取消(项目内已被 http.ts 引用)
默认配置
- 配置文件:
src/config/index.ts
const config = {
// 版本编号
version: '1.0.0',
// 请求域名
baseUrl: `${import.meta.env.VITE_APP_BASE_URL || ''}`,
// 请求前缀
urlPrefix: '/api',
// 请求超时
timeout: 10 * 1000,
// 请求重试次数
retryCount: 2,
// 请求重试间隔(ms)
retryTimeout: 1000
}
请求拦截
const requestHooks: RequestHooks = {
// 当前代码所在位置: src/utils/request/index.ts
requestInterceptorsHook(options: RequestOptions, config: RequestConfigs) {
// 请求前拦截逻辑处理
return options
}
}
响应拦截
const requestHooks: RequestHooks = {
async responseInterceptorsHook(
response: ResponseResult,
config: RequestConfigs,
options: RequestOptions
): Promise<any> {
// 接收配置
const isTransformResponse: boolean = config.isTransformResponse
const isReturnDefaultResponse: boolean = config.isReturnDefaultResponse
// 用户存储
const userStore = useUserStore()
// 需响应头及其它时可使用
if (isReturnDefaultResponse) {
return response
}
// 不需要对数据进行处理时
if (!isTransformResponse) {
return response.data
}
// 对响应回的数据进行处理
const { code, msg, data } = response.data as any
switch (code) {
case ErrorEnum.SUCCESS:
return data
case ErrorEnum.SYSTEM_ERROR:
case ErrorEnum.PARAMS_ERROR:
case ErrorEnum.METHOD_ERROR:
case ErrorEnum.CONTROL_ERROR:
case ErrorEnum.REQUEST_ERROR:
case ErrorEnum.OPERATE_ERROR:
case ErrorEnum.UPLOADS_ERROR:
case ErrorEnum.PURVIEW_ERROR:
await uni.showToast({
title: msg,
icon: 'none',
duration: 1500
})
return Promise.reject(response.data)
case ErrorEnum.LOGIN_EMPTY_ERROR:
userStore.logout()
return uni.reLaunch({ url: '/pages/index/index' })
case ErrorEnum.LOGIN_EXPIRE_ERROR:
userStore.logout()
if (options.method?.toUpperCase() !== 'GET') {
await uni.navigateTo({
url: '/pages/login/index'
})
}
return Promise.reject(response.data)
default:
return data
}
}
}
接口开发
- 我们对所有请求接口进行了统一管理, 统一放在:
src/api/..目录下面 - 我们以文章管理的接口作为示例子展开说明一下:
src/api/article/index.ts - 你还可以对响应的数据定义ts的数据结构:
src/api/article/types.d.ts
import request from '@/utils/request'
const articleApi = {
/**
* 文章列表
*/
lists(params: any): Promise<ArticleListsResponse[]> {
return request.get<ArticleListsResponse[]>({
url: '/article/lists',
params
})
},
/**
* 文章详情
*/
detail(id: number): Promise<ArticleDetailResponse> {
return request.get<ArticleDetailResponse>({
url: '/article/detail',
params: {
id
}
})
}
}
export default articleApi
请求配置
请求接口的第二个参数是请求配置参数,示例如下:
const articleApi = {
detail(id: number){
return request.get({
url: '/article/detail',
params: { id }
}, {
// 这里可以传一些请求配置 (RequestConfigs)
isTransformResponse: true,
isReturnDefaultResponse: true
})
}
}
RequestConfigs 配置说明
| 名称 | 类型 | 说明 |
|---|---|---|
| baseUrl | string | 请求接口域名 |
| urlPrefix | string | 请求接口前缀 |
| withToken | boolean | 自动携带令牌 |
| ignoreCancel | boolean | 忽略重复请求 |
| requestHooks | RequestHooks | 请求拦截钩子事件 |
| isTransformResponse | boolean | 直接返回接口数据(不拦截错误码) |
| isReturnDefaultResponse | boolean | 返回原始接口数据(需响应头及其它时可使用) |
| retryCount | number | 重试请求最大次数 |
| retryTimeout | number | 重试请求间隔时长(ms) |
| onProgress | (progress: number) | 上传进度回调函数 |
主题样式
基础样式
- 系统使用了
Tailwindcss来简化样式的书写方式。 - 所以在你使用本系统开发前,您最好先了解一下该工具。
- 官方网站:
https://tailwindcss.com/docs
样式穿透
- **开启scoped属性后需要如果需要将样式作用到子组件上,可以这样处理:**
<style lang="scss" scoped>
:deep(.el-menu-item) {
// todo
}
</style>
主题配置
- 主题的css样式统一配置在以下文件中
src/asssets/theme.css - 目前提供3种主题颜色,您也可以扩展自己的主题色
- 如果你扩展了别的主题色,别忘记在后台也加上哦
/* 默认的主题 */
:root {
--color-black: #000000;
}
/* 暗黑模式 */
.wot-theme-dark {
--bg-color: #0a0a0a;
}
// 热情红主题
[theme-scheme="red-theme"] {
--color-primary: #ff5058;
--color-primary-dark-2: #cc4046;
--color-primary-light-3: #ff858a;
--color-primary-light-5: #ffa8ac;
--color-primary-light-7: #ffcbcd;
--color-primary-light-8: #ffdcde;
--color-primary-light-9: #ffeeee;
}
// 生鲜绿主题
[theme-scheme="green-theme"]{
--color-primary: #40ca4d;
--color-primary-dark-2: #33a23e;
--color-primary-light-3: #79da82;
--color-primary-light-5: #a0e5a6;
--color-primary-light-7: #c6efca;
--color-primary-light-8: #d9f4db;
--color-primary-light-9: #ecfaed;
}
关于主题
- 我们是如何控制主题颜色修改的呢?答: 请您留意一下
App.ku.vue这个文件。 - 这个是根页面文件,他会包裹着您其它的的页面,我们在此绑定了两个主题参数。
- 分别是:
theme='light和theme-scheme="themeName" - 示例如下:
<wd-config-provider theme="light" theme-scheme="red-theme">
<ku-root-view />
</wd-config-provider>
| 参数名 | 默认值 | 说明 |
|---|---|---|
| theme | light | 主题风格: light=明亮, dark=暗黑 |
| theme-scheme | default | 主题颜色: red-theme,green-theme,... |
常用工具
- 为了开发更方便快捷,我们编写了一些常用的工具类 都放在以下目录:
src/utils/...
缓存工具 (cacheUtil)
import cacheUtil from '@/utils/cache'
/**
* 设置缓存
*
* @param {string} key 键
* @param {any} value 值
* @param {number} [expire] 过期时长(秒)
* @returns {boolean}
*/
cacheUtil.set(key, value, expire = 0)
/**
* 获取缓存
*
* @param string key (键)
* @param isShowExpire {boolean} 是否显示过期时间
* @returns {any}
*/
cacheUtil.get(key, isShowExpire)
/**
* 删除缓存
*
* @param string key (键)
*/
cacheUtil.remove(key)
/**
* 清空缓存
*/
cacheUtil.clear()
终端工具 (clientUtil)
import clientUtil from '@/utils/client'
// 是否是微信环境 (公众号/微信小程序)
// 用于判断是否在微信内置浏览器打开的
clientUtil.isWeixin()
// 是否为安卓环境 (如果是APP端)
// true=是安卓, false=苹果
clientUtil.isAndroid()
// 返回当前客户端标识
// 1 = 微信小程序
// 2 = 微信公众号
// 3 = H5
// 4 = PC
// 5 = 苹果
// 6 = 安卓
// 7 = 支付宝小程序
clientUtil.fetchClient()
// 按平台执行方法
callback(callbacks, platforms)
// 使用示例
clientUtil.callback({
'mp-alipay': () => {
// 这里的代码只有在支付宝小程序会被执行
uni.setNavigationBarTitle({
title: ' '
})
uni.setNavigationBarColor({
frontColor: '#ffffff',
backgroundColor: '#4d80f0'
})
}
})
日期工具 (datetimeUtil)
import datetimeUtil from '@/utils/datetime'
/**
* 格式化日期格式
*
* @param {Date} dateTime 日期对象
* @param {string} [format='YYYY-MM-DD'] 时间格式
* @returns {string} 格式化后的日期
* @example:
* 原始: new Date() => Fri May 31 2024 15:43:03 GMT+0800 (中国标准时间)
* 最终: 2024-05-31
*/
datetimeUtil.formatDate(dateTime, format)
/**
* 时间戳转时间格式
*
* @param {number} timestamp 时间戳
* @param {string} [format='YYYY-MM-DD hh:mm:ss'] 时间格式
* @returns {string} 转换后的日期时间
* @example: 1717139415 => 2024-05-31 15:10:15
*/
datetimeUtil.timestampToDate(timestamp, format)
/**
* 日期格式转时间戳
*
* @param {string} datetime 日期时间字符串
* @returns {number} 转换后的时间戳(秒)
* @example: 2024-05-31 15:10:15 => 1717139415
*/
datetimeUtil.dateToTimestamp(datetime)
/**
* 秒数转分钟格式
*
* @param {number} time 秒数(如: 120)
* @returns {string} 分钟格式时间: 02:00
*/
datetimeUtil.secondToMin(time)
/**
* 获取当前日期时间
*
* @returns {string} 当前日期时间字符串
* @example: 2024-05-31 15:54:00
*/
datetimeUtil.datetime()
/**
* 获取当前时间戳
*
* @returns {number} 当前时间戳(毫秒)
* @example: 1717142058720
*/
datetimeUtil.time()
/**
* 获取今日开始和结束的时间戳
*
* @returns {number[]} [开始时间戳, 结束时间戳]
* @example: [1717084800, 1717171199]
*/
datetimeUtil.today()
/**
* 获取昨日开始和结束的时间戳
*
* @returns {number[]} [开始时间戳, 结束时间戳]
* @example: [1716998400, 1717084799]
*/
datetimeUtil.yesterday()
/**
* 获取本周开始和结束的时间戳
*
* @returns {number[]} [开始时间戳, 结束时间戳]
* @example: [1716739200, 1717343999]
*/
datetimeUtil.week()
/**
* 获取本月开始和结束的时间戳
*
* @returns {number[]} [开始时间戳, 结束时间戳]
* @example: [1714492800, 1717171199]
*/
datetimeUtil.month()
/**
* 获取今年开始和结束的时间戳
*
* @returns {number[]} [开始时间戳, 结束时间戳]
* @example: [1704038400, 1735660799]
*/
datetimeUtil.year()
其它工具 (toolUtil)
import toolUtil from '@/utils/tool'
// 提取微信小程序Code
toolUtil.obtainWxCode()
// 提取微信位置(定位坐标)
toolUtil.obtainWxLocation()
// 获取当前页面
toolUtil.currentPage()
// 树转数组
treeToArray(data, props)
// 数组转树
arrayToTree(data, props)
验证工具 (validateUtil)
import validateUtil from '@/utils/validate'
// PS: 以下验证都是,如果为true=是, false=不是
// 类型验证
validateUtil.is(val, type)
// Map类型
validateUtil.isMap(val)
// RegExp类型
validateUtil.isRegExp(val)
// Date类型
validateUtil.isDate(val)
// Number类型
validateUtil.isNumber(val)
// String类型
validateUtil.isString(val)
// Promise类型
validateUtil.isPromise(val)
// Boolean类型
validateUtil.isBoolean(val)
// RegExp类型
validateUtil.isRegExp(val)
// Array类型
validateUtil.isArray(val)
// Function类型
validateUtil.isFunction(val)
// Object类型
validateUtil.isObject(val)
// 是否是手机号
validateUtil.isMobile(val)
// 是否是邮箱号
validateUtil.isEmail(val)
// 是否是[http/邮件/电话号码]
validateUtil.isExternal(val)
// 是否为空
validateUtil.isEmpty(val)
// 是否为空对象
validateUtil.isEmptyObject(val)
国际化(多语言)
- 程序提供了国际化的方案,但是程序默认使用简体中文,如果你需要国际化,请按照下面文档自行适配。
- 因为适配多端国际化会增加很多开发时间,而且像只做微信小程序端基本上就是国内使用不需要多语言。
- 另外: 官方推荐使用vue-i18n@9.1.9固定版本,但是在H5有个警告,建议固定
9.1.10,其它版本可能某些端报错。
关于多语言
注意
uni-app的国际化,即多语言,分为应用部分和框架部分。
- 应用部分,即开发者自己的代码里涉及的界面部分。
- 框架部分,即uni-app内置组件和API涉及界面的部分。
不同端的国际化方案也有差异,uni-app 自 3.1.5起,App 和 H5 支持框架国际化。
小程序平台的国际化依赖于小程序平台框架自身。一般而言海外用户更多使用的是App和H5。
看完本文档还不知道怎么使用,请看官方文档
PS: Uniapp关于对语言的文档: https://uniapp.dcloud.net.cn/tutorial/i18n.html#
小程序国际化
- 已支持:
- 页面
- 组件
- 不支持:
- pages.json,可以通过调用API来设置,例如更改标题
uni.setNavigationBarTitle() - tabbar 不支持动态修改内容,但是可以通过自定义tabbar的方式。
- 自定义tabbar文档:
https://uniapp.dcloud.net.cn/collocation/pages?id=custom-tab-bar
- pages.json,可以通过调用API来设置,例如更改标题
语言包管理
1、语言包统一放在
src/lang/..目录下2、我们内置了常用三个语言包(其它的自行扩展),内置的有:
- en.json 英文
- zh-Hans.json 简体中文
- zh-Hant.json 繁体中文
3、UniApp 支持多种语言地区代码,以下是一些常见语言地区代码的示例:
简体中文:zh-Hans
繁体中文:zh-Hant
英文:en
法文:fr
德文:de
日文:ja
韩文:ko
俄文:ru
语言包配置
- 这里说的是语言包要怎么配置
- 我们已简体中文语言包
zh-Hans.json为示例: - PS: 其它语言包也是一样的,把里面的值换成对应的就行
{
"pages.index.index": "WaitAdmin开源系统",
"pages.login.home": "欢迎您 `{name}` 回家",
"pages.login.enroll": "登录"
}
语言的扩展
- 1、假设我们要增加日文语言报
- 2、在lang目录加入语言包如
jp.json - 3、在
main.ts导入语言包 - 示例:
import App from './App.vue'
import en from './lang/en.json'
import zhHans from './lang/zh-Hans.json'
import zhHant from './lang/zh-Hant.json'
// 1、导入你扩展的语言包
import jp from './lang/jp.json'
// 2、把语言包加入到配置
let i18nConfig = {
locale: 'en',
messages:{
'en': en,
'zh-Hans': zhHans,
'zh-Hant': zhHant,
'jp': jp // 加入到这里
}
}
语言包的使用
- 前面一直在在说如何去定义语言包。
- 这里我们说一下怎么去使用语言包。
在页面中的使用
- 页面模板中使用 $t() 获取,并传递国际化json文件中定义的key,js中使用 this.$t('')
- PS: 在vue3中如果使用了 setup 语法糖 是无法直接在 js 中使用 this对象的,下面我再讲怎么用。
<template>
<view class="container">
<!-- 默认方式 -->
<view class="title">{{ $t('pages.index.index') }}</view>
<!-- 传参方式 -->
<view class="home">{{ $t('pages.login.home', {name: "Wait"}) }}</view>
</view>
</template>
在Js中的使用
// 使用方法1: (推荐)
<script setup>
import { useI18n } from 'vue-i18n'
const { t } = useI18n()
console.log(t('pages.index.index'))
</script>
// 使用方法2:
<script setup>
import { getCurrentInstance } from 'vue'
const { proxy } = getCurrentInstance()
proxy.$t('pages.index.index')
</script>
在pages.json中使用
- 使用 %% 占位
{
"pages": [
{
"path": "pages/index/index",
"style": {
"navigationBarTitleText": "%pages.index.index%"
}
}
],
"tabBar": {
"list": [{
"pagePath": "pages/index/index",
"text": "%pages.index.index%"
}
]
}
}
注意
在小程序中不支持以上这种国际化方法,你可以使用tabbar和setNavigationBar的API来设置文字
如何切换语言
- 在
src/main.js文件中进行切换 locale参数是控制使用什么语言的。- 你要改成别的语言(如英文)你可以这样配置:
locale: 'en'
// 以下是默认的语言: zh-Hans (简体中文)
let i18nConfig = {
locale: uni.getLocale(),
messages:{
'en': en,
'zh-Hans': zhHans,
'zh-Hant': zhHant
}
}
// 切换到英文语言
let i18nConfig = {
locale: 'en', // 这里直接改成对应的语言包就行
messages:{
'en': en,
'zh-Hans': zhHans,
'zh-Hant': zhHant
}
}
获取当前语言
文档地址: https://uniapp.dcloud.net.cn/api/ui/locale.html#getlocale
const name: string = uni.getLocale()
console.log(name)
// 输出结果: zh-Hans
设置其它语言
文档地址: https://uniapp.dcloud.net.cn/api/ui/locale.html#setlocale
作用说明: 您可以使用以下方式动态更换语言
uni.setLocale('en')
内置组件
页面加载
- 组件:
src/components/loading - 场景: 因为当页面切换的时候,数据还没加载完成就显示了,导致页面闪烁。
- 作用: 可以让页面切换看起来更平滑,当然你也可以改用骨架屏更丝滑。
这个组件在自带的很多页面都使用了,不知道怎么用的看下代码。
<template>
<w-loading :show="isFirstLoading" />
</template>
<script setup lang="ts">
// 首次加载
const isFirstLoading = ref<boolean>(true)
</script>
页头占位
- 组件:
src/components/widget-bar - 场景: 当页面使用了自定义导航的时候,微信端会存在兼容问题。
- 作用: 主要用于微信小程序自定义导航时,导航栏占位撑开高度。
用户个人中心有使用到这个组件,src/pages/user/index.vue
<w-widget-bar background-color="var(--color-primary)" />
文件上传
<template>
<!-- 单图上传 -->
<w-upload
v-model="imageUrl"
:limit="1"
type="picture"
upload-text="单图"
@success="handleSuccess"
></w-upload>
<!-- 多图上传 -->
<w-upload
v-model="images"
type="picture"
:multiple="true"
:limit="3"
upload-text="多图"
></w-upload>
</template>
<script>
import WUpload from '@/components/upload/index.vue'
// 单图
const imageUrl = ref('')
// 多图
const images = ref([])
// 上传成功回调
function handleSuccess(file, response) {
/* eslint-disable no-console */
console.log('上传成功', file, response)
}
</script>
参数说明
| 参数名 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| modelValue | string string[] object | - | 是 | 双向绑定值 |
| url | string | - | 否 | 文件上传接口地址 |
| name | string | file | 否 | 上传文件的字段名 |
| temp | boolean | false | 否 | 上传到临时的目录 |
| data | Record<string, any> | - | 否 | 附加的上传参数 |
| headers | Record<string, any> | - | 否 | 上传请求的HTTP头 |
| 限制 | ||||
| type | picture,video,document,package | - | 是 | 允许上传文件类型 |
| limit | number | 1 | 否 | 最大可选的文件数 |
| maxSize | number | - | 否 | 单个文件最大体积(B) |
| multiple | boolean | false | 否 | 是否支持多选文件 |
| disabled | boolean | false | 否 | 是否禁用上传功能 |
| deletable | boolean | true | 否 | 是否显示删除按钮 |
| showProgress | boolean | true | 否 | 是否显示上传进度条 |
| showFileList | boolean | true | 否 | 是否显示文件的列表 |
| acceptMime | string[] | - | 否 | 筛选可选的扩展类型 |
| emitsType | string,object | string | 否 | 返回通知的数据结构 |
| 选择 | ||||
| sizeType | ('original' 、 'compressed')[] | ['original', 'compressed'] | 否 | 图片压缩类型(仅对图片有效) |
| sourceType | ('album' 、 'camera')[] | ['album', 'camera'] | 否 | 图片/视频的来源类型(相册/相机) |
| 显示 | ||||
| uploadText | string | - | 否 | 上传区域的文字 |
| uploadIcon | string | - | 否 | 上传区域的图标名 |
| uploadIconSize | string | 48rpx | 否 | 上传区域图标的大小 |
| uploadIconColor | string | #999999 | 否 | 上传区域图标的颜色 |
| uploadItemSize | string | 160rpx | 否 | 上传区域按钮的尺寸 |
杂项
微信小程序登录
- 1、如果你想使用
微信一键授权登录,你需要先配置好相关密钥。 - 2、如果同时使用个端 如:
小程序和公众号,建议您把开放平台给关联上,否则账号不同步。 - 3、APP端微信登录需到
微信开放平台获取到对应的appid,然后配置在manifest.json - 4、APP端获取配置的教程: https://blog.csdn.net/fengspirit/article/details/154742951
后台的配置
Uniapp的配置
短信邮件发送


import indexApi from '@/api/index'
// 发送短信 (获取登录验证码)
indexApi.sendSms({
scene: 101, // 场景编号
mobile: '13800138000'
})
// 发送邮件 (和短信是同理的)
// 注意: 邮件发送也需要在【后台 -> 设置 -> 邮件设置】 配置好才行。
indexApi.sendEmail({
scene: 106,
email: 'waitadmin@163.com'
})
// 如果您是获取验证码场景,你可以考虑使用封装的 verify-code 组件
// 具体使用方式你可以查看登录的代码 src/pages/login/_components/login-mobile.vue
问题
支付宝小程序编译报错
1、可能是组件导入问题
1.1、在支付宝端,如果components的组件没有在主包调用过,在分包调用时,则会报错。
1.2、其它端则不会报错, 如果需要适配支付宝小程序端,你最好主动导入组件。
1.3、报错信息: error[CE1000.01]: cannot resolve module
2、可能使用了不兼容依赖
import { debounce } from 'lodash-es'
这个函数在支付宝小程序端使用会报错
[Vue warn]: Unhandled error during execution of native event handler
at <LoginAccount show-register=true show-protocol=true >
at <App.ku >
at <Index >
vue-i18n国际化版本问题
- 1、请尽量不要使用除
vue-i18n@9.1.10或vue-i18n@9.1.9外的其它版本。 - 2、
vue-i18n@9.1.9经测试可以正常运行,但是H5端会有一个警告提示。 - 3、
vue-i18n@9.1.10可以正常运行并且没有警告,所以建议固定这个版本。
底部导航如何增加按钮
注意
- 1、当前系统是通过接口控制是否显示底部导航的。
- 2、导航分为两种
系统导航和自定义导航 - 3、
系统导航: 体验较好,但限制比较多,不能修改跳转地址,必须在pages.json添加页面配置。 - 4、
自定义导航: 体验差,切换页面可能会闪烁,但是没什么限制。
建议你阅读一下官方文档: https://uniapp.dcloud.net.cn/collocation/pages.html#tabbar
导航加载说明
1、在程序启动的时候执行了 onLaunch 方法, 这时候会请求获取装修数据。
// App.vue
onLaunch(async () => {
appStore.getRoutePages()
await appStore.getDecorates() // 获取装修数据
await decorUtil.setNavBar() // 这里是初始化页面风格的
await decorUtil.setTabBar() // 这里是设置底部导航的
})
setTabBar()的作用
- 1、会根据装修数据,是采用
系统导航还是自定义导航。 - 2、如果是
系统导航会根据接口的参数 替换图标 和 文字。 - 3、如果是
自定义导航那就会隐藏系统导航
系统导航增加
- 1、到
pages.json增加tabBar配置, 最多5个。 - 2、在后台
装修 -> 底部导航添加一样的配置。
自定义导航增加
- 1、直接到后台
装修 -> 底部导航添加 - 2、注意: 填写的路径需要存在
pages.json里才可以。