[improvement] 新增 Select 组件支持 form 中 submit 使用 (#104)

* support select form submit

* 增加使用示例 && 增加提示

example/pages/dashboard/config.js

@@ -81,7 +81,7 @@ export default {
         name: 'Toast 轻提示',
         path: '/pages/toast/index'
       }, {
-        name: 'Toptips 顶部提示',
+        name: 'TopTips 顶部提示',
         path: '/pages/toptips/index'
       }
     ]

example/pages/select/index.js

@@ -1,6 +1,6 @@
 var Zan = require('../../dist/index');
 
-Page(Object.assign({}, Zan.CheckLabel, {
+Page(Object.assign({}, Zan.Select, Zan.TopTips, {
 
   data: {
     items: [
@@ -18,7 +18,8 @@ Page(Object.assign({}, Zan.CheckLabel, {
 
     checked: {
       base: -1,
-      color: -1
+      color: -1,
+      form: -1
     },
 
     activeColor: '#4b0'
@@ -28,5 +29,10 @@ Page(Object.assign({}, Zan.CheckLabel, {
     this.setData({
       [`checked.${componentId}`]: value
     });
+  },
+
+  formSubmit(event) {
+    console.log('[zan:field:submit]', event.detail.value);
+    this.showZanTopTips(`选中的值为${event.detail.value.formtest}`);
   }
 }));

example/pages/select/index.wxml

@@ -1,4 +1,5 @@
 <import src="/dist/select/index.wxml" />
+<import src="/dist/toptips/index.wxml" />
 
 <view class="container">
 
@@ -17,4 +18,23 @@
       <template is="zan-select" data="{{ items, checkedValue: checked.color, activeColor, componentId: 'color' }}" ></template>
     </view>
   </view>
+
+  <view class="zan-panel-title">Form 表单中的select应用</view>
+  <form bindsubmit="formSubmit">
+    <view class="zan-panel">
+      <view>
+        <template
+          is="zan-select"
+          data="{{ items, checkedValue: checked.form, name: 'formtest', componentId: 'form' }}" ></template>
+      </view>
+    </view>
+
+    <view class="zan-btns">
+      <button
+        class="zan-btn zan-btn--primary"
+        formType="submit">提交数据</button>
+    </view>
+  </form>
 </view>
+
+<template is="zan-toptips" data="{{ zanTopTips }}"></template>

packages/index.js

@@ -1,13 +1,16 @@
 exports.Actionsheet = require('./actionsheet/index');
-exports.CheckLabel = require('./select/index');
 exports.Dialog = require('./dialog/index');
 exports.Field = require('./field/index');
 exports.NoticeBar = require('./noticebar/index');
+exports.Select = require('./select/index');
 exports.Stepper = require('./stepper/index');
 exports.Switch = require('./switch/index');
 exports.Tab = require('./tab/index');
 exports.Toast = require('./toast/index');
 exports.TopTips = require('./toptips/index');
 
+// 兼容老版本，在下次大版本发布时会被移除
+exports.CheckLabel = require('./select/index');
+
 const { extend } = require('./common/helper');
 exports.extend = extend;

packages/select/README.md

@@ -1,3 +1,68 @@
 ## Select 选择
 
-文档补充中
+### 使用指南
+在 app.wxss 中引入组件库所有样式
+```css
+@import "path/to/zanui-weapp/dist/index.wxss";
+```
+
+在需要使用的页面里引入组件库模板和脚本
+```html
+<import src="path/to/zanui-weapp/dist/select/index.wxml" />
+
+<template is="zan-select" data="{{ items, checkedValue: checked.base, componentId: 'base' }}" ></template>
+```
+```js
+const { extend, Select } = require('path/to/zanui-weapp/dist/index');
+
+// 在 Page 中混入 Select 里面声明的方法
+Page(extend({}, Select, {
+  // ...
+}));
+```
+
+### 代码演示
+#### 基础功能
+`Select` 组件通过传入的 items 对象控制显示，用 checkedValue 确认显示的高亮项目
+```html
+<template is="zan-select" data="{{ items, checkedValue: checked.base, componentId: 'base' }}" ></template>
+```
+
+当 Select 被点击时，可以在页面中注册 handleZanTabChange 方法来监听
+```js
+Page(extend({}, Select, {
+  handleZanSelectChange({ componentId, value }) {
+    // componentId 即为在模板中传入的 componentId
+    // 用于在一个页面上使用多个 Select 时，进行区分
+    // value 表示被选中项的 value
+  }
+}));
+```
+
+#### 具体参数
+| 参数       | 说明      | 类型       | 默认值       | 必须      |
+|-----------|-----------|-----------|-------------|-------------|
+| items | select 显示各个项的配置 | Array | - | |
+| checkedValue | 高亮的 item 的 value 值 | String | - | |
+| name | Select 的名字，作为 form 表单提交时数据的 key | String | - | |
+| activeColor | Select 高亮颜色 | String | #ff4444 | |
+| componentId | 用于区分页面多个 Select 组件 | String | - | |
+
+items 参数格式
+```js
+[
+  {
+    // 当前选项离左侧的距离
+    padding: 0,
+    // 当前选项的值，在被选中时，会在 handleZanSelectChange 中获取到
+    value: '1',
+    // 选项文案
+    name: '选项一',
+  },
+  {
+    padding: 0,
+    value: '2',
+    name: '选项二',
+  },
+]
+```

packages/select/index.wxml

@@ -1,5 +1,10 @@
 <template name="zan-select">
-  <radio-group class="zan-select__list" bindchange="_handleZanSelectChange" data-component-id="{{ componentId }}">
+  <radio-group
+    class="zan-select__list"
+    name="{{ name || componentId || '' }}"
+    bindchange="_handleZanSelectChange"
+    data-component-id="{{ componentId }}"
+  >
     <label wx:for="{{ items }}" wx:key="value">
       <view class="zan-cell">
         <radio class="zan-select__radio" value="{{ item.value }}" checked="{{ item.value === checkedValue }}"/>

packages/toptips/README.md

@@ -1,4 +1,4 @@
-## Toptips 顶部提示
+## TopTips 顶部提示
 
 ### 使用指南
 在 app.wxss 中引入组件库所有样式
@@ -14,10 +14,10 @@
 <template is="zan-toptips" data="{{ zanTopTips }}"></template>
 ```
 ```js
-const { Toptips, extend } = require('path/to/zanui-weapp/dist/index');
+const { TopTips, extend } = require('path/to/zanui-weapp/dist/index');
 
-// 在 Page 中混入 Toptips 里面声明的方法
-Page(extend({}, Toptips, {
+// 在 Page 中混入 TopTips 里面声明的方法
+Page(extend({}, TopTips, {
   // ...
 }));
 ```