Skip to content

快速上手

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

关于安装

Wot Design Uni提供了uni_modulesnpm两种安装方式,按需选择。

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

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

npm 安装

bash
npm i wot-design-uni
bash
yarn add wot-design-uni
bash
pnpm add wot-design-uni

配置easycom自动引入组件自动引入方案1

传统vue组件,需要安装、引用、注册,三个步骤后才能使用组件。easycom将其精简为一步。
只要组件路径符合规范(具体见easycom),就可以不用引用、注册,直接在页面中使用。

提醒

  • uni-app 考虑到编译速度,直接在pages.json内修改easycom不会触发重新编译,需要改动页面内容触发。
  • 请确保您的pages.json中只有一个easycom字段,否则请自行合并多个引入规则。
JSON
// 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-uniresolver
  • 如果使用此方案时控制台打印很多Sourcemap for points to missing source files​,可以尝试将vite版本升级至4.5.x。
bash
npm i @uni-helper/vite-plugin-uni-components -D
bash
yarn add @uni-helper/vite-plugin-uni-components -D
bash
pnpm add @uni-helper/vite-plugin-uni-components -D

@uni-helper/vite-plugin-uni-components 0.0.8及之前版本

ts
// vite.config.ts
import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";

import Components, { kebabCase } from '@uni-helper/vite-plugin-uni-components'

export default defineConfig({
  plugins: [
    // make sure put it before `Uni()`
    Components({
    resolvers: [
      {
        type: 'component',
        resolve: (name: string) => {
          if (name.match(/^Wd[A-Z]/)) {
            const compName = kebabCase(name)
            return {
              name,
              from: `wot-design-uni/components/${compName}/${compName}.vue`,
            }
          }
        },
      }
    ]
  }), uni()],
});

@uni-helper/vite-plugin-uni-components 0.0.9及以后版本

ts
// 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()],
});

UI 组件类型提示

如果你使用 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安装时需要配置。

json
// tsconfig.json
{
  "compilerOptions": {
    "types": ["wot-design-uni/global"]
  }
}

使用

Wot Design Uni安装、配置完成之后,支持组件自动引入,故可以直接在SFC中使用,无需在页面内import,也不需要在components内声明,即可在任意页面使用。值得注意的是,uni-app平台不支持全局挂载组件,所以MessageToast等组件仍需在SFC中显式使用,例如:

html
<wd-toast></wd-toast>

提示

使用uni_modules 安装时Wot Design Uni的组件天然支持easycom规范,无需额外配置就可以自动引入组件,而使用npm安装需要自行配置easycom@uni-helper/vite-plugin-uni-components

Released under the MIT License.

Released under the MIT License.