组件名称

DatePicker（日期选择器）

概述

• 功能描述
  • 支持选择单日或日期范围，精度至“日”。
  • 以“输入框 + 弹层（日历面板）”的复合结构提供交互，含跨月导航与快捷预设。
  • 兼容受控与非受控两种数据管理方式，支持国际化日期格式（默认 YYYY-MM-DD）。
• 设计原则
  • 明确性：输入框与面板分工清晰，选择路径直观（起始-结束）。
  • 一致性：状态样式统一（默认/聚焦/悬停/选中/禁用/错误），导航与预设行为一致。
  • 可达性：所有可交互目标触达区域≥44px；支持键盘与读屏辅助。
  • 可预期：范围选择规则稳定（起始≤结束，跨月一致导航），错误与空状态提示明确。
• 使用场景（按场景概述）
  • 日程安排
    • 常用单日选择或短范围（1–7天）；需清晰的当天高亮与跨周导航。
    • 可提供“今天/明天/本周”等快捷预设。
  • 报表筛选
    • 多见范围选择（如“本月”“上月”“近7天”）；强调快速设定与格式标准化（YYYY-MM-DD）。
    • 支持禁用未来日期或超出数据可用期的日期。
  • 预订流程
    • 典型为起止日期（入住—离店）；需清晰的选中状态连线与禁选规则（不可逆、最短/最长天数）。
    • 提供跨月稳定导航与已售罄/不可用日期的禁用样式。

属性说明

组件结构

• 输入区
  • 文本输入框：显示当前选择值；支持占位、清除、错误提示。
  • 触发图标：点击展开/收起弹层。
  • 清除控件（可选）：当 allowClear=true 且有值时显示。
• 弹层（日历面板）
  • 月份头部：当前年月、跨月导航（前一月/后一月）。
  • 日期网格：按周显示日期；包含默认、悬停、选中、禁用等状态。
  • 范围高亮（type='range'）：起始/结束日期标记与连续选区高亮。
  • 快捷预设区（可选）：列出预设项，点击后快速填充值。
• 辅助信息
  • 错误/帮助文案：位于输入框下方或内部，提示格式错误、越界等。
  • 无数据或空结果说明：用于空状态。

交互状态

• 默认状态
  • 输入框显示占位或当前值；弹层收起；控件可点击。
• 聚焦状态
  • 输入框获得焦点；弹层可根据策略自动展开；边框高亮。
• 悬停状态
  • 鼠标悬停输入框、清除控件或日期单元格时，显示悬停样式。
• 选中状态
  • 单日模式：选中日期高亮。
  • 范围模式：起始与结束高亮，区间连续高亮；跨月选择保持连续性。
• 禁用状态
  • 输入框与弹层不可交互；禁用日期单元格不可点击且样式弱化。
• 错误状态
  • 输入框与辅助文案显示错误提示；错误样式与读屏提示同步。

交互（按场景说明）

• 日程安排
  • 选择流程：点击输入框展开面板 → 选择单日或短范围 → 确认后收起。
  • 快捷：提供“今天/明天/本周”，点击即填充值。
  • 约束：可禁用过去日期或非工作日视业务规则。
• 报表筛选
  • 选择流程：优先使用范围预设（“近7天/本月/上月”），减少手动选择成本。
  • 键盘与输入：允许直接键入标准格式（YYYY-MM-DD），失焦校验并同步面板。
  • 约束：禁用未来日期；当越界时给出错误并阻止提交。
• 预订流程
  • 选择流程：先选入住日期，再选离店日期，自动高亮连线；支持跨月。
  • 约束：rangeConstraints 限制最短/最长天数；禁用售罄或不可用日期。
  • 反馈：当离店早于入住或不满足最短/最长时，显示错误并清晰指示修正方式。

空状态与错误提示（按场景说明）

• 空状态
  • 通用：输入框显示 placeholder；面板可显示“请选择日期”或预设列表。
  • 日程安排：空状态下强调当日高亮与“快速选择”入口。
  • 报表筛选：展示与数据有效期相关的说明（如“数据更新至：YYYY-MM-DD”）。
  • 预订流程：在空状态下，禁用不可预订日期并展示说明（如“节假日已满”）。
• 错误提示类型与文案
  • 格式错误：输入不符合 format；文案示例：“请输入有效日期，格式为 YYYY-MM-DD。”
  • 越界错误：选择超出 minDate/maxDate；文案示例：“选择日期需在可选范围内。”
  • 逻辑错误（范围）：结束早于开始；文案示例：“结束日期需不早于开始日期。”
  • 约束不满足：不满足最短/最长跨度；文案示例：“选择范围至少 X 天/不超过 Y 天。”
  • 不可用日期：命中 disabledDate；文案示例：“该日期不可选择。”
• 错误呈现
  • 在输入框下方或内联展示错误文本；同时应用错误边框与图标。
  • 读屏文本与 ARIA 属性同步，确保无障碍提示一致。
  • 更正策略：保留已选起点，引导用户重新选择有效终点（范围模式）。

使用示例

// 注意：以下为与技术栈无关的伪代码，属性名与事件需按实际项目实现对齐。

// 1. 单日选择（受控）
<DatePicker
  type="single"
  value={Date('2025-10-10')}
  format="YYYY-MM-DD"
  presets={[
    { label: '今天', value: Date('2025-10-10') },
    { label: '明天', value: Date('2025-10-11') },
  ]}
  minDate={Date('2020-01-01')}
  maxDate={Date('2030-12-31')}
  onChange={(d) => setDate(d)}
/>

// 2. 日期范围（非受控，含约束与禁用未来）
<DatePicker
  type="range"
  defaultValue={[Date('2025-10-01'), Date('2025-10-07')]}
  format="YYYY-MM-DD"
  rangeConstraints={{ minSpan: 2, maxSpan: 30 }}
  disabledDate={(d) => d > Today()}
  presets={[
    { label: '近7天', value: [Today().addDays(-6), Today()] },
    { label: '本月', value: [StartOfMonth(Today()), EndOfMonth(Today())] },
  ]}
/>

// 3. 报表筛选（允许输入与空状态）
<FormField label="统计周期">
  <DatePicker
    type="range"
    placeholder={['开始日期', '结束日期']}
    allowClear={true}
    format="YYYY-MM-DD"
    readOnlyInput={false}
    onChange={(range) => refreshReport(range)}
  />
  <HelperText>数据更新至：2025-10-10</HelperText>
</FormField>

注意事项

• 使用限制
  • 精度至“日”，不支持时分秒；如需时间选择，请使用 TimePicker 或 DateTime 组合组件。
  • 范围模式下结束日期必须不早于开始日期；跨月选择应保持连续高亮。
  • 当启用 rangeConstraints 时，必须在 UI 与校验层同时生效。
• 兼容性说明
  • 国际化：默认格式为 YYYY-MM-DD；应与 locale 配合展示月份与星期文案。
  • 无障碍：交互目标≥44px；为输入与日期单元格提供可感知焦点与 ARIA 属性。
  • 键盘交互建议：Tab 在可交互元素间切换；方向键在日历中移动；Enter 确认选择。
• 性能考虑
  • disabledDate 为高频调用函数时，应避免复杂计算；可对结果进行缓存。
  • 跨月导航与范围高亮需在渲染层优化，避免整面板重绘。
  • 受控模式下，onChange 与值更新应保持幂等与最小重渲染。

相关组件

• Input（输入框）
• Popover（弹层/气泡层）
• Calendar（日历网格）
• TimePicker（时间选择器）
• FormField（表单字段容器）

组件名称

OTPInput

概述

• 功能描述
  • 用于输入一次性短验证码（One-Time Password/Code），以等宽格承载多位字符，支持自动聚焦与整串粘贴，完成后触发回调。
• 设计原则
  • 明确性：将多位验证码分割为等宽格，降低认知负担。
  • 可达性：提供清晰的读屏提示与分组语义，确保键盘与读屏器可用。
  • 稳定性：粘贴、删除、禁用与错误等状态下行为可预期。
• 使用场景
  • 登录二次验证（2FA/OTP）
  • 敏感操作（如转账、修改安全设置）确认

属性说明

说明：

• 组件默认在挂载后将焦点置于第一格（自动聚焦）。
• “错误/禁用”为组件支持的交互状态，具体呈现通常由上层表单或样式体系控制（例如通过表单校验结果为组件根元素添加错误态样式，或通过业务逻辑控制禁用态）。

交互状态

• 默认状态
  • 等宽格显示，占位符为空；可逐位输入；支持整串粘贴。
• 悬停状态
  • 非触屏设备上，边框或背景可轻微强化，提示可交互（不影响输入逻辑）。
• 激活状态（聚焦）
  • 当前格获得聚焦，具备清晰的焦点可视指示；读屏器应提示“请输入共 length 位验证码”或等效说明。
• 错误状态
  • 视觉上以错误样式标识（如边框/说明文案），同时为根容器或单元格添加可被读屏识别的错误语义（详见无障碍说明）。
• 禁用状态
  • 禁止输入与粘贴，维持占位展示；焦点不可进入。

行为补充：

• 粘贴：当用户粘贴完整验证码时，自动按位分配至各格；若超出 length，额外字符忽略；若不足 length，按序填充已有位。
• 删除：按退格键可删除当前位内容。若业务有特殊删除规则，应对外一致。

使用示例

// 场景：登录二次验证（6位数字验证码）
// 框架无关伪代码/类 React 风格示例（仅使用本文档声明的 props）

function TwoFactorForm() {
  const [code, setCode] = useState('');      // 当前输入串
  const [submitting, setSubmitting] = useState(false);
  const [error, setError] = useState('');

  const handleChange = (val) => {
    setCode(val);              // 局部状态更新
    setError('');              // 输入变化时清理错误展示（如有）
    // 注意：如需实时校验，请在此对请求做防抖处理，避免高频请求。
  };

  const handleComplete = async (val) => {
    setSubmitting(true);
    setError('');
    try {
      // 将 val 发送到后端进行校验
      await api.verifyOTP(val);
      // 通过后进入下一步流程
      proceed();
    } catch (e) {
      setError('验证码有误，请重试');
      // 可在错误态下清空或保留输入，依业务需求决定
      // setCode('');
    } finally {
      setSubmitting(false);
    }
  };

  return (
    <form aria-labelledby="otp-label" onSubmit={(e) => e.preventDefault()}>
      <div id="otp-label">验证码</div>
      <OTPInput
        length={6}
        mask={false}
        type="number"
        onChange={handleChange}
        onComplete={handleComplete}
      />
      {error ? (
        <div role="alert" aria-live="assertive">{error}</div>
      ) : null}

      <button type="submit" disabled={submitting || code.length < 6}>
        下一步
      </button>
    </form>
  );
}

// 场景：敏感操作确认（禁用/错误态展示由外部控制）
// - 禁用时不允许编辑与粘贴
function SensitiveActionOTP({ disabled }) {
  const [code, setCode] = useState('');
  const [error, setError] = useState('');

  return (
    <div className={`otp-field ${disabled ? 'is-disabled' : ''} ${error ? 'is-error' : ''}`}>
      <label>短信验证码</label>
      <OTPInput
        length={6}
        mask
        type="number"
        onChange={setCode}
        onComplete={(v) => { /* 提交或下一步 */ }}
      />
      {error ? <div className="field-error" role="alert">{error}</div> : null}
    </div>
  );
}

// 防抖示例：在 onChange 中做服务端预校验（例如黑名单检测/速率限制提示）
const debounce = (fn, wait = 200) => {
  let t; return (...args) => { clearTimeout(t); t = setTimeout(() => fn(...args), wait); };
};

function OTPWithDebouncedCheck() {
  const [tip, setTip] = useState('');
  const debouncedCheck = useMemo(() => debounce(async (val) => {
    if (!val) return;
    const ok = await api.precheck(val); // 轻量接口
    setTip(ok ? '' : '验证码格式异常或已过期提示');
  }, 250), []);

  return (
    <div>
      <OTPInput
        length={6}
        type="number"
        onChange={(val) => {
          debouncedCheck(val);
        }}
        onComplete={(val) => {/* 提交校验 */}}
      />
      {tip ? <div aria-live="polite">{tip}</div> : null}
    </div>
  );
}

注意事项

• 使用限制
  • length 应与后端约定保持一致；跨端（Web/移动）需统一位数与校验规则。
  • 粘贴仅接受可见 ASCII 数字与常见全角数字；超长截断，不足不触发完成回调。
  • mask 仅影响展示，不应改变 onChange/onComplete 传出的实际值。
• 兼容性说明
  • 数字键盘：在 Web 实现中，为保证移动端数字键盘可用且保留前导零，应确保实现方案不会丢失前导零；如使用原生 number 类型可能导致前导零被省略，需谨慎评估。
  • 读屏器：应提供分组与错误提示（见无障碍）。在低版本读屏器上，完成提示可通过 aria-live polite 提示补偿。
• 性能考虑
  • 受控渲染：内部更新应尽量局部化，避免每次输入全量重渲染。
  • 输入防抖：将频繁的网络校验逻辑放入 onChange 的防抖中；将最终提交放入 onComplete，可减少请求次数。
  • 粘贴优化：对整串粘贴的解析应一次性写入，避免逐格触发多次回调。

无障碍

• 分组与标签
  • 根容器应使用 role="group" 并配有清晰可见的标签文本（例如“验证码”）；若通过可见标签标注，可通过 aria-labelledby 关联。
• 读屏提示
  • 聚焦时提示“请输入共 N 位验证码”；完成时通过 aria-live polite 提示“已输入 N 位验证码”或等效文案。
• 错误与描述
  • 错误态应设置 aria-invalid（适用于输入单元）或通过 aria-describedby 与错误信息绑定，使读屏器可感知。
• 键盘可达性
  • 焦点应明确可见；Tab 可进入组件，Shift+Tab 可离开组件；删除与粘贴行为对键盘与读屏一致可用。

相关组件

• Input/TextField（基础输入）
• FormField（表单校验与错误呈现）
• Button（提交/下一步）
• Message/Toast（校验结果反馈）
• Countdown/ResendCode（重发验证码）