DateAdd、DateDiff 和 TimeZoneOffset 函式
適用於：
畫布應用程式 模型導向應用程式 Dataverse 公式欄 Power Platform CLI
在日期/時間值新增或尋找差異，並且在當地時間與 UTC 之間轉換。
描述
DateAdd 函式會將單位數新增至日期/時間值。 結果是新的日期/時間值。 您也可以藉由指定負數值以從日期/時間值減去單位數。
DateDiff 函式會傳回兩個日期/時間值之間的差異。 結果是單位整數。
對於這兩個函式，單位可以是 TimeUnit.Milliseconds、TimeUnit.Seconds、TimeUnit.Minutes、TimeUnit.Hours、TimeUnit.Days、TimeUnit.Months、TimeUnit.Quarters 或 TimeUnit.Years。 這兩個函式預設會使用 TimeUnit.Days 做為單位。
TimeZoneOffset 函式會傳回使用者當地時間與 UTC (國際標準時間) 之間的分鐘數。
您可以搭配使用 DateAdd 與 TimeZoneOffset，在使用者的當地時間與 UTC (國際標準時間) 之間進行轉換。 新增 TimeZoneOffset 會將當地時間轉換為 UTC，而減去 (新增負數) 會從 UTC 轉換為當地時間。
另請參閱 Date、Time 和 DateTime 資料類型 及 處理日期和時間。
語法
DateAdd (DateTime，Addition [，Units ])
- DateTime - 必要項目。 要運作的日期/時間值。
- Addition - 必要項目。 要新曾至 DateTime 中的數目，以 Units 為單位。
- Units - 非必要。 要加上的單位類型：TimeUnit.Milliseconds、TimeUnit.Seconds、TimeUnit.Minutes、TimeUnit.Hours、TimeUnit.Days、TimeUnit.Months、TimeUnit.Quarters 或 TimeUnit.Years。 如果未指定，則會使用 TimeUnit.Days。
DateDiff(StartDateTime，EndDateTime [，Units ])
- StartDateTime - 必要項目。 開始日期/時間值。
- EndDateTime - 必要項目。 結束日期/時間值。
- Units - 非必要。 要減去的單位類型：TimeUnit.Milliseconds、TimeUnit.Seconds、TimeUnit.Minutes、TimeUnit.Hours、TimeUnit.Days、TimeUnit.Months、TimeUnit.Quarters 或 TimeUnit.Years。 如果未指定，則會使用 TimeUnit.Days。
TimeZoneOffset( [ DateTime ] )
- DateTime - 非必要。 預計傳回時差的日期/時間值。 根據預設，會使用目前的日期/時間。
範例
在所有範例中，假設目前的日期與時間是 2013 年 7 月 15 日，下午 1:02。
簡單的 DateAdd
| 公式 | 描述 | 結果 |
|---|---|---|
| Text( DateAdd( Now(), 3 ), "dd-mm-yyyy hh:mm" ) |
將三天 (預設單位) 新增至目前的日期與時間。 | "18-07-2013 13:02" |
| Text( DateAdd( Now(), 4, TimeUnit.Hours ), "dd-mm-yyyy hh:mm" ) |
將四個小時新增至目前的日期與時間。 | "15-07-2013 17:02" |
| Text( DateAdd( Today(), 1, TimeUnit.Months ), "dd-mm-yyyy hh:mm" ) |
將一個月新增至目前的日期，今天 的時間不會傳回時間元件。 | "15-08-2013 00:00" |
| Text( DateAdd( Now(), ‑30, TimeUnit.Minutes ), "dd-mm-yyyy hh:mm" ) |
從目前的日期與時間減去 30 分鐘。 | "15-07-2013 12:32" |
簡單的 DateDiff
| 公式 | 描述 | 結果 |
|---|---|---|
| DateDiff( Now(), DateValue("1/1/2014") ) | 以 TimeUnit.Days 為預設單位傳回兩個單位之間的差異 | 170 |
| DateDiff( Now(), DateValue("1/1/2014"), TimeUnit.Months ) | 以 TimeUnit.Months 為單位傳回兩個值之間的差異 | 6 |
| DateDiff( Now(), Today(), TimeUnit.Minutes ) | 傳回目前的日期/時間與目前日期 (不含時間) 之間的差異，以分鐘為單位。 因為 現在 晚於 今天，所以結果會是負數。 | -782 |
日期與分數結果的差異
函式 DateDiff 只會傳回要減去的單位整數，而有效位數則會在指定的單位中提供。 若要以較高的有效位數計算差異，請使用較小的單位，並適當地轉換結果，如下列範例所示。
| 公式 | 描述 | 結果 |
|---|---|---|
| DateDiff( TimeValue("09:45:00"), TimeValue("10:15:36"), TimeUnit.Hours ) | 將忽略分鐘/秒，差異是根據時間決定，最多以小時為單位。 | 1 |
| DateDiff( TimeValue("09:45:00"), TimeValue("10:15:36"), TimeUnit.Minutes )/60 | 在差異中使用分鐘數，而結果會除以 60 以表示以小時為單位的差異。 | 0.5 |
| DateDiff( TimeValue("09:45:00"), TimeValue("10:15:36"), TimeUnit.Seconds )/3600 | 在差異中使用分鐘數和秒數，結果會除以 3600 以表示以小時為單位的差異。 | 0.51 |
轉換成 UTC
若要轉換成 UTC (國際標準時間)，新增指定的時間 TimeZoneOffset。
例如，假設目前的日期與時間是太平洋日光節約時間 (PDT UTC-7) 2013 年 7 月 15 日，下午 1:02。 若要判斷目前的 UTC 時間，請使用：
- DateAdd( Now(), TimeZoneOffset(), TimeUnit.Minutes )
TimeZoneOffset 預設為目前的時間，因此您不需要傳遞引數給它。
若要查看結果，請使用 Text 函式與格式 dd-mm-yyyy hh:mm ，這會傳回 15-07-2013 20:02。
從 UTC 轉換
若要從 UTC 轉換，針對指定的時間減去 TimeZoneOffset (新增負數)。
例如，假設 UTC 日期與時間 2013 年 7 月 15 日，下午 8:02 是儲存在名為 StartTime 的變數。 若要調整使用者時區的時間，請使用：
- DateAdd( StartTime, −TimeZoneOffset( StartTime ), TimeUnit.Minutes )
請注意，TimeZoneOffset 前面的負號會減去時差，而不是新增它。
若要查看結果，請使用 Text 函式與格式 dd-mm-yyyy hh:mm ，如果您位於太平洋日光節約時間的時區，這會傳回 15-07-2013 13:02。