refactor: DatePicker Component

packages/vant/src/date-picker/DatePicker.tsx

@@ -0,0 +1,191 @@
+import {
+  ref,
+  watch,
+  computed,
+  nextTick,
+  defineComponent,
+  type PropType,
+  ExtractPropTypes,
+} from 'vue';
+
+// Utils
+import {
+  pick,
+  clamp,
+  extend,
+  isDate,
+  padZero,
+  createNamespace,
+} from '../utils';
+import {
+  times,
+  sharedProps,
+  getTrueValue,
+  getMonthEndDay,
+  pickerInheritKeys,
+} from '../datetime-picker/utils';
+
+// Components
+import { Picker, PickerOption } from '../picker';
+
+const currentYear = new Date().getFullYear();
+const [name] = createNamespace('date-picker');
+
+export type DatePickerColumnType = 'year' | 'month' | 'day';
+
+const datePickerProps = extend({}, sharedProps, {
+  modelValue: Date,
+  columnsType: {
+    type: Array as PropType<DatePickerColumnType[]>,
+    default: () => ['year', 'month', 'day'],
+  },
+  minDate: {
+    type: Date,
+    default: () => new Date(currentYear - 10, 0, 1),
+    validator: isDate,
+  },
+  maxDate: {
+    type: Date,
+    default: () => new Date(currentYear + 10, 11, 31),
+    validator: isDate,
+  },
+});
+
+export type DatePickerProps = ExtractPropTypes<typeof datePickerProps>;
+
+export default defineComponent({
+  name,
+
+  props: datePickerProps,
+
+  emits: ['confirm', 'cancel', 'change', 'update:modelValue'],
+
+  setup(props, { emit, slots }) {
+    const formatValue = (value?: Date) => {
+      if (isDate(value)) {
+        const timestamp = clamp(
+          value.getTime(),
+          props.minDate.getTime(),
+          props.maxDate.getTime()
+        );
+        return new Date(timestamp);
+      }
+
+      return undefined;
+    };
+
+    const currentDate = ref(formatValue(props.modelValue));
+
+    const getBoundary = (type: 'max' | 'min', value: Date) => {
+      const boundary = props[`${type}Date` as const];
+      const year = boundary.getFullYear();
+      let month = 1;
+      let date = 1;
+
+      if (type === 'max') {
+        month = 12;
+        date = getMonthEndDay(value.getFullYear(), value.getMonth() + 1);
+      }
+
+      if (value.getFullYear() === year) {
+        month = boundary.getMonth() + 1;
+
+        if (value.getMonth() + 1 === month) {
+          date = boundary.getDate();
+        }
+      }
+
+      return {
+        [`${type}Year`]: year,
+        [`${type}Month`]: month,
+        [`${type}Date`]: date,
+      };
+    };
+
+    const ranges = computed(() => {
+      const { maxYear, maxDate, maxMonth } = getBoundary(
+        'max',
+        currentDate.value || props.minDate
+      );
+      const { minYear, minDate, minMonth } = getBoundary(
+        'min',
+        currentDate.value || props.minDate
+      );
+
+      return props.columnsType.map((type) => {
+        switch (type) {
+          case 'year':
+            return {
+              type: 'year',
+              range: [minYear, maxYear],
+            };
+          case 'month':
+            return {
+              type: 'month',
+              range: [minMonth, maxMonth],
+            };
+          case 'day':
+            return {
+              type: 'day',
+              range: [minDate, maxDate],
+            };
+          default:
+            throw new Error(
+              `[Vant] DatePicker: unsupported columns type: ${type}`
+            );
+        }
+      });
+    });
+
+    const columns = computed(() =>
+      ranges.value.map(({ type, range }) => {
+        const options = times(
+          range[1] - range[0] + 1,
+          (index): PickerOption => {
+            const value = padZero(range[0] + index);
+            return props.formatter(type, {
+              text: value,
+              value,
+            });
+          }
+        );
+
+        if (props.filter) {
+          return props.filter(type, options);
+        }
+
+        return options;
+      })
+    );
+
+    // watch(currentDate, (value, oldValue) =>
+    //   emit('update:modelValue', oldValue ? value : null)
+    // );
+
+    // watch(
+    //   () => props.modelValue,
+    //   (value) => {
+    //     value = formatValue(value);
+
+    //     if (value && value.valueOf() !== currentDate.value?.valueOf()) {
+    //       currentDate.value = value;
+    //     }
+    //   }
+    // );
+
+    const onChange = (...args: unknown[]) => emit('change', ...args);
+    const onCancel = (...args: unknown[]) => emit('cancel', ...args);
+    const onConfirm = (...args: unknown[]) => emit('confirm', ...args);
+
+    return () => (
+      <Picker
+        v-slots={slots}
+        columns={columns.value}
+        onChange={onChange}
+        onCancel={onCancel}
+        onConfirm={onConfirm}
+        {...pick(props, pickerInheritKeys)}
+      />
+    );
+  },
+});

packages/vant/src/date-picker/README.md

@@ -0,0 +1,201 @@
+# DatePicker
+
+### Intro
+
+Used to select date, usually used with the [Popup](#/en-US/popup) component.
+
+### Install
+
+Register component globally via `app.use`, refer to [Component Registration](#/en-US/advanced-usage#zu-jian-zhu-ce) for more registration ways.
+
+```js
+import { createApp } from 'vue';
+import { DatePicker } from 'vant';
+
+const app = createApp();
+app.use(DatePicker);
+```
+
+## Usage
+
+### Basic Usage
+
+```html
+<van-date-picker v-model="currentDate" title="Choose Date" />
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const currentDate = ref(new Date(2021, 0, 1));
+    return {
+      minDate: new Date(2020, 0, 1),
+      maxDate: new Date(2025, 10, 1),
+      currentDate,
+    };
+  },
+};
+```
+
+### Columns Type
+
+Using `columns-type` prop to control the type of columns.
+
+For example:
+
+- Pass in `['year']` to select year.
+- Pass in `['month']` to select month.
+- Pass in `['year', 'month']` to select year and month.
+- Pass in `['month', 'day']` to select month and day.
+
+```html
+<van-date-picker
+  v-model="currentDate"
+  title="Choose Year-Month"
+  :min-date="minDate"
+  :max-date="maxDate"
+  :columns-type="['year', 'month']"
+/>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const currentDate = ref(new Date(2021, 0, 1));
+    return {
+      minDate: new Date(2020, 0, 1),
+      maxDate: new Date(2025, 10, 1),
+      currentDate,
+    };
+  },
+};
+```
+
+### Options Formatter
+
+```html
+<van-date-picker
+  v-model="currentDate"
+  title="Choose Year-Month"
+  :min-date="minDate"
+  :max-date="maxDate"
+  :formatter="formatter"
+  :columns-type="['year', 'month']"
+/>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const currentDate = ref(new Date(2021, 0, 1));
+
+    const formatter = (type, val) => {
+      if (type === 'year') {
+        return `${val} Year`;
+      }
+      if (type === 'month') {
+        return `${val} Month`;
+      }
+      return val;
+    };
+
+    return {
+      minDate: new Date(2020, 0, 1),
+      maxDate: new Date(2025, 10, 1),
+      formatter,
+      currentDate,
+    };
+  },
+};
+```
+
+### Options Filter
+
+```html
+<van-date-picker
+  v-model="currentDate"
+  title="Choose Year-Month"
+  :filter="filter"
+  :min-date="minDate"
+  :max-date="maxDate"
+  :columns-type="['year', 'month']"
+/>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const currentDate = ref(new Date(2021, 0, 1));
+    const filter = (type, options) => {
+      if (type === 'month') {
+        return options.filter((option) => Number(option.value) % 6 === 0);
+      }
+      return options;
+    };
+
+    return {
+      filter,
+      minDate: new Date(2020, 0, 1),
+      maxDate: new Date(2025, 10, 1),
+      currentTime,
+    };
+  },
+};
+```
+
+## API
+
+### Props
+
+| Attribute | Description | Type | Default |
+| --- | --- | --- | --- |
+| columns-type | Columns type | _string[]_ | `['year', 'month', 'day']` |
+| min-date | Min date | _Date_ | Ten years ago on January 1 |
+| max-date | Max date | _Date_ | Ten years later on December 31 |
+| title | Toolbar title | _string_ | `''` |
+| confirm-button-text | Text of confirm button | _string_ | `Confirm` |
+| cancel-button-text | Text of cancel button | _string_ | `Cancel` |
+| show-toolbar | Whether to show toolbar | _boolean_ | `true` |
+| loading | Whether to show loading prompt | _boolean_ | `false` |
+| readonly | Whether to be readonly | _boolean_ | `false` |
+| filter | Option filter | _(type: string, options: PickerOption[]) => PickerOption[]_ | - |
+| formatter | Option formatter | _(type: string, option: PickerOption) => PickerOption_ | - |
+| option-height | Option height, supports `px` `vw` `vh` `rem` unit, default `px` | _number \| string_ | `44` |
+| visible-option-num | Count of visible columns | _number \| string_ | `6` |
+| swipe-duration | Duration of the momentum animation，unit `ms` | _number \| string_ | `1000` |
+
+### Events
+
+| Event | Description | Arguments |
+| --- | --- | --- |
+| confirm | Emitted when the confirm button is clicked | _{ selectedValues, selectedOptions }_ |
+| cancel | Emitted when the cancel button is clicked | _{ selectedValues, selectedOptions }_ |
+| change | Emitted when current option is changed | _{ selectedValues, selectedOptions, columnIndex }_ |
+
+### Slots
+
+| Name           | Description                  | SlotProps              |
+| -------------- | ---------------------------- | ---------------------- |
+| default        | Custom toolbar content       | -                      |
+| title          | Custom title                 | -                      |
+| confirm        | Custom confirm button text   | -                      |
+| cancel         | Custom cancel button text    | -                      |
+| option         | Custom option content        | _option: PickerOption_ |
+| columns-top    | Custom content above columns | -                      |
+| columns-bottom | Custom content below columns | -                      |
+
+### Types
+
+The component exports the following type definitions:
+
+```ts
+import type { DatePickerProps } from 'vant';
+```

packages/vant/src/date-picker/README.zh-CN.md

@@ -0,0 +1,225 @@
+# DatePicker 日期选择
+
+### 介绍
+
+日期选择器，用于选择年、月、日，通常与[弹出层](#/zh-CN/popup)组件配合使用。
+
+### 引入
+
+通过以下方式来全局注册组件，更多注册方式请参考[组件注册](#/zh-CN/advanced-usage#zu-jian-zhu-ce)。
+
+```js
+import { createApp } from 'vue';
+import { DatePicker } from 'vant';
+
+const app = createApp();
+app.use(DatePicker);
+```
+
+## 代码演示
+
+### 基础用法
+
+通过 `v-model` 绑定当前选中的日期，通过 `min-date` 和 `max-date` 属性来设定可选的时间范围。
+
+```html
+<van-date-picker v-model="currentDate" title="选择日期" />
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const currentDate = ref(new Date(2021, 0, 1));
+    return {
+      minDate: new Date(2020, 0, 1),
+      maxDate: new Date(2025, 10, 1),
+      currentDate,
+    };
+  },
+};
+```
+
+### 选项类型
+
+通过 `columns-type` 属性可以控制选项的类型，支持以任意顺序对 `year`、`month` 和 `day` 进行排列组合。
+
+比如：
+
+- 传入 `['year']` 来单独选择年份。
+- 传入 `['month']` 来单独选择月份。
+- 传入 `['year', 'month']` 来选择年份和月份。
+- 传入 `['month', 'day']` 来选择月份和日期。
+
+```html
+<van-date-picker
+  v-model="currentDate"
+  title="选择年月"
+  :min-date="minDate"
+  :max-date="maxDate"
+  :columns-type="['year', 'month']"
+/>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const currentDate = ref(new Date(2021, 0, 1));
+    return {
+      minDate: new Date(2020, 0, 1),
+      maxDate: new Date(2025, 10, 1),
+      currentDate,
+    };
+  },
+};
+```
+
+### 格式化选项
+
+通过传入 `formatter` 函数，可以对选项文字进行格式化处理。
+
+```html
+<van-date-picker
+  v-model="currentDate"
+  title="选择年月"
+  :min-date="minDate"
+  :max-date="maxDate"
+  :formatter="formatter"
+  :columns-type="['year', 'month']"
+/>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const currentDate = ref(new Date(2021, 0, 1));
+
+    const formatter = (type, val) => {
+      if (type === 'year') {
+        return `${val}年`;
+      }
+      if (type === 'month') {
+        return `${val}月`;
+      }
+      return val;
+    };
+
+    return {
+      minDate: new Date(2020, 0, 1),
+      maxDate: new Date(2025, 10, 1),
+      formatter,
+      currentDate,
+    };
+  },
+};
+```
+
+### 过滤选项
+
+通过传入 `filter` 函数，可以对选项数组进行过滤，实现自定义选项间隔。
+
+```html
+<van-date-picker
+  v-model="currentDate"
+  title="选择年月"
+  :filter="filter"
+  :min-date="minDate"
+  :max-date="maxDate"
+  :columns-type="['year', 'month']"
+/>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const currentDate = ref(new Date(2021, 0, 1));
+    const filter = (type, options) => {
+      if (type === 'month') {
+        return options.filter((option) => Number(option.value) % 6 === 0);
+      }
+      return options;
+    };
+
+    return {
+      filter,
+      minDate: new Date(2020, 0, 1),
+      maxDate: new Date(2025, 10, 1),
+      currentTime,
+    };
+  },
+};
+```
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| columns-type | 选项类型，由 `year`、`month` 和 `day` 组成的数组 | _string[]_ | `['year', 'month', 'day']` |
+| min-date | 可选的最小时间，精确到日 | _Date_ | 十年前 |
+| max-date | 可选的最大时间，精确到日 | _Date_ | 十年后 |
+| title | 顶部栏标题 | _string_ | `''` |
+| confirm-button-text | 确认按钮文字 | _string_ | `确认` |
+| cancel-button-text | 取消按钮文字 | _string_ | `取消` |
+| show-toolbar | 是否显示顶部栏 | _boolean_ | `true` |
+| loading | 是否显示加载状态 | _boolean_ | `false` |
+| readonly | 是否为只读状态，只读状态下无法切换选项 | _boolean_ | `false` |
+| filter | 选项过滤函数 | _(type: string, options: PickerOption[]) => PickerOption[]_ | - |
+| formatter | 选项格式化函数 | _(type: string, option: PickerOption) => PickerOption_ | - |
+| option-height | 选项高度，支持 `px` `vw` `vh` `rem` 单位，默认 `px` | _number \| string_ | `44` |
+| visible-option-num | 可见的选项个数 | _number \| string_ | `6` |
+| swipe-duration | 快速滑动时惯性滚动的时长，单位 `ms` | _number \| string_ | `1000` |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| confirm | 点击完成按钮时触发 | _{ selectedValues, selectedOptions }_ |
+| cancel | 点击取消按钮时触发 | _{ selectedValues, selectedOptions }_ |
+| change | 选项改变时触发 | _{ selectedValues, selectedOptions, columnIndex }_ |
+
+### Slots
+
+| 名称           | 说明                   | 参数                   |
+| -------------- | ---------------------- | ---------------------- |
+| default        | 自定义整个顶部栏的内容 | -                      |
+| title          | 自定义标题内容         | -                      |
+| confirm        | 自定义确认按钮内容     | -                      |
+| cancel         | 自定义取消按钮内容     | -                      |
+| option         | 自定义选项内容         | _option: PickerOption_ |
+| columns-top    | 自定义选项上方内容     | -                      |
+| columns-bottom | 自定义选项下方内容     | -                      |
+
+### 类型定义
+
+组件导出以下类型定义：
+
+```ts
+import type { DatePickerProps } from 'vant';
+```
+
+## 常见问题
+
+### 设置 min-date 或 max-date 后出现页面卡死的情况？
+
+请注意不要在模板中直接使用类似 `min-date="new Date()"` 的写法，这样会导致每次渲染组件时传入一个新的 Date 对象，而传入新的数据会触发下一次渲染，从而陷入死循环。
+
+正确的做法是将 `min-date` 作为一个数据定义在 `data` 函数或 `setup` 中。
+
+### 在 iOS 系统上初始化组件失败？
+
+如果你遇到了在 iOS 上无法渲染组件的问题，请确认在创建 Date 对象时没有使用 `new Date('2020-01-01')` 这样的写法，iOS 不支持以中划线分隔的日期格式，正确写法是 `new Date('2020/01/01')`。
+
+对此问题的详细解释：[stackoverflow](https://stackoverflow.com/questions/13363673/javascript-date-is-invalid-on-ios)。
+
+### 在桌面端无法操作组件？
+
+参见[桌面端适配](#/zh-CN/advanced-usage#zhuo-mian-duan-gua-pei)。

packages/vant/src/date-picker/demo/index.vue

@@ -0,0 +1,99 @@
+<script setup lang="ts">
+import VanDatePicker from '..';
+import { ref } from 'vue';
+import { useTranslate } from '../../../docs/site/use-translate';
+import type { PickerOption } from '../../picker';
+
+const t = useTranslate({
+  'zh-CN': {
+    day: '日',
+    year: '年',
+    month: '月',
+    chooseDate: '选择日期',
+    columnsType: '选项类型',
+    optionsFilter: '过滤选项',
+    chooseYearMonth: '选择年月',
+    optionsFormatter: '格式化选项',
+  },
+  'en-US': {
+    day: ' Day',
+    year: ' Year',
+    month: ' Month',
+    chooseDate: 'Choose Date',
+    columnsType: 'Columns Type',
+    optionsFilter: 'Options Filter',
+    chooseYearMonth: 'Choose Year-Month',
+    optionsFormatter: 'Options Formatter',
+  },
+});
+
+const minDate = new Date(2020, 0, 1);
+const maxDate = new Date(2025, 10, 1);
+const basicDate = ref(new Date(2021, 0, 1));
+const yearMonthDate = ref(new Date(2021, 0, 1));
+const formatterDate = ref(new Date(2021, 0, 1));
+const filterDate = ref(new Date(2021, 0, 1));
+
+const filter = (type: string, options: PickerOption[]) => {
+  if (type === 'month') {
+    return options.filter((option) => Number(option.value) % 6 === 0);
+  }
+  return options;
+};
+
+const formatter = (type: string, option: PickerOption) => {
+  if (type === 'year') {
+    option.text += t('year');
+  }
+  if (type === 'month') {
+    option.text += t('month');
+  }
+  if (type === 'day') {
+    option.text += t('day');
+  }
+  return option;
+};
+</script>
+
+<template>
+  <demo-block card :title="t('basicUsage')">
+    <van-date-picker
+      v-model="basicDate"
+      :title="t('chooseDate')"
+      :min-date="minDate"
+      :max-date="maxDate"
+    />
+  </demo-block>
+
+  <demo-block card :title="t('columnsType')">
+    <van-date-picker
+      v-model="yearMonthDate"
+      :title="t('chooseYearMonth')"
+      :min-date="minDate"
+      :max-date="maxDate"
+      :columns-type="['year', 'month']"
+    />
+  </demo-block>
+
+  <demo-block card :title="t('optionsFormatter')">
+    <van-date-picker
+      v-model="formatterDate"
+      :title="t('chooseYearMonth')"
+      :min-date="minDate"
+      :max-date="maxDate"
+      :formatter="formatter"
+      :columns-type="['year', 'month']"
+    />
+  </demo-block>
+
+  <demo-block card :title="t('optionsFilter')">
+    <van-date-picker
+      v-model="filterDate"
+      :title="t('optionFilter')"
+      :filter="filter"
+      :min-date="minDate"
+      :max-date="maxDate"
+      :columns-type="['year', 'month']"
+    />
+  </demo-block>
+</template>

packages/vant/src/date-picker/index.ts

@@ -0,0 +1,12 @@
+import { withInstall } from '../utils';
+import _DatePicker, { DatePickerProps } from './DatePicker';
+
+export const DatePicker = withInstall(_DatePicker);
+export default DatePicker;
+export type { DatePickerProps };
+
+declare module 'vue' {
+  export interface GlobalComponents {
+    VanDatePicker: typeof DatePicker;
+  }
+}

packages/vant/src/time-picker/README.md

@@ -132,6 +132,10 @@ export default {
 | Attribute | Description | Type | Default |
 | --- | --- | --- | --- |
 | v-model | Current time | _string_ | - |
+| min-hour | Min hour for `time` type | _number \| string_ | `0` |
+| max-hour | Max hour for `time` type | _number \| string_ | `23` |
+| min-minute | Max minute for `time` type | _number \| string_ | `0` |
+| max-minute | Max minute for `time` type | _number \| string_ | `59` |
 | title | Toolbar title | _string_ | `''` |
 | confirm-button-text | Text of confirm button | _string_ | `Confirm` |
 | cancel-button-text | Text of cancel button | _string_ | `Cancel` |
@@ -143,10 +147,6 @@ export default {
 | option-height | Option height, supports `px` `vw` `vh` `rem` unit, default `px` | _number \| string_ | `44` |
 | visible-option-num | Count of visible columns | _number \| string_ | `6` |
 | swipe-duration | Duration of the momentum animation，unit `ms` | _number \| string_ | `1000` |
-| min-hour | Min hour for `time` type | _number \| string_ | `0` |
-| max-hour | Max hour for `time` type | _number \| string_ | `23` |
-| min-minute | Max minute for `time` type | _number \| string_ | `0` |
-| max-minute | Max minute for `time` type | _number \| string_ | `59` |
 
 ### Events
 

packages/vant/src/time-picker/README.zh-CN.md

@@ -131,6 +131,10 @@ export default {
 | 参数 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |
 | v-model | 当前选中的时间 | _string_ | - |
+| min-hour | 可选的最小小时 | _number \| string_ | `0` |
+| max-hour | 可选的最大小时 | _number \| string_ | `23` |
+| min-minute | 可选的最小分钟 | _number \| string_ | `0` |
+| max-minute | 可选的最大分钟 | _number \| string_ | `59` |
 | title | 顶部栏标题 | _string_ | `''` |
 | confirm-button-text | 确认按钮文字 | _string_ | `确认` |
 | cancel-button-text | 取消按钮文字 | _string_ | `取消` |
@@ -142,10 +146,6 @@ export default {
 | option-height | 选项高度，支持 `px` `vw` `vh` `rem` 单位，默认 `px` | _number \| string_ | `44` |
 | visible-option-num | 可见的选项个数 | _number \| string_ | `6` |
 | swipe-duration | 快速滑动时惯性滚动的时长，单位 `ms` | _number \| string_ | `1000` |
-| min-hour | 可选的最小小时 | _number \| string_ | `0` |
-| max-hour | 可选的最大小时 | _number \| string_ | `23` |
-| min-minute | 可选的最小分钟 | _number \| string_ | `0` |
-| max-minute | 可选的最大分钟 | _number \| string_ | `59` |
 
 ### Events
 

packages/vant/vant.config.mjs

@@ -169,8 +169,8 @@ export default {
                 title: 'Checkbox 复选框',
               },
               {
-                path: 'datetime-picker',
+                path: 'date-picker',
-                title: 'DatetimePicker 日期选择',
+                title: 'DatePicker 日期选择',
               },
               {
                 path: 'field',
@@ -579,8 +579,8 @@ export default {
                 title: 'Checkbox',
               },
               {
-                path: 'datetime-picker',
+                path: 'date-picker',
-                title: 'DatetimePicker',
+                title: 'DatePicker',
               },
               {
                 path: 'field',