> ## 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 屬性，以便為 ArcScript 屬性賦值，你可能需要使用不同的引號樣式或轉義序列，以避免字串過早結束。

例如，如果你在自定義指令碼中為專案屬性建立 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>
```