tencent cloud

All product documents
Tencent Cloud Super App as a Service
DocumentationTencent Cloud Super App as a ServiceGuildlines for Mini Program DevelopmentComponentsForm Component
Form Component
Download PDF
Last updated: 2025-03-25 18:15:56
Form Component
Last updated: 2025-03-25 18:15:56
Download PDF

button

Feature description:Button.
Parameter and description:
Property
Type
Valid values and description
Default value
‍Required
Description
size
string
default: Default size
mini: Small size
default
False
Button size.
type
string
primary: Green
default: White
warn: Red
default
False
Button style type.
plain
boolean
-
false
False
Whether the button is hollow with a background color.
disabled
boolean
-
false
False
Whether the button is disabled.
loading
boolean
-
false
False
Whether to show a loading icon before the button name.
form-type
string
submit: Submits the form
reset: Resets the form
-
False
Used for the form component. Triggers the form component's submit/reset event when tapped
open-type
string
share: Triggers user sharing
getPhoneNumber (Only supported on SaaS): Gets the user’s phone number from the bindgetphonenumber callback
getEmailAddress (Only supported on SaaS): Gets the user’s email address from the bindgetemailaddress callback
getUserInfo: Gets user information from the bindgetuserinfo callback
openSetting: Opens the authorization settings page
feedback: Opens the Feedback page, where users can submit feedback and upload logs
chooseAvatar (Only supported on SaaS): Gets the user’s profile photo from the bindchooseavatar callback
-
False
Host app capabilities
hover-class
string
-
button-hover
False
Specifies the style class when the button is tapped. When hover-class="none" is set, no tap effect is available.
hover-start-time
number
-
20
False
Time in milliseconds before the tap effect appears after pressing.
hover-stay-time
number
-
70
False
Time in milliseconds the tap effect remains after the finger is released.
lang
string
en: English
zh_CN: Simplified Chinese
zh_TW: Traditional Chinese
en
False
Specifies the language for returning user information.
bindgetuserinfo
eventhandle
-
-
False
When this button is tapped, the acquired user information will be returned. The callback detail is consistent with that returned by wx.getUserInfo. Effective when open-type="getUserInfo".
bindgetphonenumber
eventhandle
-
-
False
Callback for quick verification of phone number. Effective when open-type=getPhoneNumber.
Note: After triggering the bindgetphonenumber callback, immediately hide the phone number button component or set it to disabled to avoid extra charges from repeated authorizations.
bindopensetting
eventhandle
-
-
False
Callback after opening the authorization setting page. Effective when open-type=openSetting.
Notes:
Currently, a button with form-type will only be effective for the form within the current component. Therefore, encapsulating the button in a custom component and the form outside the custom component will make the form-type of the button invalid.
Example:
WXML
JAVASCRIPT
WXSS
<view class="page-body">
  <view class="btn-area" id="buttonContainer">
    <button type="primary">Primary Page Action Normal</button>
    <button type="primary" loading="true">Primary Page Action Loading</button>
    <button type="primary" disabled="true">Primary Page Action Disabled</button>

    <button type="default">Secondary Page Action Normal</button>
    <button type="default" disabled="true">Secondary Page Action Disabled</button>

    <button type="warn">Warning Action Normal</button>
    <button type="warn" disabled="true">Warning Action Disabled</button>

    <view class="button-sp-area">
      <button type="primary" plain="true">Button</button>
      <button type="primary" disabled="true" plain="true">Disabled button</button>

      <button type="default" plain="true">Button</button>
      <button type="default" disabled="true" plain="true">Button</button>

      <button class="mini-btn" type="primary" size="mini">Button</button>
      <button class="mini-btn" type="default" size="mini">Button</button>
      <button class="mini-btn" type="warn" size="mini">Button</button>
    </view>
  </view>
</view>
const types = ['default', 'primary', 'warn']
const pageObject = {
  data: {
    defaultSize: 'default',
    primarySize: 'default',
    warnSize: 'default',
    disabled: false,
    plain: false,
    loading: false
  },

  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 &lt; 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

Feature description:Checkbox.
Parameter and description:
Property
Type
Default value
‍Required
Description
value
string
-
False
Checkbox identifier. When selected, it triggers the change event of the checkbox-group and carries the checkbox's value.
disabled
boolean
false
False
Whether the checkbox is disabled.
checked
boolean
false
False
Whether the checkbox is currently selected. The checkbox can be set to selected by default.
color
string
#09BB07
False
Checkbox color, similar to the CSS color property.
Example:
WXML
JAVASCRIPT
<view class="container">
  <view class="page-body">
    <view class="page-section page-section-gap">
      <view class="page-section-title">Default style</view>
      <label class="checkbox">
        <checkbox value="cb" checked="true"/>Selected
      </label>
      <label class="checkbox">
        <checkbox value="cb" />Unselected
      </label>
    </view>
  
    <view class="page-section">
      <view class="page-section-title">Recommended display style</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: 'United States'},
      {value: 'CHN', name: 'China', checked: 'true'},
      {value: 'BRA', name: 'Brazil'},
      {value: 'JPN', name: 'Japan'},
      {value: 'ENG', name: 'United Kingdom'},
      {value: 'FRA', name: 'France'}
    ]
  },

  checkboxChange(e) {
    console.log('A change event is triggered in the checkbox, and the carried value is', e.detail.value)

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

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

    this.setData({
      items
    })
  }
})


checkbox-group

Feature description:A multiple selection component, which consists of multiple checkboxes.
Parameter and description:
Property
Type
Default value
‍Required
Description
bindchange
eventhandle
-
False
A change event is triggered when the selected checkboxes in the checkbox-group change, detail = {value:[array of values of selected checkboxes]}.

editor

Feature description:A rich text editor that allows editing of images and text.
The editor can export content asHTML and plain text. Internally, it uses the delta format for storage.
When setting content via the setContents API, parsing insertedHTML may result in errors due to illegal tags. It is recommended to use delta for insertion within the app.
The rich text component includes basic styles to ensure proper content display, which can be overridden during development.
The configurations to the image controls are only effective if set during initialization.
Related API:EditorContext.
Parameter and description:
Property
Type
Default value
‍Required
Description
read-only
boolean
false
False
Specifies whether the editor is set to read-only.
placeholder
string
-
False
Placehoder text.
show-img-size
boolean
false
False
Displays image size controls when an image is tapped.
show-img-toolbar
boolean
false
False
Displays toolbar controls when an image is tapped.
show-img-resize
boolean
false
False
Displays resize controls when an image is tapped.
bindready
eventhandle
-
False
Triggered when the editor is initialized.
bindfocus
eventhandle
-
False
Triggered when the editor gains focus. event.detail = {html, text, delta}.
bindblur
eventhandle
-
False
Triggered when the editor loses focus, detail = {html, text, delta}.
bindinput
eventhandle
-
False
Triggered when the editor content changes. detail = {html, text, delta}.
bindstatuschange
eventhandle
-
False
Triggered when the editor's internal style is changed via Context methods. Returns the styles set in the selection.
The editor supports certainHTMLtags and inline styles but does not support classandid attributes.
Supported tags
Unsupported tags will be ignored or converted to supported tags (e.g.,<div>will be converted to <p>supported tags.
Type
Node
Inline elements
<span> <strong> <b> <ins> <em> <i> <u> <a> <del> <s> <sub> <sup> <img>
Block-level elements
<p> <h1> <h2> <h3> <h4> <h5> <h6> <hr> <ol> <ul> <li>
Supported inline styles
Inline styles can only be applied to inline elements or block elements, but not both simultaneously. For example,font-size is categorized as an inline element property, so setting it on a p tag is invalid.
Type
Style
Block-level styles
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
Inline styles
font ,font-size ,font-style ,font-variant ,font-weight ,font-family ,letter-spacing ,text-decoration ,color ,background-color
Notes:
Event bindings in the inserted HTML will be removed.
When pasting, only the plain text content will be copied into the editor.
When inserting HTML into the editor, some unnecessary tags will be deleted to ensure the consistency of the content. For example,<p><span>xxx</span></p>will be rewritten as<p>xxx</p>.
The page will be pushed up when the editor gains focus to ensure the editing area is visible, which is a system behavior.

form

Feature description:A form, which submits user input from components like slider,picker ,checkbox,radio,switch and input .
When a user tap the button component where the form-type is set to submit in the form, the values of the form component will be submitted. Each form component should have a name attribute to serve as the key.
Parameter and description:
Property
Type
Default value
‍Required
Description
bindsubmit
eventhandle
-
False
A submit event is triggered when the form is submitted, carrying the data from the form. event.detail = {value : {'name': 'value'} , formId: ''}.
bindreset
eventhandle
-
False
A reset event is triggered when the form is reset.
Example:
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"/>Option 1</label>
          <label><radio value="radio2"/>Option 2</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"/>Option 1</label>
          <label><checkbox value="checkbox2"/>Option 2</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="This is an input box" />
            </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('A submit event is triggered in the form, and the carried data is', e.detail.value)
  },

  formReset(e) {
    console.log('A reset event is triggered in the form, and the carried data is', e.detail.value)
    this.setData({
      chosen: ''
    })
  }
})


input

Feature description:An input field. This component is a Native Component and there are some restrictions for using it.
Parameter and description:
Property
Type
Valid values and description
Default value
‍Required
Description
value
string
-
-
True
Initial content of the input field.
type
string
text: Text input keyboard
number: Numeric input keyboard
idcard: ID number input keyboard
digit: Numeric keyboard with a decimal point
nickname (Only supported on SaaS): Nickname input keyboard
text
False
Input type.
password
boolean
-
false
False
Whether the input is of password type.
placeholder
string
-

True
Placeholder text when the input field is empty.
placeholder-style
string
-
-
True
Specifies the placeholder style.
placeholder-class
string
-
input-placeholder
False
Specifies the placeholder style class.
disabled
boolean
-
false
False
Whether the input field is disabled.
maxlength
number
-
140
False
Maximum input length. Set to -1 for no limit.
cursor-spacing
number
-
0
False
Distance between the cursor and the keyboard. The minimum value between the input's bottom distance and cursor-spacing is used.
auto-focus
boolean
-
false
False
(Deprecated, use focus instead) Automatically focuses and brings up the keyboard
focus
boolean
-
false
False
Specifies whether to get the focus.
confirm-type
string
send: Sets the button in the bottom-right corner to "Send"
search: Sets the button in the bottom-right corner to "Search"
next: Sets the button in the bottom-right corner to "Next"
go: Sets the button in the bottom-right corner to "Go"
done: Sets the button in the bottom-right corner to "Done"
done
False
Sets the text of the button in the bottom-right corner of the keyboard. Effective only when type='text'.
confirm-hold
boolean
-
false
False
Whether to keep the keyboard open when the button in the bottom-right corner is tapped.
cursor
number
-
-
True
Specifies the position of the cursor when the input field gets focus.
selection-start
number
-
-1
False
Start position of the selection, effective when auto-focusing, should be used with selection-end.
selection-end
number
-
-1
False
End position of the selection, effective when auto-focusing, should be used with selection-start.
adjust-position
boolean
-
true
False
Whether to automatically adjust the page position when the keyboard pops up.
hold-keyboard
boolean
-
false
False
Whether to keep the keyboard open when tapping on the page.
bindinput
eventhandle
-
-
True
Triggered when the keyboard input occurs. event.detail = {value, cursor, keyCode}. The handler can return a string to replace the input field content.
bindfocus
eventhandle
-
-
True
Triggered when the input field gets focus. event.detail = { value, height }, where height is the keyboard height.
bindblur
eventhandle
-
-
True
Triggered when the input box loses focus, event.detail = { value, encryptedValue, encryptError }.
bindconfirm
eventhandle
-
-
True
Triggered when the user taps the Done button, event.detail = { value }.
bindkeyboardheightchange
eventhandle
-
-
True
Triggered when the keyboard height changes, event.detail = {height: height, duration: duration}.
Notes:
The final behavior of confirm-type depends on the implementation of the mobile input method itself. Some Android system input methods and third-party input methods may not support or fully support it.
The input component is a native component, and the font is the system font, so font-family cannot be set.
Avoid using CSS animations during the input focus period.
If the input is wrapped in a custom component and the form is outside of this custom component, the form will not be able to retrieve the value of the input within the custom component.
When the keyboard height changes, the keyboardheightchange event may be triggered multiple times. Developers should ignore events with the same height value to avoid redundant processing.
Example:
WXML
JAVASCRIPT
<view class="page-body">
  <view class="page-section">
    <view class="weui-cells__title">Input that can be auto-focused</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" auto-focus placeholder="Will be focused"/>
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">Input that controls the max input length</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" maxlength="10" placeholder="The max input length is 10" />
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">Get the input value in real-time: {{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="Input is synced to the view"/>
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">Input that the controls the typing</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input"  bindinput="bindReplaceInput" placeholder="Typing two consecutive ones will generate a two" />
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">Input that controls the keyboard</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input"  bindinput="bindHideKeyboard" placeholder="Typing 123 will automatically close the keyboard" />
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">Input for entering numbers</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" type="number" placeholder="This is a number input box" />
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">Input for entering a password</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" password type="text" placeholder="This is a password input box" />
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">Input with a decimal point</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" type="digit" placeholder="Numeric keyboard with a decimal point"/>
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">Input for entering ID card numbers</view>
    <view class="weui-cells weui-cells_after-title">
      <view class="weui-cell weui-cell_input">
        <input class="weui-input" type="idcard" placeholder="ID card input keyboard" />
      </view>
    </view>
  </view>
  <view class="page-section">
    <view class="weui-cells__title">Input that controls the placeholder color</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="The color of the placeholder font is red" />
      </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) {
      // The cursor is in the middle
      left = e.detail.value.slice(0, pos)
      // Calculates the cursor position
      pos = left.replace(/11/g, '2').length
    }

    // Returns the object directly, filters the input, and controls the cursor position
    return {
      value: value.replace(/11/g, '2'),
      cursor: pos
    }

    // Or returns the string directly, with the cursor at the end
    // return value.replace(/11/g,'2'),
  },
  bindHideKeyboard: function (e) {
    if (e.detail.value === '123') {
      // Closes the keyboard
      wx.hideKeyboard()
    }
  }
})


label

Feature description:This component is used to improve the usability of form components.
Use the for property to find the corresponding id, or place the control under the label. When tapping, the corresponding control will be triggered. The for property has a higher priority than internal controls. When there are multiple internal controls, the first control is triggered by default. Currently, the following controls can be bound:button,checkbox,radio,switch and input.
Parameter and description:
Property
Type
Default value
‍Required
Description
for
string
-
False
The ID of the bound control.
Example:
WXML
JAVASCRIPT
WXSS
<view class="container">
  <view class="page-body">
    <view class="page-section page-section-gap">
      <view class="page-section-title">The form component is inside the 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 uses for to identify the form component</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">If there are multiple controls in the label, the first one is selected</view>
      <label class="label-3">
        <checkbox class="checkbox-3">Option 1</checkbox>
        <checkbox class="checkbox-3">Option 2</checkbox>
        <view class="label-3-text">When tapping the text under this label, the first checkbox is selected by default</view>
      </label>
    </view>
  </view>
</view>
Page({
  onShareAppMessage() {
    return {
      title: 'label',
      path: 'page/component/pages/label/label'
    }
  },

  data: {
    checkboxItems: [
      {name: 'USA', value: 'United States'},
      {name: 'CHN', value: 'China', checked: 'true'}
    ],
    radioItems: [
      {name: 'USA', value: 'United States'},
      {name: 'CHN', value: 'China', checked: 'true'}
    ],
    hidden: false
  },

  checkboxChange(e) {
    const checked = e.detail.value
    const changed = {}
    for (let i = 0; i &lt; 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 &lt; 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('the button is tapped')
  }
})
.label-1, .label-2{
  margin: 30rpx 0;
}
.label-3-text{
  color: #576B95;
  font-size: 28rpx;
}
.checkbox-3{
  display: block;
  margin: 30rpx 0;
}


picker

Feature description:A scroll picker that pops up from the bottom.
Parameter and description:
Property
Type
Valid values and description
Default value
‍Required
Description
mode
string
selector: Normal picker
multiSelector: Multi-column picker
time: Time picker
date: Date picker
region: Region picker
selector
False
Type of the picker.
disabled
boolean
-
false
False
Whether the selector is disabled.
bindcancel
eventhandle
-
-
False
Triggered when selection is canceled.
In addition to the common properties above, thepickerhas different properties for different modes.

Normal picker: mode = selector

Property
Type
Default value
Description
range
array/object array
[]
Effective when mode is selector or multiSelector.
range-key
string
-
When range is an object array, specifies the key in the Object Array to display as the content of the picker.
value
number
0
Specifies which one in the range is selected (index starts from 0).
bindchange
eventhandle
-
The change event is triggered when value changes, event.detail = {value}.

Multi-column picker: mode = multiSelector

Property
Type
Default value
Description
range
array/object array
[]
Effective when mode is selector or multiSelector.
range-key
string
-
When range is an object array, specifies the key in the Object Array to display as the content of the picker.
value
array
[]
Specifies which one in the range is selected (index starts from 0).
bindchange
eventhandle
-
The change event is triggered when value changes, event.detail = {value}.
bindcolumnchange
eventhandle
-
Triggered when the column changes.

Time picker: mode = time

Property
Type
Default value
Description
value
string
-
Indicates the selected time, format is "hh:mm".
start
string
-
Indicates the start of the valid time range, format is "hh:mm".
end
string
-
Indicates the end of the valid time range, format is "hh:mm".
bindchange
eventhandle
-
The change event is triggered when value changes, event.detail = {value}.

Date picker: mode = date

Property
Type
Valid values
Default value
Description
value
string
-
Current day
Specifies the selected date in YYYY-MM-DD format.
start
string
-
-
Indicates the selected date, format is "YYYY-MM-DD".
end
string
-
-
Indicates the start of the valid date range, format is "YYYY-MM-DD".
fields
string
year: Year
month: Month
day: Day
day
Indicates the granularity of the picker.
bindchange
eventhandle
-
-
The change event is triggered when value changes, event.detail = {value}.

Region picker: mode = region

Property
Type
Default value
Description
value
Array
[]
Specifies the selected regions. The first value in each column is selected by default.
custom-item
string
-
Adds a custom item at the top of each column.
bindchange
evenhandle
-
The change event is triggered when value changes, event.detail = {value: value, code: code, postcode: postcode}, where the code field is the statistical division code and postcode is the postal code.
Example:
WXML
JAVASCRIPT
<view class="section">
  <view class="section__title">Normal picker</view>
  <picker bindchange="bindPickerChange" value="{{index}}" range="{{array}}">
    <view class="picker">
      Currently selected: {{array[index]}}
    </view>
  </picker>
</view>
<view class="section">
  <view class="section__title">Multi-column picker</view>
  <picker mode="multiSelector" bindchange="bindMultiPickerChange" bindcolumnchange="bindMultiPickerColumnChange" value="{{multiIndex}}" range="{{multiArray}}">
    <view class="picker">
      Currently selected: {{multiArray[0][multiIndex[0]]}}, {{multiArray[1][multiIndex[1]]}}, {{multiArray[2][multiIndex[2]]}}
    </view>
  </picker>
</view>
<view class="section">
  <view class="section__title">Time picker</view>
  <picker mode="time" value="{{time}}" start="09:01" end="21:01" bindchange="bindTimeChange">
    <view class="picker">
      Currently selected: {{time}}
    </view>
  </picker>
</view>

<view class="section">
  <view class="section__title">Date picker</view>
  <picker mode="date" value="{{date}}" start="2015-09-01" end="2017-09-01" bindchange="bindDateChange">
    <view class="picker">
      Currently selected: {{date}}
    </view>
  </picker>
</view>
<view class="section">
  <view class="section__title">Region picker</view>
  <picker mode="region" bindchange="bindRegionChange" value="{{region}}" custom-item="{{customItem}}">
    <view class="picker">
      Currently selected: {{region[0]}}, {{region[1]}}, {{region[2]}}
    </view>
  </picker>
</view>
Page({
  data: {
    array: ['United States', 'China', 'Brazil', 'Japan'],
    objectArray: [
      {
        id: 0,
        name: 'United States'
      },
      {
        id: 1,
        name: 'China'
      },
      {
        id: 2,
        name: 'Brazil'
      },
      {
        id: 3,
        name: 'Japan'
      }
    ],
    index: 0,
    multiArray: [['Invertebrates', 'Vertebrates'], ['Flatworms', 'Nematodes', 'Annelates', 'Mollusks', 'Arthropods'], ['Pork tapeworms', 'Blood-sucking worms']],
    objectMultiArray: [
      [
        {
          id: 0,
          name: 'Invertebrates'
        },
        {
          id: 1,
          name: 'Vertebrates'
        }
      ], [
        {
          id: 0,
          name: 'Flatworms'
        },
        {
          id: 1,
          name: 'Nematodes'
        },
        {
          id: 2,
          name: 'Annelates'
        },
        {
          id: 3,
          name: 'Mollusks'
        },
        {
          id: 4,
          name: 'Arthropods'
        }
      ], [
        {
          id: 0,
          name: 'Pork tapeworms'
        },
        {
          id: 1,
          name: 'Blood-sucking worms'
        }
      ]
    ],
    multiIndex: [0, 0, 0],
    date: '2016-09-01',
    time: '12:01',
    region: ['Guangdong Province', 'Guangzhou', 'Haizhu District'],
    customItem: 'All'
  },
  bindPickerChange: function(e) {
    console.log('The picker sends selection change, and the carried value is' e.detail.value)
    this.setData({
      index: e.detail.value
    })
  },
  bindMultiPickerChange: function (e) {
    console.log('The picker sends selection change, and the carried value is' e.detail.value)
    this.setData({
      multiIndex: e.detail.value
    })
  },
  bindMultiPickerColumnChange: function (e) {
    console.log('The modified column is', e.detail.column, ', and the value is', 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] = ['Flatworms', 'Nematodes', 'Annelates', 'Mollusks', 'Arthropods'];
            data.multiArray[2] = ['Pork tapeworms', 'Blood-sucking worms'];
            break;
          case 1:
            data.multiArray[1] = ['Fish', ''Amphibians', 'Reptiles'];
            data.multiArray[2] = ['Carassius auratus', 'Hairtail'];
            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] = ['Pork tapeworms', 'Blood-sucking worms'];
                break;
              case 1:
                data.multiArray[2] = ['Roundworms'];
                break;
              case 2:
                data.multiArray[2] = ['Ants', 'Leech'];
                break;
              case 3:
                data.multiArray[2] = ['Mussels', 'Snails', 'Slugs'];
                break;
              case 4:
                data.multiArray[2] = ['Insects', 'Crustaceans', 'Arachnids', 'Myriapods'];
                break;
            }
            break;
          case 1:
            switch (data.multiIndex[1]) {
              case 0:
                data.multiArray[2] = ['Carassius auratus', 'Hairtail'];
                break;
              case 1:
                data.multiArray[2] = [''Frogs', 'Giant salamanders'];
                break;
              case 2:
                data.multiArray[2] = ['Lizards', 'Turtles', 'Geckos'];
                break;
            }
            break;
        }
        data.multiIndex[2] = 0;
        break;
    }
    console.log(data.multiIndex);
    this.setData(data);
  },
  bindDateChange: function(e) {
    console.log('The picker sends selection change, and the carried value is' e.detail.value)
    this.setData({
      date: e.detail.value
    })
  },
  bindTimeChange: function(e) {
    console.log('The picker sends selection change, and the carried value is' e.detail.value)
    this.setData({
      time: e.detail.value
    })
  },
  bindRegionChange: function (e) {
    console.log('The picker sends selection change, and the carried value is' e.detail.value)
    this.setData({
      region: e.detail.value
    })
  }
})


picker-view

Feature description:An embedded scroll picker for the page. Only picker-view-column component can be placed, and other nodes will not be displayed.
Parameter and description:
Property
Type
Default value
‍Required
Description
value
Array.<number>
-
False
The numbers in the array represent the selected item in each picker-view-column (index starts from 0). If the number exceeds the length of the options, the last item is selected.
mask-class
string
-
False
Sets the class name for the mask layer.
indicator-style
string
-
False
Sets the style of the selected box in the picker.
bindchange
eventhandle
-
False
The change event is triggered when scrolling selection changes, event.detail = {value}; value is an array indicating the current selection in each picker-view-column (index starts from 0).
bindpickstart
eventhandle
-
False
The event is triggered when scrolling selection starts.
bindpickend
eventhandle
-
False
The event is triggered when scrolling selection ends.
indicator-class
string
-
False
Sets the class name of the selected box in the picker.
mask-style
string
-
False
Sets the style of the mask layer.
immediate-change
boolean
false
False
Whether to trigger the change event immediately when the finger is released. If not enabled, the change event will be triggered after the scrolling animation ends.
Example:
WXML
JAVASCRIPT
<view class="container">
  <view class="page-body">
    <view class="selected-date">{{year}}Year{{month}}Month{{day}}Day{{isDaytime ? "Day" : "Night"}}</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}}Year</view>
      </picker-view-column>
      <picker-view-column>
        <view wx:for="{{months}}" wx:key="{{months}}" style="line-height: 50px; text-align: center;">{{item}}Month</view>
      </picker-view-column>
      <picker-view-column>
        <view wx:for="{{days}}" wx:key="{{days}}" style="line-height: 50px; text-align: center;">{{item}}Day</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 &lt;= date.getFullYear(); i++) {
  years.push(i)
}

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

for (let i = 1; i &lt;= 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

Feature description:A sub-item of the scroll picker. This component can only be placed in picker-view, and the height of its child nodes will be automatically match the height of the selection box in picker-view.

radio

Feature description:A single selection item.
Parameter and description
Property
Type
Default value
‍Required
Description
value
string
-
False
Identifier of the radio. When the radio is selected, the change event of radio-group is triggered and the radio value will be carried.
checked
boolean
false
False
Whether the radio is selected.
disabled
boolean
false
False
Whether the radio is disabled.
color
string
#09BB07
False
The color of the radio, similar to the CSS color property.
Example:
WXML
JAVASCRIPT
<view class="page-body">
  <view class="page-section">
    <view class="page-section-title">Default style</view>
    <label class="radio">
      <radio value="r1" checked="true"/>Selected
    </label>
    <label class="radio">
      <radio value="r2" />Unselected
    </label>
  </view>


  <view class="page-section">
    <view class="page-section-title">Recommended display style</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: 'United States'},
      {value: 'CHN', name: 'China', checked: 'true'},
      {value: 'BRA', name: 'Brazil'},
      {value: 'JPN', name: 'Japan'},
      {value: 'ENG', name: 'United Kingdom'},
      {value: 'FRA', name: 'France'},
    ]
  },

  radioChange(e) {
    console.log('A change event is triggered in the radio, and the carried value is: ', e.detail.value)

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

    this.setData({
      items
    })
  }
})


radio-group

Feature description:A single selection group composed of multiple radio items.
Parameter and description
Property
Type
Default value
‍Required
Description
bindchange
eventhandle
-
False
A change event is triggered when the selected item in the radio-group component changes, detail = {value:[array of values of selected radio buttons]}.

slider

Feature description:A sliding picker.
Parameter and description
Property
Type
Default value
‍Required
Description
min
number
0
False
Minimum value.
max
number
100
False
Maximum value.
step
number
1
False
Step size, must be greater than 0 and divisible by (max - min).
disabled
boolean
false
False
Whether the slider is disabled.
value
number
0
False
Current value.
color
color
#e9e9e9
False
Background bar color (use backgroundColor).
selected-color
color
#1aad19
False
Selected color (use activeColor).
activeColor
color
#1aad19
False
Selected color.
backgroundColor
color
#e9e9e9
False
Background bar color.
block-size
number
28
False
Size of the slider block, range is 12 - 28.
block-color
color
#ffffff
False
Color of the slider block.
show-value
boolean
false
False
Whether to display the current value.
bindchange
eventhandle
-
False
Event triggered after a drag is completed, event.detail = {value}.
bindchanging
eventhandle
-
False
Event triggered during the drag, event.detail = {value}.
Example:
WXML
JAVASCRIPT
<view class="page">
    <view class="page__hd">
        <text class="page__title">slider</text>
        <text class="page__desc">Slider</text>
    </view>
    <view class="page__bd">
        <view class="page-section page-section-gap">
          <view class="page-section-title">Set the 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">Show the current 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">Set the min/max values</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 &lt; 5; ++i) {
  (function (index) {
    pageData[`slider${index}change`] = function (e) {
      console.log(`A change event is triggered in slider${index}, and the carried value is` e.detail.value)
    }
  })(i);
}
Page(pageData)


switch

Feature description:A switch picker.
Parameter and description
Property
Type
Default value
‍Required
Description
checked
boolean
false
False
Whether the switch is selected.
disabled
boolean
false
False
Whether the switch is disabled.
type
string
switch
False
Style of the switch, valid values: switch, checkbox.
color
string
#04BE02
False
Color of the switch, similar to the CSS color property.
bindchange
eventhandle
-
False
The change event is triggered when the component is tapped and the value of checked changes, event.detail={ value}.
Example:
WXML
JAVASCRIPT
<view class="page">
    <view class="page__hd">
        <text class="page__title">switch</text>
        <text class="page__desc">Switch</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 &lt;= 2; ++i) {
  (function (index) {
    pageData[`switch${index}Change`] = function (e) {
      console.log(`A change event is triggered in switch${index}, and the carried value is` 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

Feature description:A multi-line input box. This component is a Native Component and there are some restrictions for using it.
Parameter and description:
Property
Type
Valid values and description
Default value
‍Required
Description
value
string
-
-
False
Content of the input box.
placeholder
string
-
-
False
Placeholder text when the input field is empty.
placeholder-style
string
-
-
False
Style for the placeholder, currently supports color, font-size, and font-weight.
placeholder-class
string
-
textarea-placeholder
False
Style class for the placeholder.
fixed
boolean
-
false
False
If the textarea is in a position:fixed area, the property fixed should be set to true.
show-confirm-bar
boolean
-
true
False
Whether to show the bar with the "Done" button above the keyboard.
disabled
boolean
-
false
False
Whether the textarea is disabled.
maxlength
number
-
140
False
Maximum input length. Set to -1 for no limit.
auto-focus
boolean
-
false
False
Automatically focuses and brings up the keyboard.
focus
boolean
-
false
False
Gets the focus.
auto-height
boolean
-
false
False
Whether to enable automatic height adjustment for the input box. If auto-height is set to true, the style.height is invalid.
cursor-spacing
number / string
-
0
False
Distance between the cursor and the keyboard. Use the smaller value between the distance from the textarea to the bottom and the distance specified by cursor-spacing as the distance between the cursor and the keyboard.
cursor
number
-
-1
False
Cursor position when focused.
selection-start
number
-
-1
False
Start position of the cursor, effective when auto-focusing, used withselection-end.
selection-end
number
-
-1
False
End position of the cursor, effective when auto-focusing, used withselection-start.
adjust-position
boolean
-
true
False
Automatically pushes the page up when the keyboard pops up.
hold-keyboard
boolean
-
false
False
Whether to keep the keyboard open when tapping on the page.
confirm-type
string
send: Sets the button in the bottom-right corner to "Send";
search: Sets the button in the bottom-right corner to "Search";
next: Sets the button in the bottom-right corner to "Next";
go: Sets the button in the bottom-right corner to "Go";
done: Sets the button in the bottom-right corner to "Done";
return: Sets the button in the bottom-right corner to “Carriage return”.
return
False
Specifies the text on the button in the bottom-right corner of the keyboard.
confirm-hold
boolean
-
false
False
Whether to keep the keyboard open when the button in the bottom-right corner is tapped.
bindfocus
eventhandle
-
-
False
Triggered when the input field gets focus. event.detail = { value, height }, where height is the keyboard height.
bindblur
eventhandle
-
-
False
Triggered when the input box loses focus, event.detail = {value, cursor}.
bindlinechange
eventhandle
-
-
False
This event is triggered when the number of lines in the input box changes, event.detail = {height: 0, heightRpx: 0, lineCount: 0}
bindinput
eventhandle
-
-
False
When keyboard input occurs, the input event is triggered, with event.detail = {value, cursor, keyCode}. The keyCode represents the key value, but currently, the tool does not support returning the keyCode parameter. The return value of the bindinput handler will not be reflected in the textarea.
bindconfirm
eventhandle
-
-
False
Triggered when the user taps the Done button, event.detail = {value: value}.
bindkeyboardheightchange
eventhandle
-
-
False
Triggered when the keyboard height changes, event.detail = {height: height, duration: duration}
Notes:
The blur event in textarea will be later than the tap event on the page. If you need to get the textarea in the tap event of the button, use bindsubmit of the form component.
It is not recommended to modify user input on multi-line text, so the return value of the bindinput processing function will not be reflected on the textarea.
When the keyboard height changes, the keyboardheightchange event may be triggered multiple times. Developers should ignore events with the same height value to avoid redundant processing.
Example:
WXML
JAVASCRIPT
<view class="section">
  <textarea bindblur="bindTextAreaBlur" auto-height placeholder="Automatic height adjustment" />
</view>
<view class="section">
  <textarea placeholder="The placeholder color is red" placeholder-style="color:red;"  />
</view>
<view class="section">
  <textarea placeholder="This is a textarea that can be automatically focused" auto-focus />
</view>
<view class="section">
  <textarea placeholder="This will only be focused when the button is tapped" focus="{{focus}}" />
  <view class="btn-area">
    <button bindtap="bindButtonTap">Make the input box focused</button>
  </view>
</view>
<view class="section">
  <form bindsubmit="bindFormSubmit">
    <textarea placeholder="Textarea in the form component" name="textarea"/>
    <button form-type="submit"> 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)
  }
})



Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

Contact our sales team or business advisors to help your business.

Contact Us
Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 available.

Submit a Ticket
7x24 Phone Support
Hong Kong, China
+852 800 906 020 (Toll Free)
United States
+1 844 606 0804 (Toll Free)
United Kingdom
+44 808 196 4551 (Toll Free)
Canada
+1 888 605 7930 (Toll Free)
Australia
+61 1300 986 386 (Toll Free)
EdgeOne hotline
+852 300 80699
More local hotlines coming soon