1# picker 2 3> **NOTE** 4> 5> This component is supported since API version 4. Updates will be marked with a superscript to indicate their earliest API version. 6 7The **\<picker>** component supports common, date, time, data and time, and multi-column text selectors. 8 9 10## Required Permissions 11 12None 13 14 15## Child Components 16 17Not supported 18 19 20## Attributes 21 22In addition to the [universal attributes](../arkui-js/js-components-common-attributes.md), the following attributes are supported. 23 24| Name | Type | Default Value | Mandatory | Description | 25| ---- | ------ | ---- | ---- | ---------------------------------------- | 26| type | string | - | No | Picker type. Dynamic modification is not supported. The options are as follows:<br>- **text**: text selector.<br>- **date**: date selector.<br>- **time**: time selector.<br>- **datetime**: date and time selector.<br>- **multi-text**: multi-column text selector.| 27 28 29### Common Selector 30 31When **type** is set to **text**, a common selector is used. 32 33| Name | Type | Default Value | Mandatory | Description | 34| -------- | ------ | ---- | ---- | ---------------------------------------- | 35| range | Array | - | No | Value range of the common selector, for example, **["15", "20", "25"]**.<br>Use the data binding mode, for example, `range = {{data}}`. Declare the corresponding variable `data: ["15", "20", "25"]` in JavaScript.| 36| selected | string | 0 | No | Default value of the common selector. The value should be the index of **range**.| 37| value | string | - | No | Value of the common selector. | 38 39 40### Date Selector 41 42When **type** is set to **date**, a date selector is used. 43 44| Name | Type | Default Value | Mandatory | Description | 45| ------------------ | ------------ | ---------- | ---- | ---------------------------------------- | 46| start | <time> | 1970-1-1 | No | Start date of the date selector, in the format of YYYY-MM-DD. | 47| end | <time> | 2100-12-31 | No | End date of the date selector, in the format of YYYY-MM-DD. | 48| selected | string | Current date | No | Default value of the date selector, in format of YYYY-MM-DD.| 49| value | string | - | Yes | Value of the date selector. | 50| lunar<sup>5+</sup> | boolean | false | No | Whether the pop-up window displays the lunar calendar. | 51| lunarswitch | boolean | false | No | Whether the date selector displays the lunar calendar switch, which is used to switch between the Gregorian calendar and lunar calendar. The value **true** means to display the lunar calendar switch for users to switch between the Gregorian calendar and lunar calendar. The value **false** means not to display the lunar calendar switch.<br>When both **lunarswitch** and **lunar** are set to **true**, the switch is selected.| 52 53 54### Time Selector 55 56When **type** is set to **time**, a time selector is used. 57 58| Name | Type | Default Value | Mandatory | Description | 59| ------------- | ------- | ----------------------------------- | ---- | ---------------------------------------- | 60| containsecond | boolean | false | No | Whether seconds are contained. | 61| selected | string | Current time | No | Default value of the time selector, in format of HH:mm. If seconds are contained, the format is HH:mm:ss.<br> | 62| value | string | - | No | Value of the time selector. | 63| hours | number | 24<sup>1-4</sup><br>-<sup>5+</sup> | No | Time format used by the time selector. Available values are as follows:<br>- **12**: displayed in 12-hour format and distinguished by a.m. and p.m.<br>- **24**: displayed in 24-hour format.<br>Since API version 5, the default value is the most commonly-used hour format in the current locale.| 64 65 66### Date and Time Selector 67 68When **type** is set to **datetime**, a date and time selector is used. 69 70| Name | Type | Default Value | Mandatory | Description | 71| ------------------ | ------- | ----------------------------------- | ---- | ---------------------------------------- | 72| selected | string | Current date and time | No | Default value of the date and time selector. The value can be in either of the following formats:<br>- MM-DD-HH-mm<br>- YYYY-MM-DD-HH-mm<br>If the year is not set, the current year is used by default. The value you set is the date selected by default in the pop-up window.| 73| value | string | - | Yes | Value of the date and time selector. | 74| hours | number | 24<sup>1-4</sup><br>-<sup>5+</sup> | No | Time format used by the date and time selector. Available values are as follows:<br>- **12**: displayed in 12-hour format and distinguished by a.m. and p.m.<br>- **24**: displayed in 24-hour format.<br>Since API version 5, the default value is the most commonly-used hour format in the current locale.| 75| lunar<sup>5+</sup> | boolean | false | No | Whether the pop-up window displays the lunar calendar. | 76| lunarswitch | boolean | false | No | Whether the date selector displays the lunar calendar switch, which is used to switch between the Gregorian calendar and lunar calendar. The value **true** means to display the lunar calendar switch for users to switch between the Gregorian calendar and lunar calendar. The value **false** means not to display the lunar calendar switch.<br>When both **lunarswitch** and **lunar** are set to **true**, the switch is selected.| 77 78 79### Multi-Column Text Selector 80 81When **type** is set to **multi-text**, a multi-column text selector is used. 82 83| Name | Type | Default Value | Mandatory | Description | 84| -------- | ------- | --------- | ---- | ---------------------------------------- | 85| columns | number | - | Yes | Number of columns in the multi-column text selector. | 86| range | Two-dimensional array| - | No | Items of the multi-column text selector. **range** is a two-dimensional array that indicates the number of columns. Each item in the array indicates the data of each column, for example, **[["a", "b"], ["c", "d"]]**.<br>Use the data binding mode, for example, `range = {{data}}`. Declare the corresponding variable `data: ["15", "20", "25"]` in JavaScript.| 87| selected | Array | [0,0,0, ...]| No | Default value of the multi-column text selector, which is an array consisting of the indexes of the selected items in each column.| 88| value | Array | - | No | Value of the multi-column text selector, which is an array consisting of the values of the selected items in each column. | 89 90 91## Styles 92 93In addition to the [universal styles](../arkui-js/js-components-common-styles.md), the following styles are supported. 94 95| Name | Type | Default Value | Mandatory | Description | 96| -------------------------- | -------------------------- | ---------- | ---- | ---------------------------------------- | 97| text-color | <color> | - | No | Text color of the selector. | 98| font-size | <length> | - | No | Font size of the selector. | 99| allow-scale | boolean | true | No | Whether the font size changes with the system's font size settings.<br>If the **config-changes** tag of **fontSize** is configured for abilities in the **config.json** file, the setting takes effect without application restart.| 100| letter-spacing | <length> | 0 | No | Letter spacing of the selector. For details, see **letter-spacing** in the **[\<text>](../arkui-js/js-components-basic-text.md#styles)** component.| 101| text-decoration | string | - | No | Text decoration of the selector. For details, see **text-decoration** in the **[\<text>](../arkui-js/js-components-basic-text.md#styles)** component.| 102| font-style | string | normal | No | Font style of the selector. For details, see **font-style** in the **[\<text>](../arkui-js/js-components-basic-text.md#styles)** component.| 103| font-weight | number \| string | normal | No | Font weight of the selector. For details, see **font-weight** in the **[\<text>](../arkui-js/js-components-basic-text.md#styles)** component.| 104| font-family | string | sans-serif | No | Font family, in which fonts are separated by commas (,). Each font is set using a font name or font family name. The first font in the family or the specified [custom font](../arkui-js/js-components-common-customizing-font.md) is used for the text.| 105| line-height | <length> | 0px | No | Text line height of the selector. | 106| column-height<sup>5+</sup> | <length> | - | No | Height of the selector option list. | 107 108 109## Events 110 111In addition to the [universal events](../arkui-js/js-components-common-events.md), the following events are supported. 112 113 114### Common Selector 115 116| Name | Parameter | Description | 117| ------ | ---------------------------------------- | ---------------------------------------- | 118| change | { newValue: newValue, newSelected: newSelected } | Triggered when an item is selected and the OK button is clicked in the displayed pop-up window. **newSelected** is the index.| 119| cancel | - | Triggered when the cancel button is clicked. | 120 121 122### Date Selector 123 124| Name | Parameter | Description | 125| ------ | ---------------------------------------- | ---------------------------------------- | 126| change | { year: year, month: month, day: day } | Triggered when an item is selected and the OK button is clicked in the displayed pop-up window.<br>The value of **month** ranges from **0** (January) to **11** (December) since API version 5.| 127| cancel | - | Triggered when the cancel button is clicked. | 128 129 130### Date and Time Selector 131 132| Name | Parameter | Description | 133| ------ | ---------------------------------------- | ---------------------------- | 134| change | { year: year, month: month, day: day, hour: hour, minute: minute} | Triggered when an item is selected and the OK button is clicked in the displayed pop-up window.| 135| cancel | - | Triggered when the cancel button is clicked. | 136 137 138### Time Selector 139 140| Name | Parameter | Description | 141| ------ | ---------------------------------------- | ---------------------------------------- | 142| change | { hour: hour, minute: minute, [second: second] } | Triggered when an item is selected and the OK button is clicked in the displayed pop-up window. If **containsecond** is set to true, value contains seconds.| 143| cancel | - | Triggered when the cancel button is clicked. | 144 145 146### Multi-Column Text Selector 147 148| Name | Parameter | Description | 149| ------------ | ---------------------------------------- | ---------------------------------------- | 150| change | { newValue: [newValue1, newValue2, newValue3, …], newSelected:[newSelected1, newSelected2, newSelected3, …] } | Triggered when an item is selected and the OK button is clicked in the displayed pop-up window.<br>- **newValue** is an array consisting of the values of the selected items.<br>- **newSelected** is an array consisting of the indexes of the selected items. The lengths of **newValue** and **newSelected** are the same as the length of **range**.| 151| columnchange | { column: column, newValue: newValue, newSelected: newSelected } | Triggered when the value of a column in the multi-column selector changes.<br>- **column**: column whose value has changed.<br>- **newValue**: selected value.<br>- **newSelected**: index of the selected value.| 152| cancel | - | Triggered when the cancel button is clicked. | 153 154 155## Methods 156 157In addition to the [universal methods](../arkui-js/js-components-common-methods.md), the following methods are supported. 158 159| Name | Parameter | Description | 160| ---- | ---- | --------------- | 161| show | - | Shows the picker.| 162 163 164## Example 165 166```html 167<!-- xxx.hml --> 168<div class="container"> 169 <select @change="selectChange"> 170 <option value="{{ item }}" for="item in selectList"> 171 {{ item }} 172 </option> 173 </select> 174 <picker id="picker0" type="text" value="{{ textvalue }}" selected="{{ textselect }}" range="{{ rangetext }}" 175 onchange="textonchange" 176 oncancel="textoncancel" class="pickertext" show="false"></picker> 177 178 <picker id="picker1" type="date" value="{{ datevalue }}" start="2002-2-5" end="2030-6-5" selected="{{ dateselect }}" 179 lunarswitch="true" 180 onchange="dateonchange" oncancel="dateoncancel" class="pickerdate" show="false"></picker> 181 182 <picker id="picker2" type="time" value="{{ timevalue }}" containsecond="{{ containsecond }}" 183 selected="{{ timeselect }}" hours="12" 184 onchange="timeonchange" oncancel="timeoncancel" class="pickertime" show="false"></picker> 185 186 <picker id="picker3" type="datetime" value="{{ datetimevalue }}" selected="{{ datetimeselect }}" hours="24" 187 lunarswitch="true" 188 onchange="datetimeonchange" oncancel="datetimeoncancel" class="pickerdatetime" show="false"></picker> 189 190 <picker id="picker4" type="multi-text" value="{{ multitextvalue }}" columns="3" range="{{ multitext }}" 191 selected="{{ multitextselect }}" 192 onchange="multitextonchange" oncancel="multitextoncancel" class="pickermuitl" show="false"></picker> 193</div> 194``` 195 196```css 197/* xxx.css */ 198.container { 199 flex-direction: column; 200 justify-content: center; 201 align-items: center; 202} 203 204picker { 205 width: 60%; 206 height: 80px; 207 border-radius: 20px; 208 text-color: white; 209 font-size: 15px; 210 background-color: #4747e3; 211 margin-left: 20%; 212} 213 214select { 215 background-color: #efecec; 216 height: 50px; 217 width: 60%; 218 margin-left: 20%; 219 margin-top: 300px; 220 margin-bottom: 50px; 221 font-size: 22px; 222} 223``` 224 225```js 226// xxx.js 227import router from '@system.router'; 228import prompt from '@system.prompt'; 229 230export default { 231 data: { 232 selectList: ["text", "data", "time", "datetime", "multitext"], 233 rangetext: ['15', "20", "25"], 234 multitext: [["a", "b", "c"], ["e", "f", "g"], ["h", "i"], ["k", "l", "m"]], 235 textvalue: 'default textvalue', 236 datevalue: 'default datevalue', 237 timevalue: 'default timevalue', 238 datetimevalue: 'default datetimevalue', 239 multitextvalue: 'default multitextvalue', 240 containsecond: true, 241 multitextselect: [1, 2, 0], 242 datetimeselect: '2012-5-6-11-25', 243 timeselect: '11:22:30', 244 dateselect: '2021-3-2', 245 textselect: '2' 246 }, 247 selectChange(e) { 248 for (let i = 0;i < this.selectList.length; i++) { 249 if (e.newValue == this.selectList[i]) { 250 this.$element("picker" + i).show(); 251 } 252 } 253 }, 254 textonchange(e) { 255 this.textvalue = e.newValue; 256 prompt.showToast({ 257 message: "text:" + e.newValue + ",newSelected:" + e.newSelected 258 }) 259 }, 260 textoncancel(e) { 261 prompt.showToast({ 262 message: "text: textoncancel" 263 }) 264 }, 265 dateonchange(e) { 266 this.datevalue = e.year + "-" + e.month + "-" + e.day; 267 prompt.showToast({ 268 message: "date:" + e.year + "-" + (e.month + 1) + "-" + e.day 269 }) 270 }, 271 dateoncancel() { 272 prompt.showToast({ 273 message: "date: dateoncancel" 274 }) 275 }, 276 timeonchange(e) { 277 if (this.containsecond) { 278 this.timevalue = e.hour + ":" + e.minute + ":" + e.second; 279 prompt.showToast({ 280 message: "Time:" + e.hour + ":" + e.minute + ":" + e.second 281 }) 282 } else { 283 this.timevalue = e.hour + ":" + e.minute; 284 prompt.showToast({ 285 message: "Time:" + e.hour + ":" + e.minute 286 }) 287 } 288 }, 289 timeoncancel() { 290 prompt.showToast({ 291 message: "timeoncancel" 292 }) 293 }, 294 datetimeonchange(e) { 295 this.datetimevalue = e.year + "-" + e.month + "-" + e.day + " " + e.hour + ":" + e.minute; 296 prompt.showToast({ 297 message: "Time:" + (e.month + 1) + "-" + e.day + " " + e.hour + ":" + e.minute 298 }) 299 }, 300 datetimeoncancel() { 301 prompt.showToast({ 302 message: "datetimeoncancel" 303 }) 304 }, 305 multitextonchange(e) { 306 this.multitextvalue = e.newValue; 307 prompt.showToast({ 308 message: "Multi-column text change" + e.newValue 309 }) 310 }, 311 multitextoncancel() { 312 prompt.showToast({ 313 message: "multitextoncancel" 314 }) 315 }, 316 popup_picker() { 317 this.$element("picker_text").show(); 318 }, 319} 320``` 321 322 323
