useDateFormatter

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

Usage

使用自动导入的 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 提供本地化日期格式化。
支持单个日期、日期范围、日期数组以及嵌套对象的批量转换。

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

时区处理

默认情况下，useDateFormatter 使用本地时区。如需指定时区，使用 timeZone 参数：

const formatter = useDateFormatter({
  timeZone: 'Asia/Shanghai'
})

// 或使用其他时区
const formatterNY = useDateFormatter({
  timeZone: 'America/New_York'
})

时区标识符遵循 IANA 时区数据库规范。常用时区包括：

'Asia/Shanghai' - 中国标准时间
'America/New_York' - 美国东部时间
'Europe/London' - 英国时间
'Asia/Tokyo' - 日本标准时间

类型安全

useDateFormatter 提供了类型守卫函数用于运行时类型检查：

const formatter = useDateFormatter()

// 检查是否为 DateValue
if (formatter.isDateValue(someValue)) {
  // TypeScript 自动推断 someValue 为 DateValue 类型
  const formatted = formatter.format(someValue)
}

// 检查是否为 DateRange
if (formatter.isDateRange(someValue)) {
  // TypeScript 自动推断 someValue 为 DateRange 类型
  const { start, end } = someValue
}

与 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>

这种方式可以：

自动处理所有嵌套的日期字段
保持对象结构不变
避免手动遍历转换

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()