WaitAdmin(PHP)开发手册
首页
问题反馈
演示站点
  • gitee
  • github
  • 主页
  • PHP
  • Python
首页
问题反馈
演示站点
  • gitee
  • github
  • 主页
  • PHP
  • Python
  • 文档

    • 介绍
    • 快速上手
    • 环境部署
    • 开发规范
    • 增删改查
    • 表单组件
    • 上传组件
    • 内置工具
    • 插件开发
    • 其它杂项
    • Uniapp (旧版本V1.*)
    • Uniapp (新版V2.*)
    • 更新日志

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.320.19.3
npm>=10.8.210.8.2
HBuilder X>=4.85>=4.87

前置知识

使用前请了解以下内容

  • TypeScript: https://www.runoob.com/typescript/ts-tutorial.html
  • Tailwindcss: https://tailwindcss.com
  • WotUI: 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微信小程序支付宝小程序AndroidIOS
√√√√√

代码规范

  • 采用了 Eslint 控制vue和js等代码规范
  • 采用了 Stylelint 控制css的代码规范
  • 规范配置文件所在位置:
    • Eslint: eslint.config.ts
    • Stylelint: .stylelintrc.cjs

页面配置

页面配置文件位置: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"
    }
}
名称类型默认说明
loginbooleanfalse自定义参数,控制是否需要登录才可访问
themebooleanfalse自定义参数,顶部导航栏是否设置主题色
pathstringnulluni官方参数,页面的路径,"必须存在"
styleobjectnulluni官方参数,配置页面的样式
---更多参数请看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 配置说明

名称类型说明
baseUrlstring请求接口域名
urlPrefixstring请求接口前缀
withTokenboolean自动携带令牌
ignoreCancelboolean忽略重复请求
requestHooksRequestHooks请求拦截钩子事件
isTransformResponseboolean直接返回接口数据(不拦截错误码)
isReturnDefaultResponseboolean返回原始接口数据(需响应头及其它时可使用)
retryCountnumber重试请求最大次数
retryTimeoutnumber重试请求间隔时长(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>
参数名默认值说明
themelight主题风格: light=明亮, dark=暗黑
theme-schemedefault主题颜色: 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

语言包管理

  • 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>

参数说明

参数名类型默认值必填说明
modelValuestring string[] object-是双向绑定值
urlstring-否文件上传接口地址
namestringfile否上传文件的字段名
tempbooleanfalse否上传到临时的目录
dataRecord<string, any>-否附加的上传参数
headersRecord<string, any>-否上传请求的HTTP头
限制
typepicture,video,document,package-是允许上传文件类型
limitnumber1否最大可选的文件数
maxSizenumber-否单个文件最大体积(B)
multiplebooleanfalse否是否支持多选文件
disabledbooleanfalse否是否禁用上传功能
deletablebooleantrue否是否显示删除按钮
showProgressbooleantrue否是否显示上传进度条
showFileListbooleantrue否是否显示文件的列表
acceptMimestring[]-否筛选可选的扩展类型
emitsTypestring,objectstring否返回通知的数据结构
选择
sizeType('original' 、 'compressed')[]['original', 'compressed']否图片压缩类型(仅对图片有效)
sourceType('album' 、 'camera')[]['album', 'camera']否图片/视频的来源类型(相册/相机)
显示
uploadTextstring-否上传区域的文字
uploadIconstring-否上传区域的图标名
uploadIconSizestring48rpx否上传区域图标的大小
uploadIconColorstring#999999否上传区域图标的颜色
uploadItemSizestring160rpx否上传区域按钮的尺寸

杂项

微信小程序登录

  • 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 里才可以。
上次更新: 2025/12/23 18:28
贡献者: zero
Prev
Uniapp (旧版本V1.*)
Next
更新日志