# vue: <DateTime>
URL: https://generaltranslation.com/zh/docs/vue/reference/components/datetime.mdx
---

title: "<DateTime>"
description: 按活动区域设置格式化日期或时间。<DateTime> 组件的 API 参考。

---

`<DateTime>` 组件使用 `Intl.DateTimeFormat` 格式化必填的日期或时间类 `value`。可单独使用，也可作为 [`<T>`](/docs/vue/reference/components/t) 中的运行时变量。

## 概述 [#overview]

通过 `value` 绑定 `Date`、Unix 时间戳 (毫秒) 或日期字符串：

```vue
<DateTime
  :value="publishedAt"
  :options="{ dateStyle: 'medium', timeZone: 'UTC' }"
/>
```

格式化在本地完成。该值不会包含在富文本翻译源中。

## 工作原理 [#how-it-works]

* `Date` 会直接格式化。数字和字符串会先传给 JavaScript `Date` 构造函数。
* `null` 和仅含空白字符的字符串会渲染为空。无效日期字符串会原样渲染。
* 日期字符串的解析和默认时区由 JavaScript 运行时决定。若输出必须在不同环境中保持一致，请使用无歧义的时间戳，并设置 `timeZone`。
* 格式化器 slot 中的子元素会被忽略。请始终提供 `value`，并使用自闭合标签。
* 该组件不会添加任何 HTML 包装元素。

### 区域设置解析

当活动区域设置为配置的默认区域设置时，格式化仅使用该默认区域设置，并忽略 `locales`。对于其他任何活动区域设置，独立 格式化器 会依次尝试显式指定的 `locales`、活动区域设置和默认区域设置。

在 [`<T>`](/docs/vue/reference/components/t) 内，源后备内容使用默认区域设置。已翻译内容会依次尝试活动区域设置和默认区域设置，并忽略显式指定的 `locales` prop。

## 属性 [#props]

| 属性                    | 说明                             | 类型                                 | 可选 | 默认值      |
| --------------------- | ------------------------------ | ---------------------------------- | -- | -------- |
| [`value`](#value)     | 要格式化的日期类值。                     | `Date \| number \| string \| null` | 否  | —        |
| [`options`](#options) | 传递给 `Intl.DateTimeFormat` 的选项。 | `Intl.DateTimeFormatOptions`       | 是  | `{}`     |
| [`locales`](#locales) | 首选的格式化区域设置。                    | `string[]`                         | 是  | 区域设置解析顺序 |

### `value`

**类型** `Date | number | string | null` · **必填**

要格式化的值。数字表示自 Unix 纪元起经过的毫秒数。传入字符串时，建议使用 ISO 8601 时间戳，因为其他日期格式在不同运行时中的解析结果可能不同。

### `options`

**类型** `Intl.DateTimeFormatOptions` · **可选** · **默认值** `{}`

传递给 JavaScript 运行时中 `Intl.DateTimeFormat` 实现的选项。常用选项包括：

| 选项                       | 描述                                       | 类型                                                        | 可选 | 默认值          |
| ------------------------ | ---------------------------------------- | --------------------------------------------------------- | -- | ------------ |
| `localeMatcher`          | 区域设置匹配算法。                                | `'lookup' \| 'best fit'`                                  | 是  | `'best fit'` |
| `calendar`               | 日历系统，例如 `gregory` 或 `japanese`。          | `string`                                                  | 是  | 取决于区域设置      |
| `numberingSystem`        | 数字系统，例如 `latn` 或 `arab`。                 | `string`                                                  | 是  | 取决于区域设置      |
| `timeZone`               | IANA 时区名称，例如 `UTC` 或 `America/New_York`。 | `string`                                                  | 是  | 运行时时区        |
| `dateStyle`              | 预设日期格式长度。                                | `'full' \| 'long' \| 'medium' \| 'short'`                 | 是  | —            |
| `timeStyle`              | 预设时间格式长度。                                | `'full' \| 'long' \| 'medium' \| 'short'`                 | 是  | —            |
| `hour12`                 | 是否使用 12 小时制。                             | `boolean`                                                 | 是  | 取决于区域设置      |
| `hourCycle`              | 小时制周期。                                   | `'h11' \| 'h12' \| 'h23' \| 'h24'`                        | 是  | 取决于区域设置      |
| `weekday`                | 星期显示格式长度。                                | `'long' \| 'short' \| 'narrow'`                           | 是  | —            |
| `era`                    | 纪元显示格式长度。                                | `'long' \| 'short' \| 'narrow'`                           | 是  | —            |
| `year`                   | 年份显示格式。                                  | `'numeric' \| '2-digit'`                                  | 是  | —            |
| `month`                  | 月份显示格式。                                  | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | 是  | —            |
| `day`                    | 日期显示格式。                                  | `'numeric' \| '2-digit'`                                  | 是  | —            |
| `hour`                   | 小时显示格式。                                  | `'numeric' \| '2-digit'`                                  | 是  | —            |
| `minute`                 | 分钟显示格式。                                  | `'numeric' \| '2-digit'`                                  | 是  | —            |
| `second`                 | 秒显示格式。                                   | `'numeric' \| '2-digit'`                                  | 是  | —            |
| `fractionalSecondDigits` | 小数秒精度。                                   | `1 \| 2 \| 3`                                             | 是  | —            |
| `timeZoneName`           | 时区标签格式。                                  | `string`                                                  | 是  | —            |

在不支持此类组合的运行时中，请勿将 `dateStyle` 或 `timeStyle` 与单独的日期时间字段同时使用。有关由运行时定义的完整选项集，请参阅 [`Intl.DateTimeFormat` 选项](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options)。

### `locales`

**类型** `string[]` · **可选** · **默认值** 区域设置解析顺序

用于独立格式化的首选 BCP 47 区域设置代码。仅当活动区域设置不是配置的默认区域设置时，才会优先于当前区域设置和默认区域设置尝试这些代码。

## 示例 [#examples]

```vue title="PublishedAt.vue"
<script setup lang="ts">
import { DateTime, T } from 'gt-vue';

defineProps<{ publishedAt: Date }>();
</script>

<template>
  <T>
    Published
    <DateTime
      :value="publishedAt"
      :options="{ dateStyle: 'long', timeZone: 'UTC' }"
    />.
  </T>
</template>
```

## 服务器端渲染 [#ssr]

服务器端和客户端环境可能会使用不同的默认区域设置或时区，导致 hydration 期间生成不同的字符串。请在两个 [`createGT()`](/docs/vue/reference/functions/create-gt) 插件中配置相同的显式区域设置，并固定 格式化器 的时区：

```vue
<DateTime
  :value="publishedAt"
  :locales="['en-US']"
  :options="{ dateStyle: 'medium', timeZone: 'UTC' }"
/>
```

在服务器端渲染和客户端 hydration 前预加载相同区域设置的目录。当活动区域设置等于配置的默认值时，请注意，该组件会刻意忽略显式指定的 `locales` 列表，并按该默认值进行格式化。