ChuFix UI v0.11.0
开发预览 更新于 2026-05-10

DatePicker 日期选择

输入框 + 月历面板 —— 日 / 月 / 年三视图、约束日期、快捷预设、ISO 周序、键盘导航。

基础用法

v-model 绑定 'YYYY-MM-DD' 格式字符串。点击触发器弹出月历面板，再点击日期格子直接选中并关闭。点击月份名进入月份选择，点击年份进入年份选择。

背景 视口
2026-05-09
src/App.vue 
<script setup lang="ts">
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const value = ref<string | null>('2026-05-09');
</script>
<template>
  <div style="display: flex; gap: 12px; align-items: center;">
    <CfDatePicker v-model="value" clearable />
    <code style="font-size: 12px;">{{ value ?? '(无)' }}</code>
  </div>
</template>
<script setup>
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const value = ref<string | null>('2026-05-09');
</script>
<template>
  <div style="display: flex; gap: 12px; align-items: center;">
    <CfDatePicker v-model="value" clearable />
    <code style="font-size: 12px;">{{ value ?? '(无)' }}</code>
  </div>
</template>
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
const [value, setValue] = useState<string | null>('2026-05-09');
return <CfDatePicker value={value} clearable onChange={(v) => setValue(v)} />;
}
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
const [value, setValue] = useState<string | null>('2026-05-09');
return <CfDatePicker value={value} clearable onChange={(v) => setValue(v)} />;
}

三档尺寸 / 三种变体

size（sm/md/lg）与 Input、Button 保持一致。variant —— outline（默认）/ filled（实底，密集表单常用）/ ghost（透明，悬停描边，文档/工具栏内嵌常用）。error 让边框变红，用于表单校验提示。

背景 视口
src/App.vue 
<script setup lang="ts">
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const a = ref<string | null>('2026-05-09');
const b = ref<string | null>('2026-05-09');
const c = ref<string | null>('2026-05-09');
</script>
<template>
  <div class="demo-row">
    <CfDatePicker v-model="a" size="sm" clearable />
    <CfDatePicker v-model="b" size="md" clearable />
    <CfDatePicker v-model="c" size="lg" clearable />
  </div>
</template>
<script setup>
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const a = ref<string | null>('2026-05-09');
const b = ref<string | null>('2026-05-09');
const c = ref<string | null>('2026-05-09');
</script>
<template>
  <div class="demo-row">
    <CfDatePicker v-model="a" size="sm" clearable />
    <CfDatePicker v-model="b" size="md" clearable />
    <CfDatePicker v-model="c" size="lg" clearable />
  </div>
</template>
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
  const [a, setA] = useState('2026-05-09');
  const [a, setA] = useState('2026-05-09');
  const [b, setB] = useState('2026-05-09');
  const [b, setB] = useState('2026-05-09');
  const [c, setC] = useState('2026-05-09');
  const [c, setC] = useState('2026-05-09');
  return (
    <>
      <CfDatePicker value={a} onChange={setA} size="sm" />
      <CfDatePicker value={b} onChange={setB} size="md" />
      <CfDatePicker value={c} onChange={setC} size="lg" />
    </>
  );
}
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
  const [a, setA] = useState('2026-05-09');
  const [a, setA] = useState('2026-05-09');
  const [b, setB] = useState('2026-05-09');
  const [b, setB] = useState('2026-05-09');
  const [c, setC] = useState('2026-05-09');
  const [c, setC] = useState('2026-05-09');
  return (
    <>
      <CfDatePicker value={a} onChange={setA} size="sm" />
      <CfDatePicker value={b} onChange={setB} size="md" />
      <CfDatePicker value={c} onChange={setC} size="lg" />
    </>
  );
}
背景 视口
src/App.vue 
<script setup lang="ts">
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const a = ref<string | null>('2026-05-09');
const b = ref<string | null>('2026-05-09');
const c = ref<string | null>('2026-05-09');
const d = ref<string | null>(null);
</script>
<template>
  <div class="demo-row">
    <CfDatePicker v-model="a" variant="outline" clearable />
    <CfDatePicker v-model="b" variant="filled" clearable />
    <CfDatePicker v-model="c" variant="ghost" clearable />
    <CfDatePicker v-model="d" variant="outline" error placeholder="错误态" />
  </div>
</template>
<script setup>
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const a = ref<string | null>('2026-05-09');
const b = ref<string | null>('2026-05-09');
const c = ref<string | null>('2026-05-09');
const d = ref<string | null>(null);
</script>
<template>
  <div class="demo-row">
    <CfDatePicker v-model="a" variant="outline" clearable />
    <CfDatePicker v-model="b" variant="filled" clearable />
    <CfDatePicker v-model="c" variant="ghost" clearable />
    <CfDatePicker v-model="d" variant="outline" error placeholder="错误态" />
  </div>
</template>
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
  const [a, setA] = useState('2026-05-09');
  const [a, setA] = useState('2026-05-09');
  const [b, setB] = useState('2026-05-09');
  const [b, setB] = useState('2026-05-09');
  const [c, setC] = useState('2026-05-09');
  const [c, setC] = useState('2026-05-09');
  const [d, setD] = useState(null);
  const [d, setD] = useState(null);
  return (
    <>
      <CfDatePicker value={a} onChange={setA} variant="outline" />
      <CfDatePicker value={b} onChange={setB} variant="filled" />
      <CfDatePicker value={c} onChange={setC} variant="ghost" />
      <CfDatePicker value={d} onChange={setD} error placeholder="错误态" />
    </>
  );
}
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
  const [a, setA] = useState('2026-05-09');
  const [a, setA] = useState('2026-05-09');
  const [b, setB] = useState('2026-05-09');
  const [b, setB] = useState('2026-05-09');
  const [c, setC] = useState('2026-05-09');
  const [c, setC] = useState('2026-05-09');
  const [d, setD] = useState(null);
  const [d, setD] = useState(null);
  return (
    <>
      <CfDatePicker value={a} onChange={setA} variant="outline" />
      <CfDatePicker value={b} onChange={setB} variant="filled" />
      <CfDatePicker value={c} onChange={setC} variant="ghost" />
      <CfDatePicker value={d} onChange={setD} error placeholder="错误态" />
    </>
  );
}

周起始日

weekStartsOn 切换一周从哪天开始 —— 1 周一（默认，ISO 8601 / 大多中文场景）；0 周日（北美场景）。仅改变面板表头与日期排布，不影响 v-model 值。

背景 视口
src/App.vue 
<script setup lang="ts">
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const a = ref<string | null>('2026-05-09');
const b = ref<string | null>('2026-05-09');
</script>
<template>
  <div class="demo-row">
    <div>
      <span class="adm-label">weekStartsOn = 1（周一开头，默认）</span>
      <CfDatePicker v-model="a" :week-starts-on="1" />
    </div>
    <div>
      <span class="adm-label">weekStartsOn = 0（周日开头）</span>
      <CfDatePicker v-model="b" :week-starts-on="0" />
    </div>
  </div>
</template>
<style scoped>
.adm-label { display: block; color: var(--fg-3); font-size: var(--t-12); margin-bottom: 6px; }
</style>
<script setup>
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const a = ref<string | null>('2026-05-09');
const b = ref<string | null>('2026-05-09');
</script>
<template>
  <div class="demo-row">
    <div>
      <span class="adm-label">weekStartsOn = 1（周一开头，默认）</span>
      <CfDatePicker v-model="a" :week-starts-on="1" />
    </div>
    <div>
      <span class="adm-label">weekStartsOn = 0（周日开头）</span>
      <CfDatePicker v-model="b" :week-starts-on="0" />
    </div>
  </div>
</template>
<style scoped>
.adm-label { display: block; color: var(--fg-3); font-size: var(--t-12); margin-bottom: 6px; }
</style>
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
  const [a, setA] = useState('2026-05-09');
  const [a, setA] = useState('2026-05-09');
  const [b, setB] = useState('2026-05-09');
  const [b, setB] = useState('2026-05-09');
  return (
    <>
      <CfDatePicker value={a} onChange={setA} weekStartsOn={1} />
      <CfDatePicker value={b} onChange={setB} weekStartsOn={0} />
    </>
  );
}
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
  const [a, setA] = useState('2026-05-09');
  const [a, setA] = useState('2026-05-09');
  const [b, setB] = useState('2026-05-09');
  const [b, setB] = useState('2026-05-09');
  return (
    <>
      <CfDatePicker value={a} onChange={setA} weekStartsOn={1} />
      <CfDatePicker value={b} onChange={setB} weekStartsOn={0} />
    </>
  );
}

范围 + disabledDate

minDate / maxDate 限制可选区间；disabledDate 是一个 (date: Date) => boolean 回调，返回 true 的日期会被打上删除线、禁止点击。

背景 视口
src/App.vue 
<script setup lang="ts">
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const value = ref<string | null>(null);

function noWeekends(d: Date) {
  const day = d.getDay();
  return day === 0 || day === 6;
}
</script>
<template>
  <CfDatePicker
    v-model="value"
    placeholder="工作日，2026 全年"
    min-date="2026-01-01"
    max-date="2026-12-31"
    :disabled-date="noWeekends"
    clearable
  />
</template>
<script setup>
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const value = ref<string | null>(null);

function noWeekends(d) {
  const day = d.getDay();
  return day === 0 || day === 6;
}
</script>
<template>
  <CfDatePicker
    v-model="value"
    placeholder="工作日，2026 全年"
    min-date="2026-01-01"
    max-date="2026-12-31"
    :disabled-date="noWeekends"
    clearable
  />
</template>
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

const noWeekends = (d: Date) => d.getDay() === 0 || d.getDay() === 6;

export default function Demo() {
const [value, setValue] = useState<string | null>(null);
return (
  <CfDatePicker
    value={value}
    minDate="2026-01-01"
    maxDate="2026-12-31"
    disabledDate={noWeekends}
    clearable
    onChange={(v) => setValue(v)}
  />
);
}
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

const noWeekends = (d) => d.getDay() === 0 || d.getDay() === 6;

export default function Demo() {
const [value, setValue] = useState<string | null>(null);
return (
  <CfDatePicker
    value={value}
    minDate="2026-01-01"
    maxDate="2026-12-31"
    disabledDate={noWeekends}
    clearable
    onChange={(v) => setValue(v)}
  />
);
}

显示格式

format 控制触发器上显示的格式（不影响 v-model 的存储格式，存储始终是 'YYYY-MM-DD'）。支持 token：YYYY YY MM M DD D。

背景 视口
src/App.vue 
<script setup lang="ts">
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const a = ref<string | null>('2026-05-09');
const b = ref<string | null>('2026-05-09');
const c = ref<string | null>('2026-05-09');
</script>
<template>
  <div style="display:flex; flex-direction:column; gap: 8px; max-width: 320px;">
    <CfDatePicker v-model="a" format="YYYY-MM-DD" />
    <CfDatePicker v-model="b" format="YYYY 年 M 月 D 日" />
    <CfDatePicker v-model="c" format="DD/MM/YYYY" />
  </div>
</template>
<script setup>
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const a = ref<string | null>('2026-05-09');
const b = ref<string | null>('2026-05-09');
const c = ref<string | null>('2026-05-09');
</script>
<template>
  <div style="display:flex; flex-direction:column; gap: 8px; max-width: 320px;">
    <CfDatePicker v-model="a" format="YYYY-MM-DD" />
    <CfDatePicker v-model="b" format="YYYY 年 M 月 D 日" />
    <CfDatePicker v-model="c" format="DD/MM/YYYY" />
  </div>
</template>
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
  const [a, setA] = useState<string | null>('2026-05-09');
  const [b, setB] = useState<string | null>('2026-05-09');
  const [c, setC] = useState<string | null>('2026-05-09');
  return (
    <>
      <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 320 }}>
          <CfDatePicker value={a} onChange={setA} format="YYYY-MM-DD" />
          <CfDatePicker value={b} onChange={setB} format="YYYY 年 M 月 D 日" />
          <CfDatePicker value={c} onChange={setC} format="DD/MM/YYYY" />
        </div>
    </>
  );
}
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
  const [a, setA] = useState<string | null>('2026-05-09');
  const [b, setB] = useState<string | null>('2026-05-09');
  const [c, setC] = useState<string | null>('2026-05-09');
  return (
    <>
      <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 320 }}>
          <CfDatePicker value={a} onChange={setA} format="YYYY-MM-DD" />
          <CfDatePicker value={b} onChange={setB} format="YYYY 年 M 月 D 日" />
          <CfDatePicker value={c} onChange={setC} format="DD/MM/YYYY" />
        </div>
    </>
  );
}

快捷预设

presets 接受一个 { label, value } 数组，在面板左侧渲染一列预设按钮。value 可以是固定 Date / ISO 字符串，或是一个返回它们的函数（每次点击重新求值，适合”今天” / “7 天前”这类相对日期）。

背景 视口
src/App.vue 
<script setup lang="ts">
import { ref } from 'vue';
import { CfDatePicker, type DatePickerPreset } from '@chufix-design/vue';

const value = ref<string | null>(null);

const presets: DatePickerPreset[] = [
  { label: '今天', value: () => new Date() },
  {
    label: '昨天',
    value: () => {
      const d = new Date();
      d.setDate(d.getDate() - 1);
      return d;
    },
  },
  {
    label: '7 天前',
    value: () => {
      const d = new Date();
      d.setDate(d.getDate() - 7);
      return d;
    },
  },
  {
    label: '本月 1 号',
    value: () => {
      const d = new Date();
      return new Date(d.getFullYear(), d.getMonth(), 1);
    },
  },
  {
    label: '上月 1 号',
    value: () => {
      const d = new Date();
      return new Date(d.getFullYear(), d.getMonth() - 1, 1);
    },
  },
];
</script>
<template>
  <CfDatePicker v-model="value" clearable :presets="presets" />
</template>
<script setup>
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const value = ref<string | null>(null);

const presets= [
  { label: '今天', value: () => new Date() },
  {
    label: '昨天',
    value: () => {
      const d = new Date();
      d.setDate(d.getDate() - 1);
      return d;
    },
  },
  {
    label: '7 天前',
    value: () => {
      const d = new Date();
      d.setDate(d.getDate() - 7);
      return d;
    },
  },
  {
    label: '本月 1 号',
    value: () => {
      const d = new Date();
      return new Date(d.getFullYear(), d.getMonth(), 1);
    },
  },
  {
    label: '上月 1 号',
    value: () => {
      const d = new Date();
      return new Date(d.getFullYear(), d.getMonth() - 1, 1);
    },
  },
];
</script>
<template>
  <CfDatePicker v-model="value" clearable :presets="presets" />
</template>
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
  const [value, setValue] = useState<string | null>(null);

  const presets: DatePickerPreset[] = [
    { label: '今天', value: () => new Date() },
    {
      label: '昨天',
      value: () => {
        const d = new Date();
        d.setDate(d.getDate() - 1);
        return d;
      },
    },
    {
      label: '7 天前',
      value: () => {
        const d = new Date();
        d.setDate(d.getDate() - 7);
        return d;
      },
    },
    {
      label: '本月 1 号',
      value: () => {
        const d = new Date();
        return new Date(d.getFullYear(), d.getMonth(), 1);
      },
    },
    {
      label: '上月 1 号',
      value: () => {
        const d = new Date();
        return new Date(d.getFullYear(), d.getMonth() - 1, 1);
      },
    },
  ];
  return (
    <>
      <CfDatePicker value={value} onChange={setValue} clearable presets={presets} />
    </>
  );
}
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
  const [value, setValue] = useState<string | null>(null);

  const presets= [
    { label: '今天', value: () => new Date() },
    {
      label: '昨天',
      value: () => {
        const d = new Date();
        d.setDate(d.getDate() - 1);
        return d;
      },
    },
    {
      label: '7 天前',
      value: () => {
        const d = new Date();
        d.setDate(d.getDate() - 7);
        return d;
      },
    },
    {
      label: '本月 1 号',
      value: () => {
        const d = new Date();
        return new Date(d.getFullYear(), d.getMonth(), 1);
      },
    },
    {
      label: '上月 1 号',
      value: () => {
        const d = new Date();
        return new Date(d.getFullYear(), d.getMonth() - 1, 1);
      },
    },
  ];
  return (
    <>
      <CfDatePicker value={value} onChange={setValue} clearable presets={presets} />
    </>
  );
}

ISO 周序

show-week-number 在日期网格左侧加一列 ISO 8601 周数（周一为一周起点）。

背景 视口
src/App.vue 
<script setup lang="ts">
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const value = ref<string | null>(null);
</script>
<template>
  <CfDatePicker v-model="value" clearable show-week-number />
</template>
<script setup>
import { ref } from 'vue';
import { CfDatePicker } from '@chufix-design/vue';

const value = ref<string | null>(null);
</script>
<template>
  <CfDatePicker v-model="value" clearable show-week-number />
</template>
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <>
      <CfDatePicker value={value} onChange={setValue} clearable showWeekNumber />
    </>
  );
}
import { useState } from 'react';
import { CfDatePicker } from '@chufix-design/react';

export default function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <>
      <CfDatePicker value={value} onChange={setValue} clearable showWeekNumber />
    </>
  );
}

键盘导航

面板打开时支持以下按键：

按键行为
← / → / ↑ / ↓在日期网格上移动焦点
PageUp / PageDown上一月 / 下一月
Home / End跳到本月第一天 / 最后一天
Enter选中当前 focus 的日期
Esc关闭面板

API

Props

属性类型默认值说明
modelValue (Vue) / value (React)Date | string | number | nullnull当前日期，输入容忍 ISO / 时间戳 / Date
formatstring'YYYY-MM-DD'触发器显示格式
placeholderstring'选择日期'占位文案
variant'outline' | 'filled' | 'ghost''outline'触发器视觉模式
size'sm' | 'md' | 'lg''md'尺寸
disabledbooleanfalse禁用
clearablebooleanfalse显示清除按钮
errorbooleanfalse错误态
minDate / maxDateDateLike—可选范围
disabledDate(date: Date) => boolean—自定义禁用规则
weekStartsOn0 | 110 = 周日开头，1 = 周一开头
view'day' | 'month' | 'year''day'初始打开视图
showWeekNumberbooleanfalse在日期网格前加一列 ISO 周序
presetsDatePickerPreset[]—快捷预设按钮：{ label, value: Date | string | () => ... }
namestring—透传给隐式表单字段，用于原生表单提交
idstring—触发器的 id，便于外部 <label for> 关联

Events

Vue 事件React 回调载荷类型说明
update:modelValueonChange（第一参数）string | null日期变化时触发，载荷是 ISO 'YYYY-MM-DD' 或 null
changeonChange（第二参数）Date | null同步触发；载荷是 JS Date 对象（便于直接做 < / > 比较）

React 端 onChange(value, date) 同时接收两个参数 —— 第一个是 ISO 字符串（与 value 同型），第二个是 Date \| null。

反馈与讨论

DatePicker 日期选择 的讨论

0
0 / 600
正在加载评论...