> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 日期格式化器

> ArcScript 中用于解析、格式化、比较以及转换日期和时间值的格式化器。

## 常用日期格式化器

以下格式化器是最常用的日期格式化器。每个格式化器都提供了一个示例供参考。

更多日期格式语法示例请参阅[示例日期格式](#示例日期格式)。

<Note>某些格式化器的可选参数周围的方括号不是必需的；它们仅用于表示该参数是可选的。</Note>

### now(\[outputformat])

根据指定的 *outputformat* 返回当前系统日期时间（默认格式为：`yyyy-MM-dd'T'hh:mm:sszzz`）。此格式化器的特殊之处在于它不会修改输入属性（变量），因此不需要输入属性。

* **outputformat**：可选的格式说明符。有效说明符包括 `d`（短日期模式）、`D`（长日期模式）、`f`（长日期/短时间模式）、`F`（长日期/时间模式）、`g`（常规短日期/时间模式）、`G`（常规短日期/长时间模式）、`r` 或 `R`（RFC1123 模式）、`s`（可排序日期/时间模式）、`t`（短时间模式）、`T`（长时间模式）、`file`（Windows 文件时间）、`MM/dd/yy` 等。

#### 示例

```xml theme={null}
<arc:set attr="timestamp" value="[now()]" />
```

### todate(\[outputformat]\[, inputformat]\[, strictInputFormat])

将输入属性格式化为 *outputformat* 指定格式的日期（默认输出格式为：`yyyy-MM-dd'T'hh:mm:sszzz`）。有关日期格式示例及其表达方式，请参阅[示例日期格式](#示例日期格式)。

<Note>如果在空输入属性上调用此格式化器，它会输出按上述默认输出格式格式化的当前系统时间。</Note>

* **outputformat**：可选的格式说明符。有效说明符包括 `d`（短日期模式）、`D`（长日期模式）、`f`（长日期/短时间模式）、`F`（长日期/时间模式）、`g`（常规短日期/时间模式）、`G`（常规短日期/长时间模式）、`r` 或 `R`（RFC1123 模式）、`s`（可排序日期/时间模式）、`t`（短时间模式）、`T`（长时间模式）、`file`（Windows 文件时间）、`MM/dd/yy` 等。
* **inputformat**：可选的输入格式说明符。默认值为 `autodetected`。
* **strictInputFormat**：检查传入的日期值是否与输入格式匹配。如果不匹配，则抛出错误。

此格式化器会尝试自动检测输入值的格式；如果格式化器无法确定输入格式，你可以指定 *inputformat* 参数。

使用 *strictInputFormat* 参数检查传入的日期值是否与输入格式匹配：如果不匹配，任务会抛出错误，而不是将日期转换为标准日期格式。默认情况下不检查。要强制检查，请向格式化器添加 `true`。

#### 示例

```xml theme={null}
<arc:set attr="simpleDate" value="01-30-2020" />
<arc:set attr="reformattedDate" value="[simpleDate | todate('yyyyMMdd', 'dd-MM-yyyy')]" />
```

### dateadd(intervaltype, value\[, outputformat]\[, inputformat])

向输入日期添加指定时间量并返回结果。

* **intervaltype**：要添加的时间单位（year、month、day、hour、minute、second 或 millisecond）。
* **value**：要添加多少个 *intervaltype* 中所选单位。
* **outputformat**：可选的格式说明符。有效说明符包括 `d`（短日期模式）、`D`（长日期模式）、`f`（长日期/短时间模式）、`F`（长日期/时间模式）、`g`（常规短日期/时间模式）、`G`（常规短日期/长时间模式）、`r` 或 `R`（RFC1123 模式）、`s`（可排序日期/时间模式）、`t`（短时间模式）、`T`（长时间模式）、`file`（Windows 文件时间）、`MM/dd/yy` 等。
* **inputformat**：可选的输入格式说明符。默认值为 `autodetected`。

此格式化器会尝试自动检测输入值的格式；如果格式化器无法确定输入属性的日期时间格式，你可以指定 *inputformat* 参数。结果会以 *outputformat* 指定的格式返回（默认格式为：`yyyy-MM-dd'T'hh:mm:sszzz`）。

#### 示例

```xml theme={null}
<arc:set attr="shipdate" value="2020-03-15" />
<arc:set attr="estmArrivalDate" value="[shipdate | dateadd('day', 2)]" />
```

## 更多日期格式化器

下面列出了不太常用的格式化器。

### compare(\[value]\[, inputformat])

返回一个带符号数字，表示属性值和参数值所代表日期的相对大小。

* **value**：可选的日期字符串表示形式，用于与属性值进行比较。默认值为 `now`。
* **inputformat**：可选的输入格式说明符。默认值为 `autodetected`。

### convertTimezone(\[targetTimezone]\[, inputformat]\[, outputformat]\[, sourceTimezone])

将 `datetime` 从一个时区转换为另一个时区。

* **targetTimezone**：转换的目标时区。默认值为 `Local`，即应用程序服务器的本地时区。时区字符串必须采用 IANA 格式，例如 `America/Los_Angeles`。
* **inputformat**：可选的输入格式说明符。默认值为 `autodetected`。
* **outputformat**：可选的输出格式（例如 `MM/dd/yyyy HH:mm`）。
* **sourceTimezone**：源日期时间的时区。仅当未指定输入日期时才需要。

#### 示例

```xml theme={null}
<arc:set attr="old.timezone" value="2025-04-25T15:53:57" />
<arc:set attr="output.data" value="The current timezone is [old.timezone|converttimezone('Asia/Tokyo','yyyy-MM-ddTHH:mm:ss','yyyy-MM-dd HH:mm:ss','America/Los_Angeles')]" />
<arc:set attr="output.filename" value="time.txt" />
<arc:push item="output" />
```

### date(\[outputformat])

如果提供了参数，则以参数指定的格式返回当前系统日期和时间。

* **outputformat**：可选的格式说明符。有效说明符包括 `d`（短日期模式）、`D`（长日期模式）、`f`（长日期/短时间模式）、`F`（长日期/时间模式）、`g`（常规短日期/时间模式）、`G`（常规短日期/长时间模式）、`r` 或 `R`（RFC1123 模式）、`s`（可排序日期/时间模式）、`t`（短时间模式）、`T`（长时间模式）、`file`（Windows 文件时间）、`MM/dd/yy` 等。

<Note>此格式化器是上文所述 *now()* 格式化器的别名。</Note>

### datediff(\[interval]\[, value]\[, inputformat])

返回当前时间与 *value* 参数指定日期之间的差值（以 *interval* 参数指定的单位表示）。

* **interval**：可选的结果间隔单位。指定 day、hour、minute、second 或 millisecond。
* **value**：可选的日期字符串表示形式，用于与属性值进行比较。默认值为 `now`。
* **inputformat**：可选的输入格式说明符。默认值为 `autodetected`。

### day(\[inputformat])

返回属性值所代表日期的日组成部分，以 1 到 31 之间的值表示。

* **inputformat**：可选的输入格式说明符。默认值为 `autodetected`。

### dayofweek(\[inputformat])

返回属性值所代表日期的星期几。

* **inputformat**：可选的输入格式说明符。默认值为 `autodetected`。

### dayofyear(\[inputformat])

返回属性值所代表日期在一年中的第几天，以 1 到 366 之间的值表示。

* **inputformat**：可选的输入格式说明符。默认值为 `autodetected`。

### filetimenow()

返回当前系统文件时间的日期和时间。

### fromfiletime(\[outputformat])

将有效文件时间转换为有效日期时间值，并按 `outputformat` 参数指定的格式进行格式化（如果提供）。

* **outputformat**：可选的格式说明符。有效说明符包括 `d`（短日期模式）、`D`（长日期模式）、`f`（长日期/短时间模式）、`F`（长日期/时间模式）、`g`（常规短日期/时间模式）、`G`（常规短日期/长时间模式）、`r` 或 `R`（RFC1123 模式）、`s`（可排序日期/时间模式）、`t`（短时间模式）、`T`（长时间模式）、`file`（Windows 文件时间）、`MM/dd/yy` 等。

### isleap(\[ifleap]\[, ifnotleap])

如果属性值所代表的 4 位年份是闰年，则返回 *true*（或 *ifleap*）；否则返回 *false*（或 *ifnotleap*）。

* **ifleap**：如果属性值是闰年，则返回的可选值。
* **ifnotleap**：如果属性值不是闰年，则返回的可选值。

### month(\[inputformat])

返回属性值所代表日期的月份组成部分，以 1 到 12 之间的值表示。

* **inputformat**：可选的输入格式说明符。默认值为 *autodetected*。

### timezone()

获取 IANA 格式的默认时区（例如 `America/Los_Angeles`）。

#### 示例

```xml theme={null}
<arc:set attr="output.data" value="The current timezone is [_|timezone()]" />
<arc:set attr="output.filename" value="time.txt" />
<arc:push item="output" />
```

### tofiletime(\[inputformat])

将有效日期时间转换为有效文件时间值。

* **inputformat**：可选的输入格式说明符。默认值为 `autodetected`。

### toutc(\[outputformat]\[, inputformat])

返回属性值指定的日期，将其转换为 UTC，并按 *outputformat* 参数指定的格式进行格式化（如果提供）。

* **outputformat**：可选的格式说明符。有效说明符包括 `d`（短日期模式）、`D`（长日期模式）、`f`（长日期/短时间模式）、`F`（长日期/时间模式）、`g`（常规短日期/时间模式）、`G`（常规短日期/长时间模式）、`r` 或 `R`（RFC1123 模式）、`s`（可排序日期/时间模式）、`t`（短时间模式）、`T`（长时间模式）、`file`（Windows 文件时间）、`MM/dd/yy` 等。

### utcnow(\[outputformat])

返回当前系统 UTC 日期和时间。

* **outputformat**：可选的格式说明符。有效说明符包括 `d`（短日期模式）、`D`（长日期模式）、`f`（长日期/短时间模式）、`F`（长日期/时间模式）、`g`（常规短日期/时间模式）、`G`（常规短日期/长时间模式）、`r` 或 `R`（RFC1123 模式）、`s`（可排序日期/时间模式）、`t`（短时间模式）、`T`（长时间模式）、`file`（Windows 文件时间）、`MM/dd/yy` 等。

### weekday(\[inputformat])

以整数形式返回星期几，其中周一为 0，周日为 6。

* **inputformat**：可选的输入格式说明符。默认值为 `autodetected`。

### year(\[inputformat])

返回属性值所代表日期的年份组成部分。

* **inputformat**：可选的输入格式说明符。默认值为 `autodetected`。

## 示例日期格式

以下是供参考的日期格式字符串示例。使用它们可以自定义日期格式化器以适应你的用例。由于各版本支持的内容存在差异，本节同时包含跨平台版本和 .NET 版本的结果。

在下表的每个示例中，日期为 2024 年 3 月 5 日。时间为东部标准时区（UTC-5）午夜后 12 小时 31 分 5 秒 336 毫秒。

| **日期格式字符串**                  | **跨平台结果**                       | **.NET 结果**                     |
| ---------------------------- | ------------------------------- | ------------------------------- |
| MM-dd-yy                     | 03-05-24                        | 03-05-24                        |
| MM/dd/yyyy HH:mm             | 03/05/2024 12:31                | 03/05/2024 12:31                |
| yyyy-MM-dd HH:mm:ss          | 2024-03-05 12:31:05             | 2024-03-05 12:31:05             |
| yyyy-MM-dd HH:mm:ss.SSS      | 2024-03-05 12:31:05.336         | 不适用于 .NET                       |
| yyyy-MM-dd HH:mm:ss.fff      | 2024-03-05 12:31:05.336         | 2024-03-05 12:31:05.336         |
| yyyy-MM-dd HH:mm:ss X        | 2024-03-05 17:31:05 -05         | 不适用于 .NET                       |
| ddd dd MMM yyyy HH:mm:ss zzz | Tue 05 Mar 2024 12:31:05 -05:00 | Tue 05 Mar 2024 12:31:05 -05:00 |
| ddd dd MMM yyyy HH:mm:ss z   | Tue 05 Mar 2024 12:31:05 -0500  | Tue 05 Mar 2024 12:31:05 -5     |

### 带字面字符的日期格式

在 DateTime 字符串中使用字面字符（例如 'T'）时，请特别注意格式化器外部可能使用的引号字符。例如，如果格式化器用于值 XML 属性，以便为 {siteNameShort}Script 属性赋值，你可能需要使用不同的引号样式或转义序列，以避免字符串过早结束。

例如，如果你在自定义脚本中为项目属性创建 datetime 值，并且需要字面字符，可以选择在开始和结束 [arc:set](../keyword-reference/op-arc-set) 标签之间定义属性值。请注意，未设置 `value=""`。

```xml theme={null}
<arc:set attr="out.data">[_ | now("yyyy-MM-dd'T'HH:mm:ss")]</arc:set>
```