#跟着若城学鸿蒙# UI组件篇-日期滑动选择器弹窗 (DatePickerDialog) 及其属性

DatePickerDialog 是 ArkUI 提供的一个日期选择器组件，允许用户在弹窗中通过滑动选择器选择日期。该组件从 API Version 8 开始支持，并在后续版本中不断优化和扩展功能。DatePickerDialog 是 ArkUI 提供的一个强大且灵活的日期选择器组件，通过丰富的配置选项和回调函数，可以满足各种复杂的日期选择需求。开发者可以根据实际需求，灵活配置 DatePicke

Huang兄

955人浏览 · 2025-05-21 18:26:15

Huang兄 · 2025-05-21 18:26:15 发布

在 ArkUI 框架中，日期滑动选择器弹窗（DatePickerDialog）是一个非常实用的组件，用于让用户方便地选择日期。本文将详细介绍 DatePickerDialog 的使用方法、参数配置、示例代码以及在实际开发中的应用场景。

一、DatePickerDialog 概述

DatePickerDialog 是 ArkUI 提供的一个日期选择器组件，允许用户在弹窗中通过滑动选择器选择日期。该组件从 API Version 8 开始支持，并在后续版本中不断优化和扩展功能。

主要特点

滑动选择：用户可以通过滑动选择器轻松选择日期。
自定义配置：支持多种配置选项，如日期范围、农历显示、时间显示等。
事件回调：提供多种回调函数，方便开发者在用户选择日期后进行相应处理。

二、DatePickerDialog 的使用方法

1. 导入相关模块

在使用 DatePickerDialog 之前，需要先导入相关的模块和组件：

import { DatePickerDialog } from '@kit.ArkUI';

2. 创建 DatePickerDialog 实例

通过静态方法 show 可以创建并显示 DatePickerDialog 实例：

DatePickerDialog.show(options?: DatePickerDialogOptions);

3. 配置选项

DatePickerDialog 支持多种配置选项，可以通过 DatePickerDialogOptions 对象进行配置。以下是一些常用的配置选项：

start: 设置日期选择器的起始日期。
end: 设置日期选择器的结束日期。
selected: 设置默认选中的日期。
lunar: 是否显示农历。
showTime: 是否显示时间选择器。
useMilitaryTime: 是否使用24小时制。
disappearTextStyle: 设置最上和最下两个选项的文本样式。
textStyle: 设置除最上、最下及选中项以外的文本样式。
selectedTextStyle: 设置选中项的文本样式。
acceptButtonStyle: 设置确认按钮的样式。
cancelButtonStyle: 设置取消按钮的样式。
alignment: 设置弹窗在竖直方向上的对齐方式。
offset: 设置弹窗相对对齐位置的偏移量。
maskRect: 设置弹窗遮蔽层区域。
onDateAccept: 点击“确定”按钮时的回调函数。
onDateChange: 滑动选择器改变时的回调函数。
onCancel: 点击“取消”按钮时的回调函数。

4. 示例代码

以下是一个使用 DatePickerDialog 的示例代码：

@Entry
@Component
struct CalendarPickerDialogExample {
  private selectedDate: Date = new Date("2024-04-23")

  build() {
    Column() {
      Button("Show CalendarPicker Dialog").margin(20).onClick(() => {
        console.info("CalendarDialog.show")

        let selectedDate: Date = new Date("2010-1-1");
        DatePickerDialog.show({
          start: new Date("2000-1-1"),
          end: new Date("2100-12-31"),
          selected: selectedDate,
          showTime: true,
          useMilitaryTime: false,
          disappearTextStyle: { color: Color.Pink, font: { size: '22fp', weight: FontWeight.Bold } },
          textStyle: { color: '#ff00ff00', font: { size: '18fp', weight: FontWeight.Normal } },
          selectedTextStyle: { color: '#ff182431', font: { size: '14fp', weight: FontWeight.Regular } },
          onDateAccept: (value: Date) => {
            selectedDate = value;
            console.info("DatePickerDialog:onDateAccept()" + value.toString());
          },
          onCancel: () => {
            console.info("DatePickerDialog:onCancel()");
          },
          onDateChange: (value: Date) => {
            console.info("DatePickerDialog:onDateChange()" + value.toString());
          }
        });
      })
    }.width('100%')
  }
}

三、DatePickerDialogOptions 对象说明

DatePickerDialogOptions 对象包含了 DatePickerDialog 的所有配置选项。以下是各个选项的详细说明：

1. start

类型: Date
必填: 否
说明: 设置日期选择器的起始日期。默认值：Date('1970-1-1')

2. end

类型: Date
必填: 否
说明: 设置日期选择器的结束日期。默认值：Date('2100-12-31')

3. selected

类型: Date
必填: 否
说明: 设置选中项的日期。默认值：当前系统日期

4. lunar

类型: boolean
必填: 否
说明: 设置日期是否显示为农历。默认值：false

5. showTime

类型: boolean
必填: 否
说明: 是否展示时间项。默认值：false

6. useMilitaryTime

类型: boolean
必填: 否
说明: 展示时间是否为24小时制。默认值：false

7. disappearTextStyle

类型: PickerTextStyle
必填: 否
说明: 设置所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。默认值：{ color: '#ff182431', font: { size: '14fp', weight: FontWeight.Regular } }

8. textStyle

类型: PickerTextStyle
必填: 否
说明: 设置所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。默认值：{ color: '#ff182431', font: { size: '16fp', weight: FontWeight.Regular } }

9. selectedTextStyle

类型: PickerTextStyle
必填: 否
说明: 设置选中项的文本颜色、字号、字体粗细。默认值：{ color: '#ff007dff', font: { size: '20vp', weight: FontWeight.Medium } }

10. acceptButtonStyle

类型: PickerDialogButtonStyle
必填: 否
说明: 设置确认按钮显示样式、样式和重要程度、角色、背景色、圆角、文本颜色、字号、字体粗细、字体样式、字体列表、按钮是否默认响应Enter键。

11. cancelButtonStyle

类型: PickerDialogButtonStyle
必填: 否
说明: 设置取消按钮显示样式、样式和重要程度、角色、背景色、圆角、文本颜色、字号、字体粗细、字体样式、字体列表、按钮是否默认响应Enter键。

12. alignment

类型: DialogAlignment
必填: 否
说明: 弹窗在竖直方向上的对齐方式。默认值：DialogAlignment.Default

13. offset

类型: Offset
必填: 否
说明: 弹窗相对alignment所在位置的偏移量。默认值：{ dx: 0 , dy: 0 }

14. maskRect

类型: Rectangle
必填: 否
说明: 弹窗遮蔽层区域，在遮蔽层区域内的事件不透传，在遮蔽层区域外的事件透传。默认值：{ x: 0, y: 0, width: '100%', height: '100%' }

15. onDateAccept

类型: Callback<Date>
必填: 否
说明: 点击弹窗中的“确定”按钮时触发该回调。返回选中的日期值。

16. onDateChange

类型: Callback<Date>
必填: 否
说明: 滑动弹窗中的滑动选择器使当前选中项改变时触发该回调。返回选中的日期值。

17. onCancel

类型: VoidCallback
必填: 否
说明: 点击弹窗中的“取消”按钮时触发该回调。

四、LunarSwitchStyle14+ 类型说明

LunarSwitchStyle14+ 类型定义了 DatePickerDialog 组件中切换农历开关的样式。以下是各个属性的详细说明：

1. selectedColor

类型: ResourceColor
必填: 否
说明: 设置开关开启时开关的背景颜色。默认值：$r('sys.color.ohos_id_color_text_primary_actived')

2. unselectedColor

类型: ResourceColor
必填: 否
说明: 设置开关未开启时开关的边框颜色。默认值：$r('sys.color.ohos_id_color_switch_outline_off')

3. strokeColor

类型: ResourceColor
必填: 否
说明: 设置开关内部图标颜色。默认值：Color.White

五、PickerDialogButtonStyle12+ 类型说明

PickerDialogButtonStyle12+ 类型定义了 DatePickerDialog 组件中按钮的样式。以下是各个属性的详细说明：

1. type

类型: ButtonType
必填: 否
说明: 按钮显示样式。

2. style

类型: ButtonStyleMode
必填: 否
说明: 按钮的样式和重要程度。

3. role

类型: ButtonRole
必填: 否
说明: Button组件的角色。

4. fontSize

类型: Length
必填: 否
说明: 文本显示字号。

5. fontColor

类型: ResourceColor
必填: 否
说明: 文本显示颜色。

6. fontWeight

类型: FontWeight | number | string
必填: 否
说明: 文本的字体粗细。

7. fontStyle

类型: FontStyle
必填: 否
说明: 文本的字体样式。

8. fontFamily

类型: Resource | string
必填: 否
说明: 字体列表。默认字体'HarmonyOS Sans'，当前支持'HarmonyOS Sans'字体和注册自定义字体。

9. backgroundColor

类型: ResourceColor
必填: 否
说明: 按钮背景色。

10. borderRadius

类型: Length | BorderRadiuses
必填: 否
说明: 圆角半径。

11. primary

类型: boolean
必填: 否
说明: 在弹窗获焦且未进行tab键走焦时，按钮是否默认响应Enter键。

六、异常情形说明

以下是 DatePickerDialog 在不同异常情形下的处理方式：

异常情形	对应结果
起始日期晚于结束日期，选中日期未设置	起始日期、结束日期和选中日期都为默认值
起始日期晚于结束日期，选中日期早于起始日期默认值	起始日期、结束日期都为默认值，选中日期为起始日期默认值
起始日期晚于结束日期，选中日期晚于结束日期默认值	起始日期、结束日期都为默认值，选中日期为结束日期默认值
起始日期晚于结束日期，选中日期在起始日期与结束日期默认值范围内	起始日期、结束日期都为默认值，选中日期为设置的值
选中日期早于起始日期	选中日期为起始日期
选中日期晚于结束日期	选中日期为结束日期
起始日期晚于当前系统日期，选中日期未设置	选中日期为起始日期
结束日期早于当前系统日期，选中日期未设置	选中日期为结束日期
日期格式不符合规范，如‘1999-13-32’	取默认值
起始日期或结束日期早于系统有效范围	起始日期或结束日期取系统有效范围最早日期
起始日期或结束日期晚于系统有效范围	起始日期或结束日期取系统有效范围最晚日期

七、示例代码

以下是一个更复杂的示例代码，展示了如何在 ArkUI 中使用 DatePickerDialog，并配置各种选项和回调函数：

@Entry
@Component
struct CalendarPickerDialogExample {
  private selectedDate: Date = new Date("2024-04-23")

  build() {
    Column() {
      Button("Show DatePickerDialog").margin(20).onClick(() => {
        console.info("CalendarDialog.show")


          DatePickerDialog.show({
            start: new Date("2000-1-1"),
            end: new Date("2100-12-31"),
            selected: this.selectedDate,
            lunar: true,
            showTime: true,
            useMilitaryTime: false,
            disappearTextStyle: { color: Color.Pink, font: { size: '22fp', weight: FontWeight.Bold } },
            textStyle: { color: '#ff00ff00', font: { size: '18fp', weight: FontWeight.Normal } },
            selectedTextStyle: { color: '#ff182431', font: { size: '14fp', weight: FontWeight.Regular } },
            acceptButtonStyle: {
              type: ButtonType.Normal,
              style: ButtonStyleMode.NORMAL,
              role: ButtonRole.NORMAL,
              fontColor: Color.Red,
              fontSize: '26fp',
              fontWeight: FontWeight.Bolder,
              fontStyle: FontStyle.Normal,
              fontFamily: 'sans-serif',
              backgroundColor: '#80834511',
              borderRadius: 20
            },
            cancelButtonStyle: {
              type: ButtonType.Normal,
              style: ButtonStyleMode.NORMAL,
              role: ButtonRole.NORMAL,
              fontColor: Color.Blue,
              fontSize: '16fp',
              fontWeight: FontWeight.Normal,
              fontStyle: FontStyle.Italic,
              fontFamily: 'sans-serif',
              backgroundColor: '#50182431',
              borderRadius: 10
            },
            onDateAccept: (value: Date) => {
              this.selectedDate = value;
              console.info("DatePickerDialog:onDateAccept()" + value.toString());
            },
            onCancel: () => {
              console.info("DatePickerDialog:onCancel()");
            },
            onDateChange: (value: Date) => {
              console.info("DatePickerDialog:onDateChange()" + value.toString());
            }
          });
        }
      )
    }.width('100%')
  }
}


class DatePickerExample {

}

八、应用场景

DatePickerDialog 在实际开发中有广泛的应用场景，以下是一些常见的使用场景：

注册和登录页面：用户需要选择出生日期或其他重要日期。
事件提醒：用户需要设置事件的日期和时间。
日程管理：用户需要选择会议的日期和时间。
旅游预订：用户需要选择出行和返回的日期。

九、注意事项

在使用 DatePickerDialog 时，需要注意以下几点：

日期范围：确保设置的起始日期和结束日期在合理范围内，避免用户选择无效日期。
样式配置：根据应用的设计风格，合理配置弹窗的样式，确保用户体验。
回调函数：合理使用回调函数，处理用户选择日期后的逻辑。

十、总结

DatePickerDialog 是 ArkUI 提供的一个强大且灵活的日期选择器组件，通过丰富的配置选项和回调函数，可以满足各种复杂的日期选择需求。开发者可以根据实际需求，灵活配置 DatePickerDialog 的各项参数，实现个性化的日期选择功能。希望本文能帮助开发者更好地理解和使用 DatePickerDialog 组件。

----

以上