[Doc] custom theme

2018-11-04 22:24:21 +08:00
parent df60f0be5e
commit 54a576d519
2 changed files with 152 additions and 65 deletions
@@ -2,50 +2,98 @@

 `Vant`提供了一套默认主题，CSS 命名采用 BEM 的风格，方便使用者覆盖样式。如果你想完全替换主题色或者其他样式，可以使用下面的方法：

-### 方案一. PostCSS 插件
-在项目中直接引入组件对应的 postcss 源代码，并通过 postcss 插件 [postcss-theme-variables](https://www.npmjs.com/package/postcss-theme-variables) 替换颜色变量，步骤如下：
+### 示例工程

-```javascript
-// 引入基础样式
-import 'vant/packages/style/base.css';
+我们提供了一个基于 Vue Cli 3 的示例工程，仓库地址为 [Vant Demo](https://github.com/youzan/vant-demo)，其中包含了定制主题的基本配置，可以作为参考。

-// 引入组件对应的样式
-import 'vant/packages/style/button/index.css';
-import 'vant/packages/style/checkbox/index.css';
+### 样式变量
+
+Vant 使用了 [Less](http://lesscss.org/) 对样式进行预处理，并内置了一些样式变量，通过替换样式变量即可定制你自己需要的主题。
+
+下面是一些基本的样式变量，所有可用的颜色变量请参考 [配置文件](https://github.com/youzan/vant/blob/dev/packages/style/var.less)。
+
+```less
+// color variables
+@black: #000;
+@white: #fff;
+@red: #f44;
+@blue: #1989fa;
+@orange: #ff976a;
+@orange-dark: #ed6a0c;
+@orange-light: #fffbe8;
+@green: #4b0;
+@gray: #c9c9c9;
+@gray-light: #e5e5e5;
+@gray-darker: #666;
+@gray-dark: #999;
+
+// default colors
+@text-color: #333;
+@border-color: #eee;
+@active-color: #e8e8e8;
+@background-color: #f8f8f8;
+@background-color-light: #fafafa;
 ```

-接着在 postcss.config.js 中引入所需的 postcss 插件，并根据项目需求配置颜色变量，所有可用的颜色变量请参考 [配置文件](https://github.com/youzan/vant/blob/dev/packages/style/var.less)
+### 定制方法

-```javascript
+定制主题分为两步：引入样式源文件和修改样式变量
+
+#### 步骤一. 引入样式源文件
+
+Vant 支持通过 babel 插件按需引入和手动引入两种方式，推荐使用按需引入的方式。
+
+```js
+// 在 babel.config.js 中配置按需引入样式源文件
 module.exports = {
  plugins: [
-    require('postcss-theme-variables')({
-      vars: {
-        red: '#F60',
-        gray: '#CCC',
-        blue: '#03A9F4'
+    [
+      'import',
+      {
+        libraryName: 'vant',
+        libraryDirectory: 'es',
+        // 指定样式路径
+        style: name => `${name}/style/less`
      },
-      prefix: '$'
-    }),
-    require('precss')(),
-    require('postcss-calc')(),
-    require('autoprefixer')({
-      browsers: ['Android >= 4.0', 'iOS >= 7']
-    })
+      'vant'
+    ]
  ]
 };
 ```

-### 方案二. 本地构建
-可以通过在本地构建 style 的方式生成所需的主题
+下面是手动引入的方法：

-```bash
-# 克隆仓库
-git clone git@github.com:youzan/vant.git
-cd packages/style
+```js
+// 手动引入组件的样式源文件
+import Button from 'vant/lib/button';
+import 'vant/lib/button/style/less';
 ```

-在本地 style 仓库中，修改 src/var.less 中的颜色变量，然后执行以下构建命令，即可生成对应的样式文件
-```bash
-npm run build
+#### 步骤二. 修改样式变量
+
+使用 less 提供的 [modifyVars](http://lesscss.org/usage/#using-less-in-the-browser-modify-variables) 即可对变量进行修改，下面是参考的 webpack 配置。
+
+```js
+// webpack.config.js
+module.exports = {
+  rules: [
+    {
+      test: /\.less$/,
+      use: [
+        // ...other loaders
+        {
+          loader: 'less-loader',
+          options: {
+            modifyVars: {
+              red: '#03a9f4',
+              blue: '#3eaf7c',
+              orange: '#f08d49',
+              'text-color': '#111'
+            }
+          }
+        }
+      ]
+    }
+  ]
+};
 ```