快速上手

本节介绍如何在 uni-app 项目中安装、配置并使用 Wot Design Uni。

使用之前

使用前，请确保你已经学习过 Vue 官方的 快速上手 和 uni-app 提供的 学习路线。

安装

关于安装

Wot Design Uni 提供了 uni_modules 和 npm 两种安装方式，按需选择。

• 使用uni_modules安装无需额外配置，即插即用，但是每次更新组件库需要处理代码差异（一般直接覆盖就可以）。
• 使用npm安装需要额外配置，更新组件库时无需处理代码差异。

npm 安装

npm

npm i wot-design-uni

yarn

yarn add wot-design-uni

pnpm

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

npm i sass -D

yarn

yarn add sass -D

pnpm

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

npm i @uni-helper/vite-plugin-uni-components -D

yarn

yarn add @uni-helper/vite-plugin-uni-components -D

pnpm

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-demo <你的项目名称>