aurora-admin/.design_library/kole-ui-mobile/components/mobile-datepicker.json

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "confidence": "high",
  "specSection": "18 · 日期选择器 DatePicker",
  "slug": "mobile-datepicker",
  "name": "日期选择器 DatePicker",
  "semanticTypeCandidates": [
    "datepicker",
    "calendar",
    "wheel"
  ],
  "variantDimensions": [
    {
      "name": "mode",
      "values": [
        "date",
        "month"
      ]
    },
    {
      "name": "round",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "mode": "date",
      "round": "true",
      "label": "年月日三列"
    },
    {
      "mode": "month",
      "round": "true",
      "label": "年月两列"
    },
    {
      "mode": "date",
      "round": "false",
      "label": "直角（不含圆角）"
    }
  ],
  "anatomy": {
    "mask": "遮罩，点击关闭",
    "picker": "底部浮层",
    "picker__header": "取消 / 标题 / 确定",
    "picker__columns": "年 / 月 / 日三列",
    "picker__column": "单列，可滚动",
    "picker__option": "单个选项"
  },
  "structurePatterns": {
    "mode": "date（年月日）/ month（年月）",
    "round": "false / true"
  },
  "usageHints": [
    "从底部弹出的年 / 月 / 日选择器，用于生日、有效期这类需要日期输入的场景",
    "遮罩点击关闭；closeOnMask=false 时不关闭",
    "选项行高不小于 44px，滚动容器 -webkit-overflow-scrolling: touch",
    "确定 / 取消按钮热区不小于 44px",
    "浮层 role=\"dialog\" + aria-modal=\"true\"",
    "每列 role=\"listbox\"，选项 role=\"option\" + aria-selected",
    "遮罩 aria-hidden=\"true\"",
    "选中值以 YYYY-MM-DD 文本呈现（不依赖视觉滚动位置）"
  ],
  "doNotInvent": [
    "日期范围的禁用规则（由宿主传入）",
    "滚轮惯性 / 吸附动画的物理参数"
  ],
  "unknowns": [
    "可选年份的范围",
    "是否支持「至今」这类特殊选项"
  ],
  "interaction": [
    "遮罩点击关闭；closeOnMask=false 时不关闭",
    "选项行高不小于 44px，滚动容器 -webkit-overflow-scrolling: touch",
    "确定 / 取消按钮热区不小于 44px"
  ],
  "accessibility": [
    "浮层 role=\"dialog\" + aria-modal=\"true\"",
    "每列 role=\"listbox\"，选项 role=\"option\" + aria-selected",
    "遮罩 aria-hidden=\"true\"",
    "选中值以 YYYY-MM-DD 文本呈现（不依赖视觉滚动位置）"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "mode",
        "type": "'date' | 'month'",
        "default": "'date'",
        "desc": "变体 mode：date 为年月日三列，month 为年月两列（规格 §18.3）",
        "required": false
      },
      {
        "name": "round",
        "type": "boolean",
        "default": "false",
        "desc": "变体 round：靠内容一侧是否切圆角（规格 §18.3）",
        "required": false
      },
      {
        "name": "open",
        "type": "boolean",
        "default": "false",
        "desc": "状态 open：浮层是否展开（规格 §18.4）",
        "required": false
      },
      {
        "name": "closeOnMask",
        "type": "boolean",
        "default": "true",
        "desc": "遮罩点击是否关闭（规格 §18.5）",
        "required": false
      },
      {
        "name": "value",
        "type": "string",
        "default": "''",
        "desc": "当前选中值，YYYY-MM-DD（mode=month 时 YYYY-MM）；用于让选中项可见（规格 §18.6）",
        "required": false
      },
      {
        "name": "years",
        "type": "Array<string>",
        "default": "[]",
        "desc": "年份列选项（宿主提供，本组件不发明年份范围）（规格 §18.7）",
        "required": false
      },
      {
        "name": "months",
        "type": "Array<string>",
        "default": "[]",
        "desc": "月份列选项（规格 §18.2 picker__column）",
        "required": false
      },
      {
        "name": "days",
        "type": "Array<string>",
        "default": "[]",
        "desc": "日期列选项；mode=month 时不渲染该列（规格 §18.3）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "confirm",
        "params": "—",
        "desc": "点击确定时触发（规格 §18.2 picker__header）"
      },
      {
        "name": "close",
        "params": "—",
        "desc": "点击取消或遮罩（closeOnMask=true 时）时触发（规格 §18.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "自定义内容（追加在列区之后）"
      }
    ]
  },
  "variantClasses": {
    "mode": {
      "date": [],
      "month": []
    },
    "round": {
      "false": [],
      "true": [
        ".kole-m-datepicker--round"
      ]
    }
  },
  "demos": [
    {
      "id": "date",
      "group": "01 组件类型",
      "title": "年月日",
      "desc": "三列滚动，选中项用品牌色高亮并以 aria-selected 标注，不依赖视觉位置。",
      "variant": "mode=date"
    },
    {
      "id": "month",
      "group": "01 组件类型",
      "title": "年月",
      "desc": "只有两列，用于账单月份这类不需要具体日期的场景。",
      "variant": "mode=month"
    },
    {
      "id": "closed",
      "group": "02 组件状态",
      "title": "收起态",
      "desc": "默认态：遮罩 pointer-events: none，页面可正常滚动与点击。",
      "variant": "状态 closed"
    }
  ],
  "related": [
    {
      "slug": "actionsheet",
      "why": "从底部弹出的选择器与动作面板形态接近；选项是日期时才用日期选择器"
    },
    {
      "slug": "cell",
      "why": "「已选日期」的展示入口用单元格，点开才拉起选择器"
    },
    {
      "slug": "mobile-popup",
      "why": "日期选择器本身就是底部浮层，不要在弹出层里再套一层"
    }
  ]
}