---
url: /components/date-input.md
---

# DateInput 日期输入框

把 `Input` 的日期模式与日历按钮合在一起：直接输入数字日期，或点右侧日历按钮打开选择器。

* `v-model` 绑定 `Date | null`；输入框里始终按当前语言的顺序显示（英文 `MM/DD/YYYY`，中日 `YYYY/MM/DD`）。
* 失焦或回车时解析输入；非法日期标红并显示错误，合法日期写回模型。
* `picker="false"` 去掉日历按钮，只剩输入。
* 标签始终浮动在描边上方，空值时占位提示（按当前语言的顺序生成，如 `yyyy/mm/dd`）仍完整可见。
* 选择器默认是贴着输入框的弹出层；`modal` 改成模态对话框。
* `description` 默认显示数字顺序提示，可以换成自己的说明。

## 基础用法

当前值：{{ show(date) }}

```vue
<script setup lang="ts">
import { ref } from "vue";
import { DateInput } from "@sharpdotnut/dotsharp";

const date = ref<Date | null>(new Date(2025, 7, 17));
</script>

<template>
  <DateInput v-model="date" />
</template>
```

输入框接受 `/`、`-`、`.` 或空格作分隔符，例如 `08/17/2025`、`2025-8-17`；
年份需要写满四位，`2 月 30 日` 这类不存在的日期会被拒绝。

## 弹出层选择

默认 `picker` 打开贴住输入框的日历弹出层，按「取消」/「确定」提交或丢弃。

当前值：{{ show(picked) }}

```vue
<template>
  <DateInput v-model="picked" label="日期" />
</template>
```

## 模态选择器

`modal` 把日历换成模态对话框，适合窄屏或需要打断当前流程的场景。

当前值：{{ show(modalDate) }}

```vue
<template>
  <DateInput v-model="modalDate" modal label="日期" />
</template>
```

## 样式

`variant` 与 `Input` 一致（`outlined` / `filled`）；`disabled`、`readonly` 直接透传给内部的 `Input`。不通过时与 `Input` 使用同一套错误样式；输入无法解析时同样按不通过显示。

## 表单校验

`validator` 接收当前值（`Date | null`），返回 `false` 表示通过；返回 `true` 或错误文案表示不通过。默认在失焦与选择日期后校验，用 `validateOn` 调整；也暴露 `validate()` / `clearValidate()`。输入无法解析时仍然按内部解析错误显示，优先于验证函数。完整约定见[表单指南](/guide/form)。

## API

| 属性          | 类型                                         | 默认值              | 说明                                          |
| ------------- | -------------------------------------------- | ------------------- | --------------------------------------------- |
| `v-model`     | `Date \| null`                               | `null`              | 选中日期                                      |
| `label`       | `string`                                     | 当前语言的日期      | 浮动标签                                      |
| `variant`     | `"outlined" \| "filled"`                     | `"outlined"`        | 容器样式                                      |
| `disabled`    | `boolean`                                    | `false`             | 禁用                                          |
| `readonly`    | `boolean`                                    | `false`             | 只读                                          |
| `description` | `string`                                     | 数字顺序提示        | 辅助文字                                      |
| `picker`      | `boolean`                                    | `true`              | 是否显示日历按钮                              |
| `modal`       | `boolean`                                    | `false`             | 选择器以模态对话框打开                        |
| `pickerMode`  | `"calendar" \| "input"`                      | `"calendar"`        | 模态选择器的初始模式                          |
| `title`       | `string`                                     | 当前语言            | 模态选择器的标题                              |
| `validator`   | `(value: Date \| null) => boolean \| string` | —                   | 验证函数：`false` 通过，`true` / 字符串不通过 |
| `validateOn`  | `"input" \| "blur" \| ("input" \| "blur")[]` | `["input", "blur"]` | 自动校验时机；传 `[]` 关闭自动校验            |