uniapp整合viewPlus vue3

uniapp+vue3+vite+ts+uview-plus 最完整最详细搭建项目步骤#

搭建项目的准备工作：

通过vue-cli脚手架 创建 uni-app 项目，便于更好的兼容 TS 写法

node 版本：v18.16.0

pnpm 版本：8.3.0

vscode 安装 uni-app 开发插件：

uni-create-view ：快速创建 uni-app 页面；
uni-helper ：uni-app 代码提示，其中包括 5 个小程序扩展包；

一。创建 `uni-app` 项目#

主要是通过vue-cli脚手架 创建 uni-app 项目，便于更好的兼容 TS 写法，使用 Vue3/Vite 版：

npx degit dcloudio/uni-preset-vue#vite-ts my-vue3-project

注意：

Vue3/Vite 版要求 node 版本^14.18.0 || >=16.0.0
如命令行创建失败，请直接访问 gitee 下载模板

更多的注意安装流程和注意事项可以参考官网：uni-app 官网

二。编译和运行 uni-app 项目#

安装依赖 pnpm install

2. 运行项目 pnpm dev:mp-weixin

在运行项目时，可以打开 package.json 文件，在 scripts 配置中可以查看到运行项目的命令，如果是运行微信小程序，则通过 pnpm dev，打包则是 pnpm build，当然也可以自行配置快捷启动命名哦，如 "serve": "pnpm dev"；

运行完项目后，目录会生成 dist 文件夹，里面的 dev 中 mp-weixin 文件则是用于运行编译的文件；

3. 导入微信开发者工具

在运行项目完成后，按照提示运行方式：打开微信开发者工具，导入 dist\dev\mp-weixin 运行，此时就可以在微信开发者工具成功运行并编译该项目；

三. TS 类型校验#

打开项目结构，会发现 tsconfig.json 有报错提示：

Option 'importsNotUsedAsValues' is deprecated and will stop functioning in TypeScript 5.5. Specify compilerOption '"ignoreDeprecations": "5.0"' to silence this error.
  Use 'verbatimModuleSyntax' instead.ts

描述：警告消息与 TypeScript 编译器选项的弃用有关 importsNotUsedAsValues，并建议改用该 verbatimModuleSyntax 选项。要在 TypeScript 5.5 之前使错误消息静音，您可以添加 ignoreDeprecations":"5.0" 到编译器选项；

解决：可以在 tsconfig.json 文件中 "compilerOptions" 配置项内添加 "ignoreDeprecations": "5.0"

  "compilerOptions": {
    "ignoreDeprecations": "5.0"
  },

此时我们打开 vue 文件中，任意写一些组件，如：

在 image 内置组件的 mode 属性中很显然是没有 “xxx” 的属性值，但是代码中并没有错误提示，所以为了符合 Ts 校验，我们需要额外配置 Ts 类型校验：

1. 安装类型声明文件：

npm i -D @types/wechat-miniprogram @uni-helper/uni-app-types

2. 配置 tsconfig.json：

// tsconfig.json
{
  "extends": "@vue/tsconfig/tsconfig.json",
  "compilerOptions": {
    "ignoreDeprecations": "5.0",
    "sourceMap": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    },
    "lib": ["esnext","dom"],
    "types": [
      "@dcloudio/types", // uni-app API 类型
      "miniprogram-api-typings", // 原生微信小程序类型
      "@uni-helper/uni-app-types" // uni-app 组件类型
    ]
  },
  // vue 编译器类型，校验标签类型
  "vueCompilerOptions": {
    "nativeTags": ["block","component","template","slot"],
  },
  "include": ["src/**/*.ts","src/**/*.d.ts","src/**/*.tsx","src/**/*.vue"]
}

在配置完成后，刚才的 vue 组件就会提示报错信息，~~ 并且在 image 组件下方会有红色波浪线显示；~~ 也可能不会

四. JSON 注释问题#

在 manifest.json 和 pages.json 文件中，往往我们会添加一些注释信息，但是 JSON 规范不支持在文件中添加注释，会被视为无效的标记，并且会导致解析错误。

此时我们可以 vscode 工作区中进行配置：

在 vscode 面板中，点击右小角设置按钮→点击设置→在搜索设置中搜索 “文件关联”→找到 Files: Associations 的配置项→点击添加项→把 manifest.json 和 pages.json 设置为 jsonc即可；

五。安装 uview-plus#

我们使用的 UI 框架是 uview-plus, uview-plus 是基于 uView2.0 初步修改，支持 vue3 写法，组件也是很丰富的，这里会简单介绍一下安装以及配置的步骤，具体的详细步骤流程可以参考官网：uview-plus 3.0 - 全面兼容 nvue 的 uni-app 生态框架 - uni-app UI 框架

1. 安装

注意：此安装方式必须要按照npm 方式安装的配置中的说明配置了才可用，且项目名称不能有中文字符。

因为 uview-plus 依赖 SCSS，所以必须要安装此插件，否则无法正常运行。

2. 配置步骤

引入 uview-plus 主 JS 库：在项目src目录中的main.ts中，引入并使用 uview-plus 的 JS 库，注意这两行要放在const app = createSSRApp(App)之后。

// main.ts
import uviewPlus from 'uview-plus'
import App from './App.vue'
// #ifdef VUE3
import { createSSRApp } from 'vue'
export function createApp() {
  const app = createSSRApp(App)
  app.use(uviewPlus)
  return {
    app
  }
}
// #endif

引入 uview-plus 的全局 SCSS 主题文件：在项目根目录的uni.scss中引入此文件。

/* uni.scss */
@import 'uview-plus/theme.scss';

记得删除掉其他的 css

引入 uview-plus 基础样式：在App.vue中首行的位置引入，注意给 style 标签加入 lang="scss" 属性。

配置 easycom 组件模式：需要在项目src目录的pages.json中进行。

// pages.json
{
	"easycom": {
		// 注意一定要放在custom里，否则无效，https://ask.dcloud.net.cn/question/131175
		"custom": {
			"^u--(.*)": "uview-plus/components/u-$1/u-$1.vue",
			"^up-(.*)": "uview-plus/components/u-$1/u-$1.vue",
	        "^u-([^-].*)": "uview-plus/components/u-$1/u-$1.vue"
		}
	},
	
	// 此为本身已有的内容
	"pages": [
		// ......
	]
}

注意：

在配置完后，可以发现在 mian.ts 中引入 uview-plus 时会提示 ts 报错：无法找到模块 “uview-plus” 的声明文件。

可以在 src 文件中创建一个 types 文件夹专门用来存放 ts 类型声明文件，在文件中新建 uview.d.ts 文件写入下方声明代码即可：

3. 使用

下载和配置完成之后，在某个页面可以直接使用组件，无需通过import引入组件

<u-button text="提交"></u-button>

六。配置 pinia 持久化#

在 vue3+vite 中使用的状态管理库是 pinia，官网：Pinia 中文文档

**1. 安装 pinia:** 使用 HBuilder X 不需要手动安装，直接使用即可。使用 CLI 需要手动安装:

用法：

//main.ts
 
import { createSSRApp } from 'vue';
import * as Pinia from 'pinia';
 
export function createApp() {
	const app = createSSRApp(App);
	app.use(Pinia.createPinia());
	return {
		app,
		Pinia, // 此处必须将 Pinia 返回
	};
}

创建创建一个 Store 文件夹 counter.ts

// stores/counter.js
import { defineStore } from 'pinia';
 
export const useCounterStore = defineStore('counter', {
	state: () => {
		return { count: 0 };
	},
	// 也可以这样定义
	// state: () => ({ count: 0 })
	actions: {
		increment() {
			this.count++;
		},
	},
});

在组件中使用它:

注意：pinia 和 vuex 同样有个缺点刷新页面后数据是会丢失的，所以一般登录的 token 等信息既会保存到 store 中也会保存到本地存储等，从而实现持久化存储。

这里我们实现持久化存储用到了插件快速开始 | pinia-plugin-persistedstate

1. 安装插件

2. 将插件添加到 pinia 实例上

import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
 
const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)

3. 用法

创建 Store 时，将 persist 选项设置为 true

import { defineStore } from 'pinia'
 
export const useStore = defineStore(
  'main',
  () => {
    const someState = ref('你好 pinia')
    return { someState }
  },
  {
    persist: true,
  },
)

4. 多端兼容

export const useMemberStore = defineStore(
  'main',
  () => {
    //…省略
  },
  {
    // 配置持久化
    persist: {
      // 调整为兼容多端的API
      storage: {
        setItem(key, value) {
          uni.setStorageSync(key, value) 
        },
        getItem(key) {
          return uni.getStorageSync(key) 
        },
      },
    },
  },
)

七。封装 http 请求#

为了更方便的进行 axios 数据请求，可以将小程序的数据请求封装为 Promise 请求函数

1. 请求和上传文件拦截器

uniapp 拦截器： uni.addInterceptor

注意事项：微信小程序端，需登录微信公众平台配置合法域名；

2. 封装 Promise 请求函数

需求：返回 Promise 对象，用于处理返回值类型，成功通过 resolve 提取数据与添加泛型，失败通过 reject 捕捉错误。

/**
 * 请求函数
 * @param  UniApp.RequestOptions
 * @returns Promise
 *  1. 返回 Promise 对象，用于处理返回值类型
 *  2. 获取数据成功
 *    2.1 提取核心数据 res.data
 *    2.2 添加类型，支持泛型
 *  3. 获取数据失败
 *    3.1 401错误  -> 清理用户信息，跳转到登录页
 *    3.2 其他错误 -> 根据后端错误信息轻提示
 *    3.3 网络错误 -> 提示用户换网络
 */
type Data<T> = {
  code: string
  msg: string
  result: T
}
// 2.2 添加类型，支持泛型
export const http = <T>(options: UniApp.RequestOptions) => {
  // 1. 返回 Promise 对象
  return new Promise<Data<T>>((resolve, reject) => {
    uni.request({
      ...options,
      // 响应成功
      success(res) {
        // 状态码 2xx，参考 axios 的设计
        if (res.statusCode >= 200 && res.statusCode < 300) {
          // 2.1 提取核心数据 res.data
          resolve(res.data as Data<T>)
        } else if (res.statusCode === 401) {
          // 401错误  -> 清理用户信息，跳转到登录页
          const memberStore = useMemberStore()
          memberStore.clearProfile()
          uni.navigateTo({ url: '/pages/login/login' })
          reject(res)
        } else {
          // 其他错误 -> 根据后端错误信息轻提示
          uni.showToast({
            icon: 'none',
            title: (res.data as Data<T>).msg || '请求错误',
          })
          reject(res)
        }
      },
      // 响应失败
      fail(err) {
        uni.showToast({
          icon: 'none',
          title: '网络错误，换个网络试试',
        })
        reject(err)
      },
    })
  })
}

八。其他配置#

1. vue3 自动按需导入：

在使用 vue3 的方法如‘ref’等需要手动进行导入很麻烦，这里使用到插件 unplugin-auto-import 可以实现自动按需导入，官网：unplugin-auto-import - npm

安装：

npm i unplugin-auto-import -save

vue.config.js 文件中添加配置：

//vite.config.ts
 
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import AutoImport from 'unplugin-auto-import/vite'
 
// https://vitejs.dev/config/
export default defineConfig({
  build: {
    sourcemap: process.env.NODE_ENV === 'development',
  },
  plugins: [
    uni(),
    AutoImport({ // 使用
      imports: ['vue'],
      dts: 'src/auto-import.d.ts',
      // 如有用到eslint记得加上写段，没有用到可以忽略
      eslintrc: {
        enabled: true,
      },
    })
  ],
})

eslintrc.js 文件配置（用到 eslint 才配置）：

//.eslintrc.js
  extends: [
    'plugin:vue/vue3-essential',
    'eslint:recommended',
    '@vue/eslint-config-typescript',
    '@vue/eslint-config-prettier',
    'plugin:prettier/recommended', // 添加 prettier 插件,
  ],

配置完成后重新启动一下项目就可以啦！

在项目配置过程中可以参考哔哩哔哩网站：Day1-01-uni-app 小兔鲜儿导学视频_哔哩哔哩_bilibili

欢迎各位大佬讨论、提供建议补充...

文章来源

其他依赖#

npm install miniprogram-api-typings --save-dev

如果 vscode 有报相关错误装下这个包