Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: fix create-uni command error #874

Merged
merged 1 commit into from
Feb 11, 2025
Merged

docs: fix create-uni command error #874

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 60 additions & 39 deletions docs/guide/quick-use.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,26 @@
# 快速上手

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

## 使用之前
使用前，请确保你已经学习过Vue官方的 [快速上手](https://cn.vuejs.org/guide/quick-start.html) 和 uni-app提供的 [学习路线](https://uniapp.dcloud.net.cn/resource.html)。

使用前，请确保你已经学习过 Vue 官方的 [快速上手](https://cn.vuejs.org/guide/quick-start.html) 和 uni-app 提供的 [学习路线](https://uniapp.dcloud.net.cn/resource.html)。

## 安装

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

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

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

:::

### npm 安装

::: code-group

```bash [npm]
npm i wot-design-uni
```
Expand All @@ -26,25 +32,28 @@ yarn add wot-design-uni
```bash [pnpm]
pnpm add wot-design-uni
```
:::

:::

### uni_modules 安装

`Wot Design Uni` 支持 [uni_modules](https://uniapp.dcloud.net.cn/plugin/uni_modules.html#uni-modules) 规范，已经上架到 uni-app 的插件市场。

在`uni-app插件市场`选择使用`HBuildX`导入，或者选择手动在src目录下创建uni_modules文件夹并将`Wot Design Uni`解压到uni_modules中，结构如下:
```
在 `uni-app 插件市场` 选择使用 `HBuildX` 导入，或者选择手动在 src 目录下创建 uni_modules 文件夹并将 `Wot Design Uni` 解压到 uni_modules 中，结构如下：

```bash
- uni_modules
- - - wot-design-uni
```

下载地址：<a href="https://ext.dcloud.net.cn/plugin?id=13889"><span >wot-design-uni</span></a>

下载地址：<a href="https://ext.dcloud.net.cn/plugin?id=13889"><span>wot-design-uni</span></a>

## Sass

`Wot Design Uni` 依赖 `sass` ，因此在使用之前需要确认项目中是否已经安装了 `sass`，如果没有安装，可以通过以下命令进行安装：

::: code-group

```bash [npm]
npm i sass -D
```
Expand All @@ -56,54 +65,63 @@ yarn add sass -D
```bash [pnpm]
pnpm add sass -D
```

:::

::: warning 提醒
`Dart Sass 3.0.0` 废弃了一批API，而组件库目前还未兼容，因此请确保你的`sass`版本为`1.78.0`及之前的版本。参见参见[常见问题](/guide/common-problems.html#sass抛出大量错误和警告)。
`Dart Sass 3.0.0` 废弃了一批 API，而组件库目前还未兼容，因此请确保你的`sass`版本为`1.78.0`及之前的版本。参见参见[常见问题](/guide/common-problems.html#sass抛出大量错误和警告)。
:::

## 配置

### 导入组件

::: tip 提醒
使用 `uni_modules` 安装时`Wot Design Uni`的组件天然支持`easycom`规范，无需额外配置就可以自动引入组件，而使用 `npm安装 `需按照此步骤配置，以下两种方案二选一即可。
使用 `uni_modules` 安装时 `Wot Design Uni` 的组件天然支持 `easycom` 规范，无需额外配置就可以自动引入组件，而使用 `npm 安装` 需按照此步骤配置，以下两种方案二选一即可。
:::

#### 配置easycom自动引入组件<el-tag type="primary" style="vertical-align: middle;margin-left:8px;" effect="dark" >方案1</el-tag>
传统vue组件，需要安装、引用、注册，三个步骤后才能使用组件。`easycom`将其精简为一步。
#### 配置 easycom 自动引入组件<el-tag type="primary" style="vertical-align: middle;margin-left:8px;" effect="dark" >方案 1</el-tag>

传统 vue 组件，需要安装、引用、注册，三个步骤后才能使用组件。`easycom`将其精简为一步。
只要组件路径符合规范（具体见[easycom](https://uniapp.dcloud.net.cn/collocation/pages.html#easycom)），就可以不用引用、注册，直接在页面中使用。

:::tip 提醒
- uni-app 考虑到编译速度，直接在`pages.json`内修改`easycom`不会触发重新编译，需要改动页面内容触发。
- 请确保您的pages.json中只有一个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": [
// ......
]
"easycom": {
"autoscan": true,
"custom": {
"^wd-(.*)": "wot-design-uni/components/wd-$1/wd-$1.vue"
}
},
// 此为本身已有的内容
"pages": [
// ......
]
}
```

#### 基于vite配置自动引入组件<el-tag type="primary" style="vertical-align: middle;margin-left:8px;" effect="dark" >方案2</el-tag>
如果不熟悉`easycom`，也可以通过[@uni-helper/vite-plugin-uni-components](https://github.com/uni-helper/vite-plugin-uni-components)实现组件的自动引入。
#### 基于 vite 配置自动引入组件<el-tag type="primary" style="vertical-align: middle;margin-left:8px;" effect="dark" >方案 2</el-tag>

如果不熟悉 `easycom`，也可以通过 [@uni-helper/vite-plugin-uni-components](https://github.com/uni-helper/vite-plugin-uni-components) 实现组件的自动引入。

:::tip 提醒
- 推荐使用@uni-helper/[email protected]及以上版本，因为在0.0.9版本开始其内置了`wot-design-uni`的`resolver`。
- 如果使用此方案时控制台打印很多`Sourcemap for points to missing source files​`，可以尝试将vite版本升级至`4.5.x`以上版本。

- 推荐使用 `@uni-helper/[email protected]` 及以上版本，因为在 0.0.9 版本开始其内置了 `wot-design-uni` 的`resolver`。
- 如果使用此方案时控制台打印很多 `Sourcemap for points to missing source files​` ，可以尝试将 `Vite` 版本升级至 `4.5.x` 以上版本。

:::

::: code-group

```bash [npm]
npm i @uni-helper/vite-plugin-uni-components -D
```
Expand All @@ -115,6 +133,7 @@ yarn add @uni-helper/vite-plugin-uni-components -D
```bash [pnpm]
pnpm add @uni-helper/vite-plugin-uni-components -D
```

:::

```ts
Expand All @@ -135,21 +154,23 @@ export default defineConfig({
});
```

如果你使用 `pnpm` ，请在根目录下创建一个 `.npmrc` 文件，参见[issue](https://github.com/antfu/unplugin-vue-components/issues/389)。
如果你使用 `pnpm` ，请在根目录下创建一个 `.npmrc` 文件，参见 [Issue](https://github.com/antfu/unplugin-vue-components/issues/389)。

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


## Volar 支持

如果您使用 `Volar`，请在 `tsconfig.json` 中通过 `compilerOptions.type` 指定全局组件类型。

:::tip
cli项目使用`uni_modules`安装无需配置，对`Volar`的支持自动生效，`HbuildX`项目不支持此配置，故此步骤仅在`cli`项目使用`npm`安装时需要配置。
cli 项目使用 `uni_modules` 安装无需配置，对 `Volar` 的支持自动生效，`HbuildX` 项目不支持此配置，故此步骤仅在 `cli` 项目使用 `npm` 安装时需要配置。
:::

```json
// tsconfig.json
{
Expand All @@ -159,20 +180,20 @@ cli项目使用`uni_modules`安装无需配置，对`Volar`的支持自动生效
}
```

## 使用

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

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


## 脚手架
我们提供了快速上手项目[wot-demo](https://github.com/Moonofweisheng/wot-demo)，它集成了`Wot Design Uni`和众多优秀插件，你可以直接克隆该项目。

我们提供了快速上手项目 [wot-demo](https://github.com/Moonofweisheng/wot-demo)，它集成了 `Wot Design Uni` 和众多优秀插件，你可以直接克隆该项目。

你也可以使用[create-uni](https://github.com/uni-helper/create-uni)，通过以下命令快速创建一个起手项目：

```bash
pnpm create uni@latest <你的项目名称> -t wot
pnpm create uni@latest -t wot-demo <你的项目名称>
```