# Form Components
# Form Component Description
| Component | Description | Minimum Version |
|---|---|---|
| button | Button | 1.0.0 |
| checkbox-group | Multiple choice selector, composed of multiple checkboxes internally | 1.0.0 |
| checkbox | Multiple choice item | 1.0.0 |
| form | Form | 1.0.0 |
| input | Input box | 1.0.0 |
| label | Used to improve the usability of form components | 1.0.0 |
| picker | Scroll selector that pops up from the bottom, currently supports three types of selectors, distinguished by mode: normal selector, time selector, date selector; default is normal selector | 1.0.0 |
| picker-view | Scroll selector embedded in the page | 1.0.0 |
| picker-view-column | Scroll selector sub-item | 1.0.0 |
| radio-group | Single-choice selector, composed of multiple radios internally | 1.0.0 |
| radio | Single-choice item | 1.0.0 |
| slider | Slider selector | 1.0.0 |
| switch | Switch selector | 1.0.0 |
| textarea | Multi-line input box | 1.0.0 |
| editor | Rich text editor | 2.5.2 |
| editor-portal | Custom block used to render the editor component | 3.10.1 |
| keyboard-accessory | Sets the toolbar view above the keyboard when input/textarea is focused (cover-view/cover-image) | 2.11.6 |
# button
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| size | string | default | No | Button size | 1.0.0 |
| type | string | default | No | Button style type | 1.0.0 |
| plain | boolean | false | No | Whether the button is hollow with a transparent background color | 1.0.0 |
| disabled | boolean | false | No | Whether disabled | 1.0.0 |
| loading | boolean | false | No | Whether to show a loading icon before the name | 1.0.0 |
| form-type | string | No | Used for form components; clicking triggers submit/reset events of the form component respectively | 1.0.0 | |
| open-type | string | No | Open capabilities | 2.12.11 | |
| hover-class | string | button-hover | No | Specifies the style class when the button is pressed. When hover-class="none", there will be no click effect | 2.11.4 |
| hover-stop-propagation | boolean | false | No | Specifies whether to prevent ancestor nodes from showing click effects | 2.11.4 |
| hover-start-time | number | 20 | No | Time in milliseconds after which the click effect appears when pressed | 2.11.4 |
| hover-stay-time | number | 70 | No | Duration in milliseconds the click effect stays after releasing | 2.11.4 |
| lang | string | en | No | Specifies the language of the returned user information: zh_CN (Simplified Chinese), zh_TW (Traditional Chinese), en (English). | Not supported |
| session-from | string | No | Session source, valid when open-type="contact" | 2.12.11 | |
| send-message-title | string | Current title | No | Title of the message card within the session, valid when open-type="contact" | 2.12.11 |
| send-message-path | Current share path | default | No | Mini-program path to jump to when clicking the message card within the session, valid when open-type="contact" | 2.12.11 |
| send-message-img | string | Screenshot | No | Image of the message card within the session, valid when open-type="contact" | 2.12.11 |
| app-parameter | string | No | Parameters passed to the APP when opening it, valid when open-type=launchApp | 2.12.11 | |
| show-message-card | boolean | false | No | Whether to display the message card within the session. Setting this parameter to true shows "Mini-program may be sent" prompt at the bottom right when the user enters customer service chat. Clicking it allows quick sending of mini-program messages, valid when open-type="contact" | 2.12.11 |
| bindgetuserinfo | eventhandle | No | Returns user information when the user clicks the button. The callback detail data is consistent with ft.getUserInfo, valid when open-type="getUserInfo" | 2.12.11 | |
| bindcontact | eventhandle | No | Customer service message callback, valid when open-type="contact" | Not supported | |
| bindgetphonenumber | eventhandle | No | Callback to get the user's phone number, valid when open-type=getPhoneNumber | 2.12.11 | |
| binderror | eventhandle | No | Error callback when using open capabilities, valid when open-type=launchApp | 2.12.11 | |
| bindopensetting | eventhandle | No | Callback after opening the authorization settings page, valid when open-type=openSetting | 2.12.11 | |
| bindlaunchapp | eventhandle | No | Successful callback when opening the APP, valid when open-type=launchApp | 2.12.11 | |
| bindchooseavatar | eventhandle | No | Successful callback when opening the APP, valid when open-type=launchApp | 2.12.11 |
# Valid values for size
| Value | Description | Minimum Version |
|---|---|---|
| default | Default size | |
| mini | Small size |
# Valid values for type
| Value | Description | Minimum Version |
|---|---|---|
| primary | Green | |
| default | White | |
| warn | Red |
# Valid values for form-type
| Value | Description | Minimum Version |
|---|---|---|
| submit | Submit form | |
| reset | Reset form |
# Valid values for open-type
| Value | Description | Minimum Version |
|---|---|---|
| contact | Open customer service session | 2.12.11 |
| share | Trigger user sharing | 2.12.11 |
| getPhoneNumber | Get user's phone number, can retrieve user info via bindgetphonenumber callback | 2.12.11 |
| getUserInfo | Get user info, can retrieve user info via bindgetuserinfo callback | 2.12.11 |
| launchApp | Open APP, can set parameters passed to APP via app-parameter attribute | 2.12.11 |
| openSetting | Open authorization settings page | 2.12.11 |
| feedback | Open feedback page | 2.12.11 |
| chooseAvatar | Get user avatar, can retrieve avatar info via bindchooseavatar callback | 2.12.11 |
Note that functions such as contact, getPhoneNumber, feedback, chooseAvatar are not implemented in the SDK. When calling these functions, parameters will be passed through to the APP, and the APP needs to implement the related functions itself. For details, refer to the APP documentation:
# Valid values for lang
| Value | Description | Minimum Version |
|---|---|---|
| en | English | |
| zh_CN | Simplified Chinese | |
| zh_TW | Traditional Chinese |
# checkbox
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| color | string | #09BB07 | No | Checkbox color, same as CSS color | 1.0.0 |
| value | string | No | Checkbox identifier, triggers checkbox-group's change event when selected, carrying the checkbox's value | 2.11.4 | |
| disabled | boolean | false | No | Whether disabled | 2.11.4 |
| checked | boolean | false | No | Whether currently selected, can be used to set default selection | 2.11.4 |
# checkbox-group
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| bindchange | EventHandle | No | Triggers change event when the selected item in checkbox-group changes, detail = {value:[array of selected checkbox values]} | 2.11.4 |
# editor
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| read-only | boolean | false | No | Set the editor to read-only | 2.7.0 |
| placeholder | string | No | Placeholder text | 2.7.0 | |
| show-img-size | boolean | false | No | Show image size control when clicking on an image | 2.7.0 |
| show-img-toolbar | boolean | false | No | Show toolbar control when clicking on an image | 2.7.0 |
| show-img-resize | boolean | false | No | Show resize control when clicking on an image | 2.7.0 |
| hold-keyboard | boolean | false | No | Do not dismiss the keyboard when clicking on the page while focused | 3.9.3 |
| bindready | eventhandle | No | Triggered when the editor initialization is complete | 2.7.0 | |
| bindfocus | eventhandle | No | Triggered when the editor gains focus, event.detail = {html, text, delta} | 2.7.0 | |
| bindblur | eventhandle | No | Triggered when the editor loses focus, detail = {html, text, delta} | 2.7.0 | |
| bindinput | eventhandle | No | Triggered when the editor content changes, detail = {html, text, delta} | 2.7.0 | |
| bindstatuschange | eventhandle | No | Triggered when changing styles inside the editor via Context methods, returns the styles set in the selection | 2.7.0 |
# editor-portal
Supported starting from Base Library 3.0.45, Android SDK 2.40.11.
Custom block used to render the editor component, related interface EditorContext.insertCustomBlock.
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| key | string | Yes | blockId of the custom block |
Notes
- Use EditorContext.insertCustomBlock to insert a custom block (only a placeholder at this point), and obtain the returned blockId;
- Render the
editor-portalcomponent, specifying the key attribute as blockId; the content ofeditor-portalwill be inserted at the position of the custom block; - Due to the underlying rendering reasons of native components, it is not recommended to use native components as custom blocks. There might be exceptions when native components are non-co-layer components.
Example Code
<editor id="editor">
<block ft:for="{{customBlockList}}" ft:key="blockId">
<editor-portal key="{{item.blockId}}">
<view class="flex"></view>
</editor-portal>
</block>
</editor>
Page({
insertCustomBlock() {
const { customBlockList } = this.data
this.editorContext.insertCustomBlock({
success:(res) => {
customBlockList.push({
blockId: res.blockId
})
this.setData({ customBlockList })
}
})
}
})
# form
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| report-submit | boolean | false | No | Whether to return formId for sending template messages | 1.0.0 |
| bindsubmit | eventhandle | No | Triggers submit event with form data, event.detail = {value : {'name': 'value'} , formId: ''} | 1.0.0 | |
| bindreset | eventhandle | No | Triggers reset event when the form is reset | 1.0.0 | |
| report-submit-timeout | number | 0 | No | Wait for a period of time (in milliseconds) to confirm if formId takes effect. If this parameter is not specified, there is a small probability that formId might be invalid (e.g., in case of network failure). Specifying this parameter allows detecting if formId is valid, using this parameter's time as the timeout for this detection. If failed, it will return formId starting with requestFormId:fail | Not supported |
# label
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| for | string | No | ID of the bound control | 1.0.0 |
# picker
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| mode | string | selector | No | Selector type | 1.0.0 |
| disabled | boolean | false | No | Whether disabled | 1.0.0 |
| confirm-color | string | #586c94 | No | Confirm button text color | 1.0.0 |
| cancel-color | string | #586c94 | No | Cancel button text color | 1.0.0 |
| bindcancel | eventhandle | No | Triggered when selection is canceled | ||
| header-text | string | No | Title of the selector, only available on Android | Not supported |
# Valid values for mode
| Value | Description | Minimum Version |
|---|---|---|
| selector | Normal selector | |
| multiSelector | Multi-column selector | |
| time | Time selector | |
| date | Date selector | |
| region | Province/City/District selector |
In addition to the above common attributes, picker has different attributes for different modes.
# Multi-column selector: mode = multiSelector
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| range | array/object array | [] | No | Effective when mode is selector or multiSelector | |
| range-key | string | No | Effective when mode is selector or multiSelector | ||
| value | array | [] | No | Indicates which one in range is selected (index starts from 0) | |
| bindchange | eventhandle | No | Triggers change event when value changes, event.detail = {value} | ||
| bindcolumnchange | eventhandle | No | Triggers when column changes |
# Multi-column selector: mode = time
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| value | string | No | Represents the selected time, format is "hh:mm" | ||
| start | string | No | Represents the start of the valid time range, format is "hh:mm" | ||
| end | string | No | Represents the end of the valid time range, format is "hh:mm" | ||
| bindchange | eventhandle | No | Triggers change event when value changes, event.detail = {value} |
# Multi-column selector: mode = date
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| value | string | Today | No | Represents the selected date, format is "YYYY-MM-DD" | |
| start | string | No | Represents the start of the valid date range, format is "YYYY-MM-DD" | ||
| end | string | No | Represents the end of the valid date range, format is "YYYY-MM-DD" | ||
| fields | string | day | No | Valid values: year, month, day, indicating the granularity of the selector | |
| bindchange | eventhandle | No | Triggers change event when value changes, event.detail = {value} |
# Valid values for fields:
| Value | Description | Minimum Version |
|---|---|---|
| year | Selector granularity is year | |
| month | Selector granularity is month | |
| day | Selector granularity is day |
# Multi-column selector: mode = region
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| value | array | [] | No | Represents the selected province/city/district, default selects the first value of each column | |
| custom-item | string | No | Can add a custom item at the top of each column | ||
| level | string | No | region | Selector hierarchy | |
| bindchange | eventhandle | No | Triggers change event when value changes, event.detail = {value, code, postcode}, where code is the statistical division code, postcode is the postal code |
# picker-view
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| value | Array | No | Numbers in the array sequentially indicate which item (index starts from 0) is selected in picker-view's picker-view-column. If the number is greater than the length of picker-view-column options, the last option is selected. | 1.0.0 | |
| indicator-style | string | No | Sets the style of the middle selection box in the picker | 1.0.0 | |
| indicator-class | string | No | Sets the class name of the middle selection box in the picker | 2.11.4 | |
| immediate-change | boolean | false | No | Whether to immediately trigger the change event when the finger is released. If not enabled, the change event will be triggered after the scrolling animation ends. | Not supported |
| mask-style | string | No | Sets the style of the mask layer | 2.11.4 | |
| mask-class | string | No | Sets the class name of the mask layer | 2.11.4 | |
| bindchange | eventhandle | No | Triggers change event when scrolling selection, event.detail = {value}; value is an array, indicating which item (index starts from 0) is currently selected in picker-view's picker-view-column | 2.11.4 | |
| bindpickstart | eventhandle | No | Triggers when scrolling selection starts | 2.11.4 | |
| bindpickend | eventhandle | No | Triggers when scrolling selection ends | 2.11.4 |
# picker-view-column
Scroll selector sub-item. Can only be placed inside picker-view, and its child node height will automatically be set to match the height of picker-view's selection box.
# radio
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| color | string | #09BB07 | No | Radio color, same as CSS color | 1.0.0 |
| value | string | No | Radio identifier. When this radio is selected, radio-group's change event carries the radio's value | 2.11.4 | |
| checked | boolean | false | No | Whether currently selected | 2.11.4 |
| disabled | boolean | false | No | Whether disabled | 2.11.4 |
# radio-group
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| bindchange | EventHandle | No | Triggers change event when the selected item in radio-group changes, detail = {value:[array of selected radio values]} | 2.11.4 |
# slider
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| min | number | 0 | No | Minimum value | 1.0.0 |
| max | number | 100 | No | Maximum value | 1.0.0 |
| step | number | 1 | No | Step size, must be greater than 0 and divisible by (max - min) | 1.0.0 |
| disabled | boolean | false | No | Whether disabled | 1.0.0 |
| value | number | 0 | No | Current value | 1.0.0 |
| color | color | #e9e9e9 | No | Background bar color (please use backgroundColor) | 1.0.0 |
| selected-color | color | #1aad19 | No | Selected color (please use activeColor) | 1.0.0 |
| show-value | boolean | false | No | Whether to display current value | 1.0.0 |
| bindchange | eventhandle | No | Triggers event after completing a drag, event.detail = {value} | 1.0.0 | |
| activeColor | color | #1aad19 | No | Selected color | 2.11.4 |
| backgroundColor | color | #e9e9e9 | No | Background bar color | 2.11.4 |
| block-size | number | 28 | No | Slider size, range is 12 - 28 | 2.11.4 |
| block-color | color | #ffffff | No | Slider color | 2.11.4 |
| bindchanging | eventhandle | No | Triggers event during dragging, event.detail = {value} | 2.11.4 |
# switch
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| checked | boolean | false | No | Whether selected | 1.0.0 |
| disabled | boolean | false | No | Whether disabled | 1.0.0 |
| type | string | switch | No | Style, valid values: switch, checkbox | 1.0.0 |
| color | string | #04BE02 | No | Switch color, same as CSS color | 1.0.0 |
| bindchange | eventhandle | No | Triggers change event when checked changes, event.detail={ value} | 1.0.0 |
# input
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| value | string | Yes | Initial content of the input box | 2.11.4 | |
| type | string | text | No | Type of the input | 2.11.4 |
| password | boolean | false | No | Whether it is a password type | 2.11.4 |
| placeholder | string | Yes | Placeholder when the input box is empty | 2.11.4 | |
| placeholder-style | string | Yes | Specify the style of the placeholder | 2.11.4 | |
| placeholder-class | string | input-placeholder | No | Specify the style class of the placeholder | 2.11.4 |
| disabled | boolean | false | No | Whether to disable | 2.11.4 |
| maxlength | number | 140 | No | Maximum input length, setting to -1 means no maximum length limit | 2.11.4 |
| cursor-spacing | number | 0 | No | Specify the distance between the cursor and the keyboard, taking the minimum value of the input's distance from the bottom and the specified cursor-spacing as the distance between the cursor and the keyboard | |
| auto-focus | boolean | false | No | (Deprecated, please use focus directly) Automatically focus and bring up the keyboard | |
| focus | boolean | false | No | Get focus | |
| confirm-type | string | done | No | Set the text of the button at the bottom right of the keyboard, only effective when type='text' | |
| cursor | number | Yes | Specify the cursor position when focused | ||
| confirm-hold | boolean | false | No | Whether to keep the keyboard from retracting when clicking the button at the bottom right of the keyboard | |
| selection-start | number | -1 | No | Starting position of the cursor, effective when automatically focused, must be used with selection-end | |
| selection-end | number | -1 | No | Ending position of the cursor, effective when automatically focused, must be used with selection-start | |
| adjust-position | boolean | true | No | Whether to automatically push the page up when the keyboard pops up | |
| hide-keyboard-when-scroll | boolean | false | No | By default, the input will have logic to dismiss the keyboard when the user scrolls the page, but some non-user-triggered scrolls won't dismiss it. This attribute can control whether the input forcibly dismisses the keyboard during non-user-triggered scroll behaviors on the page | 3.5.1 |
| bindinput | eventhandle | Yes | Triggered when typing on the keyboard, event.detail = {value, cursor, keyCode}, keyCode is the key value, supported since version 2.1.0. The handler function can directly return a string to replace the content of the input box. | ||
| bindfocus | eventhandle | Yes | Triggered when the input box gains focus, event.detail = { value, height }, height is the keyboard height | ||
| bindblur | eventhandle | Yes | Triggered when the input box loses focus, event.detail = {value: value} | ||
| bindconfirm | eventhandle | Yes | Triggered when the "Done" button is clicked, event.detail = {value: value} | ||
| bindkeyboardheightchange | eventhandle | Yes | Triggered when the keyboard height changes, event.detail = {height: height, duration: duration} | ||
| always-embed | boolean | false | No | Force the input to remain in the same layer state; by default, the input switches to a non-same-layer state when focused (only effective on iOS) | Not Supported |
| hold-keyboard | boolean | false | No | When focused, clicking elsewhere on the page does not dismiss the keyboard | |
| safe-password-cert-path | string | No | Path to the public key for secure keyboard encryption, only supports paths within the package | Not Supported | |
| safe-password-length | number | No | Length of the password entered via the secure keyboard | Not Supported | |
| safe-password-time-stamp | number | No | Timestamp for secure keyboard encryption | Not Supported | |
| safe-password-nonce | string | No | Salt value for secure keyboard encryption | Not Supported | |
| safe-password-salt | string | No | Salt value for secure keyboard hash calculation; if custom-hash is specified, this is invalid | Not Supported | |
| safe-password-custom-hash | string | No | Expression for the algorithm to calculate the hash for the secure keyboard, e.g., md5(sha1('foo' + sha256(sm3(password + 'bar')))) | Not Supported |
# Legal values for type
| Value | Description | Minimum Version |
|---|---|---|
| text | Text input keyboard | |
| number | Numeric input keyboard | |
| idcard | ID card input keyboard | |
| digit | Numeric keyboard with decimal point |
# Legal values for confirm-type
| Value | Description | Minimum Version |
|---|---|---|
| send | Bottom-right button is "Send" | |
| search | Bottom-right button is "Search" | |
| next | Bottom-right button is "Next" | |
| go | Bottom-right button is "Go" | |
| done | Bottom-right button is "Done" |
# textarea
| Attribute | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| value | string | No | Content of the input box | ||
| placeholder | string | No | Placeholder when the input box is empty | ||
| placeholder-style | string | No | Specify the style of the placeholder, currently only supports color, font-size, and font-weight | ||
| placeholder-class | string | textarea-placeholder | No | Specify the style class of the placeholder | |
| disabled | boolean | false | No | Whether to disable | |
| maxlength | number | 140 | No | Maximum input length, setting to -1 means no maximum length limit | |
| auto-focus | boolean | false | No | Automatically focus and bring up the keyboard | |
| focus | boolean | false | No | Get focus | |
| auto-height | boolean | false | No | Whether to automatically increase height; when set, style.height does not take effect | |
| cursor-spacing | number | 0 | No | Specify the distance between the cursor and the keyboard. Takes the minimum value of the textarea's distance from the bottom and the specified cursor-spacing as the distance between the cursor and the keyboard | |
| cursor | number | -1 | No | Specify the cursor position when focused | |
| show-confirm-bar | boolean | true | No | Whether to display the bar above the keyboard with the "Done" button | |
| selection-start | number | -1 | No | Starting position of the cursor, effective when automatically focused, must be used with selection-end | |
| selection-end | number | -1 | No | Ending position of the cursor, effective when automatically focused, must be used with selection-start | |
| adjust-position | boolean | true | No | Whether to automatically push the page up when the keyboard pops up | |
| hold-keyboard | boolean | false | No | When focused, clicking elsewhere on the page does not dismiss the keyboard | |
| disable-default-padding | boolean | false | No | Whether to remove the default padding on iOS | |
| bindfocus | eventhandle | No | Triggered when the input box gains focus, event.detail = { value, height }, height is the keyboard height, supported since base library version 1.9.90 | ||
| bindblur | eventhandle | No | Triggered when the input box loses focus, event.detail = {value, cursor} | ||
| bindlinechange | eventhandle | No | Called when the number of lines in the input box changes, event.detail = {height: 0, heightRpx: 0, lineCount: 0} | ||
| bindinput | eventhandle | No | Triggered when typing on the keyboard, event.detail = {value, cursor, keyCode}, keyCode is the key value. Currently, the tool does not support returning the keyCode parameter. The return value of the bindinput handler function will not reflect on the textarea | ||
| bindconfirm | eventhandle | No | Triggered when the "Done" button is clicked, event.detail = {value: value} | ||
| bindkeyboardheightchange | eventhandle | No | Triggered when the keyboard height changes, event.detail = {height: height, duration: duration} |
# keyboard-accessory
tip: The maximum height of the view is 200px.
Example code:
<textarea hold-keyboard="{{true}}">
<keyboard-accessory class="container" style="height: 50px;">
<cover-view bindtap="tap" style="flex: 1; background: green;">1</cover-view>
<cover-view bindtap="tap" style="flex: 1; background: red;">2</cover-view>
</keyboard-accessory>
</textarea>