DatePart 函式 (Visual Basic)

發行項
08/21/2008

更新：2007 年 11 月

傳回包含指定 Date 值的特定元件之 Integer 值。

Public Overloads Function DatePart( _
   ByVal Interval As DateInterval, _
   ByVal DateValue As DateTime, _
   Optional ByVal FirstDayOfWeekValue As FirstDayOfWeek = VbSunday, _
   Optional ByVal FirstWeekOfYearValue As FirstWeekOfYear = VbFirstJan1 _
) As Integer
' -or-
Public Overloads Function DatePart( _
    ByVal Interval As String, _
   ByVal DateValue As Object, _
   Optional ByVal DayOfWeek As FirstDayOfWeek = FirstDayOfWeek.Sunday, _
   Optional ByVal WeekOfYear As FirstWeekOfYear = FirstWeekOfYear.Jan1 _
) As Integer

參數

Interval
必要項。代表您想要傳回的日期/時間部分的 DateInterval 列舉值或 String 運算式。
DateValue
必要項。您想要評估的 Date 值。
FirstDayOfWeekValue, DayOfWeek
選擇項。選自 FirstDayOfWeek 列舉型別的值，指定一週的第一天。如果未指定，就使用 FirstDayOfWeek.Sunday。
FirstWeekOfYearValue, WeekOfYear
選擇項。選自 FirstWeekOfYear 列舉型別的值，指定一年的第一週。如果未指定，就使用 FirstWeekOfYear.Jan1。

設定

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

列舉型別值	字串	傳回的日期/時間值部分
DateInterval.Day	d	月中的日 (1 到 31)
DateInterval.DayOfYear	y	年中的日 (1 到 366)
DateInterval.Hour	h	小時
DateInterval.Minute	n	分鐘
DateInterval.Month	m	月
DateInterval.Quarter	q	季
DateInterval.Second	s	秒
DateInterval.Weekday	w	星期資訊 (1 到 7)
DateInterval.WeekOfYear	ww	一年中的週 (1 到 53)
DateInterval.Year	yyyy	年份

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

列舉型別值	值	描述
FirstDayOfWeek.System	0	系統設定中指定的每週第一天
FirstDayOfWeek.Sunday	1	星期日 (預設值)
FirstDayOfWeek.Monday	2	星期一 (符合 ISO 標準 8601 的第 3.17 節)
FirstDayOfWeek.Tuesday	3	星期二
FirstDayOfWeek.Wednesday	4	星期三
FirstDayOfWeek.Thursday	5	星期四
FirstDayOfWeek.Friday	6	星期五
FirstDayOfWeek.Saturday	7	星期六

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

列舉型別值	值	描述
FirstWeekOfYear.System	0	系統設定中指定的每年第一週
FirstWeekOfYear.Jan1	1	一月一日當週 (預設值)
FirstWeekOfYear.FirstFourDays	2	新年度至少有四天在該週 (符合 ISO 8601 標準，第 3.17 節)
FirstWeekOfYear.FirstFullWeek	3	新年度的第一個完整星期

例外狀況

例外狀況類型	錯誤代碼	條件
ArgumentException	5	Interval 無效。
InvalidCastException	13	無法將 DateValue 強制為 Date。

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

備註

您可以使用 DatePart 函式來評估日期/時間值並傳回特定的元件。例如，您可使用 DatePart 來計算星期幾或是目前的小時。

如果選擇 DateInterval.Weekday 做為 Interval 引數，則傳回值會與 FirstDayOfWeek 列舉型別的值一致。如果選擇 DateInterval.WeekOfYear，則 DatePart 會使用 System.Globalization 命名空間的 Calendar 和 CultureInfo 子句來判斷目前設定。

FirstDayOfWeekValue 引數會影響使用 DateInterval.Weekday 和 DateInterval.WeekOfYear Interval 設定所進行的計算。FirstWeekOfYearValue 引數會影響指定 DateInterval.WeekOfYear 做為 Interval 所進行的計算。

因為 DateTime 結構可支援每一個 Date 值所以它在擷取日期/時間部分時，可為您提供一些額外的選項。例如，您可以取得 Date 變數的整個日期值，且其時間值設定為午夜，如下所示：

Dim CurrDatTim As Date = Now   ' Current date and time.
Dim LastMidnight As Date = CurrDatTim.Date   ' At midnight.

範例

這個範例會使用 DatePart 函式取得日期並顯示它是發生在年度的第幾季。

Dim FirstDate, Msg As String   'Declare variables.
Dim SecondDate As Date
FirstDate = InputBox("Enter a date:")
SecondDate = CDate(FirstDate)
Msg = "Quarter: " & DatePart(DateInterval.Quarter, SecondDate)
MsgBox(Msg)