tencent cloud

腾讯云超级应用服务

Dokumentasi腾讯云超级应用服务小程序开发指南组件表单组件

表单组件

Download
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-01-30 22:22:22

button

功能说明：按钮。
参数及说明：
属性
类型
合法值及说明
默认值
必填
说明
size
string
default：默认大小
mini：小尺寸
default
否
按钮的大小
type
string
primary：绿色
default：白色
warn：红色
default
否
按钮的样式类型
plain
boolean
-
false
否
按钮是否镂空，背景色
disabled
boolean
-
false
否
是否禁用
loading
boolean
-
false
否
名称前是否带 loading 图标
form-type
string
submit：提交表单
reset：重置表单
-
否
用于 form 组件，单击分别会触发 form 组件的 submit/reset 事件
open-type
string
share：触发用户转发，默认分享到APP配置的渠道，也可以配置share-mode属性来指定分享渠道
getPhoneNumber：获取用户手机号码，可以从 bindgetphonenumber 回调中获取到用户手机号码
getEmailAddress：获取用户邮箱地址，可以从 bindgetemailaddress 回调中获取到用户邮箱地址
getUserInfo：获取用户信息，可以从 bindgetuserinfo 回调中获取到用户信息
openSetting：打开授权设置页
feedback：打开“意见反馈”页面，用户可提交反馈内容并上传日志
chooseAvatar：获取用户头像，可以从 bindchooseavatar 回调中获取到头像信息
-
否
Superapp开放能力
hover-class
string
-
button-hover
否
指定按钮按下去的样式类。当 hover-class="none"; 时，没有单击态效果
hover-start-time
number
-
20
否
按住后多久出现单击态，单位毫秒
hover-stay-time
number
-
70
否
手指松开后单击态保留时间，单位毫秒
lang
string
en：英文
zh_CN：简体中文
zh_TW：繁体中文
en
否
指定返回用户信息的语言
bindgetuserinfo
eventhandle
-
-
否
用户点击该按钮时，会返回获取到的用户信息，回调的 detail 数据与 wx.getUserInfo 返回的一致，open-type="getUserInfo"时有效
bindgetphonenumber
eventhandle
-
-
否
手机号快速验证回调，open-type=getPhoneNumber 时有效。注意：在触发 bindgetphonenumber 回调后应立即隐藏手机号按钮组件，或置为 disabled 状态，避免用户重复授权手机号产生额外费用。
bindopensetting
eventhandle
-
-
否
在打开授权设置页后回调，open-type=openSetting时有效
注意：
目前设置了 form-type 的 button 只会对当前组件中的 form 有效。因而，将 button 封装在自定义组件中，而 form 在自定义组件外，将会使这个 button 的 form-type 失效。
设置open-type为share的button，若设置share-mode属性来指定多分享渠道，所设置的渠道需要APP自定义分享渠道，否则所设置的渠道失效不显示。
示例代码：
WXML
JAVASCRIPT
WXSS
<view class="page-body">
  <view class="btn-area" id="buttonContainer">
    <button type="primary">页面主操作 Normal</button>
    <button type="primary" loading="true">页面主操作 Loading</button>
    <button type="primary" disabled="true">页面主操作 Disabled</button>

    <button type="default">页面次要操作 Normal</button>
    <button type="default" disabled="true">页面次要操作 Disabled</button>

    <button type="warn">警告类操作 Normal</button>
    <button type="warn" disabled="true">警告类操作 Disabled</button>

    <view class="button-sp-area">
      <button type="primary" plain="true">按钮</button>
      <button type="primary" disabled="true" plain="true">不可点击的按钮</button>

      <button type="default" plain="true">按钮</button>
      <button type="default" disabled="true" plain="true">按钮</button>

      <button class="mini-btn" type="primary" size="mini">按钮</button>
      <button class="mini-btn" type="default" size="mini">按钮</button>
      <button class="mini-btn" type="warn" size="mini">按钮</button>
    </view>
    
    <button open-type="share">分享</button>
    <button open-type="share" share-mode = "{{shareMode}}">分享按钮</button>
    
  </view>
</view>
const types = ['default', 'primary', 'warn']
const pageObject = {
  data: {
    defaultSize: 'default',
    primarySize: 'default',
    warnSize: 'default',
    disabled: false,
    plain: false,
    loading: false,
    shareMode: ['whatsapp','twitter']
  },

  onShareAppMessage() {
    return {
      title: 'button',
      path: 'page/component/pages/button/button'
    }
  },

  setDisabled() {
    this.setData({
      disabled: !this.data.disabled
    })
  },

  setPlain() {
    this.setData({
      plain: !this.data.plain
    })
  },

  setLoading() {
    this.setData({
      loading: !this.data.loading
    })
  },
  
  handleContact(e) {
    console.log(e.detail)
  },

  handleGetPhoneNumber(e) {
    console.log(e.detail)
  },

  handleGetUserInfo(e) {
    console.log(e.detail)
  },

  handleOpenSetting(e) {
    console.log(e.detail.authSetting)
  },

  handleGetUserInfo(e) {
    console.log(e.detail.userInfo)
  }
}

for (let i = 0; i < types.length; ++i) {
  (function (type) {
    pageObject[type] = function () {
      const key = type + 'Size'
      const changedData = {}
      changedData[key] =
        this.data[key] === 'default' ? 'mini' : 'default'
      this.setData(changedData)
    }
  }(types[i]))
}

Page(pageObject)
button{
  margin-top: 30rpx;
  margin-bottom: 30rpx;
}
.button-sp-area{
  margin: 0 auto;
  width: 60%;
}
.mini-btn{
  margin-right: 10rpx;
}


checkbox

功能说明：多选项目。
参数及说明：
属性
类型
默认值
必填
说明
value
string
-
否
checkbox 标识，选中时触发 checkbox-group的 change 事件，并携带 checkbox 的 value
disabled
boolean
false
否
是否禁用
checked
boolean
false
否
当前是否选中，可用来设置默认选中
color
string
#09BB07
否
checkbox 的颜色，同 css 的 color
示例代码：
WXML
JAVASCRIPT
<view class="container">
  <view class="page-body">
    <view class="page-section page-section-gap">
      <view class="page-section-title">默认样式</view>
      <label class="checkbox">
        <checkbox value="cb" checked="true"/>选中
      </label>
      <label class="checkbox">
        <checkbox value="cb" />未选中
      </label>
    </view>
  
    <view class="page-section">
      <view class="page-section-title">推荐展示样式</view>
      <view class="weui-cells weui-cells_after-title">
        <checkbox-group bindchange="checkboxChange">
          <label class="weui-cell weui-check__label" wx:for="{{items}}" wx:key="{{item.value}}">
            <view class="weui-cell__hd">
              <checkbox value="{{item.value}}" checked="{{item.checked}}"/>
            </view>
            <view class="weui-cell__bd">{{item.name}}</view>
          </label>
        </checkbox-group>
      </view>
    </view>
  </view>
  
</view>
Page({
  onShareAppMessage() {
    return {
      title: 'checkbox',
      path: 'page/component/pages/checkbox/checkbox'
    }
  },

  data: {
    items: [
      {value: 'USA', name: '美国'},
      {value: 'CHN', name: '中国', checked: 'true'},
      {value: 'BRA', name: '巴西'},
      {value: 'JPN', name: '日本'},
      {value: 'ENG', name: '英国'},
      {value: 'FRA', name: '法国'}
    ]
  },

  checkboxChange(e) {
    console.log('checkbox发生change事件，携带value值为：', e.detail.value)

    const items = this.data.items
    const values = e.detail.value
    for (let i = 0, lenI = items.length; i < lenI; ++i) {
      items[i].checked = false

      for (let j = 0, lenJ = values.length; j < lenJ; ++j) {
        if (items[i].value === values[j]) {
          items[i].checked = true
          break
        }
      }
    }

    this.setData({
      items
    })
  }
})


checkbox-group

功能描述：多项选择器，内部由多个 checkbox组成。
参数及说明：
属性
类型
默认值
必填
说明
bindchange
eventhandle
-
否
checkbox-group 中选中项发生改变时触发 change 事件，detail = {value:[选中的 checkbox 的 value 的数组]}

editor

功能说明：富文本编辑器，可以对图片、文字进行编辑。
编辑器导出内容支持带标签的html和纯文本的text，编辑器内部采用delta格式进行存储。
通过setContents接口设置内容时，解析插入的html可能会由于一些非法标签导致解析错误，建议开发者在小程序内使用时通过delta进行插入。
富文本组件内部引入了一些基本的样式使得内容可以正确的展示，开发时可以进行覆盖。
图片控件仅初始化时设置有效。
相关 api：EditorContext
参数及说明：
属性
类型
默认值
必填
说明
read-only
boolean
false
否
设置编辑器为只读
placeholder
string
-
否
提示信息
show-img-size
boolean
false
否
点击图片时显示图片大小控件
show-img-toolbar
boolean
false
否
点击图片时显示工具栏控件
show-img-resize
boolean
false
否
点击图片时显示修改尺寸控件
bindready
eventhandle
-
否
编辑器初始化完成时触发
bindfocus
eventhandle
-
否
编辑器聚焦时触发，event.detail = {html, text, delta}
bindblur
eventhandle
-
否
编辑器失去焦点时触发，detail = {html, text, delta}
bindinput
eventhandle
-
否
编辑器内容改变时触发，detail = {html, text, delta}
bindstatuschange
eventhandle
-
否
通过 Context 方法改变编辑器内样式时触发，返回选区已设置的样式
编辑器内支持部分HTML标签和内联样式，不支持class和id
支持的标签
不满足的标签会被忽略，例如<div>会被转换为<p>储存。
类型
节点
行内元素
<span> <strong> <b> <ins> <em> <i> <u> <a> <del> <s> <sub> <sup> <img>
块级元素
<p> <h1> <h2> <h3> <h4> <h5> <h6> <hr> <ol> <ul> <li>
支持的内联样式
内联样式仅能设置在行内元素或块级元素上，不能同时设置。例如font-size归类为行内元素属性，在p标签上设置是无效的。
类型
样式
块级样式
text-align 、direction 、margin 、margin-top 、margin-left 、margin-right 、margin-bottom padding 、padding-top 、padding-left 、padding-right 、padding-bottom 、line-height 、text-indent
行内样式
font 、font-size 、font-style 、font-variant 、font-weight 、font-family 、letter-spacing 、text-decoration 、color 、background-color
注意：
插入的 html 中事件绑定会被移除。
粘贴时仅纯文本内容会被拷贝进编辑器。
插入 html 到编辑器内时，编辑器会删除一些不必要的标签，以保证内容的统一。例如<p><span>xxx</span></p>会改写为<p>xxx</p>。
编辑器聚焦时页面会被上推，系统行为以保证编辑区可见。

form

功能说明：表单，将组件内的用户输入的 slider、picker ，checkbox，radio，switch，input 提交。
当单击 form 表单中 form-type 为 submit 的 button 组件时，会将表单组件中的 value 值进行提交，需要在表单组件中加上 name 来作为 key。
参数及说明：
属性
类型
默认值
必填
说明
bindsubmit
eventhandle
-
否
携带 form 中的数据触发 submit 事件，event.detail = {value : {'name': 'value'} , formId: ''}
bindreset
eventhandle
-
否
表单重置时会触发 reset 事件
示例代码：
WXML
JAVASCRIPT
<view class="container">
  <view class="page-body">
    <form catchsubmit="formSubmit" catchreset="formReset">
      <view class="page-section page-section-gap">
        <view class="page-section-title">switch</view>
        <switch name="switch"/>
      </view>

      <view class="page-section page-section-gap">
        <view class="page-section-title">radio</view>
        <radio-group name="radio">
          <label><radio value="radio1"/>选项一</label>
          <label><radio value="radio2"/>选项二</label>
        </radio-group>
      </view>

      <view class="page-section page-section-gap">
        <view class="page-section-title">checkbox</view>
        <checkbox-group name="checkbox">
          <label><checkbox value="checkbox1"/>选项一</label>
          <label><checkbox value="checkbox2"/>选项二</label>
        </checkbox-group>
      </view>

      <view class="page-section page-section-gap">
        <view class="page-section-title">slider</view>
        <slider value="50" name="slider" show-value ></slider>
      </view>

      <view class="page-section">
        <view class="page-section-title">input</view>
        <view class="weui-cells weui-cells_after-title">
          <view class="weui-cell weui-cell_input">
            <view class="weui-cell__bd" style="margin: 30rpx 0" >
              <input class="weui-input" name="input" placeholder="这是一个输入框" />
            </view>
          </view>
        </view>
      </view>

      <view class="btn-area">
        <button style="margin: 30rpx 0" type="primary" formType="submit">Submit</button>
        <button style="margin: 30rpx 0" formType="reset">Reset</button>
      </view>
    </form>
  </view>
</view>
Page({
  onShareAppMessage() {
    return {
      title: 'form',
      path: 'page/component/pages/form/form'
    }
  },

  data: {
    pickerHidden: true,
    chosen: ''
  },

  pickerConfirm(e) {
    this.setData({
      pickerHidden: true
    })
    this.setData({
      chosen: e.detail.value
    })
  },

  pickerCancel() {
    this.setData({
      pickerHidden: true
    })
  },

  pickerShow() {
    this.setData({
      pickerHidden: false
    })
  },

  formSubmit(e) {
    console.log('form发生了submit事件，携带数据为：', e.detail.value)
  },

  formReset(e) {
    console.log('form发生了reset事件，携带数据为：', e.detail.value)
    this.setData({
      chosen: ''
    })
  }
})


input

功能说明：输入框，该组件是 原生组件，使用时请注意相关限制。
参数及说明：
属性
类型
合法值及说明
默认值
必填
说明
value
string
-
-
是
输入框的初始内容
type
string
text：文本输入键盘
number：数字输入键盘
idcard：身份证输入键盘
digit：带小数点的数字键盘
nickname：昵称输入键盘
text
否
input 的类型
password
boolean
-
false
否
是否是密码类型
placeholder
string
-

是
输入框为空时占位符
placeholder-style
string
-
-
是
指定 placeholder 的样式
placeholder-class
string
-
input-placeholder
否
指定 placeholder 的样式类
disabled
boolean
-
false
否
是否禁用
maxlength
number
-
140
否
最大输入长度，设置为 -1 的时候不限制最大长度
cursor-spacing
number
-
0
否
指定光标与键盘的距离，取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离
auto-focus
boolean
-
false
否
(即将废弃，请直接使用 focus )自动聚焦，拉起键盘
focus
boolean
-
false
否
获取焦点
confirm-type
string
send：右下角按钮为“发送”
search：右下角按钮为“搜索”
next：右下角按钮为“下一个”
go：右下角按钮为“前往”
done：右下角按钮为“完成”
done
否
设置键盘右下角按钮的文字，仅在type='text'时生效
confirm-hold
boolean
-
false
否
点击键盘右下角按钮时是否保持键盘不收起
cursor
number
-
-
是
指定focus时的光标位置
selection-start
number
-
-1
否
光标起始位置，自动聚集时有效，需与selection-end搭配使用
selection-end
number
-
-1
否
光标结束位置，自动聚集时有效，需与selection-start搭配使用
adjust-position
boolean
-
true
否
键盘弹起时，是否自动上推页面
hold-keyboard
boolean
-
false
否
focus时，点击页面的时候不收起键盘
bindinput
eventhandle
-
-
是
键盘输入时触发，event.detail = {value, cursor, keyCode}，keyCode 为键值，处理函数可以直接 return 一个字符串，将替换输入框的内容。
bindfocus
eventhandle
-
-
是
输入框聚焦时触发，event.detail = { value, height }，height 为键盘高度
bindblur
eventhandle
-
-
是
输入框失去焦点时触发，event.detail = { value, encryptedValue, encryptError }
bindconfirm
eventhandle
-
-
是
单击完成按钮时触发，event.detail = { value }
bindkeyboardheightchange
eventhandle
-
-
是
键盘高度发生变化的时候触发此事件，event.detail = {height: height, duration: duration}
注意：
confirm-type的最终表现与手机输入法本身的实现有关，部分安卓系统输入法和第三方输入法可能不支持或不完全支持。
input 组件是一个原生组件，字体是系统字体，所以无法设置 font-family。
在 input 聚焦期间，避免使用 css 动画。
对于将 input 封装在自定义组件中、而 form 在自定义组件外的情况， form 将不能获得这个自定义组件中 input 的值。
键盘高度发生变化，keyboardheightchange事件可能会多次触发，开发者对于相同的height值应该忽略掉。
示例代码：
WXML
JAVASCRIPT
<view class="page-body">
  <view class="page-section">
    <view class="weui-cells__title">可以自动聚焦的input</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" auto-focus placeholder="将会获取焦点"/>
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">控制最大输入长度的input</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" maxlength="10" placeholder="最大输入长度为10" />
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">实时获取输入值：{{inputValue}}</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input"  maxlength="10" bindinput="bindKeyInput" placeholder="输入同步到view中"/>
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">控制输入的input</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input"  bindinput="bindReplaceInput" placeholder="连续的两个1会变成2" />
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">控制键盘的input</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input"  bindinput="bindHideKeyboard" placeholder="输入123自动收起键盘" />
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">数字输入的input</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" type="number" placeholder="这是一个数字输入框" />
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">密码输入的input</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" password type="text" placeholder="这是一个密码输入框" />
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">带小数点的input</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" type="digit" placeholder="带小数点的数字键盘"/>
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">身份证输入的input</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" type="idcard" placeholder="身份证输入键盘" />
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">控制占位符颜色的input</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" placeholder-style="color:#F76260" placeholder="占位符字体是红色的" />
      </view>
    </view>
  </view>
</view>
Page({
  data: {
    focus: false,
    inputValue: ''
  },
  bindKeyInput: function (e) {
    this.setData({
      inputValue: e.detail.value
    })
  },
  bindReplaceInput: function (e) {
    var value = e.detail.value
    var pos = e.detail.cursor
    var left
    if (pos !== -1) {
      // 光标在中间
      left = e.detail.value.slice(0, pos)
      // 计算光标的位置
      pos = left.replace(/11/g, '2').length
    }

    // 直接返回对象，可以对输入进行过滤处理，同时可以控制光标的位置
    return {
      value: value.replace(/11/g, '2'),
      cursor: pos
    }

    // 或者直接返回字符串,光标在最后边
    // return value.replace(/11/g,'2'),
  },
  bindHideKeyboard: function (e) {
    if (e.detail.value === '123') {
      // 收起键盘
      wx.hideKeyboard()
    }
  }
})


label

功能说明：用来改进表单组件的可用性。
使用 for 属性找到对应的 id，或者将控件放在该标签下，当单击时，就会触发对应的控件。 for 优先级高于内部控件，内部有多个控件的时候默认触发第一个控件。目前可以绑定的控件有：button，checkbox，radio，switch，input。
参数及说明：
属性
类型
默认值
必填
说明
for
string
-
否
绑定控件的 id
示例代码：
WXML
JAVASCRIPT
WXSS
<view class="container">
  <view class="page-body">
    <view class="page-section page-section-gap">
      <view class="page-section-title">表单组件在label内</view>
      <checkbox-group class="group" bindchange="checkboxChange">
        <view class="label-1" wx:for="{{checkboxItems}}">
          <label>
            <checkbox value="{{item.name}}" checked="{{item.checked}}"></checkbox>
            <text class="label-1-text">{{item.value}}</text>
          </label>
        </view>
      </checkbox-group>
    </view>

    <view class="page-section page-section-gap">
      <view class="page-section-title">label用for标识表单组件</view>
      <radio-group class="group" bindchange="radioChange">
        <view class="label-2" wx:for="{{radioItems}}">
          <radio id="{{item.name}}" value="{{item.name}}" checked="{{item.checked}}"></radio>
          <label class="label-2-text" for="{{item.name}}"><text>{{item.name}}</text></label>
        </view>
      </radio-group>
    </view>

    <view class="page-section page-section-gap">
      <view class="page-section-title">label内有多个时选中第一个</view>
      <label class="label-3">
        <checkbox class="checkbox-3">选项一</checkbox>
        <checkbox class="checkbox-3">选项二</checkbox>
        <view class="label-3-text">点击该label下的文字默认选中第一个checkbox</view>
      </label>
    </view>
  </view>
</view>
Page({
  onShareAppMessage() {
    return {
      title: 'label',
      path: 'page/component/pages/label/label'
    }
  },

  data: {
    checkboxItems: [
      {name: 'USA', value: '美国'},
      {name: 'CHN', value: '中国', checked: 'true'}
    ],
    radioItems: [
      {name: 'USA', value: '美国'},
      {name: 'CHN', value: '中国', checked: 'true'}
    ],
    hidden: false
  },

  checkboxChange(e) {
    const checked = e.detail.value
    const changed = {}
    for (let i = 0; i < this.data.checkboxItems.length; i++) {
      if (checked.indexOf(this.data.checkboxItems[i].name) !== -1) {
        changed['checkboxItems[' + i + '].checked'] = true
      } else {
        changed['checkboxItems[' + i + '].checked'] = false
      }
    }
    this.setData(changed)
  },

  radioChange(e) {
    const checked = e.detail.value
    const changed = {}
    for (let i = 0; i < this.data.radioItems.length; i++) {
      if (checked.indexOf(this.data.radioItems[i].name) !== -1) {
        changed['radioItems[' + i + '].checked'] = true
      } else {
        changed['radioItems[' + i + '].checked'] = false
      }
    }
    this.setData(changed)
  },

  tapEvent() {
    console.log('按钮被点击')
  }
})
.label-1, .label-2{
  margin: 30rpx 0;
}
.label-3-text{
  color: #576B95;
  font-size: 28rpx;
}
.checkbox-3{
  display: block;
  margin: 30rpx 0;
}


picker

功能描述：从底部弹起的滚动选择器。
参数及说明：
属性
类型
合法值及说明
默认值
必填
说明
mode
string
selector：普通选择器
multiSelector：多列选择器
time：时间选择器
date：日期选择器
region：省市区选择器
selector
否
选择器类型
disabled
boolean
-
false
否
是否禁用
bindcancel
eventhandle
-
-
否
取消选择时触发
除了上述通用的属性，对于不同的 mode，picker拥有不同的属性。

普通选择器：mode = selector

属性名
类型
默认值
说明
range
array/object array
[]
mode 为 selector 或 multiSelector 时，range 有效
range-key
string
-
当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
value
number
0
表示选择了 range 中的第几个（下标从0开始）
bindchange
eventhandle
-
value 改变时触发 change 事件，event.detail = {value}

多列选择器：mode = multiSelector

属性名
类型
默认值
说明
range
array/object array
[]
mode 为 selector 或 multiSelector 时，range 有效
range-key
string
-
当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
value
array
[]
表示选择了 range 中的第几个（下标从0开始）
bindchange
eventhandle
-
value 改变时触发 change 事件，event.detail = {value}
bindcolumnchange
eventhandle
-
列改变时触发

时间选择器：mode = time

属性名
类型
默认值
说明
value
string
-
表示选中的时间，格式为"hh:mm"
start
string
-
表示有效时间范围的开始，字符串格式为"hh:mm"
end
string
-
表示有效时间范围的结束，字符串格式为"hh:mm"
bindchange
eventhandle
-
value 改变时触发 change 事件，event.detail = {value}

日期选择器：mode = date

属性名
类型
有效值及说明
默认值
说明
value
string
-
当天
表示选中的日期，格式为"YYYY-MM-DD"
start
string
-
-
表示有效日期范围的开始，字符串格式为"YYYY-MM-DD"
end
string
-
-
表示有效日期范围的结束，字符串格式为"YYYY-MM-DD"
fields
string
year：选择器粒度为年
month：选择器粒度为月份
day：选择器粒度为天
day
有效值 year,month,day，表示选择器的粒度
bindchange
eventhandle
-
-
value 改变时触发 change 事件，event.detail = {value}

省市区选择器：mode = region

属性名
类型
默认值
说明
value
Array
[]
表示选中的省市区，默认选中每一列的第一个值
custom-item
string
-
可为每一列的顶部添加一个自定义的项
bindchange
evenhandle
-
value 改变时触发 change 事件，event.detail = {value: value, code: code, postcode: postcode}，其中字段 code 是统计用区划代码，postcode 是邮政编码
示例代码：
WXML
JAVASCRIPT
<view class="section">
  <view class="section__title">普通选择器</view>
  <picker bindchange="bindPickerChange" value="{{index}}" range="{{array}}">
    <view class="picker">
      当前选择：{{array[index]}}
    </view>
  </picker>
</view>
<view class="section">
  <view class="section__title">多列选择器</view>
  <picker mode="multiSelector" bindchange="bindMultiPickerChange" bindcolumnchange="bindMultiPickerColumnChange" value="{{multiIndex}}" range="{{multiArray}}">
    <view class="picker">
      当前选择：{{multiArray[0][multiIndex[0]]}}，{{multiArray[1][multiIndex[1]]}}，{{multiArray[2][multiIndex[2]]}}
    </view>
  </picker>
</view>
<view class="section">
  <view class="section__title">时间选择器</view>
  <picker mode="time" value="{{time}}" start="09:01" end="21:01" bindchange="bindTimeChange">
    <view class="picker">
      当前选择: {{time}}
    </view>
  </picker>
</view>

<view class="section">
  <view class="section__title">日期选择器</view>
  <picker mode="date" value="{{date}}" start="2015-09-01" end="2017-09-01" bindchange="bindDateChange">
    <view class="picker">
      当前选择: {{date}}
    </view>
  </picker>
</view>
<view class="section">
  <view class="section__title">省市区选择器</view>
  <picker mode="region" bindchange="bindRegionChange" value="{{region}}" custom-item="{{customItem}}">
    <view class="picker">
      当前选择：{{region[0]}}，{{region[1]}}，{{region[2]}}
    </view>
  </picker>
</view>
Page({
  data: {
    array: ['美国', '中国', '巴西', '日本'],
    objectArray: [
      {
        id: 0,
        name: '美国'
      },
      {
        id: 1,
        name: '中国'
      },
      {
        id: 2,
        name: '巴西'
      },
      {
        id: 3,
        name: '日本'
      }
    ],
    index: 0,
    multiArray: [['无脊柱动物', '脊柱动物'], ['扁性动物', '线形动物', '环节动物', '软体动物', '节肢动物'], ['猪肉绦虫', '吸血虫']],
    objectMultiArray: [
      [
        {
          id: 0,
          name: '无脊柱动物'
        },
        {
          id: 1,
          name: '脊柱动物'
        }
      ], [
        {
          id: 0,
          name: '扁性动物'
        },
        {
          id: 1,
          name: '线形动物'
        },
        {
          id: 2,
          name: '环节动物'
        },
        {
          id: 3,
          name: '软体动物'
        },
        {
          id: 4,
          name: '节肢动物'
        }
      ], [
        {
          id: 0,
          name: '猪肉绦虫'
        },
        {
          id: 1,
          name: '吸血虫'
        }
      ]
    ],
    multiIndex: [0, 0, 0],
    date: '2016-09-01',
    time: '12:01',
    region: ['广东省', '广州市', '海珠区'],
    customItem: '全部'
  },
  bindPickerChange: function(e) {
    console.log('picker发送选择改变，携带值为', e.detail.value)
    this.setData({
      index: e.detail.value
    })
  },
  bindMultiPickerChange: function (e) {
    console.log('picker发送选择改变，携带值为', e.detail.value)
    this.setData({
      multiIndex: e.detail.value
    })
  },
  bindMultiPickerColumnChange: function (e) {
    console.log('修改的列为', e.detail.column, '，值为', e.detail.value);
    var data = {
      multiArray: this.data.multiArray,
      multiIndex: this.data.multiIndex
    };
    data.multiIndex[e.detail.column] = e.detail.value;
    switch (e.detail.column) {
      case 0:
        switch (data.multiIndex[0]) {
          case 0:
            data.multiArray[1] = ['扁性动物', '线形动物', '环节动物', '软体动物', '节肢动物'];
            data.multiArray[2] = ['猪肉绦虫', '吸血虫'];
            break;
          case 1:
            data.multiArray[1] = ['鱼', '两栖动物', '爬行动物'];
            data.multiArray[2] = ['鲫鱼', '带鱼'];
            break;
        }
        data.multiIndex[1] = 0;
        data.multiIndex[2] = 0;
        break;
      case 1:
        switch (data.multiIndex[0]) {
          case 0:
            switch (data.multiIndex[1]) {
              case 0:
                data.multiArray[2] = ['猪肉绦虫', '吸血虫'];
                break;
              case 1:
                data.multiArray[2] = ['蛔虫'];
                break;
              case 2:
                data.multiArray[2] = ['蚂蚁', '蚂蟥'];
                break;
              case 3:
                data.multiArray[2] = ['河蚌', '蜗牛', '蛞蝓'];
                break;
              case 4:
                data.multiArray[2] = ['昆虫', '甲壳动物', '蛛形动物', '多足动物'];
                break;
            }
            break;
          case 1:
            switch (data.multiIndex[1]) {
              case 0:
                data.multiArray[2] = ['鲫鱼', '带鱼'];
                break;
              case 1:
                data.multiArray[2] = ['青蛙', '娃娃鱼'];
                break;
              case 2:
                data.multiArray[2] = ['蜥蜴', '龟', '壁虎'];
                break;
            }
            break;
        }
        data.multiIndex[2] = 0;
        break;
    }
    console.log(data.multiIndex);
    this.setData(data);
  },
  bindDateChange: function(e) {
    console.log('picker发送选择改变，携带值为', e.detail.value)
    this.setData({
      date: e.detail.value
    })
  },
  bindTimeChange: function(e) {
    console.log('picker发送选择改变，携带值为', e.detail.value)
    this.setData({
      time: e.detail.value
    })
  },
  bindRegionChange: function (e) {
    console.log('picker发送选择改变，携带值为', e.detail.value)
    this.setData({
      region: e.detail.value
    })
  }
})


picker-view

功能说明：嵌入页面的滚动选择器。其中只可放置picker-view-column组件，其它节点不会显示。
参数及说明：
属性
类型
默认值
必填
说明
value
Array.<number>
-
否
数组中的数字依次表示 picker-view 内的 picker-view-column 选择的第几项（下标从 0 开始），数字大于 picker-view-column 可选项长度时，选择最后一项。
mask-class
string
-
否
设置蒙层的类名
indicator-style
string
-
否
设置选择器中间选中框的样式
bindchange
eventhandle
-
否
滚动选择时触发 change 事件，event.detail = {value}；value为数组，表示 picker-view 内的 picker-view-column 当前选择的是第几项（下标从 0 开始）
bindpickstart
eventhandle
-
否
当滚动选择开始时候触发事件
bindpickend
eventhandle
-
否
当滚动选择结束时候触发事件
indicator-class
string
-
否
设置选择器中间选中框的类名
mask-style
string
-
否
设置蒙层的样式
immediate-change
boolean
false
否
是否在手指松开时立即触发 change 事件。若不开启则会在滚动动画结束后触发 change 事件
示例代码：
WXML
JAVASCRIPT
<view class="container">
  <view class="page-body">
    <view class="selected-date">{{year}}年{{month}}月{{day}}日{{isDaytime ? "白天" : "夜晚"}}</view>
    <picker-view indicator-style="height: 50px;" style="width: 100%; height: 300px;" value="{{value}}" bindchange="bindChange">
      <picker-view-column>
        <view wx:for="{{years}}" wx:key="{{years}}" style="line-height: 50px; text-align: center;">{{item}}年</view>
      </picker-view-column>
      <picker-view-column>
        <view wx:for="{{months}}" wx:key="{{months}}" style="line-height: 50px; text-align: center;">{{item}}月</view>
      </picker-view-column>
      <picker-view-column>
        <view wx:for="{{days}}" wx:key="{{days}}" style="line-height: 50px; text-align: center;">{{item}}日</view>
      </picker-view-column>
      <picker-view-column>
        <view class="icon-container">
          <image class="picker-icon" src="../lib/daytime.png" />
        </view>
        <view class="icon-container">
          <image class="picker-icon" src="../lib/night.png" />
        </view>
      </picker-view-column>
    </picker-view>
  </view>

</view>
const date = new Date()
const years = []
const months = []
const days = []

for (let i = 1990; i <= date.getFullYear(); i++) {
  years.push(i)
}

for (let i = 1; i <= 12; i++) {
  months.push(i)
}

for (let i = 1; i <= 31; i++) {
  days.push(i)
}

Page({
  onShareAppMessage() {
    return {
      title: 'picker-view',
      path: 'page/component/pages/picker-view/picker-view'
    }
  },

  data: {
    years,
    year: date.getFullYear(),
    months,
    month: 2,
    days,
    day: 2,
    value: [9999, 1, 1],
    isDaytime: true,
  },

  bindChange(e) {
    const val = e.detail.value
    this.setData({
      year: this.data.years[val[0]],
      month: this.data.months[val[1]],
      day: this.data.days[val[2]],
      isDaytime: !val[3]
    })
  }
})


picker-view-column

功能说明：滚动选择器子项。仅可放置于picker-view中，其子节点的高度会自动设置成与picker-view的选中框的高度一致。

radio

功能说明：单选项目。
参数及说明
属性
类型
默认值
必填
说明
value
string
-
否
radio 标识。当该 radio 选中时，radio-group 的 change 事件会携带 radio 的 value
checked
boolean
false
否
当前是否选中
disabled
boolean
false
否
是否禁用
color
string
#09BB07
否
radio 的颜色，同 css 的 color
示例代码：
WXML
JAVASCRIPT
<view class="page-body">
  <view class="page-section">
    <view class="page-section-title">默认样式</view>
    <label class="radio">
      <radio value="r1" checked="true"/>选中
    </label>
    <label class="radio">
      <radio value="r2" />未选中
    </label>
  </view>


  <view class="page-section">
    <view class="page-section-title">推荐展示样式</view>
    <view class="weui-cells weui-cells_after-title">
      <radio-group bindchange="radioChange">
        <label class="weui-cell weui-check__label" wx:for="{{items}}" wx:key="{{item.value}}">

          <view class="weui-cell__hd">
            <radio value="{{item.value}}" checked="true"/>
          </view>
          <view class="weui-cell__bd">{{item.name}}</view>
        </label>
      </radio-group>
    </view>
  </view>
</view>
Page({
  onShareAppMessage() {
    return {
      title: 'radio',
      path: 'page/component/pages/radio/radio'
    }
  },

  data: {
    items: [
      {value: 'USA', name: '美国'},
      {value: 'CHN', name: '中国', checked: 'true'},
      {value: 'BRA', name: '巴西'},
      {value: 'JPN', name: '日本'},
      {value: 'ENG', name: '英国'},
      {value: 'FRA', name: '法国'},
    ]
  },

  radioChange(e) {
    console.log('radio发生change事件，携带value值为：', e.detail.value)

    const items = this.data.items
    for (let i = 0, len = items.length; i < len; ++i) {
      items[i].checked = items[i].value === e.detail.value
    }

    this.setData({
      items
    })
  }
})


radio-group

功能说明：单项选择器，内部由多个 radio 组成。
参数及说明
属性
类型
默认值
必填
说明
bindchange
eventhandle
-
否
radio-group 中选中项发生改变时触发 change 事件，detail = {value:[选中的 radio 的 value 的数组]}

slider

功能说明：滑动选择器。
参数及说明
属性
类型
默认值
必填
说明
min
number
0
否
最小值
max
number
100
否
最大值
step
number
1
否
步长，取值必须大于 0，并且可被(max - min)整除
disabled
boolean
false
否
是否禁用
value
number
0
否
当前取值
color
color
#e9e9e9
否
背景条的颜色（请使用 backgroundColor）
selected-color
color
#1aad19
否
已选择的颜色（请使用 activeColor）
activeColor
color
#1aad19
否
已选择的颜色
backgroundColor
color
#e9e9e9
否
背景条的颜色
block-size
number
28
否
滑块的大小，取值范围为 12 - 28
block-color
color
#ffffff
否
滑块的颜色
show-value
boolean
false
否
是否显示当前 value
bindchange
eventhandle
-
否
完成一次拖动后触发的事件，event.detail = {value}
bindchanging
eventhandle
-
否
拖动过程中触发的事件，event.detail = {value}
示例代码：
WXML
JAVASCRIPT
<view class="page">
    <view class="page__hd">
        <text class="page__title">slider</text>
        <text class="page__desc">滑块</text>
    </view>
    <view class="page__bd">
        <view class="page-section page-section-gap">
          <view class="page-section-title">设置step</view>
          <view class="body-view">
            <slider value="60" bindchange="slider2change" step="5"/>
          </view>
        </view>
    
        <view class="page-section page-section-gap">
          <view class="page-section-title">显示当前value</view>
          <view class="body-view">
            <slider value="50" bindchange="slider3change" show-value/>
          </view>
        </view>
    
        <view class="page-section page-section-gap">
          <view class="page-section-title">设置最小/最大值</view>
          <view class="body-view">
            <slider value="100" bindchange="slider4change" min="50" max="200" show-value/>
          </view>
        </view>
    </view>
</view>
var pageData = {}
for (var i = 1; i < 5; ++i) {
  (function (index) {
    pageData[`slider${index}change`] = function (e) {
      console.log(`slider${index}发生change事件，携带值为`, e.detail.value)
    }
  })(i);
}
Page(pageData)


switch

功能说明：开关选择器。
参数及说明
属性
类型
默认值
必填
说明
checked
boolean
false
否
是否选中
disabled
boolean
false
否
是否禁用
type
string
switch
否
样式，有效值：switch，checkbox
color
string
#04BE02
否
switch 的颜色，同 css 的 color
bindchange
eventhandle
-
否
点击导致 checked 改变时会触发 change 事件，event.detail={ value}
示例代码：
WXML
JAVASCRIPT
<view class="page">
    <view class="page__hd">
        <text class="page__title">switch</text>
        <text class="page__desc">开关</text>
    </view>
    <view class="page__bd">
        <view class="section section_gap">
            <view class="section__title">type="switch"</view>
            <view class="body-view">
                <switch checked="{{switch1Checked}}" bindchange="switch1Change"/>
            </view>
        </view>

        <view class="section section_gap">
            <view class="section__title">type="checkbox"</view>
            <view class="body-view">
                <switch type="checkbox" checked="{{switch2Checked}}" bindchange="switch2Change"/>
            </view>
        </view>
    </view>
</view>
var pageData = {
  data: {
    switch1Checked: true,
    switch2Checked: false,
    switch1Style: '',
    switch2Style: 'text-decoration: line-through'
  }
}
for (var i = 1; i <= 2; ++i) {
  (function (index) {
    pageData[`switch${index}Change`] = function (e) {
      console.log(`switch${index}发生change事件，携带值为`, e.detail.value)
      var obj = {}
      obj[`switch${index}Checked`] = e.detail.value
      this.setData(obj)
      obj = {}
      obj[`switch${index}Style`] = e.detail.value ? '' : 'text-decoration: line-through'
      this.setData(obj)
    }
  })(i)
}
Page(pageData)


textarea

功能说明：多行输入框，该组件是 原生组件，使用时请注意相关限制。
参数及说明：
属性
类型
合法值及说明
默认值
必填
说明
value
string
-
-
否
输入框的内容
placeholder
string
-
-
否
输入框为空时占位符
placeholder-style
string
-
-
否
指定 placeholder 的样式，目前仅支持 color，font-size 和 font-weight
placeholder-class
string
-
textarea-placeholder
否
指定 placeholder 的样式类
fixed
boolean
-
false
否
如果 textarea 是在一个position:fixed的区域，需要显示指定属性 fixed 为 true
show-confirm-bar
boolean
-
true
否
是否显示键盘上方带有“完成”按钮那一栏
disabled
boolean
-
false
否
是否禁用
maxlength
number
-
140
否
最大输入长度，设置为 -1 的时候不限制最大长度
auto-focus
boolean
-
false
否
自动聚焦，拉起键盘。
focus
boolean
-
false
否
获取焦点
auto-height
boolean
-
false
否
是否自动增高，设置 auto-height 时，style.height 不生效
cursor-spacing
number / string
-
0
否
指定光标与键盘的距离。取textarea距离底部的距离和cursor-spacing指定的距离的最小值作为光标与键盘的距离
cursor
number
-
-1
否
指定 focus 时的光标位置
selection-start
number
-
-1
否
光标起始位置，自动聚集时有效，需与selection-end搭配使用
selection-end
number
-
-1
否
光标结束位置，自动聚集时有效，需与selection-start搭配使用
adjust-position
boolean
-
true
否
键盘弹起时，是否自动上推页面
hold-keyboard
boolean
-
false
否
focus时，点击页面的时候不收起键盘
confirm-type
string
send：右下角按钮为“发送”；
search：右下角按钮为“搜索”；
next：右下角按钮为“下一个”；
go：右下角按钮为“前往”；
done：右下角按钮为“完成”；
return：右下角按钮为“换行”；
return
否
设置键盘右下角按钮的文字
confirm-hold
boolean
-
false
否
点击键盘右下角按钮时是否保持键盘不收起
bindfocus
eventhandle
-
-
否
输入框聚焦时触发，event.detail = { value, height }，height 为键盘高度
bindblur
eventhandle
-
-
否
输入框失去焦点时触发，event.detail = {value, cursor}
bindlinechange
eventhandle
-
-
否
输入框行数变化时调用，event.detail = {height: 0, heightRpx: 0, lineCount: 0}
bindinput
eventhandle
-
-
否
当键盘输入时，触发 input 事件，event.detail = {value, cursor, keyCode}，keyCode 为键值，目前工具还不支持返回keyCode参数。**bindinput 处理函数的返回值并不会反映到 textarea 上**
bindconfirm
eventhandle
-
-
否
点击完成时， 触发 confirm 事件，event.detail = {value: value}
bindkeyboardheightchange
eventhandle
-
-
否
键盘高度发生变化的时候触发此事件，event.detail = {height: height, duration: duration}
注意：
textarea 的 blur 事件会晚于页面上的 tap 事件，如果需要在 button 的点击事件获取 textarea，可以使用 form 的 bindsubmit。
不建议在多行文本上对用户的输入进行修改，所以 textarea 的 bindinput 处理函数并不会将返回值反映到 textarea 上。
键盘高度发生变化，keyboardheightchange事件可能会多次触发，开发者对于相同的height值应该忽略掉。
示例代码：
WXML
JAVASCRIPT
<view class="section">
  <textarea bindblur="bindTextAreaBlur" auto-height placeholder="自动变高" />
</view>
<view class="section">
  <textarea placeholder="placeholder颜色是红色的" placeholder-style="color:red;"  />
</view>
<view class="section">
  <textarea placeholder="这是一个可以自动聚焦的textarea" auto-focus />
</view>
<view class="section">
  <textarea placeholder="这个只有在按钮点击的时候才聚焦" focus="{{focus}}" />
  <view class="btn-area">
    <button bindtap="bindButtonTap">使得输入框获取焦点</button>
  </view>
</view>
<view class="section">
  <form bindsubmit="bindFormSubmit">
    <textarea placeholder="form 中的 textarea" name="textarea"/>
    <button form-type="submit"> 提交 </button>
  </form>
</view>
Page({
  data: {
    height: 20,
    focus: false
  },
  bindButtonTap: function() {
    this.setData({
      focus: true
    })
  },
  bindTextAreaBlur: function(e) {
    console.log(e.detail.value)
  },
  bindFormSubmit: function(e) {
    console.log(e.detail.value.textarea)
  }
})


Topik sebelumnya: 导航组件Topik selanjutnya: API 概览

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan