1# CalendarPicker 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @luoying_ace_admin--> 5<!--Designer: @weixin_52725220--> 6<!--Tester: @xiong0104--> 7<!--Adviser: @HelloCrease--> 8 9日历选择器组件，提供下拉日历弹窗，可以让用户选择日期。 10 11> **说明：** 12> 13> - 该组件从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> - 该组件不支持在Wearable设备上使用。 16 17## 子组件 18 19无 20 21## 接口 22 23CalendarPicker(options?: CalendarOptions) 24 25日历选择器。 26 27**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 28 29**系统能力：** SystemCapability.ArkUI.ArkUI.Full 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| ------- | ------------------------------------------- | ---- | -------------------------- | 35| options | [CalendarOptions](#calendaroptions对象说明) | 否 | 配置日历选择器组件的参数。 | 36 37## 属性 38 39除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 40 41### edgeAlign 42 43edgeAlign(alignType: CalendarAlign, offset?: Offset) 44 45设置选择器与入口组件的对齐方式。 46 47**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 48 49**系统能力：** SystemCapability.ArkUI.ArkUI.Full 50 51**参数：** 52 53| 参数名 | 类型 | 必填 | 说明 | 54| --------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 55| alignType | [CalendarAlign](#calendaralign枚举说明) | 是 | 对齐方式的类型。<br/>默认值：CalendarAlign.END | 56| offset | [Offset](ts-types.md#offset) | 否 | 按照对齐方式对齐后，选择器相对入口组件的偏移量。<br/>默认值：{dx: 0, dy: 0} | 57 58### edgeAlign<sup>18+</sup> 59 60edgeAlign(alignType: Optional\<CalendarAlign>, offset?: Offset) 61 62设置选择器与入口组件的对齐方式。与[edgeAlign](#edgealign)相比，alignType参数新增了对undefined类型的支持。 63 64**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 65 66**系统能力：** SystemCapability.ArkUI.ArkUI.Full 67 68**参数：** 69 70| 参数名 | 类型 | 必填 | 说明 | 71| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 72| alignType | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[CalendarAlign](#calendaralign枚举说明)> | 是 | 对齐方式的类型。<br/>默认值：CalendarAlign.END<br/>当alignType的值为undefined时，使用默认值。 | 73| offset | [Offset](ts-types.md#offset) | 否 | 按照对齐方式对齐后，选择器相对入口组件的偏移量。<br/>默认值：{dx: 0, dy: 0} | 74 75### textStyle 76 77textStyle(value: PickerTextStyle) 78 79入口区的文本颜色、字号、字体粗细。 80 81**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 82 83**系统能力：** SystemCapability.ArkUI.ArkUI.Full 84 85**参数：** 86 87| 参数名 | 类型 | 必填 | 说明 | 88| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 89| value | [PickerTextStyle](ts-picker-common.md#pickertextstyle对象说明) | 是 | 设置入口区的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff182431',<br/>font: {<br/>size: '16fp', <br/>weight: FontWeight.Regular<br/>}<br/>} | 90 91### textStyle<sup>18+</sup> 92 93textStyle(style: Optional\<PickerTextStyle>) 94 95入口区的文本颜色、字号、字体粗细。与[textStyle](#textstyle)相比，style参数新增了对undefined类型的支持。 96 97**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 98 99**系统能力：** SystemCapability.ArkUI.ArkUI.Full 100 101**参数：** 102 103| 参数名 | 类型 | 必填 | 说明 | 104| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 105| style | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[PickerTextStyle](ts-picker-common.md#pickertextstyle对象说明)> | 是 | 设置入口区的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff182431',<br/>font: {<br/>size: '16fp', <br/>weight: FontWeight.Regular<br/>}<br/>}<br/>当style的值为undefined时，使用默认值。 | 106 107### markToday<sup>19+</sup> 108 109markToday(enabled: boolean) 110 111设置日历选择器中系统当前日期是否保持高亮显示。 112 113**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 114 115**系统能力：** SystemCapability.ArkUI.ArkUI.Full 116 117**参数：** 118 119| 参数名 | 类型 | 必填 | 说明 | 120| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 121| enabled | boolean | 是 | 设置日历选择器中系统当前日期是否保持高亮显示。<br/>- true：系统当前日期在日历选择器内保持高亮显示。<br/>- false：系统当前日期在日历选择器内不保持高亮显示。<br/>默认值：false | 122 123## 事件 124 125除支持[通用事件](ts-component-general-events.md)，还支持以下事件： 126 127### onChange 128 129onChange(callback: Callback\<Date>) 130 131选择日期时触发该事件。不能通过双向绑定的状态变量触发。 132 133**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 134 135**系统能力：** SystemCapability.ArkUI.ArkUI.Full 136 137**参数：** 138 139| 参数名 | 类型 | 必填 | 说明 | 140| ------ | ---- | ---- | -------------- | 141| callback | [Callback](ts-types.md#callback12)\<Date> | 是 | 选中的日期值。 | 142 143### onChange<sup>18+</sup> 144 145onChange(callback: Optional\<Callback\<Date>>) 146 147选择日期时触发该事件。不能通过双向绑定的状态变量触发。与[onChange](#onchange)相比，callback参数新增了对undefined类型的支持。 148 149**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 150 151**系统能力：** SystemCapability.ArkUI.ArkUI.Full 152 153**参数：** 154 155| 参数名 | 类型 | 必填 | 说明 | 156| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 157| callback | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[Callback](ts-types.md#callback12)\<Date>> | 是 | 选中的日期值。<br>当callback的值为undefined时，不使用回调函数。 | 158 159## CalendarOptions对象说明 160 161日历选择器组件的参数说明。 162 163**系统能力：** SystemCapability.ArkUI.ArkUI.Full 164 165| 名称 | 类型 | 只读 | 可选 | 说明 | 166| ----------- | ---------- | ------| --------------------------------- | --------------------------------- | 167| hintRadius | number \| [Resource](ts-types.md#resource) | 否 | 是 | 描述日期选中态底板样式。<br />取值范围：[0, 16]<br />单位：vp<br/>默认值：16.0vp，即底板样式为圆形。<br />**说明：**<br />当hintRadius为0时，底板样式为直角矩形。当hintRadius的值在0到16之间时，底板样式为圆角矩形。当hintRadius大于或等于16时，底板样式为圆形。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 168| selected | Date | 否 | 是 | 设置选中项的日期。选中的日期未设置或日期格式不符合规范则为默认值。<br/>默认值：当前系统日期。<br/>取值范围：\[Date('0001-01-01'), Date('5000-12-31')]<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 169| start<sup>18+</sup> | Date | 否 | 是 | 设置开始日期。<br/>默认值：Date('0001-01-01')<br/>取值范围：\[Date('0001-01-01'), Date('5000-12-31')]<br />**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 170| end<sup>18+</sup> | Date | 否 | 是 | 设置结束日期。<br/>默认值：Date('5000-12-31')<br/>取值范围：\[Date('0001-01-01'), Date('5000-12-31')]<br />**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 171| disabledDateRange<sup>19+</sup> | [DateRange](ts-picker-common.md#daterange19对象说明)[] | 否 | 是 | 设置禁用日期区间。<br/>**说明：**<br />1. 若日期区间内的开始日期或结束日期未设置或设置为异常值，则该日期区间无效。<br/>2. 若在日期区间内，结束日期早于开始日期，则该日期区间无效。<br/>3. 当在入口区选定某日期，通过上下箭头调整日期进行增加或减少操作时，若遇到禁用日期，系统将自动跳过整个禁用区间。<br/>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 172 173**start和end设置规则：** 174 175| 场景 | 说明 | 176| -------- | ------------------------------------------------------------ | 177| start日期晚于end日期 | start日期、end日期都设置无效，选中日期为默认值 | 178| 选中日期早于start日期 | 选中日期为start日期 | 179| 选中日期晚于end日期 | 选中日期为end日期 | 180| start日期晚于当前系统日期，选中日期未设置 | 选中日期为start日期 | 181| end日期早于当前系统日期，选中日期未设置 | 选中日期为end日期 | 182| 日期格式不符合规范，如‘1999-13-32’ | start日期或end日期设置无效，选中日期取默认值 | 183 184## CalendarAlign枚举说明 185 186对齐方式类型。 187 188**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 189 190**系统能力：** SystemCapability.ArkUI.ArkUI.Full 191 192| 名称 | 值 | 说明 | 193| ------ | - | ------------------------ | 194| START | 0 | 设置选择器与入口组件的对齐方式为左对齐。 | 195| CENTER | 1 | 设置选择器与入口组件的对齐方式为居中对齐。 | 196| END | 2 | 设置选择器与入口组件的对齐方式为右对齐。 | 197 198## 示例 199### 示例1（设置下拉日历弹窗） 200 201该示例实现了日历选择器组件，提供下拉日历弹窗。 202 203```ts 204// xxx.ets 205@Entry 206@Component 207struct CalendarPickerExample { 208 private selectedDate: Date = new Date('2024-03-05'); 209 210 build() { 211 Column() { 212 Column() { 213 CalendarPicker({ hintRadius: 10, selected: this.selectedDate }) 214 .edgeAlign(CalendarAlign.END) 215 .textStyle({ color: "#ff182431", font: { size: 20, weight: FontWeight.Normal } }) 216 .margin(10) 217 .onChange((value) => { 218 console.info(`CalendarPicker onChange: ${value.toString()}`); 219 }) 220 }.alignItems(HorizontalAlign.End).width("100%") 221 222 Text('日历日期选择器').fontSize(30) 223 }.width('100%').margin({ top: 350 }) 224 } 225} 226``` 227 228 229 230### 示例2（设置开始日期和结束日期） 231 232该示例通过start和end设置日历选择器的开始日期和结束日期。 233 234```ts 235// xxx.ets 236@Entry 237@Component 238struct CalendarPickerExample { 239 private selectedDate: Date = new Date('2025-01-15'); 240 private startDate: Date = new Date('2025-01-05'); 241 private endDate: Date = new Date('2025-01-25'); 242 243 build() { 244 Column() { 245 Column() { 246 CalendarPicker({ hintRadius: 10, selected: this.selectedDate, start: this.startDate, end: this.endDate }) 247 .edgeAlign(CalendarAlign.END) 248 .textStyle({ color: "#ff182431", font: { size: 20, weight: FontWeight.Normal } }) 249 .margin(10) 250 .onChange((value) => { 251 console.info(`CalendarPicker onChange: ${value.toString()}`); 252 }) 253 }.alignItems(HorizontalAlign.End).width("100%") 254 }.width('100%').margin({ top: 350 }) 255 } 256} 257``` 258 259 260 261### 示例3（设置日历选择器在系统当前日期时，保持高亮显示和禁用日期区间） 262 263该示例通过[markToday](#marktoday19)设置日历选择器在系统当前日期时，开启保持高亮显示，同时，通过[disabledDateRange](#calendaroptions对象说明)设置日历选择器的禁用日期区间。 264 265```ts 266// xxx.ets 267@Entry 268@Component 269struct CalendarPickerExample { 270 private disabledDateRange: DateRange[] = [ 271 { start: new Date('2025-01-01'), end: new Date('2025-01-02') }, 272 { start: new Date('2025-01-09'), end: new Date('2025-01-10') }, 273 { start: new Date('2025-01-15'), end: new Date('2025-01-16') }, 274 { start: new Date('2025-01-19'), end: new Date('2025-01-19') }, 275 { start: new Date('2025-01-22'), end: new Date('2025-01-25') } 276 ]; 277 278 build() { 279 Column() { 280 CalendarPicker({ disabledDateRange: this.disabledDateRange }) 281 .margin(10) 282 .markToday(true) 283 .onChange((value) => { 284 console.info(`CalendarPicker onChange: ${value.toString()}`); 285 }) 286 }.alignItems(HorizontalAlign.End).width('100%') 287 } 288} 289``` 290 291 292
