From 5f8fb05b7f832e849b4be853d9e15a90790b9f07 Mon Sep 17 00:00:00 2001 From: neverland Date: Tue, 7 Dec 2021 17:04:56 +0800 Subject: [PATCH] docs: update quickstart (#10009) * docs: update quickstart * docs: update --- .../vant/docs/markdown/quickstart.en-US.md | 119 ++++++++------ .../vant/docs/markdown/quickstart.zh-CN.md | 147 +++++++++--------- packages/vant/src/card/demo/index.vue | 24 ++- .../card/test/__snapshots__/demo.spec.ts.snap | 60 ++++--- packages/vant/src/cascader/demo/index.vue | 10 +- 5 files changed, 193 insertions(+), 167 deletions(-) diff --git a/packages/vant/docs/markdown/quickstart.en-US.md b/packages/vant/docs/markdown/quickstart.en-US.md index 8feb3b2fe..588b76db0 100644 --- a/packages/vant/docs/markdown/quickstart.en-US.md +++ b/packages/vant/docs/markdown/quickstart.en-US.md @@ -92,55 +92,21 @@ In the GUI, click on 'Dependencies' -> `Install Dependencies` and add `vant` to ## Usage -### 1. Import on demand +### Import on demand in vite projects (recommended) -Use [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) to import components on demand. +If you are using vite, please use [vite-plugin-style-import](https://github.com/anncwb/vite-plugin-style-import). -```bash -# Install plugin -npm i babel-plugin-import -D -``` - -Set babel config in .babelrc or babel.config.js: - -```json -{ - "plugins": [ - [ - "import", - { - "libraryName": "vant", - "libraryDirectory": "es", - "style": true - } - ] - ] -} -``` - -Then you can import components from vant: - -```js -// Input -import { Button } from 'vant'; - -// Output -import Button from 'vant/es/button'; -import 'vant/es/button/style'; -``` - -> If you are using TypeScript，please use [ts-import-plugin](https://github.com/Brooooooklyn/ts-import-plugin) instead. - -### 2. Vite Plugin - -If you are using Vite, please use [vite-plugin-style-import](https://github.com/anncwb/vite-plugin-style-import). +#### 1. Install Plugin ```bash npm i vite-plugin-style-import -D ``` +#### 2. Configure Plugin + +Configure the plugin in the `vite.config.js` file: + ```js -// vite.config.js import vue from '@vitejs/plugin-vue'; import styleImport from 'vite-plugin-style-import'; @@ -160,14 +126,67 @@ export default { }; ``` -### 3. Manually import +#### 3. Import Components + +Then you can import components from Vant: ```js -import Button from 'vant/es/button/index'; -import 'vant/es/button/style/index'; +import { createApp } from 'vue'; +import { Button } from 'vant'; + +const app = createApp(); +app.use(Button); ``` -### 4. Import all components +> Vant supports Tree Shaking by default. + +### Import on demand in non-vite projects (recommended) + +In non-vite projects, use [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) to import components on demand. + +#### 1. Install Plugin + +```bash +npm i babel-plugin-import -D +``` + +#### 2. Configure Plugin + +Set babel config in `.babelrc` or `babel.config.js`: + +```json +{ + "plugins": [ + [ + "import", + { + "libraryName": "vant", + "libraryDirectory": "es", + "style": true + } + ] + ] +} +``` + +#### 3. Import Components + +Then you can import components from Vant: + +```js +// Input +import { Button } from 'vant'; + +// Output +import Button from 'vant/es/button'; +import 'vant/es/button/style'; +``` + +> If you are using TypeScript，please use [ts-import-plugin](https://github.com/Brooooooklyn/ts-import-plugin) instead. + +### Import all components (not recommended) + +Import all components will **increase the bundle size**, so this is not recommended. ```js import { createApp } from 'vue'; @@ -179,3 +198,13 @@ app.use(Vant); ``` > If you configured babel-plugin-import, you won't be allowed to import all components. + +### Manually import (not recommended) + +```js +// import script +import Button from 'vant/es/button/index'; +// import style +// if the component does not have a style file, there is no need to import +import 'vant/es/button/style/index'; +``` diff --git a/packages/vant/docs/markdown/quickstart.zh-CN.md b/packages/vant/docs/markdown/quickstart.zh-CN.md index 3883b1046..8f70248e8 100644 --- a/packages/vant/docs/markdown/quickstart.zh-CN.md +++ b/packages/vant/docs/markdown/quickstart.zh-CN.md @@ -76,25 +76,6 @@ pnpm add vant@3 - 通过 npm 引入，并通过构建工具进行打包 - 下载对应文件，并托管在你自己的服务器或 CDN 上 -### 通过脚手架安装 - -在新项目中使用 Vant 时，可以使用 Vue 官方提供的脚手架 [Vue Cli](https://cli.vuejs.org/zh/) 创建项目并安装 Vant。 - -```bash -# 安装 Vue Cli -npm install -g @vue/cli - -# 创建一个项目 -vue create hello-world - -# 创建完成后，可以通过命令打开图形化界面，如下图所示 -vue ui -``` - -![](https://img.yzcdn.cn/vant/vue-cli-demo-201809032000.png) - -在图形化界面中，点击 `依赖` -> `安装依赖`，然后将 `vant` 添加到依赖中即可。 - ## 示例 ### 示例工程 @@ -112,56 +93,21 @@ vue ui ## 引入组件 -### 方式一. 通过 babel 插件按需引入组件 +### 在 vite 项目中按需引入组件（推荐） -[babel-plugin-import](https://github.com/ant-design/babel-plugin-import) 是一款 babel 插件，它会在编译过程中将 import 语句自动转换为按需引入的方式。 +在 vite 项目中使用 Vant 时，推荐安装 [vite-plugin-style-import](https://github.com/anncwb/vite-plugin-style-import) 插件，它可以自动按需引入组件的样式。 + +#### 1. 安装插件 ```bash -# 安装插件 -npm i babel-plugin-import -D -``` - -在.babelrc 或 babel.config.js 中添加配置： - -```json -{ - "plugins": [ - [ - "import", - { - "libraryName": "vant", - "libraryDirectory": "es", - "style": true - } - ] - ] -} -``` - -接着你可以在代码中直接引入 Vant 组件，插件会自动将代码转化为按需引入的形式。 - -```js -// 原始代码 -import { Button } from 'vant'; - -// 编译后代码 -import Button from 'vant/es/button'; -import 'vant/es/button/style'; -``` - -> 如果你在使用 TypeScript，可以使用 [ts-import-plugin](https://github.com/Brooooooklyn/ts-import-plugin) 实现按需引入。 - -### 方式二. 在 Vite 项目中按需引入组件 - -对于 vite 项目，可以使用 [vite-plugin-style-import](https://github.com/anncwb/vite-plugin-style-import) 实现按需引入, 原理和 `babel-plugin-import` 类似。 - -```bash -# 安装插件 npm i vite-plugin-style-import -D ``` +#### 2. 配置插件 + +安装完成后，在 `vite.config.js` 文件中配置插件： + ```js -// vite.config.js import vue from '@vitejs/plugin-vue'; import styleImport from 'vite-plugin-style-import'; @@ -181,20 +127,67 @@ export default { }; ``` -### 方式三. 手动按需引入组件 +#### 3. 引入组件 -在不使用插件的情况下，可以手动引入需要使用的组件和样式。 +完成以上两步，就可以直接使用 Vant 组件了： ```js -// 引入组件 -import Button from 'vant/es/button/index'; -// 引入组件对应的样式，若组件没有样式文件，则无须引入 -import 'vant/es/button/style/index'; +import { createApp } from 'vue'; +import { Button } from 'vant'; + +const app = createApp(); +app.use(Button); ``` -### 方式四. 导入所有组件 +> Vant 默认支持通过 Tree Shaking 实现 script 的按需引入。 -Vant 支持一次性导入所有组件，引入所有组件会增加代码包体积，因此不推荐这种做法。 +### 在非 vite 项目中按需引入组件（推荐） + +在非 vite 的项目中，可以通过 babel 插件来实现按需引入组件。我们需要安装 [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) 插件，它会在编译过程中将 import 语句自动转换为按需引入的方式。 + +#### 1. 安装插件 + +```bash +npm i babel-plugin-import -D +``` + +#### 2. 配置插件 + +在.babelrc 或 babel.config.js 中添加配置： + +```json +{ + "plugins": [ + [ + "import", + { + "libraryName": "vant", + "libraryDirectory": "es", + "style": true + } + ] + ] +} +``` + +#### 3. 引入组件 + +接着你可以在代码中直接引入 Vant 组件，插件会自动将代码转化为按需引入的形式。 + +```js +// 原始代码 +import { Button } from 'vant'; + +// 编译后代码 +import Button from 'vant/es/button'; +import 'vant/es/button/style'; +``` + +> 如果你在使用 TypeScript，可以使用 [ts-import-plugin](https://github.com/Brooooooklyn/ts-import-plugin) 实现按需引入。 + +### 导入所有组件（不推荐） + +Vant 支持一次性导入所有组件，引入所有组件会**增加代码包体积**，因此不推荐这种做法。 ```js import { createApp } from 'vue'; @@ -205,4 +198,16 @@ const app = createApp(); app.use(Vant); ``` -> Tips: 配置按需引入后，将不允许直接导入所有组件。 +> Tips: 配置按需引入插件后，将不允许直接导入所有组件。 + +### 手动按需引入组件（不推荐） + +在不使用任何构建插件的情况下，可以手动引入需要使用的组件和样式。 + +```js +// 引入组件脚本 +import Button from 'vant/es/button/index'; +// 引入组件样式 +// 若组件没有样式文件，则无须引入 +import 'vant/es/button/style/index'; +``` diff --git a/packages/vant/src/card/demo/index.vue b/packages/vant/src/card/demo/index.vue index e47f5a540..901f4ec8d 100644 --- a/packages/vant/src/card/demo/index.vue +++ b/packages/vant/src/card/demo/index.vue @@ -51,23 +51,19 @@ const imageURL = 'https://img.yzcdn.cn/vant/ipad.jpeg'; :thumb="imageURL" > diff --git a/packages/vant/src/card/test/__snapshots__/demo.spec.ts.snap b/packages/vant/src/card/test/__snapshots__/demo.spec.ts.snap index 73bed95eb..164ef9a03 100644 --- a/packages/vant/src/card/test/__snapshots__/demo.spec.ts.snap +++ b/packages/vant/src/card/test/__snapshots__/demo.spec.ts.snap @@ -134,18 +134,16 @@ exports[`should render demo and match snapshot 1`] = `
Description
-
- - - Tag - - - - - Tag - - -
+ + + Tag + + + + + Tag + +
@@ -169,26 +167,24 @@ exports[`should render demo and match snapshot 1`] = `
-
- - -
+ +
diff --git a/packages/vant/src/cascader/demo/index.vue b/packages/vant/src/cascader/demo/index.vue index 92a354d19..d821b87a1 100644 --- a/packages/vant/src/cascader/demo/index.vue +++ b/packages/vant/src/cascader/demo/index.vue @@ -55,7 +55,7 @@ const t = useTranslate({ type StateItem = { show: boolean; - value: string | number | null; + value: string | number | undefined; result: string; options?: CascaderOption[]; tabIndex?: number; @@ -68,18 +68,18 @@ const baseState = reactive({ }); const customColorState = reactive({ show: false, - value: null, + value: undefined, result: '', }); const asyncState = reactive({ show: false, - value: null, + value: undefined, result: '', options: t('asyncOptions1'), }); const customFieldState = reactive({ show: false, - value: null, + value: undefined, result: '', }); @@ -91,7 +91,7 @@ const fieldNames = { const customContentState = reactive({ show: false, - value: null, + value: undefined, result: '', });