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 with [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>16+</sup> 85 86textStyle(style: Optional\<PickerTextStyle>) 87 88Sets the font color, font size, and font weight in the entry area. Compared with [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 16. 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### markToday<sup>18+</sup> 101 102markToday(enabled: boolean) 103 104Sets whether to highlight the current system date. 105 106**Atomic service API**: This API can be used in atomic services since API version 18. 107 108**System capability**: SystemCapability.ArkUI.ArkUI.Full 109 110**Parameters** 111 112| Name| Type | Mandatory| Description | 113| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 114| enabled | boolean | Yes | Whether to highlight the current system date.<br>Default value: **false**<br> The value **true** means to highlight the current system date, and **false** means the opposite.| 115 116## Events 117 118In addition to the [universal events](ts-component-general-events.md), the following events are supported. 119 120### onChange 121 122onChange(callback: Callback\<Date>) 123 124Triggered when a date is selected. 125 126**Atomic service API**: This API can be used in atomic services since API version 11. 127 128**System capability**: SystemCapability.ArkUI.ArkUI.Full 129 130**Parameters** 131 132| Name| Type| Mandatory| Description | 133| ------ | ---- | ---- | -------------- | 134| callback | [Callback](ts-types.md#callback12)\<Date> | Yes | Selected date value| 135 136### onChange<sup>16+</sup> 137 138onChange(callback: Optional\<Callback\<Date>>) 139 140Triggered when a date is selected. Compared with [onChange](#onchange), this API supports the **undefined** type for the **callback** parameter. 141 142**Atomic service API**: This API can be used in atomic services since API version 16. 143 144**System capability**: SystemCapability.ArkUI.ArkUI.Full 145 146**Parameters** 147 148| Name | Type | Mandatory| Description | 149| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 150| 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.| 151 152## CalendarOptions 153 154**Atomic service API**: This API can be used in atomic services since API version 11. 155 156**System capability**: SystemCapability.ArkUI.ArkUI.Full 157 158| Name | Type | Mandatory | Description | 159| ----------- | ---------- | ------| --------------------------------- | 160| 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.| 161| 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| 162| start<sup>16+</sup> | Date | No | Start date.| 163| end<sup>16+</sup> | Date | No | End date.| 164| disabledDateRange<sup>16+</sup> | DateRange[] | No | Disabled date range.<br>**NOTE**<br>1. If the start date or end date within a date range is invalid, the entire date range does not take effect.<br>2. If the end date is earlier than the start date within a date range, the entire date range does not take effect.<br>3. When users select a date and adjust it with the up or down arrow keys, the system skips over all dates in the disabled date range.| 165 166**Rules for setting start and end** 167 168| Scenario | Description | 169| -------- | ------------------------------------------------------------ | 170| The start date is later than the end date. | Both start and end dates are invalid, and the selected date is the default value. | 171| The selected date is earlier than the start date. | The selected date is set to the start date. | 172| The selected date is later than the end date. | The selected date is set to the end date. | 173| 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. | 174| 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. | 175| 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. | 176 177## CalendarAlign 178 179**Atomic service API**: This API can be used in atomic services since API version 11. 180 181**System capability**: SystemCapability.ArkUI.ArkUI.Full 182 183| Name | Description | 184| ------ | ------------------------ | 185| START | The picker is left aligned with the entry component. | 186| CENTER | The picker is center aligned with the entry component.| 187| END | The picker is right aligned with the entry component. | 188 189## Example 190### Example 1: Implementing a Calendar Picker 191 192This example shows how to implement a calendar picker component. 193 194```ts 195// xxx.ets 196@Entry 197@Component 198struct CalendarPickerExample { 199 private selectedDate: Date = new Date('2024-03-05') 200 201 build() { 202 Column() { 203 Column() { 204 CalendarPicker({ hintRadius: 10, selected: this.selectedDate }) 205 .edgeAlign(CalendarAlign.END) 206 .textStyle({ color: "#ff182431", font: { size: 20, weight: FontWeight.Normal } }) 207 .margin(10) 208 .onChange((value) => { 209 console.info("CalendarPicker onChange:" + JSON.stringify(value)) 210 }) 211 }.alignItems(HorizontalAlign.End).width("100%") 212 213 Text('Calendar picker').fontSize(30) 214 }.width('100%').margin({ top: 350 }) 215 } 216} 217``` 218 219 220 221### Example 2: Setting Start and End Dates 222 223This example demonstrates how to set the start and end dates for the calendar picker using **start** and **end**. 224 225```ts 226// xxx.ets 227@Entry 228@Component 229struct CalendarPickerExample { 230 private selectedDate: Date = new Date('2025-01-15') 231 private startDate: Date = new Date('2025-01-05') 232 private endDate: Date = new Date('2025-01-25') 233 234 build() { 235 Column() { 236 Column() { 237 CalendarPicker({ hintRadius: 10, selected: this.selectedDate, start: this.startDate, end: this.endDate }) 238 .edgeAlign(CalendarAlign.END) 239 .textStyle({ color: "#ff182431", font: { size: 20, weight: FontWeight.Normal } }) 240 .margin(10) 241 .onChange((value) => { 242 console.info("CalendarPicker onChange:" + JSON.stringify(value)) 243 }) 244 }.alignItems(HorizontalAlign.End).width("100%") 245 }.width('100%').margin({ top: 350 }) 246 } 247} 248``` 249 250 251 252### Example 3: Highlighting the Current System Date and Disabling a Specific Date Range 253 254This example shows how to highlight the current system date using **markToday** and disable a specific date range using **disabledDateRange**. 255 256```ts 257// xxx.ets 258@Entry 259@Component 260struct CalendarPickerExample { 261 private disabledDateRange: DateRange[] = [ 262 { start: new Date('2025-01-01'), end: new Date('2025-01-02') }, 263 { start: new Date('2025-01-09'), end: new Date('2025-01-10') }, 264 { start: new Date('2025-01-15'), end: new Date('2025-01-16') }, 265 { start: new Date('2025-01-19'), end: new Date('2025-01-19') }, 266 { start: new Date('2025-01-22'), end: new Date('2025-01-25') } 267 ] 268 269 build() { 270 Column() { 271 CalendarPicker({ disabledDateRange: this.disabledDateRange }) 272 .margin(10) 273 .markToday(true) 274 .onChange((value) => { 275 console.info("CalendarPicker onChange:" + JSON.stringify(value)) 276 }) 277 }.alignItems(HorizontalAlign.End).width('100%') 278 } 279} 280``` 281 282 283
