DatePicker

DatePicker 在月历中选择一个日期，支持按月、按年导航以及快速选择月/年的网格。它遵循 picker 模式：关闭时通过 getAnswer()（由 show(onAnswer) 消费）返回值（见 Picker）。

🟡 · 包： dev.crossfly.ui.picker · 继承： Picker · 样式： DatePickerStyle

何时使用

用日历 UI 收集一个日期（生日、预约、到期日）。

何时不要使用

收集时间 → 使用 TimePicker。

外观

带标题栏的卡片、月份行（< 名称 >）、年份行（< 2026 >）以及一个 6×7 的日期单元格网格。尺寸约为 Screen.minSize 的 90%。

完整示例（复制、粘贴并运行）

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.picker.*;

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      Button abrir = new Button("Escolher data");
      abrir.onAction(c ->
      {
         DatePicker dp = new DatePicker().title("Data de nascimento");
         dp.show(answer -> Hint.show("Data: " + (String) answer, 2000));
      });
      add(LAY_AUTO, abrir);
   }
}

下面的代码片段只展示核心部分（放进 onShow() 内的内容）。要运行它们，请把它们放入上面的 MainWindow 骨架中。

基本用法

DatePicker dp = new DatePicker();
dp.show(answer -> campoData.setText((String) answer));

构造函数

构造函数	描述
`DatePicker()`	无参数；以今天的日期开始。

属性与自定义（流式）

方法	类型	默认值	作用
`setDate(int year, int month, int day)`	年、月从 0 开始、日从 1 开始	今天	预选日期。
`title(String)`	`String`	`"Date Picker"`	标题栏文本。
`yearRange(int before, int after)`	`int`, `int`	30, 10	年份网格向前/向后的年数。
`style(DatePickerStyle)`	样式	skin	自定义样式。
`getSelectedDay()`	`int`	—	选中的日（从 1 开始）。
`getDisplayYear()` / `getDisplayMonth()`	`int`	—	显示的年 / 月（月从 0 开始）。

回调与事件

回调	触发时机
`onSelect(Action)`	点击某一天时（接收 `DatePicker` 本身）。
`show(onAnswer)`	关闭时，传递日期的 `String`（如果已确认）。

getAnswer() 以 DateTimeUtils.formatDate 的格式返回日期——顺序（DMY/MDY/YMD）和分隔符取决于 LocaleFormats，并非固定的 dd/MM/yyyy。

状态

在月份之间导航会将 selectedDay 重置为 -1（在用户选择之前不标记任何日期）。
按状态的样式：今天、选中、其他月份、正常（通过 DatePickerStyle）。

出生日期

DatePicker dp = new DatePicker()
   .title("Data de nascimento")
   .yearRange(100, 0)     // 至多 100 年前，未来一概不允许
   .setDate(2000, 0, 1);  // 01/Jan/2000（月份从 0 开始！）

dp.onSelect(p ->
{
   DatePicker d = (DatePicker) p;
   Debug.log("dia=" + d.getSelectedDay() + " mes=" + (d.getDisplayMonth() + 1));
});

dp.show(answer ->
{
   String data = (String) answer; // 例如："01/01/2000"，符合 LocaleFormats
   campoData.setText(data);
});

最佳实践

记住在 setDate 中 month 从 0 开始。
要本地化月/日名称，请重新赋值公有常量 MONTH_NAMES/MONTH_SHORT。

常见错误

在 setDate 中传入从 1 开始的月份 —— 一月是 0。
期望固定格式 —— 输出遵循 LocaleFormats.dateFormat/dateSeparator。
把 yearRange 当作选择的钳制 —— 它只限制年份导航；所显示月份的任何一天都可选。

另见

该领域指南：ui/ · 食谱：cookbook/
模式基类：Picker
相关组件：TimePicker