shop-wx/doc/wot-design-uni/docs/en-US/guide/quick-use.md

Quick Start

This section introduces how to install, configure, and use Wot UI in your uni-app project.

Before Using

Before using, please make sure you have learned Vue's official Quick Start and uni-app's Learning Path.

Installation

:::warning About Installation

Wot UI provides two installation methods: uni_modules and npm. Choose according to your needs.

• Using uni_modules installation requires no additional configuration, it's plug-and-play, but updating the component library requires handling code differences (generally just overwriting is fine).
• Using npm installation requires additional configuration, but updating the component library doesn't require handling code differences.

:::

npm Installation

::: code-group

npm i wot-design-uni

yarn add wot-design-uni

pnpm add wot-design-uni

:::

uni_modules Installation

Wot UI supports the uni_modules specification and is available in the uni-app plugin market.

In the uni-app plugin market, choose to import using HBuildX, or manually create a uni_modules folder in the src directory and extract Wot UI into uni_modules, with the following structure:

- uni_modules
- - - wot-design-uni 

Download link: wot-design-uni

Sass

Wot UI depends on sass, so before using it, you need to confirm whether sass is already installed in your project. If not, you can install it using the following command:

::: code-group

npm i sass -D

yarn add sass -D

pnpm add sass -D

:::

::: warning Reminder Dart Sass 3.0.0 has deprecated a batch of APIs, and the component library hasn't been compatible yet, so please ensure your sass version is 1.78.0 or earlier. See Common Problems. :::

Configuration

Import Components

::: tip Reminder When using uni_modules installation, Wot UI components naturally support the easycom specification, requiring no additional configuration for automatic component import. When using npm installation, you need to follow this step. Choose one of the following two solutions. :::

Configure easycom for Automatic Component ImportSolution 1

Traditional Vue components require three steps: installation, import, and registration before they can be used. easycom simplifies this to one step. As long as the component path follows the specification (see easycom), you can use it directly in the page without importing and registering.

:::tip Reminder

• For compilation speed, uni-app won't trigger recompilation when directly modifying easycom in pages.json. You need to modify page content to trigger it.
• Please ensure you only have one easycom field in your pages.json, otherwise please merge multiple import rules yourself.

:::

// pages.json
{
 "easycom": {
  "autoscan": true,
  "custom": {
    "^wd-(.*)": "wot-design-uni/components/wd-$1/wd-$1.vue"
  }
 },
 
 // This is the existing content
 "pages": [
  // ......
 ]
}

Configure Automatic Component Import Based on viteSolution 2

If you're not familiar with easycom, you can also achieve automatic component import through @uni-helper/vite-plugin-uni-components.

:::tip Reminder

• Recommended to use @uni-helper/vite-plugin-uni-components@0.0.9 and above, as it includes the built-in resolver for wot-design-uni starting from version 0.0.9.
• If you see many Sourcemap for points to missing source files​ in the console when using this solution, try upgrading Vite to version 4.5.x or above.

:::

::: code-group

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

If you use pnpm, please create a .npmrc file in the root directory, see Issue.

// .npmrc
public-hoist-pattern[]=@vue*
// or
// shamefully-hoist = true

Volar Support

If you use Volar, please specify global component types through compilerOptions.type in tsconfig.json.

:::tip For cli projects using uni_modules installation, no configuration is needed as Volar support is automatically enabled. HbuildX projects don't support this configuration, so this step is only needed when using npm installation in cli projects. :::

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

Usage

After installing and configuring Wot UI, it supports automatic component import, so you can use it directly in SFC without importing in the page or declaring in components. It's worth noting that the uni-app platform doesn't support global component mounting, so components like Message, Toast, etc., still need to be explicitly used in SFC, for example:

<wd-toast></wd-toast>

Scaffolding

We provide a quick start project wot-starter, which integrates Wot UI and many excellent plugins, you can clone this project directly.

You can also use create-uni to quickly create a starter project through the following command:

pnpm create uni@latest -t wot-starter <your project name>

For more scaffolding and templates, see CLI & Templates.