first commit
This commit is contained in:
编码猿
1
vant/docs/markdown/.pydio
Normal file
1
vant/docs/markdown/.pydio
Normal file
@@ -0,0 +1 @@
|
||||
a771d393-31ea-4cf5-aede-b37c97a20464
|
||||
1238
vant/docs/markdown/changelog.en-US.md
Normal file
1238
vant/docs/markdown/changelog.en-US.md
Normal file
File diff suppressed because it is too large
Load Diff
1294
vant/docs/markdown/changelog.zh-CN.md
Normal file
1294
vant/docs/markdown/changelog.zh-CN.md
Normal file
File diff suppressed because it is too large
Load Diff
95
vant/docs/markdown/contribution.zh-CN.md
Normal file
95
vant/docs/markdown/contribution.zh-CN.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# 开发指南
|
||||
|
||||
### 介绍
|
||||
|
||||
感谢你使用 Vant。
|
||||
|
||||
以下是关于向 Vant 提交反馈或代码的指南。在向 Vant 提交 issue 或者 PR 之前，请先花几分钟时间阅读以下文字。
|
||||
|
||||
### Issue 规范
|
||||
|
||||
- 遇到问题时，请先确认这个问题是否已经在 issue 中有记录或者已被修复
|
||||
- 提 issue 时，请用简短的语言描述遇到的问题，并添加出现问题时的环境和复现步骤
|
||||
|
||||
## 参与开发
|
||||
|
||||
### 本地开发
|
||||
|
||||
按照下面的步骤操作，即可在本地开发 Vant 组件
|
||||
|
||||
```bash
|
||||
# 克隆仓库
|
||||
git clone git@github.com:youzan/vant.git
|
||||
|
||||
# 安装依赖
|
||||
cd vant && npm run bootstrap
|
||||
|
||||
# 进入开发模式，浏览器访问 http://localhost:8080
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 目录结构
|
||||
|
||||
- 仓库的组件代码位于 src 下，每个组件一个文件夹
|
||||
- docs 目录下是文档网站的代码，本地开发时可以在目录下运行 npm run dev 开启文档网站
|
||||
|
||||
项目主要目录如下：
|
||||
|
||||
```
|
||||
vant
|
||||
├─ build # 构建
|
||||
├─ docs # 文档
|
||||
├─ src # 组件
|
||||
├─ packages # 子包
|
||||
├─ test # 单测
|
||||
└─ types # 类型
|
||||
```
|
||||
|
||||
### 添加新组件
|
||||
|
||||
添加新组件时，请按照下面的目录结构组织文件，并在 `vant.config.js` 中配置组件名称
|
||||
|
||||
```
|
||||
src
|
||||
└─ button
|
||||
├─ demo # 示例代码
|
||||
├─ test # 单元测试
|
||||
├─ index.js # 组件入口
|
||||
├─ index.less # 组件样式
|
||||
├─ README.md # 英文文档
|
||||
└─ README.zh-CN.md # 中文文档
|
||||
```
|
||||
|
||||
## 提交 PR
|
||||
|
||||
### Pull Request 规范
|
||||
|
||||
- 如果遇到问题，建议保持你的 PR 足够小。保证一个 PR 只解决一个问题或只添加一个功能
|
||||
- 当新增组件或者修改原有组件时，记得增加或者修改测试代码，保证代码的稳定
|
||||
- 在 PR 中请添加合适的描述，并关联相关的 Issue
|
||||
|
||||
### Pull Request 流程
|
||||
|
||||
1. fork 主仓库，如果已经 fork 过，请同步主仓库的最新代码
|
||||
2. 基于 fork 后仓库的 dev 分支新建一个分支，比如`feature/button_color`
|
||||
3. 在新分支上进行开发，开发完成后，提 Pull Request 到主仓库的 dev 分支
|
||||
4. Pull Request 会在 Review 通过后被合并到主仓库
|
||||
5. 等待 Vant 发布版本，一般是每周一次
|
||||
|
||||
### 同步最新代码
|
||||
|
||||
提 Pull Request 前，请依照下面的流程同步主仓库的最新代码
|
||||
|
||||
```bash
|
||||
# 添加主仓库到 remote，作为 fork 后仓库的上游仓库
|
||||
git remote add upstream https://github.com/youzan/vant.git
|
||||
|
||||
# 拉取主仓库最新代码
|
||||
git fetch upstream
|
||||
|
||||
# 切换至 dev 分支
|
||||
git checkout dev
|
||||
|
||||
# 合并主仓库代码
|
||||
git merge upstream/dev
|
||||
```
|
||||
43
vant/docs/markdown/design.zh-CN.md
Normal file
43
vant/docs/markdown/design.zh-CN.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# 设计资源
|
||||
|
||||
### 介绍
|
||||
|
||||
这里提供了 Vant 现有的设计资源，更多资源还在整理中。
|
||||
|
||||
### 组件
|
||||
|
||||
包含 Sketch 格式的组件设计规范、色彩规范。
|
||||
|
||||
<img src="https://img.yzcdn.cn/vant/design-components-0321.png" style="width: 80%;">
|
||||
|
||||
<a class="design-download" href="https://github.com/youzan/vant/blob/dev/docs/assets/design.sketch?raw=true">下载</a>
|
||||
|
||||
> 提示：目前 Sketch 中部分组件仍为旧版样式，我们正在梳理新版设计规范，尽请期待！
|
||||
|
||||
### 图标
|
||||
|
||||
包含 Sketch 格式的图标库资源。
|
||||
|
||||
<img src="https://img.yzcdn.cn/vant/design-icons-0321.png" style="width: 80%;">
|
||||
|
||||
<a class="design-download" href="https://github.com/youzan/vant-icons/blob/master/assets/icons.sketch?raw=true">下载</a>
|
||||
|
||||
<style>
|
||||
a.design-download {
|
||||
display: inline-block;
|
||||
width: 100px;
|
||||
color: #fff;
|
||||
line-height: 40px;
|
||||
text-align: center;
|
||||
background-color: #38f;
|
||||
border-radius: 3px;
|
||||
}
|
||||
|
||||
a.design-download:hover {
|
||||
opacity: .9;
|
||||
}
|
||||
|
||||
a.design-download:active {
|
||||
opacity: .7;
|
||||
}
|
||||
</style>
|
||||
49
vant/docs/markdown/home.en-US.md
Normal file
49
vant/docs/markdown/home.en-US.md
Normal file
@@ -0,0 +1,49 @@
|
||||
<div class="card">
|
||||
<div class="van-doc-intro">
|
||||
<img class="van-doc-intro__logo" style="width: 120px; height: 120px;" src="https://img.yzcdn.cn/vant/logo.png">
|
||||
<h2 style="margin: 0; font-size: 36px; line-height: 60px;">Vant</h2>
|
||||
<p>Mobile UI Components built on Vue</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
### Features
|
||||
|
||||
* 60+ Reusable components
|
||||
* 90% Unit test coverage
|
||||
* Extensive documentation and demos
|
||||
* Support [babel-plugin-import](https://github.com/ant-design/babel-plugin-import)
|
||||
* Support Custom Theme
|
||||
* Support i18n
|
||||
* Support TS
|
||||
* Support SSR
|
||||
|
||||
### Quickstart
|
||||
|
||||
See in [Quickstart](#/en-US/quickstart).
|
||||
|
||||
### Contribution
|
||||
|
||||
Please make sure to read the [Contributing Guide](https://github.com/youzan/vant/blob/dev/.github/CONTRIBUTING.md) before making a pull request.
|
||||
|
||||
### Browser Support
|
||||
|
||||
Modern browsers and Android 4.0+, iOS 8.0+.
|
||||
|
||||
### Ecosystem
|
||||
|
||||
| Project | Description |
|
||||
|-----|------|
|
||||
| [vant-demo](https://github.com/youzan/vant-demo) | Official vant demo collection |
|
||||
| [vant-weapp](https://github.com/youzan/vant-weapp) | WeChat MiniProgram UI |
|
||||
| [vant-cli](https://github.com/youzan/vant/tree/dev/packages/vant-cli) | Scaffold for UI library |
|
||||
| [vant-icons](https://github.com/youzan/vant/tree/dev/packages/vant-icons) | Vant icons |
|
||||
| [vant-touch-emulator](https://github.com/youzan/vant/tree/dev/packages/vant-touch-emulator) | Using vant in desktop browsers |
|
||||
|
||||
### Links
|
||||
|
||||
* [Feedback](https://github.com/youzan/vant/issues)
|
||||
* [Changelog](#/en-US/changelog)
|
||||
|
||||
### LICENSE
|
||||
|
||||
[MIT](https://zh.wikipedia.org/wiki/MIT%E8%A8%B1%E5%8F%AF%E8%AD%89)
|
||||
66
vant/docs/markdown/home.zh-CN.md
Normal file
66
vant/docs/markdown/home.zh-CN.md
Normal file
@@ -0,0 +1,66 @@
|
||||
<div class="card">
|
||||
<div class="van-doc-intro">
|
||||
<img class="van-doc-intro__logo" style="width: 120px; height: 120px;" src="https://img.yzcdn.cn/vant/logo.png">
|
||||
<h2 style="margin: 0; font-size: 36px; line-height: 60px;">Vant</h2>
|
||||
<p>轻量、可靠的移动端 Vue 组件库</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
### 特性
|
||||
|
||||
* 60+ 高质量组件
|
||||
* 90% 单元测试覆盖率
|
||||
* 完善的中英文文档和示例
|
||||
* 支持按需引入
|
||||
* 支持主题定制
|
||||
* 支持国际化
|
||||
* 支持 TS
|
||||
* 支持 SSR
|
||||
|
||||
### 快速上手
|
||||
|
||||
请参考 [快速上手](#/zh-CN/quickstart) 章节
|
||||
|
||||
### 贡献代码
|
||||
|
||||
修改代码请阅读我们的 [开发指南](#/zh-CN/contribution)
|
||||
|
||||
使用过程中发现任何问题都可以提 [Issue](https://github.com/youzan/vant/issues) 给我们，当然，我们也非常欢迎你给我们发 [PR](https://github.com/youzan/vant/pulls)
|
||||
|
||||
### 浏览器支持
|
||||
|
||||
现代浏览器以及 Android 4.0+, iOS 8.0+
|
||||
|
||||
### 加入我们
|
||||
|
||||
**有赞前端团队**是由一群年轻、皮实、对技术饱含热情的小伙伴组成的，目前共有 100 多名前端工程师，分布在业务中台、电商、零售、美业、资产、赋能等业务线。
|
||||
|
||||
我们热爱分享和开源，崇尚用工程师的方式解决问题，因此造了很多工具来解决我们遇到的问题，目前我们维护的开源产品有：
|
||||
|
||||
<img src="https://img.yzcdn.cn/public_files/2019/07/22/f4b70763c55c8710c52c667ecf192c05.jpeg" style="width: 320px; height: 303px;">
|
||||
|
||||
我们正在寻找更多优秀的小伙伴，一起拓展前端技术的边界，期待你的加入！
|
||||
|
||||
- <a target="_blank" href="https://app.mokahr.com/apply/youzan/6252#/job/96f5d2c7-e657-4d31-9244-195edc443a7f?_k=jf2141">职位详情</a>（Base: 杭州/深圳）
|
||||
- <a target="_blank" href="https://tech.youzan.com/tag/front-end/">团队博客</a>
|
||||
- <a target="_blank" href="https://github.com/youzan">开源项目</a>
|
||||
|
||||
### 生态
|
||||
|
||||
| 项目 | 描述 |
|
||||
|-----|------|
|
||||
| [vant-demo](https://github.com/youzan/vant-demo) | Vant 官方示例合集 |
|
||||
| [vant-weapp](https://github.com/youzan/vant-weapp) | 微信小程序组件库 |
|
||||
| [vant-cli](https://github.com/youzan/vant/tree/dev/packages/vant-cli) | 开箱即用的组件库搭建工具 |
|
||||
| [vant-icons](https://github.com/youzan/vant/tree/dev/packages/vant-icons) | Vant 图标库 |
|
||||
| [vant-touch-emulator](https://github.com/youzan/vant/tree/dev/packages/vant-touch-emulator) | 在桌面端使用 Vant 的辅助库 |
|
||||
|
||||
### 链接
|
||||
|
||||
* [意见反馈](https://github.com/youzan/vant/issues)
|
||||
* [更新日志](#/zh-CN/changelog)
|
||||
* [码云镜像](https://gitee.com/organizations/vant-contrib)
|
||||
|
||||
### 开源协议
|
||||
|
||||
本项目基于 [MIT](https://zh.wikipedia.org/wiki/MIT%E8%A8%B1%E5%8F%AF%E8%AD%89) 协议，请自由地享受和参与开源
|
||||
143
vant/docs/markdown/quickstart.en-US.md
Normal file
143
vant/docs/markdown/quickstart.en-US.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# Quickstart
|
||||
|
||||
### Starter kit
|
||||
|
||||
We recomment to use [Vue Cli](https://cli.vuejs.org/zh/) to create a project.
|
||||
|
||||
```bash
|
||||
# Install Vue Cli
|
||||
npm install -g @vue/cli
|
||||
|
||||
# Create a project
|
||||
vue create hello-world
|
||||
|
||||
# Open GUI
|
||||
vue ui
|
||||
```
|
||||
|
||||
|
||||
|
||||
In the GUI, click on 'Dependencies' -> `Install Dependencies` and add `vant` to the dependencies.
|
||||
|
||||
### Install
|
||||
|
||||
```bash
|
||||
# Using npm
|
||||
npm i vant -S
|
||||
|
||||
# Using yarn
|
||||
yarn add vant
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### 1. Import on demand
|
||||
|
||||
Use [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) to import components on demand
|
||||
|
||||
```bash
|
||||
# Install plugin
|
||||
npm i babel-plugin-import -D
|
||||
```
|
||||
|
||||
```js
|
||||
// set babel config in .babelrc or babel-loader
|
||||
// Note: Don't set libraryDirectory if you are using webpack 1.
|
||||
{
|
||||
"plugins": [
|
||||
["import", {
|
||||
"libraryName": "vant",
|
||||
"libraryDirectory": "es",
|
||||
"style": true
|
||||
}]
|
||||
]
|
||||
}
|
||||
|
||||
// For users who use babel7, that can be configured in babel.config.js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
['import', {
|
||||
libraryName: 'vant',
|
||||
libraryDirectory: 'es',
|
||||
style: true
|
||||
}, 'vant']
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
```js
|
||||
// Then you can import components from vant
|
||||
import { Button } from 'vant';
|
||||
```
|
||||
|
||||
> If you are using TypeScript，please use [ts-import-plugin](https://github.com/Brooooooklyn/ts-import-plugin) instead
|
||||
|
||||
### 2. Manually import
|
||||
|
||||
```js
|
||||
import Button from 'vant/lib/button';
|
||||
import 'vant/lib/button/style';
|
||||
```
|
||||
|
||||
### 3. Import all components
|
||||
|
||||
```js
|
||||
import Vue from 'vue';
|
||||
import Vant from 'vant';
|
||||
import 'vant/lib/index.css';
|
||||
|
||||
Vue.use(Vant);
|
||||
```
|
||||
|
||||
> If you configured babel-plugin-import, you won't be allowed to import all components.
|
||||
|
||||
### 4. CDN
|
||||
|
||||
The easiest way to use Vant is to include a CDN link in the html file, after which you can access all components via the global variable `vant`.
|
||||
|
||||
```html
|
||||
<!-- import style -->
|
||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vant@2.4/lib/index.css">
|
||||
|
||||
<!-- import script -->
|
||||
<script src="https://cdn.jsdelivr.net/npm/vue/dist/vue.min.js"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/vant@2.4/lib/vant.min.js"></script>
|
||||
|
||||
<script>
|
||||
// Render the Button component
|
||||
new Vue({
|
||||
el: '#app',
|
||||
template: `<van-button>Button</van-button>`
|
||||
});
|
||||
|
||||
// Call function component
|
||||
vant.Toast('Message');
|
||||
</script>
|
||||
```
|
||||
|
||||
## Other
|
||||
|
||||
### Rem units
|
||||
|
||||
Vant use `px` as size units by default，you can use tools such as `postcss-pxtorem` to transform units to `rem`.
|
||||
|
||||
- [postcss-pxtorem](https://github.com/cuth/postcss-pxtorem)
|
||||
- [lib-flexible](https://github.com/amfe/lib-flexible)
|
||||
|
||||
#### PostCSS Config
|
||||
|
||||
postcss config example:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: {
|
||||
'autoprefixer': {
|
||||
browsers: ['Android >= 4.0', 'iOS >= 8']
|
||||
},
|
||||
'postcss-pxtorem': {
|
||||
rootValue: 37.5,
|
||||
propList: ['*']
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
218
vant/docs/markdown/quickstart.zh-CN.md
Normal file
218
vant/docs/markdown/quickstart.zh-CN.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 快速上手
|
||||
|
||||
### 脚手架
|
||||
|
||||
在新项目中使用 Vant 时，推荐使用 Vue 官方提供的脚手架 [Vue Cli](https://cli.vuejs.org/zh/) 创建项目
|
||||
|
||||
```bash
|
||||
# 安装 Vue Cli
|
||||
npm install -g @vue/cli
|
||||
|
||||
# 创建一个项目
|
||||
vue create hello-world
|
||||
|
||||
# 创建完成后，可以通过命令打开图形化界面，如下图所示
|
||||
vue ui
|
||||
```
|
||||
|
||||
|
||||
|
||||
在图形化界面中，点击`依赖` -> `安装依赖`，然后将 `vant` 添加到依赖中即可。
|
||||
|
||||
### 通过 npm 安装
|
||||
|
||||
在现有项目中使用 Vant 时，可以通过`npm`或`yarn`安装
|
||||
|
||||
```bash
|
||||
# 通过 npm 安装
|
||||
npm i vant -S
|
||||
|
||||
# 通过 yarn 安装
|
||||
yarn add vant
|
||||
```
|
||||
|
||||
### 示例工程
|
||||
|
||||
我们提供了一个基于 Vue Cli 的[示例工程](https://github.com/youzan/vant-demo)，示例工程会帮助你了解如下内容：
|
||||
|
||||
- 基于 Vant 搭建单页面应用，配置按需引入组件
|
||||
- 配置基于 Rem 的适配方案
|
||||
- 配置基于 Viewport 的适配方案
|
||||
- 配置基于 TypeScript 的工程
|
||||
- 配置自定义主题色方案
|
||||
|
||||
|
||||
## 引入组件
|
||||
|
||||
### 方式一. 自动按需引入组件 (推荐)
|
||||
|
||||
[babel-plugin-import](https://github.com/ant-design/babel-plugin-import) 是一款 babel 插件，它会在编译过程中将 import 的写法自动转换为按需引入的方式
|
||||
|
||||
```bash
|
||||
# 安装插件
|
||||
npm i babel-plugin-import -D
|
||||
```
|
||||
|
||||
```js
|
||||
// 在.babelrc 中添加配置
|
||||
// 注意：webpack 1 无需设置 libraryDirectory
|
||||
{
|
||||
"plugins": [
|
||||
["import", {
|
||||
"libraryName": "vant",
|
||||
"libraryDirectory": "es",
|
||||
"style": true
|
||||
}]
|
||||
]
|
||||
}
|
||||
|
||||
// 对于使用 babel7 的用户，可以在 babel.config.js 中配置
|
||||
module.exports = {
|
||||
plugins: [
|
||||
['import', {
|
||||
libraryName: 'vant',
|
||||
libraryDirectory: 'es',
|
||||
style: true
|
||||
}, 'vant']
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
```js
|
||||
// 接着你可以在代码中直接引入 Vant 组件
|
||||
// 插件会自动将代码转化为方式二中的按需引入形式
|
||||
import { Button } from 'vant';
|
||||
```
|
||||
|
||||
> 如果你在使用 TypeScript，可以使用 [ts-import-plugin](https://github.com/Brooooooklyn/ts-import-plugin) 实现按需引入
|
||||
|
||||
### 方式二. 手动按需引入组件
|
||||
|
||||
在不使用插件的情况下，可以手动引入需要的组件
|
||||
|
||||
```js
|
||||
import Button from 'vant/lib/button';
|
||||
import 'vant/lib/button/style';
|
||||
```
|
||||
|
||||
### 方式三. 导入所有组件
|
||||
|
||||
Vant 支持一次性导入所有组件，引入所有组件会增加代码包体积，因此不推荐这种做法
|
||||
|
||||
```js
|
||||
import Vue from 'vue';
|
||||
import Vant from 'vant';
|
||||
import 'vant/lib/index.css';
|
||||
|
||||
Vue.use(Vant);
|
||||
```
|
||||
|
||||
> 配置按需引入后，将不允许直接导入所有组件
|
||||
|
||||
### 方式四. 通过 CDN 引入
|
||||
|
||||
使用 Vant 最简单的方法是直接在 html 文件中引入 CDN 链接，之后你可以通过全局变量`vant`访问到所有组件。
|
||||
|
||||
```html
|
||||
<!-- 引入样式文件 -->
|
||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vant@2.4/lib/index.css">
|
||||
|
||||
<!-- 引入 Vue 和 Vant 的 JS 文件 -->
|
||||
<script src="https://cdn.jsdelivr.net/npm/vue/dist/vue.min.js"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/vant@2.4/lib/vant.min.js"></script>
|
||||
|
||||
<script>
|
||||
// 在 #app 标签下渲染一个按钮组件
|
||||
new Vue({
|
||||
el: '#app',
|
||||
template: `<van-button>按钮</van-button>`
|
||||
});
|
||||
|
||||
// 调用函数组件，弹出一个 Toast
|
||||
vant.Toast('提示');
|
||||
</script>
|
||||
```
|
||||
|
||||
## 进阶用法
|
||||
|
||||
### Rem 适配
|
||||
|
||||
Vant 中的样式默认使用`px`作为单位，如果需要使用`rem`单位，推荐使用以下两个工具：
|
||||
|
||||
- [postcss-pxtorem](https://github.com/cuth/postcss-pxtorem) 是一款 postcss 插件，用于将单位转化为 rem
|
||||
- [lib-flexible](https://github.com/amfe/lib-flexible) 用于设置 rem 基准值
|
||||
|
||||
#### PostCSS 配置
|
||||
|
||||
下面提供了一份基本的 postcss 配置，可以在此配置的基础上根据项目需求进行修改
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: {
|
||||
'autoprefixer': {
|
||||
browsers: ['Android >= 4.0', 'iOS >= 8']
|
||||
},
|
||||
'postcss-pxtorem': {
|
||||
rootValue: 37.5,
|
||||
propList: ['*']
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 在配置 postcss-loader 时，应避免 ignore node_modules 目录，否则将导致 Vant 样式无法被编译
|
||||
|
||||
### 在桌面端使用
|
||||
|
||||
Vant 是一个面向移动端的组件库，因此默认只适配了移动端设备，这意味着组件只监听了移动端的`touch`事件，没有监听桌面端的`mouse`事件。
|
||||
|
||||
如果你需要在桌面端使用 Vant，可以引入我们提供的 [@vant/touch-emulator](https://github.com/youzan/vant/tree/dev/packages/vant-touch-emulator)，这个库会在桌面端自动将`mouse`事件转换成对应的`touch`事件，使得组件能够在桌面端使用。
|
||||
|
||||
```bash
|
||||
# 安装模块
|
||||
npm i @vant/touch-emulator -S
|
||||
```
|
||||
|
||||
```js
|
||||
// 引入模块后自动生效
|
||||
import '@vant/touch-emulator';
|
||||
```
|
||||
|
||||
### 底部安全区适配
|
||||
|
||||
iPhone X 等机型底部存在底部指示条，指示条的操作区域与页面底部存在重合，容易导致用户误操作，因此我们需要针对这些机型进行底部安全区适配。Vant 中部分组件提供了`safe-area-inset-bottom`属性，设置该属性后，即可在对应的机型上开启适配，如下示例：
|
||||
|
||||
```html
|
||||
<!-- 在 head 标签中添加 meta 标签，并设置 viewport-fit=cover 值 -->
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, viewport-fit=cover">
|
||||
|
||||
<!-- 开启 safe-area-inset-bottom 属性 -->
|
||||
<van-number-keyboard safe-area-inset-bottom />
|
||||
```
|
||||
|
||||
<img src="https://b.yzcdn.cn/vant/safearea.png" style="margin-top: 30px;">
|
||||
|
||||
### 组件实例方法
|
||||
|
||||
Vant 中的许多组件提供了实例方法，调用实例方法时，我们需要通过 [ref](https://cn.vuejs.org/v2/api/#ref) 来注册组件引用信息，引用信息将会注册在父组件的`$refs`对象上。注册完成后，我们可以通过`this.$refs.xxx`访问到对应的组件实例，并调用上面的实例方法。
|
||||
|
||||
```html
|
||||
<!-- 将该组件绑定到 this.$refs.checkbox 上 -->
|
||||
<van-checkbox v-model="checked" ref="checkbox">
|
||||
复选框
|
||||
</van-checkbox>
|
||||
```
|
||||
|
||||
```js
|
||||
export default {
|
||||
data() {
|
||||
return {
|
||||
checked: false
|
||||
};
|
||||
},
|
||||
// 注意：组件挂载后才能访问到 ref 对象
|
||||
mounted() {
|
||||
this.$refs.checkbox.toggle();
|
||||
}
|
||||
}
|
||||
```
|
||||
226
vant/docs/markdown/style-guide.zh-CN.md
Normal file
226
vant/docs/markdown/style-guide.zh-CN.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# 风格指南
|
||||
|
||||
### 介绍
|
||||
|
||||
在参与 Vant 开发时，请遵守约定的单文件组件风格指南，指南内容节选自 [Vue 官方风格指南](https://cn.vuejs.org/v2/style-guide)。
|
||||
|
||||
### 组件数据
|
||||
|
||||
组件的 data 必须是一个函数。
|
||||
|
||||
```js
|
||||
// bad
|
||||
export default {
|
||||
data: {
|
||||
foo: 'bar'
|
||||
}
|
||||
}
|
||||
|
||||
// good
|
||||
export default {
|
||||
data () {
|
||||
return {
|
||||
foo: 'bar'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 单文件组件文件名称
|
||||
|
||||
单文件组件的文件名应该要么始终是单词大写开头 (PascalCase)，要么始终是横线连接 (kebab-case)。
|
||||
|
||||
```
|
||||
// bad
|
||||
mycomponent.vue
|
||||
myComponent.vue
|
||||
|
||||
// good
|
||||
my-component.vue
|
||||
MyComponent.vue
|
||||
```
|
||||
|
||||
### 紧密耦合的组件名
|
||||
|
||||
和父组件紧密耦合的子组件应该以父组件名作为前缀命名。
|
||||
|
||||
```
|
||||
// bad
|
||||
components/
|
||||
|- TodoList.vue
|
||||
|- TodoItem.vue
|
||||
└─ TodoButton.vue
|
||||
|
||||
// good
|
||||
components/
|
||||
|- TodoList.vue
|
||||
|- TodoListItem.vue
|
||||
└─ TodoListItemButton.vue
|
||||
```
|
||||
|
||||
### 自闭合组件
|
||||
|
||||
在单文件组件中没有内容的组件应该是自闭合的。
|
||||
|
||||
```html
|
||||
<!-- bad -->
|
||||
<my-component></my-component>
|
||||
|
||||
<!-- good -->
|
||||
<my-component />
|
||||
```
|
||||
|
||||
### Prop 名大小写
|
||||
|
||||
在声明 prop 的时候，其命名应该始终使用 camelCase，而在模板中应该始终使用 kebab-case。
|
||||
|
||||
```js
|
||||
// bad
|
||||
export default {
|
||||
props: {
|
||||
'greeting-text': String
|
||||
}
|
||||
};
|
||||
|
||||
// good
|
||||
export default {
|
||||
props: {
|
||||
greetingText: String
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```html
|
||||
<!-- bad -->
|
||||
<welcome-message greetingText="hi" />
|
||||
|
||||
<!-- good -->
|
||||
<welcome-message greeting-text="hi" />
|
||||
```
|
||||
|
||||
### Props 换行
|
||||
|
||||
多个 Props 的元素应该分多行撰写，每个 Props 一行，闭合标签单起一行。
|
||||
|
||||
```html
|
||||
<!-- bad -->
|
||||
<my-component foo="a" bar="b" baz="c" />
|
||||
|
||||
<!-- good -->
|
||||
<my-component
|
||||
foo="a"
|
||||
bar="b"
|
||||
baz="c"
|
||||
/>
|
||||
```
|
||||
|
||||
### 指令缩写
|
||||
|
||||
指令缩写，用 `:` 表示 `v-bind:` ，用 `@` 表示 `v-on:`
|
||||
|
||||
```html
|
||||
<!-- bad -->
|
||||
<input
|
||||
v-bind:value="value"
|
||||
v-on:input="onInput"
|
||||
>
|
||||
|
||||
<!-- good -->
|
||||
<input
|
||||
:value="value"
|
||||
@input="onInput"
|
||||
>
|
||||
```
|
||||
|
||||
### Props 顺序
|
||||
|
||||
标签的 Props 应该有统一的顺序，依次为指令、属性和事件。
|
||||
|
||||
```html
|
||||
<my-component
|
||||
v-if="if"
|
||||
v-show="show"
|
||||
v-model="value"
|
||||
ref="ref"
|
||||
:key="key"
|
||||
:text="text"
|
||||
@input="onInput"
|
||||
@change="onChange"
|
||||
/>
|
||||
```
|
||||
|
||||
### 组件选项的顺序
|
||||
|
||||
组件选项应该有统一的顺序。
|
||||
|
||||
```js
|
||||
export default {
|
||||
name: '',
|
||||
|
||||
mixins: [],
|
||||
|
||||
components: {},
|
||||
|
||||
props: {},
|
||||
|
||||
data() {},
|
||||
|
||||
computed: {},
|
||||
|
||||
watch: {},
|
||||
|
||||
created() {},
|
||||
|
||||
mounted() {},
|
||||
|
||||
destroyed() {},
|
||||
|
||||
methods: {}
|
||||
};
|
||||
```
|
||||
|
||||
### 组件选项中的空行
|
||||
|
||||
组件选项较多时，建议在属性之间添加空行。
|
||||
|
||||
```js
|
||||
export default {
|
||||
computed: {
|
||||
formattedValue() {
|
||||
// ...
|
||||
},
|
||||
|
||||
styles() {
|
||||
// ...
|
||||
}
|
||||
},
|
||||
|
||||
methods: {
|
||||
onInput() {
|
||||
// ...
|
||||
},
|
||||
|
||||
onChange() {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### 单文件组件顶级标签的顺序
|
||||
|
||||
单文件组件应该总是让顶级标签的顺序保持一致，且标签之间留有空行。
|
||||
|
||||
```html
|
||||
<template>
|
||||
...
|
||||
</template>
|
||||
|
||||
<script>
|
||||
/* ... */
|
||||
</script>
|
||||
|
||||
<style>
|
||||
/* ... */
|
||||
</style>
|
||||
```
|
||||
88
vant/docs/markdown/theme.en-US.md
Normal file
88
vant/docs/markdown/theme.en-US.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# Custom Theme
|
||||
|
||||
### Intro
|
||||
|
||||
Vant provides a set of default themes, if you want to custom the theme color or other styles, you can use the following methods:
|
||||
|
||||
### Less variables
|
||||
|
||||
Vant use [Less](http://lesscss.org/) as css preprocessor，you can modify less variables to custom theme.
|
||||
|
||||
There are some basic variables below, all available variables could be found in [var.less](https://github.com/youzan/vant/blob/dev/src/style/var.less)。
|
||||
|
||||
```less
|
||||
// Component Colors
|
||||
@text-color: #323233;
|
||||
@border-color: #ebedf0;
|
||||
@active-color: #f2f3f5;
|
||||
@background-color: #f7f8fa;
|
||||
@background-color-light: #fafafa;
|
||||
```
|
||||
|
||||
## How to custom theme
|
||||
|
||||
|
||||
### Step 1: import less file
|
||||
|
||||
First you should import the less source file to your project. you can use babel-plugin-import to automatically import or just manually import less file.
|
||||
|
||||
#### Automatically import style
|
||||
|
||||
Configure babel plugin in babel.config.js, if you are using babel6, please manually import less file.
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
'import',
|
||||
{
|
||||
libraryName: 'vant',
|
||||
libraryDirectory: 'es',
|
||||
// specify less file path
|
||||
style: name => `${name}/style/less`
|
||||
},
|
||||
'vant'
|
||||
]
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
#### Manually import style
|
||||
|
||||
```js
|
||||
// import all styles
|
||||
import 'vant/lib/index.less';
|
||||
|
||||
// import style of single component
|
||||
import 'vant/lib/button/style/less';
|
||||
```
|
||||
|
||||
### Step 2: modify less variables
|
||||
|
||||
Use [modifyVars](http://lesscss.org/usage/#using-less-in-the-browser-modify-variables) provided by less.js to modify less variables，webpack config for reference:
|
||||
|
||||
```js
|
||||
// webpack.config.js
|
||||
module.exports = {
|
||||
rules: [
|
||||
{
|
||||
test: /\.less$/,
|
||||
use: [
|
||||
// ...other loaders
|
||||
{
|
||||
loader: 'less-loader',
|
||||
options: {
|
||||
modifyVars: {
|
||||
// overide with less vars
|
||||
'text-color': '#111',
|
||||
'border-color': '#eee'
|
||||
// or override with less file
|
||||
'hack': `true; @import "your-less-file-path.less";`
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
};
|
||||
```
|
||||
91
vant/docs/markdown/theme.zh-CN.md
Normal file
91
vant/docs/markdown/theme.zh-CN.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# 定制主题
|
||||
|
||||
### 介绍
|
||||
|
||||
Vant 提供了一套默认主题，CSS 命名采用 BEM 的风格，方便使用者覆盖样式。如果你想完全替换主题色或者其他样式，可以使用下面提供的方法。
|
||||
|
||||
### 示例工程
|
||||
|
||||
我们提供了一个基于 Vue Cli 3 的示例工程，仓库地址为 [Vant Demo](https://github.com/youzan/vant-demo)，其中包含了定制主题的基本配置，可以作为参考。
|
||||
|
||||
### 样式变量
|
||||
|
||||
Vant 使用了 [Less](http://lesscss.org/) 对样式进行预处理，并内置了一些样式变量，通过替换样式变量即可定制你自己需要的主题。
|
||||
|
||||
下面是一些基本的样式变量，所有可用的颜色变量请参考 [配置文件](https://github.com/youzan/vant/blob/dev/src/style/var.less)。
|
||||
|
||||
```less
|
||||
// Component Colors
|
||||
@text-color: #323233;
|
||||
@border-color: #ebedf0;
|
||||
@active-color: #f2f3f5;
|
||||
@background-color: #f7f8fa;
|
||||
@background-color-light: #fafafa;
|
||||
```
|
||||
|
||||
## 定制方法
|
||||
|
||||
### 步骤一 引入样式源文件
|
||||
|
||||
定制主题时，需要引入组件对应的 Less 样式文件，支持按需引入和手动引入两种方式。
|
||||
|
||||
#### 按需引入样式（推荐）
|
||||
|
||||
在 babel.config.js 中配置按需引入样式源文件，注意 babel6 不支持按需引入样式，请手动引入样式
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
'import',
|
||||
{
|
||||
libraryName: 'vant',
|
||||
libraryDirectory: 'es',
|
||||
// 指定样式路径
|
||||
style: name => `${name}/style/less`
|
||||
},
|
||||
'vant'
|
||||
]
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
#### 手动引入样式
|
||||
|
||||
```js
|
||||
// 引入全部样式
|
||||
import 'vant/lib/index.less';
|
||||
|
||||
// 引入单个组件样式
|
||||
import 'vant/lib/button/style/less';
|
||||
```
|
||||
|
||||
### 步骤二 修改样式变量
|
||||
|
||||
使用 Less 提供的 [modifyVars](http://lesscss.org/usage/#using-less-in-the-browser-modify-variables) 即可对变量进行修改，下面是参考的 webpack 配置。
|
||||
|
||||
```js
|
||||
// webpack.config.js
|
||||
module.exports = {
|
||||
rules: [
|
||||
{
|
||||
test: /\.less$/,
|
||||
use: [
|
||||
// ...其他 loader 配置
|
||||
{
|
||||
loader: 'less-loader',
|
||||
options: {
|
||||
modifyVars: {
|
||||
// 直接覆盖变量
|
||||
'text-color': '#111',
|
||||
'border-color': '#eee'
|
||||
// 或者可以通过 less 文件覆盖（文件路径为绝对路径）
|
||||
'hack': `true; @import "your-less-file-path.less";`
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
};
|
||||
```
|
||||
Reference in New Issue
Block a user