V1.0.0
WinDesign A2UI Vue

WDatePicker 组件 ​

日期选择器组件，基于 WinDesignNext DatePicker Pro 封装（渲染层内部使用 WDatePickerPro），用于选择或输入日期、日期时间、周/月/年及日期范围，支持数据绑定和事件响应。

推荐配合 valueFormat 使用：在 A2UI JSON 中建议设置 valueFormat: "YYYY-MM-DD"（或 "YYYY-MM-DD HH:mm:ss"），使 modelValue 以字符串形式存储在 dataModel 中，便于序列化和 Agent 处理。

基础用法 ​

Props API ​

属性名类型默认值说明
idstring-组件唯一标识（必填）
componentstringWDatePicker组件类型（必填）
modelValueobject-绑定值（A2UI 数据绑定，支持 path）
typestring/objectdate显示类型（支持 path）
sizestringdefault输入框尺寸
readonlybooleanfalse是否只读
disabledbooleanfalse是否禁用
editablebooleantrue文本框是否可输入
clearablebooleantrue是否可清空
placeholderstring''占位文本
startPlaceholderstring-范围选择开始占位
endPlaceholderstring-范围选择结束占位
formatstring/objectYYYY-MM-DD输入框显示格式（支持 path）
valueFormatstring/object-绑定值格式（支持 path）
rangeSeparatorstring-范围分隔符
unlinkPanelsbooleanfalse范围选择时解除面板联动
teleportedbooleantrue下拉层是否挂载到 body
appendTostring-下拉层挂载目标
popperClassstring-下拉框自定义类名
placementstringbottom-start下拉框弹出位置
prefixIconstring/object-前缀图标
suffixIconstring/object-后缀图标
clearIconstring/objectCircleCloseFilled清空图标
validateEventbooleantrue是否触发表单校验
namestring/array-原生 name 属性
plainbooleanfalse朴素模式
emitFormattedValuebooleanfalsechange 事件是否附带格式化字符串
triggerSuffixbooleanfalse点击后缀图标触发下拉
actionobject-A2UI v0.9 事件定义

type 可选值 ​

值说明
date日期（默认）
datetime日期 + 时刻
daterange日期范围
datetimerange日期时间范围
week周
month月
monthrange月份范围
year年
yearrange年份范围
dates多个日期
years多个年份
months多个月份

path 支持说明 ​

通用绑定格式见 path 数据绑定速查。

属性支持 path说明
modelValue✅双向绑定选中值（单选或范围数组）
type✅动态切换显示类型（如 date / datetime / daterange）
format✅动态控制输入框显示格式
valueFormat✅动态控制绑定值格式
action.event.context[].value✅事件上下文可引用 dataModel
action.event.api.constParams[].value✅API 固定参数可引用 dataModel
placeholder / size / disabled 等❌静态配置；动态变更请用 updateProp

type / format / valueFormat 绑定示例：

json
{
  "type": { "path": "/pickerType" },
  "format": { "path": "/displayFormat" },
  "valueFormat": { "path": "/valueFormat" },
  "modelValue": { "path": "/selectedDate" }
}

配合 updateDataModel 动态切换为日期时间模式：

json
{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "main",
    "path": "/",
    "value": {
      "pickerType": "datetime",
      "displayFormat": "YYYY-MM-DD HH:mm:ss",
      "valueFormat": "YYYY-MM-DD HH:mm:ss",
      "selectedDate": "2024-06-15 09:30:00"
    }
  }
}

modelValue 绑定规则：

  • 单选（type 为 date、datetime、week 等）：path 指向 dataModel 中的单个值
  • 范围选择（type 为 daterange、datetimerange 等）：path 指向长度为 2 的数组
  • 设置 valueFormat 后，值为对应格式字符串；未设置时在 dataModel 中以 ISO 8601 字符串存储
json
// 单选日期
{ "modelValue": { "path": "/birthday" } }

// 日期范围
{ "modelValue": { "path": "/dateRange" } }

// 初始值字面量
{ "modelValue": { "literalString": "2024-06-15" } }

modelValue 数据绑定 ​

json
{
  "id": "date_birthday",
  "component": "WDatePicker",
  "type": "date",
  "valueFormat": "YYYY-MM-DD",
  "placeholder": "请选择出生日期",
  "clearable": true,
  "modelValue": { "path": "/birthday" },
  "action": {
    "event": {
      "name": "onBirthdayChange",
      "context": [{ "key": "birthday", "value": { "path": "/birthday" } }]
    }
  }
}

配合 updateDataModel 设置初始值：

json
{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "main",
    "path": "/",
    "value": {
      "birthday": "1990-01-01"
    }
  }
}

action 定义 ​

用户确认选定值时触发，默认 type 为 change。

json
{
  "action": {
    "event": {
      "name": "onDateChange",
      "type": "change",
      "context": [{ "key": "date", "value": { "path": "/appointmentDate" } }]
    }
  }
}

使用示例 ​

基础日期选择 ​

json
{
  "id": "date_001",
  "component": "WDatePicker",
  "type": "date",
  "valueFormat": "YYYY-MM-DD",
  "placeholder": "请选择日期",
  "clearable": true,
  "modelValue": { "path": "/appointmentDate" },
  "action": {
    "event": { "name": "onDateChange" }
  }
}

日期时间选择 ​

json
{
  "id": "datetime_001",
  "component": "WDatePicker",
  "type": "datetime",
  "format": "YYYY-MM-DD HH:mm:ss",
  "valueFormat": "YYYY-MM-DD HH:mm:ss",
  "placeholder": "请选择日期时间",
  "modelValue": { "path": "/visitTime" }
}

日期范围选择 ​

json
{
  "id": "daterange_001",
  "component": "WDatePicker",
  "type": "daterange",
  "valueFormat": "YYYY-MM-DD",
  "startPlaceholder": "开始日期",
  "endPlaceholder": "结束日期",
  "modelValue": { "path": "/dateRange" },
  "action": {
    "event": {
      "name": "onDateRangeChange",
      "context": [{ "key": "range", "value": { "path": "/dateRange" } }]
    }
  }
}

配合 updateDataModel：

json
{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "main",
    "path": "/",
    "value": {
      "dateRange": ["2024-01-01", "2024-01-31"]
    }
  }
}

配合 WForm 使用 ​

json
[
  {
    "id": "form_item_birthday",
    "component": "WFormItem",
    "label": "出生日期",
    "prop": "birthday",
    "children": ["date_birthday"]
  },
  {
    "id": "date_birthday",
    "component": "WDatePicker",
    "type": "date",
    "valueFormat": "YYYY-MM-DD",
    "placeholder": "请选择",
    "clearable": true,
    "modelValue": { "path": "/birthday" },
    "action": {
      "event": {
        "name": "onBirthdayChange",
        "context": [{ "key": "birthday", "value": { "path": "/birthday" } }]
      }
    }
  }
]

事件处理 ​

选择变化事件 ​

typescript
processor.onEvent((event) => {
  const eventName = event.message.userAction?.name;
  const context = event.message.userAction?.context;

  if (eventName === 'onDateChange') {
    // context: { date: "2024-06-15" } 或 { range: ["2024-01-01", "2024-01-31"] }
    console.log('选中值:', context);
    event.resolve([]);
  }
});

数据同步 ​

WDatePicker 在用户确认选择后会自动将值同步到 dataModel：

  1. 用户选择 → 更新本地值
  2. 通过 setData(component, modelValue.path, val, surfaceId) 同步到 dataModel
  3. 发送 action.event 事件
  4. WButton 提交时可通过 formParams 自动收集绑定了 path 的值

不支持 A2UI JSON 配置的能力 ​

以下 WinDesignNext 原生能力依赖函数或插槽，无法在 A2UI JSON 中直接配置：

能力原生属性替代方案
禁用特定日期disabledDateAgent 通过业务逻辑过滤可选范围，或使用 updateProp
快捷选项shortcuts通过 WButton + updateData 设置 modelValue
自定义单元格插槽暂不支持
默认打开日期defaultValue通过 updateDataModel 设置 modelValue 初始值

Pro 与经典版差异：渲染层使用 WDatePickerPro，persistent 默认为 false，automaticDropdown 默认为 true。JSON Schema 中部分经典版专属属性（如 unlinkPanels、triggerSuffix）在 Pro 上可能无效，请以 DatePicker Pro 文档 为准。

Design by UED