1# CalendarPicker 2 3The **CalendarPicker** component provides a drop-down calendar for users to select a date. 4 5> **NOTE** 6> 7> This component is supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Child Components 11 12Not supported 13 14## APIs 15 16CalendarPicker(options?: CalendarOptions) 17 18Creates a calendar picker. 19 20**Atomic service API**: This API can be used in atomic services since API version 11. 21 22**System capability**: SystemCapability.ArkUI.ArkUI.Full 23 24**Parameters** 25 26| Name | Type | Mandatory| Description | 27| ------- | ------------------------------------------- | ---- | -------------------------- | 28| options | [CalendarOptions](#calendaroptions) | No | Parameters of the calendar picker.| 29 30## Attributes 31 32In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 33 34### edgeAlign 35 36edgeAlign(alignType: CalendarAlign, offset?: Offset) 37 38How the picker is aligned with the entry component. 39 40**Atomic service API**: This API can be used in atomic services since API version 11. 41 42**System capability**: SystemCapability.ArkUI.ArkUI.Full 43 44**Parameters** 45 46| Name | Type | Mandatory| Description | 47| --------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 48| alignType | [CalendarAlign](#calendaralign) | Yes | Alignment type.<br>Default value: **CalendarAlign.END** | 49| offset | [Offset](ts-types.md#offset) | No | Offset of the picker relative to the entry component after alignment based on the specified alignment type.<br>Default value: **{dx: 0, dy: 0}**| 50 51### edgeAlign<sup>18+</sup> 52 53edgeAlign(alignType: Optional\<CalendarAlign>, offset?: Offset) 54 55How the picker is aligned with the entry component. Compared to [edgeAlign](#edgealign), this API supports the **undefined** type for the **alignType** parameter. 56 57**Atomic service API**: This API can be used in atomic services since API version 18. 58 59**System capability**: SystemCapability.ArkUI.ArkUI.Full 60 61**Parameters** 62 63| Name | Type | Mandatory| Description | 64| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 65| alignType | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[CalendarAlign](#calendaralign)> | Yes | Alignment type.<br>If **alignType** is set to **undefined**, the default value **CalendarAlign.END** is used.| 66| offset | [Offset](ts-types.md#offset) | No | Offset of the picker relative to the entry component after alignment based on the specified alignment type.<br>Default value: **{dx: 0, dy: 0}**| 67 68### textStyle 69 70textStyle(value: PickerTextStyle) 71 72Sets the font color, font size, and font weight in the entry area. 73 74**Atomic service API**: This API can be used in atomic services since API version 11. 75 76**System capability**: SystemCapability.ArkUI.ArkUI.Full 77 78**Parameters** 79 80| Name| Type | Mandatory| Description | 81| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 82| value | [PickerTextStyle](./ts-basic-components-datepicker.md#pickertextstyle10) | Yes | Font color, font size, and font weight in the entry area.<br>Default value:<br>{<br>color: '#ff182431',<br>font: {<br>size: '16fp', <br>weight: FontWeight.Regular<br>}<br>} | 83 84### textStyle<sup>18+</sup> 85 86textStyle(style: Optional\<PickerTextStyle>) 87 88Sets the font color, font size, and font weight in the entry area. Compared to [textStyle](#textstyle), this API supports the **undefined** type for the **style** parameter. 89 90**Atomic service API**: This API can be used in atomic services since API version 18. 91 92**System capability**: SystemCapability.ArkUI.ArkUI.Full 93 94**Parameters** 95 96| Name| Type | Mandatory| Description | 97| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 98| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](./ts-basic-components-datepicker.md#pickertextstyle10)> | Yes | Font color, font size, and font weight in the entry area.<br>If **style** is set to **undefined**, the default value is used:<br>{<br>color: '#ff182431',<br>font: {<br>size: '16fp', <br>weight: FontWeight.Regular<br>}<br>} | 99 100## Events 101 102In addition to the [universal events](ts-component-general-events.md), the following events are supported. 103 104### onChange 105 106onChange(callback: Callback\<Date>) 107 108Triggered when a date is selected. 109 110**Atomic service API**: This API can be used in atomic services since API version 11. 111 112**System capability**: SystemCapability.ArkUI.ArkUI.Full 113 114**Parameters** 115 116| Name| Type| Mandatory| Description | 117| ------ | ---- | ---- | -------------- | 118| callback | [Callback](ts-types.md#callback12)\<Date> | Yes | Selected date value| 119 120### onChange<sup>16+</sup> 121 122onChange(callback: Optional\<Callback\<Date>>) 123 124Triggered when a date is selected. Compared to [onChange](#onchange), this API supports the **undefined** type for the **callback** parameter. 125 126**Atomic service API**: This API can be used in atomic services since API version 16. 127 128**System capability**: SystemCapability.ArkUI.ArkUI.Full 129 130**Parameters** 131 132| Name | Type | Mandatory| Description | 133| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 134| callback | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[Callback](ts-types.md#callback12)\<Date>> | Yes | Selected date value<br>If **callback** is set to **undefined**, the callback function is not used.| 135 136## CalendarOptions 137 138**Atomic service API**: This API can be used in atomic services since API version 11. 139 140**System capability**: SystemCapability.ArkUI.ArkUI.Full 141 142| Name | Type | Mandatory | Description | 143| ----------- | ---------- | ------| --------------------------------- | 144| hintRadius | number \| [Resource](ts-types.md#resource) | No | Style of the background of the selected state.<br>Default value: The background is a circle.<br>**NOTE**<br>If the value is **0**, the background is a rectangle with square corners. If the value is in the 0–16 range, the background is a rectangle with rounded corners. If the value is greater than or equal to 16, the background is a circle.| 145| selected | Date | No | Date of the selected item. If the value is not set or does not comply with the date format specifications, the default value will be used.<br>Default value: current system date| 146| start<sup>18+</sup> | Date | No | Start date.| 147| end<sup>18+</sup> | Date | No | End date.| 148 149**Rules for setting start and end** 150 151| Scenario | Description | 152| -------- | ------------------------------------------------------------ | 153| The start date is later than the end date. | Both start and end dates are invalid, and the selected date is the default value. | 154| The selected date is earlier than the start date. | The selected date is set to the start date. | 155| The selected date is later than the end date. | The selected date is set to the end date. | 156| The start date is later than the current system date, and the selected date is not set. | The selected date is set to the start date. | 157| The end date is earlier than the current system date, and the selected date is not set. | The selected date is set to the end date. | 158| The set date is in invalid format, for example, **'1999-13-32'**.| The start or end date setting is invalid, and the selected date is the default value. | 159 160## CalendarAlign 161 162**Atomic service API**: This API can be used in atomic services since API version 11. 163 164**System capability**: SystemCapability.ArkUI.ArkUI.Full 165 166| Name | Description | 167| ------ | ------------------------ | 168| START | The picker is left aligned with the entry component. | 169| CENTER | The picker is center aligned with the entry component.| 170| END | The picker is right aligned with the entry component. | 171 172## Example 173### Example 1: Implementing a Calendar Picker 174 175This example shows how to implement a calendar picker component. 176 177```ts 178// xxx.ets 179@Entry 180@Component 181struct CalendarPickerExample { 182 private selectedDate: Date = new Date('2024-03-05') 183 184 build() { 185 Column() { 186 Column() { 187 CalendarPicker({ hintRadius: 10, selected: this.selectedDate }) 188 .edgeAlign(CalendarAlign.END) 189 .textStyle({ color: "#ff182431", font: { size: 20, weight: FontWeight.Normal } }) 190 .margin(10) 191 .onChange((value) => { 192 console.info("CalendarPicker onChange:" + JSON.stringify(value)) 193 }) 194 }.alignItems(HorizontalAlign.End).width("100%") 195 196 Text('Calendar picker').fontSize(30) 197 }.width('100%').margin({ top: 350 }) 198 } 199} 200``` 201 202 203 204### Example 2: Setting Start and End Dates 205 206This example demonstrates how to set the start and end dates for the calendar picker using **start** and **end**. 207 208```ts 209// xxx.ets 210@Entry 211@Component 212struct CalendarPickerExample { 213 private selectedDate: Date = new Date('2025-01-15') 214 private startDate: Date = new Date('2025-01-05') 215 private endDate: Date = new Date('2025-01-25') 216 217 build() { 218 Column() { 219 Column() { 220 CalendarPicker({ hintRadius: 10, selected: this.selectedDate, start: this.startDate, end: this.endDate }) 221 .edgeAlign(CalendarAlign.END) 222 .textStyle({ color: "#ff182431", font: { size: 20, weight: FontWeight.Normal } }) 223 .margin(10) 224 .onChange((value) => { 225 console.info("CalendarPicker onChange:" + JSON.stringify(value)) 226 }) 227 }.alignItems(HorizontalAlign.End).width("100%") 228 }.width('100%').margin({ top: 350 }) 229 } 230} 231``` 232 233 234
