useDateFormatter

基于 @internationalized/date 的日期格式化和处理工具。

用法

使用自动导入的 useDateFormatter composable 进行日期格式化、转换和操作，基于 @internationalized/date 库实现国际化日期处理。

<script setup lang="ts">
const formatter = useDateFormatter({ locale: 'zh-CN' })

const today = formatter.getToday()
const formattedDate = formatter.format(today)
// "2025年11月29日"

const isoString = formatter.toISO(today)
// "2025-11-29"
</script>

useDateFormatter 基于 Intl.DateTimeFormat 提供本地化日期格式化。
支持单个日期、日期范围、日期数组以及嵌套对象的批量转换。
通过 timeZone 选项指定时区（默认本地时区），标识符遵循 IANA 时区数据库规范。

所有格式化和转换方法都内置了错误处理，当传入 null 或 undefined 时会返回空字符串或 null，避免抛出异常。

能力一览

下表覆盖了 useDateFormatter 在常用日期场景下的输出形态：

当前 locale: zh-CN · timeZone: UTC

调用	返回值
format(today)	2026年6月21日
toISO(today)	2026-06-21
toTimestamp(today)	1782000000000
toUnixTimestamp(today)	1782000000
isWeekend(today)	true
isWeekday(today)	false
isToday(today)	true
getDayOfWeek(today)	6
getDayOfWeekName(today, "long")	星期日
getDayOfWeekName(today, "short")	周日
getStartOfMonth(today)	2026-06-01
getEndOfMonth(today)	2026-06-30
getStartOfYear(today)	2026-01-01
getEndOfYear(today)	2026-12-31
formatRange(start, end)	2026年6月21日 - 2026年6月28日
formatArray([d, d+1, d+2])	2026年6月21日, 2026年6月22日, 2026年6月23日
parse("2026-01-01")?.toString()	2026-01-01

<script setup lang="ts">
const f = useDateFormatter({ locale: 'zh-CN' })
const today = f.getToday()
const range = { start: today, end: today.add({ days: 7 }) }
const list = [today, today.add({ days: 1 }), today.add({ days: 2 })]

const rows = [
  { method: 'format(today)', value: f.format(today) },
  { method: 'toISO(today)', value: f.toISO(today) },
  { method: 'toTimestamp(today)', value: f.toTimestamp(today) },
  { method: 'toUnixTimestamp(today)', value: f.toUnixTimestamp(today) },
  { method: 'isWeekend(today)', value: f.isWeekend(today) },
  { method: 'isWeekday(today)', value: f.isWeekday(today) },
  { method: 'isToday(today)', value: f.isToday(today) },
  { method: 'getDayOfWeek(today)', value: f.getDayOfWeek(today) },
  { method: 'getDayOfWeekName(today, "long")', value: f.getDayOfWeekName(today, 'long') },
  { method: 'getDayOfWeekName(today, "short")', value: f.getDayOfWeekName(today, 'short') },
  { method: 'getStartOfMonth(today)', value: f.toISO(f.getStartOfMonth(today)) },
  { method: 'getEndOfMonth(today)', value: f.toISO(f.getEndOfMonth(today)) },
  { method: 'getStartOfYear(today)', value: f.toISO(f.getStartOfYear(today)) },
  { method: 'getEndOfYear(today)', value: f.toISO(f.getEndOfYear(today)) },
  { method: 'formatRange(start, end)', value: f.formatRange(range.start, range.end) },
  { method: 'formatArray([d, d+1, d+2])', value: f.formatArray(list) },
  { method: 'parse("2026-01-01")?.toString()', value: f.parse('2026-01-01')?.toString() ?? 'null' }
]

const columns = [
  { accessorKey: 'method', header: '调用' },
  { accessorKey: 'value', header: '返回值' }
]
</script>

<template>
  <div class="flex flex-col gap-3">
    <p class="text-xs text-muted">
      当前 locale: {{ f.locale }} · timeZone: {{ f.timeZone }}
    </p>
    <MDataTable :columns="columns" :data="rows" stripe bordered density="compact" />
  </div>
</template>

与 AutoForm 集成

在 AutoForm 中使用日期字段时，建议使用 convertToISO() 进行批量转换后提交：

<script setup lang="ts">
const { afz } = useAutoForm()
const formatter = useDateFormatter()

const schema = afz.object({
  eventDate: afz.calendarDate(),
  eventRange: afz.calendarDate({
    controlProps: { mode: 'range' }
  })
})

const formData = ref()

async function handleSubmit() {
  // 自动处理所有日期字段的转换
  const payload = formatter.convertToISO(formData.value)

  // payload.eventDate: "2025-11-29"
  // payload.eventRange: { start: "2025-11-01", end: "2025-11-30" }

  await api.submit(payload)
}
</script>

convertToISO 自动遍历所有嵌套日期字段并保持对象结构不变，无需手动转换。

API

useDateFormatter()

useDateFormatter(options?: DateFormatterOptions): DateFormatter

创建日期格式化器实例。

Parameters

options

DateFormatterOptions

日期格式化配置选项。

Returns

返回包含以下方法和属性的日期格式化器对象。

格式化方法

format()

(date: DateValue | undefined | null) => string

格式化单个日期为本地化字符串。

formatRange()

(start: DateValue | undefined | null, end: DateValue | undefined | null, separator?: string) => string

格式化日期范围，默认分隔符为 ' - '。

formatArray()

(dates: DateValue[] | undefined | null, separator?: string) => string

格式化日期数组，默认分隔符为 ', '。

转换方法

toISO()

(date: DateValue | undefined | null) => string

转换为 ISO 8601 字符串。

toDate()

(date: DateValue | undefined | null) => Date | null

转换为 JavaScript Date 对象。

toTimestamp()

(date: DateValue | undefined | null) => number | null

转换为时间戳（毫秒）。

toUnixTimestamp()

(date: DateValue | undefined | null) => number | null

转换为 Unix 时间戳（秒）。

parse()

(value: string) => DateValue | null

解析 ISO 8601 日期字符串。自动识别 CalendarDate、CalendarDateTime 或 ZonedDateTime。

工具方法 - 获取日期

getToday()

() => CalendarDate

获取今天的日期。

getNow()

() => ZonedDateTime

获取当前日期时间。

getStartOfWeek()