doc: 完善readme

2025-04-05 19:41:45 +08:00 · 2017-02-08 14:37:15 +08:00 · 2017-02-08 14:37:15 +08:00 · 5ab2beab70
commit 5ab2beab70
parent e06289b393
1 changed files with 111 additions and 5 deletions
--- a/README.md
+++ b/README.md
@ -3,19 +3,125 @@
 </p>


-ZanUI Weapp是有赞移动端UI规范ZanUI的小程序现实版本。
+ZanUI for WeApp 为微信小程序量身设计
 ====

 ## 概述
-[ZanUI Weapp] 是一套用于微信小程序开发的基础UI组件库，由有赞官方提供，结合了微信的视觉规范，为用户提供更加统一的使用感知。包含 `btn`、`card`、`cell`、`icon`、`tab` 等各式元素
+[ZanUI WeApp] 是一套用于微信小程序开发的基础UI组件库，由有赞官方提供，结合了微信的视觉规范，为用户提供更加统一的使用感知。包含 `btn`、`card`、`cell`、`icon`、`tab` 等各式元素

-## 例子
+## 下载
 ``` bash
 git clone https://github.com/youzan/zanui-weapp.git
-cd zan
+cd zanui-weapp
 ```

-将 [ZanUI Weapp] 目录放入 微信Web开发者工具 中，可以预览各种组件的 Demo 和使用方法
+## 预览
+用[微信web开发者工具](https://mp.weixin.qq.com/debug/wxadoc/dev/devtools/download.html)打开项目目录
+
+<img src="https://img.yzcdn.cn/public_files/2017/02/08/a5e6445075826183659742cc6946c477.png" width="320" />
+
+## 使用
+
+首先引入样式文件，我们推荐在你的`app.wxss`直接引入`zanui-weapp/dist/index.wxss`。
+
+根据功能的不同，可以将组件大致的分为4类：
+
+1. 简单组件
+
+    如按钮组件，只要按照wxml结构写就好了
+
+    ~~~html
+    <!-- example/btn/index.html -->
+
+    <view class="zan-btn">按钮</view>
+    ~~~
+
+2. 复杂组件
+
+    如加载更多组件，需要先引入定义好的模版，然后给模版传递数据
+
+    ~~~html
+    <!-- example/loadmore/index.html -->
+
+    <!-- 引入组件模版 -->
+    <import src="path/to/zanui-weapp/dist/loadmore/index.wxml" />
+
+    <!-- 使用组件 -->
+    <template is="zan-loadmore" data="{{loading: true}}" />
+    ~~~
+
+3. 带事件回掉的组件
+
+    如数量选择组件，需要先引入模版，然后给模版传递数据
+
+    ~~~html
+    <!-- example/quantity/index.html -->
+
+    <import src="path/to/zanui-weapp/dist/quantity/index.wxml" />
+
+    <template is="zan-quantity" data="{{ ...quantity, componentId: 'customId' }}" />
+    ~~~
+
+    然后通过`Zan.Quantity`把相关回掉注入到页面中
+
+    ~~~js
+    // example/quantity/index.js
+
+    var Zan = require('path/to/zanui-weapp/dist/index');
+
+    Page(Object.assign({}, Zan.Quantity, {
+      data: {
+        quantity: {
+          quantity: 10,
+          min: 1,
+          max: 20
+        },
+      },
+
+      handleZanQuantityChange(e) {
+        // 如果页面有多个Quantity组件，则通过componentId来表示唯一
+        var compoenntId = e.componentId;
+        var quantity = e.quantity;
+
+        this.setData({
+          [`quantity.quantity`]: quantity
+        });
+      }
+    }));
+    ~~~
+
+4. API类组件
+
+    如Toast组件，需要先引入模版，并在页面上使用。
+
+    >> 注意`zanToast`这个数据也是通过`Zan.Toast`注入到页面的
+
+    ~~~html
+    <!-- example/toast/index.html -->
+
+    <import src="path/to/zanui-weapp/dist/toast/index.wxml" />
+
+    <view bindtap="showToast">showToast</view>
+
+    <template is="zan-toast" data="{{ zanToast }}"></template>
+    ~~~
+
+    将API注入到页面后，就可以通过`this`来直接调用相应的API了
+
+    ~~~js
+    <!-- example/toast/index.js -->
+
+    var Zan = require('path/to/zanui-weapp/dist/index');
+
+    Page(Object.assign({}, Zan.Toast, {
+      showToast() {
+        this.showZanToast('toast的内容');
+      }
+    }));
+
+    ~~~
+
+更多示例可以在项目的 `example`目录中查看

 ## 协议
 [MIT]