DateAdd 函式 (Visual Basic)

發行項
08/21/2008

更新：2007 年 11 月

傳回已加入指定的時間間隔且包含日期和時間值的 Date 值。

Public Overloads Function DateAdd( _
   ByVal Interval As DateInterval, _
   ByVal Number As Double, _
   ByVal DateValue As DateTime _
) As DateTime
' -or-
Public Overloads Function DateAdd( _
   ByVal Interval As String, _
   ByVal Number As Double, _
   ByVal DateValue As Object _
) As DateTime

參數

Interval
必要項。代表您希望加入之時間間隔的 DateInterval 列舉值或 String 運算式。
Number
必要項。Double - 浮點運算式，表示您想要加入的間隔數；Number 可以是正數 (表示取得未來的日期 / 時間值) 或負數 (表示取得過去的日期 / 時間值)。Number 的小數點後數字部分會被忽略。
DateValue
必要項。Date - 運算式，表示要將間隔加入其中的日期和時間；DateValue 本身在呼叫程式中並不會變更。

設定

Interval 引數可以有下列其中一個設定。

列舉型別值	字串	要加入的時間間隔單位
DateInterval.Day	d	日；截斷為整數值
DateInterval.DayOfYear	y	日；截斷為整數值
DateInterval.Hour	h	時；截斷為整數值
DateInterval.Minute	n	分；截斷為整數值
DateInterval.Month	m	月份；截斷成整數值
DateInterval.Quarter	q	季；截斷為整數值
DateInterval.Second	s	秒；截斷為整數值
DateInterval.Weekday	w	日；截斷為整數值
DateInterval.WeekOfYear	ww	週；截斷為整數值
DateInterval.Year	yyyy	年；截斷為整數值

例外狀況

例外狀況類型	錯誤代碼	條件
InvalidCastException	13	無法將 DateValue 強制為 Date。
ArgumentException	5	Interval 無效。
ArgumentOutOfRangeException	9	計算出的日期早於 1 年 1 月 1 日 00:00:00 或晚於 9999 年 12 月 31 日 23:59:59。

如果將使用非結構化錯誤處理的 Visual Basic 6.0 應用程式升級，請參閱「錯誤代碼」資料行 (您可以將錯誤代碼與 Number 屬性 (Err 物件) 比對)。但是，請盡可能考慮以 Visual Basic 的結構化例外處理概觀取代這類錯誤控制項。

備註

您可以使用 DateAdd 函式，從某個日期加上或減去指定的時間間隔。例如，您可以計算 30 天後的日期或 45 分鐘之前的時間。

若要將天數加入 DateValue，您可以使用 DateInterval.Day、DateInterval.DayOfYear 或 DateInterval.Weekday。因為 DayOfYear 和 Weekday 並不是有意義的時間間隔，所以這些會視為對等用法。

DateAdd 函式絕不會傳回無效的日期。必要時，將結果日期的日部分向後調整為結果年的結果月的最後一天。下列範列會將 1 月 31 日再加上一個月：

Dim NextMonth As Date = DateAdd(DateInterval.Month, 1, #1/31/1995#)

在這個範例中，DateAdd 會傳回 #2/28/1995#，而不是 #2/31/1995#。如果 DateValue 是 #1/31/1996#，它會傳回 #2/29/1996#，因為 1996 年是閏年。

注意事項：
DateAdd 會使用 (System.Globalization 命名空間中) CultureInfo 類別之 CurrentCulture 屬性的目前月曆設定。預設的 CurrentCulture 值將由 [控制台] 設定決定。

因為 DateTime 結構可支援每一個 Date 值，所以它在加入時間間隔時，可為您提供一些額外的選項。例如，您可以將小數的天數 (四捨五入到最接近的毫秒數) 加入 Date 變數，如下所示：

Dim NextTime As Date = Now        ' Current date and time.
NextTime = NextTime.AddDays(3.4)  ' Increment by 3 2/5 days.

範例

這個範例會使用 DateAdd 函式取得日期，並顯示指定月數之後的未來對應日期。

Dim Msg, Number, StartDate As String   'Declare variables.
Dim Months As Double
Dim SecondDate As Date
Dim IntervalType As DateInterval
IntervalType = DateInterval.Month   ' Specifies months as interval.
StartDate = InputBox("Enter a date")
SecondDate = CDate(StartDate)
Number = InputBox("Enter number of months to add")
Months = Val(Number)
Msg = "New date: " & DateAdd(IntervalType, Months, SecondDate)
MsgBox(Msg)