快速上手
本节介绍如何在uni-app
项目中安装、配置并使用 Wot Design Uni
。
使用之前
使用前,请确保你已经学习过Vue官方的 快速上手 和 uni-app提供的 学习路线。
安装
关于安装
Wot Design Uni
提供了uni_modules
和npm
两种安装方式,按需选择。
- 使用
uni_modules
安装无需额外配置,即插即用,但是每次更新组件库需要处理代码差异(一般直接覆盖就可以)。 - 使用
npm
安装需要额外配置,更新组件库时无需处理代码差异。
npm 安装
npm i wot-design-uni
yarn add wot-design-uni
pnpm add wot-design-uni
uni_modules 安装
Wot Design Uni
支持 uni_modules 规范,已经上架到 uni-app 的插件市场。
在uni-app插件市场
选择使用HBuildX
导入,或者选择手动在src目录下创建uni_modules文件夹并将Wot Design Uni
解压到uni_modules中,结构如下:
- uni_modules
- - - wot-design-uni
下载地址:wot-design-uni
Sass
Wot Design Uni
依赖 sass
,因此在使用之前需要确认项目中是否已经安装了 sass
,如果没有安装,可以通过以下命令进行安装:
npm i sass -D
yarn add sass -D
pnpm add sass -D
提醒
Dart Sass 3.0.0
废弃了一批API,而组件库目前还未兼容,因此请确保你的sass
版本为1.78.0
及之前的版本。参见参见常见问题。
配置
导入组件
提醒
使用 uni_modules
安装时Wot Design Uni
的组件天然支持easycom
规范,无需额外配置就可以自动引入组件,而使用 npm安装
需按照此步骤配置,以下两种方案二选一即可。
配置easycom自动引入组件方案1
传统vue组件,需要安装、引用、注册,三个步骤后才能使用组件。easycom
将其精简为一步。
只要组件路径符合规范(具体见easycom),就可以不用引用、注册,直接在页面中使用。
提醒
- uni-app 考虑到编译速度,直接在
pages.json
内修改easycom
不会触发重新编译,需要改动页面内容触发。 - 请确保您的pages.json中只有一个easycom字段,否则请自行合并多个引入规则。
// pages.json
{
"easycom": {
"autoscan": true,
"custom": {
"^wd-(.*)": "wot-design-uni/components/wd-$1/wd-$1.vue"
}
},
// 此为本身已有的内容
"pages": [
// ......
]
}
基于vite配置自动引入组件方案2
如果不熟悉easycom
,也可以通过@uni-helper/vite-plugin-uni-components实现组件的自动引入。
提醒
- 推荐使用@uni-helper/vite-plugin-uni-components@0.0.9及以上版本,因为在0.0.9版本开始其内置了
wot-design-uni
的resolver
。 - 如果使用此方案时控制台打印很多
Sourcemap for points to missing source files
,可以尝试将vite版本升级至4.5.x
以上版本。
npm i @uni-helper/vite-plugin-uni-components -D
yarn add @uni-helper/vite-plugin-uni-components -D
pnpm add @uni-helper/vite-plugin-uni-components -D
// vite.config.ts
import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";
import Components from '@uni-helper/vite-plugin-uni-components'
import { WotResolver } from '@uni-helper/vite-plugin-uni-components/resolvers'
export default defineConfig({
plugins: [
// make sure put it before `Uni()`
Components({
resolvers: [WotResolver()]
}), uni()],
});
如果你使用 pnpm
,请在根目录下创建一个 .npmrc
文件,参见issue。
// .npmrc
public-hoist-pattern[]=@vue*
// or
// shamefully-hoist = true
Volar 支持
如果您使用 Volar
,请在 tsconfig.json
中通过 compilerOptions.type
指定全局组件类型。
TIP
cli项目使用uni_modules
安装无需配置,对Volar
的支持自动生效,HbuildX
项目不支持此配置,故此步骤仅在cli
项目使用npm
安装时需要配置。
// tsconfig.json
{
"compilerOptions": {
"types": ["wot-design-uni/global"]
}
}
使用
Wot Design Uni
安装、配置完成之后,支持组件自动引入,故可以直接在SFC中使用,无需在页面内import,也不需要在components内声明,即可在任意页面使用。值得注意的是,uni-app
平台不支持全局挂载组件,所以Message
、Toast
等组件仍需在SFC中显式使用,例如:
<wd-toast></wd-toast>
脚手架
我们提供了快速上手项目wot-demo,它集成了Wot Design Uni
和众多优秀插件,你可以直接克隆该项目。
你也可以使用create-uni,通过以下命令快速创建一个起手项目:
pnpm create uni@latest <你的项目名称> -t wot