使用行事曆

發行項
03/16/2024

雖然日期和時間值代表一個時間點，但是其字串表示區分文化特性，而且同時取決於用於顯示特定文化特性之日期和時間值的慣例，以及該文化特性所使用的曆法。本主題探索 .NET 中支援的曆法，並討論使用日期值時曆法類別的用法。

.NET 中的曆法

.NET 中的所有曆法都是衍生自 System.Globalization.Calendar 類別，該類別提供基本的曆法實作。其中一個衍生自 Calendar 類別的類別是 EastAsianLunisolarCalendar 類別，其為所有陰陽曆的基底類別。 .NET 包括下列曆法實作：

ChineseLunisolarCalendar，表示中文陰陽曆。
GregorianCalendar，表示西曆。這個曆法會進一步細分成子類型 (例如阿拉伯和中東法文)，這些子類別是由 System.Globalization.GregorianCalendarTypes 列舉類型所定義。 GregorianCalendar.CalendarType 屬性會指定西曆的子類型。
HebrewCalendar，表示希伯來曆法。
HijriCalendar，表示回曆。
JapaneseCalendar，表示日本曆法。
JapaneseLunisolarCalendar，表示日文陰陽曆。
JulianCalendar，表示凱撒曆法。
KoreanCalendar，表示韓國曆法。
KoreanLunisolarCalendar，表示韓文陰陽曆。
PersianCalendar，表示波斯曆。
TaiwanCalendar，表示台灣曆法。
TaiwanLunisolarCalendar，表示台灣使用的陰陽曆。
ThaiBuddhistCalendar，表示泰國佛教曆法。
UmAlQuraCalendar，表示 Um Al Qura 曆法。

曆法的使用方式有兩種：

做為特定文化特性使用的曆法。每個 CultureInfo 物件都有現行的曆法，也就是物件目前使用的曆法。所有日期和時間值的字串表示都會自動反映目前的文化特性及其現行曆法。通常現行曆法是文化特性的預設曆法。 CultureInfo 物件也有選用曆法，包括該文化特性可以使用的額外曆法。
做為與特定文化特性無關的獨立曆法。這種情況下會使用 Calendar 方法以反映曆法的值表達日期。

請注意，這六種曆法類別 ChineseLunisolarCalendar、JapaneseLunisolarCalendar、JulianCalendar、KoreanLunisolarCalendar、PersianCalendar 和 TaiwanLunisolarCalendar 只能做為獨立曆法使用。這些類別不會由任何文化特性做為預設曆法或選擇性曆法使用。

曆法和文化特性

每一種文化特性都有預設曆法，該曆法是由 CultureInfo.Calendar 屬性所定義。 CultureInfo.OptionalCalendars 屬性會傳回 Calendar 物件的陣列，該陣列會指定特定文化特性支援的所有曆法，包括該文化特性的預設曆法。

下列範例說明 CultureInfo.Calendar 和 CultureInfo.OptionalCalendars 屬性。範例中會為泰文 (泰國) 和日文 (日本) 文化特性建立 CultureInfo 物件，並且顯示其預設和選擇性曆法。請注意，在這兩種情況下，文化特性的預設曆法也會包含在 CultureInfo.OptionalCalendars 集合中。

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      // Create a CultureInfo for Thai in Thailand.
      CultureInfo th = CultureInfo.CreateSpecificCulture("th-TH");
      DisplayCalendars(th);

      // Create a CultureInfo for Japanese in Japan.
      CultureInfo ja = CultureInfo.CreateSpecificCulture("ja-JP");
      DisplayCalendars(ja);
   }

   static void DisplayCalendars(CultureInfo ci)
   {
      Console.WriteLine("Calendars for the {0} culture:", ci.Name);

      // Get the culture's default calendar.
      Calendar defaultCalendar = ci.Calendar;
      Console.Write("   Default Calendar: {0}", GetCalendarName(defaultCalendar));

      if (defaultCalendar is GregorianCalendar)
         Console.WriteLine(" ({0})",
                           ((GregorianCalendar) defaultCalendar).CalendarType);
      else
         Console.WriteLine();

      // Get the culture's optional calendars.
      Console.WriteLine("   Optional Calendars:");
      foreach (var optionalCalendar in ci.OptionalCalendars) {
         Console.Write("{0,6}{1}", "", GetCalendarName(optionalCalendar));
         if (optionalCalendar is GregorianCalendar)
            Console.Write(" ({0})",
                          ((GregorianCalendar) optionalCalendar).CalendarType);

         Console.WriteLine();
      }
      Console.WriteLine();
   }

   static string GetCalendarName(Calendar cal)
   {
      return cal.ToString().Replace("System.Globalization.", "");
   }
}
// The example displays the following output:
//       Calendars for the th-TH culture:
//          Default Calendar: ThaiBuddhistCalendar
//          Optional Calendars:
//             ThaiBuddhistCalendar
//             GregorianCalendar (Localized)
//
//       Calendars for the ja-JP culture:
//          Default Calendar: GregorianCalendar (Localized)
//          Optional Calendars:
//             GregorianCalendar (Localized)
//             JapaneseCalendar
//             GregorianCalendar (USEnglish)

Imports System.Globalization

Public Module Example
    Public Sub Main()
        ' Create a CultureInfo for Thai in Thailand.
        Dim th As CultureInfo = CultureInfo.CreateSpecificCulture("th-TH")
        DisplayCalendars(th)

        ' Create a CultureInfo for Japanese in Japan.
        Dim ja As CultureInfo = CultureInfo.CreateSpecificCulture("ja-JP")
        DisplayCalendars(ja)
    End Sub

    Sub DisplayCalendars(ci As CultureInfo)
        Console.WriteLine("Calendars for the {0} culture:", ci.Name)

        ' Get the culture's default calendar.
        Dim defaultCalendar As Calendar = ci.Calendar
        Console.Write("   Default Calendar: {0}", GetCalendarName(defaultCalendar))

        If TypeOf defaultCalendar Is GregorianCalendar Then
            Console.WriteLine(" ({0})",
                              CType(defaultCalendar, GregorianCalendar).CalendarType)
        Else
            Console.WriteLine()
        End If

        ' Get the culture's optional calendars.
        Console.WriteLine("   Optional Calendars:")
        For Each optionalCalendar In ci.OptionalCalendars
            Console.Write("{0,6}{1}", "", GetCalendarName(optionalCalendar))
            If TypeOf optionalCalendar Is GregorianCalendar Then
                Console.Write(" ({0})",
                              CType(optionalCalendar, GregorianCalendar).CalendarType)
            End If
            Console.WriteLine()
        Next
        Console.WriteLine()
    End Sub

    Function GetCalendarName(cal As Calendar) As String
        Return cal.ToString().Replace("System.Globalization.", "")
    End Function
End Module
' The example displays the following output:
'       Calendars for the th-TH culture:
'          Default Calendar: ThaiBuddhistCalendar
'          Optional Calendars:
'             ThaiBuddhistCalendar
'             GregorianCalendar (Localized)
'       
'       Calendars for the ja-JP culture:
'          Default Calendar: GregorianCalendar (Localized)
'          Optional Calendars:
'             GregorianCalendar (Localized)
'             JapaneseCalendar
'             GregorianCalendar (USEnglish)

特定 CultureInfo 物件目前使用的曆法是由文化特性的 DateTimeFormatInfo.Calendar 屬性定義。文化特性的 DateTimeFormatInfo 物件是由 CultureInfo.DateTimeFormat 屬性所傳回。建立文化特性時，其預設值與 CultureInfo.Calendar 屬性的值相同。不過，您可以將文化特性的現行曆法變更為 CultureInfo.OptionalCalendars 屬性所傳回陣列中包含的任何曆法。如果您嘗試將現行曆法設定為不包括在 CultureInfo.OptionalCalendars 屬性值中的曆法，則會顯示 ArgumentException。

下列範例會變更阿拉伯文 (沙烏地阿拉伯) 文化特性使用的曆法。首先會具現化 DateTime 值，並且使用現行文化特性 (此案例中是英文 (美國)) 和目前文化特性的曆法 (此案例中是西曆) 顯示該值。接著會將目前的文化特性變更為阿拉伯文 (沙烏地阿拉伯)，並且使用其預設的 Um Al-Qura 曆法顯示日期。最後呼叫 CalendarExists 方法，判斷阿拉伯文 (沙烏地阿拉伯) 文化特性是否支援回曆。由於支援此曆法，因此會將現行曆法變更為回曆，並且再次顯示日期。請注意，在各案例中，日期會使用目前文化特性的現行曆法顯示。

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      DateTime date1 = new DateTime(2011, 6, 20);

      DisplayCurrentInfo();
      // Display the date using the current culture and calendar.
      Console.WriteLine(date1.ToString("d"));
      Console.WriteLine();

      CultureInfo arSA = CultureInfo.CreateSpecificCulture("ar-SA");

      // Change the current culture to Arabic (Saudi Arabia).
      Thread.CurrentThread.CurrentCulture = arSA;
      // Display date and information about the current culture.
      DisplayCurrentInfo();
      Console.WriteLine(date1.ToString("d"));
      Console.WriteLine();

      // Change the calendar to Hijri.
      Calendar hijri = new HijriCalendar();
      if (CalendarExists(arSA, hijri)) {
         arSA.DateTimeFormat.Calendar = hijri;
         // Display date and information about the current culture.
         DisplayCurrentInfo();
         Console.WriteLine(date1.ToString("d"));
      }
   }

   private static void DisplayCurrentInfo()
   {
      Console.WriteLine("Current Culture: {0}",
                        CultureInfo.CurrentCulture.Name);
      Console.WriteLine("Current Calendar: {0}",
                        DateTimeFormatInfo.CurrentInfo.Calendar);
   }

   private static bool CalendarExists(CultureInfo culture, Calendar cal)
   {
      foreach (Calendar optionalCalendar in culture.OptionalCalendars)
         if (cal.ToString().Equals(optionalCalendar.ToString()))
            return true;

      return false;
   }
}
// The example displays the following output:
//    Current Culture: en-US
//    Current Calendar: System.Globalization.GregorianCalendar
//    6/20/2011
//
//    Current Culture: ar-SA
//    Current Calendar: System.Globalization.UmAlQuraCalendar
//    18/07/32
//
//    Current Culture: ar-SA
//    Current Calendar: System.Globalization.HijriCalendar
//    19/07/32

Imports System.Globalization
Imports System.Threading

Module Example
    Public Sub Main()
        Dim date1 As Date = #6/20/2011#

        DisplayCurrentInfo()
        ' Display the date using the current culture and calendar.
        Console.WriteLine(date1.ToString("d"))
        Console.WriteLine()

        Dim arSA As CultureInfo = CultureInfo.CreateSpecificCulture("ar-SA")

        ' Change the current culture to Arabic (Saudi Arabia).
        Thread.CurrentThread.CurrentCulture = arSA
        ' Display date and information about the current culture.
        DisplayCurrentInfo()
        Console.WriteLine(date1.ToString("d"))
        Console.WriteLine()

        ' Change the calendar to Hijri.
        Dim hijri As Calendar = New HijriCalendar()
        If CalendarExists(arSA, hijri) Then
            arSA.DateTimeFormat.Calendar = hijri
            ' Display date and information about the current culture.
            DisplayCurrentInfo()
            Console.WriteLine(date1.ToString("d"))
        End If
    End Sub

    Private Sub DisplayCurrentInfo()
        Console.WriteLine("Current Culture: {0}",
                          CultureInfo.CurrentCulture.Name)
        Console.WriteLine("Current Calendar: {0}",
                          DateTimeFormatInfo.CurrentInfo.Calendar)
    End Sub

    Private Function CalendarExists(ByVal culture As CultureInfo,
                                    cal As Calendar) As Boolean
        For Each optionalCalendar As Calendar In culture.OptionalCalendars
            If cal.ToString().Equals(optionalCalendar.ToString()) Then Return True
        Next
        Return False
    End Function
End Module
' The example displays the following output:
'    Current Culture: en-US
'    Current Calendar: System.Globalization.GregorianCalendar
'    6/20/2011
'    
'    Current Culture: ar-SA
'    Current Calendar: System.Globalization.UmAlQuraCalendar
'    18/07/32
'    
'    Current Culture: ar-SA
'    Current Calendar: System.Globalization.HijriCalendar
'    19/07/32

日期和曆法

除了包括 Calendar 類型的參數且允許日期的項目 (也就是月、日和年) 以指定的曆法反映值的建構函式之外，DateTime 和 DateTimeOffset 這兩個值永遠以西曆為主。例如，這表示 DateTime.Year 屬性會傳回西曆的年，而 DateTime.Day 屬性會傳回西曆的月份日期。

重要

務必記得，日期值及其字串表示之間有一項差異。前者是以西曆為主，後者是以特定文化特性的現行曆法為主。

下列範例會說明 DateTime 屬性及其對應的 Calendar 方法之間的這項差異。在此範例中，目前文化特性為阿拉伯文 (埃及)，而現行曆法為 Um Al Qura。 DateTime 值會設定為 2011 年第七個月的第 15 天。很清楚這個日期是解譯為西曆日期，因為這些相同值是 DateTime.ToString(String, IFormatProvider) 方法在使用不因文化特性而異的慣例時所傳回。使用目前文化特性格式化之日期的字串表示為 14/08/32，其為 Um Al Qura 曆法的同等日期。其次，DateTime 和 Calendar 的成員會用來傳回 DateTime 值的日、月和年。在各案例中，DateTime 成員傳回的值會反映西曆的值，而 UmAlQuraCalendar 成員傳回的值則會反映 Uum al-Qura 曆法的值。

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      // Make Arabic (Egypt) the current culture
      // and Umm al-Qura calendar the current calendar.
      CultureInfo arEG = CultureInfo.CreateSpecificCulture("ar-EG");
      Calendar cal = new UmAlQuraCalendar();
      arEG.DateTimeFormat.Calendar = cal;
      Thread.CurrentThread.CurrentCulture = arEG;

      // Display information on current culture and calendar.
      DisplayCurrentInfo();

      // Instantiate a date object.
      DateTime date1 = new DateTime(2011, 7, 15);

      // Display the string representation of the date.
      Console.WriteLine("Date: {0:d}", date1);
      Console.WriteLine("Date in the Invariant Culture: {0}",
                        date1.ToString("d", CultureInfo.InvariantCulture));
      Console.WriteLine();

      // Compare DateTime properties and Calendar methods.
      Console.WriteLine("DateTime.Month property: {0}", date1.Month);
      Console.WriteLine("UmAlQura.GetMonth: {0}",
                        cal.GetMonth(date1));
      Console.WriteLine();

      Console.WriteLine("DateTime.Day property: {0}", date1.Day);
      Console.WriteLine("UmAlQura.GetDayOfMonth: {0}",
                        cal.GetDayOfMonth(date1));
      Console.WriteLine();

      Console.WriteLine("DateTime.Year property: {0:D4}", date1.Year);
      Console.WriteLine("UmAlQura.GetYear: {0}",
                        cal.GetYear(date1));
      Console.WriteLine();
   }

   private static void DisplayCurrentInfo()
   {
      Console.WriteLine("Current Culture: {0}",
                        CultureInfo.CurrentCulture.Name);
      Console.WriteLine("Current Calendar: {0}",
                        DateTimeFormatInfo.CurrentInfo.Calendar);
   }
}
// The example displays the following output:
//    Current Culture: ar-EG
//    Current Calendar: System.Globalization.UmAlQuraCalendar
//    Date: 14/08/32
//    Date in the Invariant Culture: 07/15/2011
//
//    DateTime.Month property: 7
//    UmAlQura.GetMonth: 8
//
//    DateTime.Day property: 15
//    UmAlQura.GetDayOfMonth: 14
//
//    DateTime.Year property: 2011
//    UmAlQura.GetYear: 1432

Imports System.Globalization
Imports System.Threading

Module Example
    Public Sub Main()
        ' Make Arabic (Egypt) the current culture 
        ' and Umm al-Qura calendar the current calendar. 
        Dim arEG As CultureInfo = CultureInfo.CreateSpecificCulture("ar-EG")
        Dim cal As Calendar = New UmAlQuraCalendar()
        arEG.DateTimeFormat.Calendar = cal
        Thread.CurrentThread.CurrentCulture = arEG

        ' Display information on current culture and calendar.
        DisplayCurrentInfo()

        ' Instantiate a date object.
        Dim date1 As Date = #07/15/2011#

        ' Display the string representation of the date.
        Console.WriteLine("Date: {0:d}", date1)
        Console.WriteLine("Date in the Invariant Culture: {0}",
                          date1.ToString("d", CultureInfo.InvariantCulture))
        Console.WriteLine()

        ' Compare DateTime properties and Calendar methods.
        Console.WriteLine("DateTime.Month property: {0}", date1.Month)
        Console.WriteLine("UmAlQura.GetMonth: {0}",
                          cal.GetMonth(date1))
        Console.WriteLine()

        Console.WriteLine("DateTime.Day property: {0}", date1.Day)
        Console.WriteLine("UmAlQura.GetDayOfMonth: {0}",
                          cal.GetDayOfMonth(date1))
        Console.WriteLine()

        Console.WriteLine("DateTime.Year property: {0:D4}", date1.Year)
        Console.WriteLine("UmAlQura.GetYear: {0}",
                          cal.GetYear(date1))
        Console.WriteLine()
    End Sub

    Private Sub DisplayCurrentInfo()
        Console.WriteLine("Current Culture: {0}",
                          CultureInfo.CurrentCulture.Name)
        Console.WriteLine("Current Calendar: {0}",
                          DateTimeFormatInfo.CurrentInfo.Calendar)
    End Sub
End Module
' The example displays the following output:
'    Current Culture: ar-EG
'    Current Calendar: System.Globalization.UmAlQuraCalendar
'    Date: 14/08/32
'    Date in the Invariant Culture: 07/15/2011
'    
'    DateTime.Month property: 7
'    UmAlQura.GetMonth: 8
'    
'    DateTime.Day property: 15
'    UmAlQura.GetDayOfMonth: 14
'    
'    DateTime.Year property: 2011
'    UmAlQura.GetYear: 1432

根據曆法具現化日期

由於 DateTime 和 DateTimeOffset 值是以西曆為主，因此，如果您想要使用不同曆法的日、月或年值，則必須呼叫包含 Calendar 類型之參數的多載建構函式來具現化日期值。您也可以呼叫特定曆法之 Calendar.ToDateTime 方法的其中一個多載，依據特殊曆法的值具現化 DateTime 物件。

下列範例會藉由將 DateTime 物件傳遞至 HebrewCalendar 建構函式具現化一個 DateTime 值，並且藉由呼叫 DateTime 方法具現化另一個 HebrewCalendar.ToDateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32) 值。由於這兩個值是使用希伯來曆法的相同值所建立，因此呼叫 DateTime.Equals 方法會顯示這兩個 DateTime 值相等。

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      HebrewCalendar hc = new HebrewCalendar();

      DateTime date1 = new DateTime(5771, 6, 1, hc);
      DateTime date2 = hc.ToDateTime(5771, 6, 1, 0, 0, 0, 0);

      Console.WriteLine("{0:d} (Gregorian) = {1:d2}/{2:d2}/{3:d4} ({4}): {5}",
                        date1,
                        hc.GetMonth(date2),
                        hc.GetDayOfMonth(date2),
                        hc.GetYear(date2),
                        GetCalendarName(hc),
                        date1.Equals(date2));
   }

   private static string GetCalendarName(Calendar cal)
   {
      return cal.ToString().Replace("System.Globalization.", "").
                            Replace("Calendar", "");
   }
}
// The example displays the following output:
//    2/5/2011 (Gregorian) = 06/01/5771 (Hebrew): True

Imports System.Globalization

Module Example
    Public Sub Main()
        Dim hc As New HebrewCalendar()

        Dim date1 As New Date(5771, 6, 1, hc)
        Dim date2 As Date = hc.ToDateTime(5771, 6, 1, 0, 0, 0, 0)

        Console.WriteLine("{0:d} (Gregorian) = {1:d2}/{2:d2}/{3:d4} ({4}): {5}",
                          date1,
                          hc.GetMonth(date2),
                          hc.GetDayOfMonth(date2),
                          hc.GetYear(date2),
                          GetCalendarName(hc),
                          date1.Equals(date2))
    End Sub

    Private Function GetCalendarName(cal As Calendar) As String
        Return cal.ToString().Replace("System.Globalization.", "").
                              Replace("Calendar", "")
    End Function
End Module
' The example displays the following output:
'   2/5/2011 (Gregorian) = 06/01/5771 (Hebrew): True

以目前曆法表示日期

日期和時間格式化方法會固定使用現行曆法將日期轉換為字串。這表示年、月和月份日期的字串表示會反映現行曆法，而且不一定會反映西曆。

下列範例顯示現行曆法如何影響日期的字串表示。它會將目前文化特性變更為中文 (繁體，台灣)，並且具現化日期值。接著會顯示現行曆法和日期，將現行曆法變更為 TaiwanCalendar，然後再次顯示現行曆法和日期。第一次顯示日期時，該日期會以西曆日期表示。第二次顯示日期時，該日期會以台灣曆法的日期表示。

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      // Change the current culture to zh-TW.
      CultureInfo zhTW = CultureInfo.CreateSpecificCulture("zh-TW");
      Thread.CurrentThread.CurrentCulture = zhTW;
      // Define a date.
      DateTime date1 = new DateTime(2011, 1, 16);

      // Display the date using the default (Gregorian) calendar.
      Console.WriteLine("Current calendar: {0}",
                        zhTW.DateTimeFormat.Calendar);
      Console.WriteLine(date1.ToString("d"));

      // Change the current calendar and display the date.
      zhTW.DateTimeFormat.Calendar = new TaiwanCalendar();
      Console.WriteLine("Current calendar: {0}",
                        zhTW.DateTimeFormat.Calendar);
      Console.WriteLine(date1.ToString("d"));
   }
}
// The example displays the following output:
//    Current calendar: System.Globalization.GregorianCalendar
//    2011/1/16
//    Current calendar: System.Globalization.TaiwanCalendar
//    100/1/16

Imports System.Globalization
Imports System.Threading

Module Example
    Public Sub Main()
        ' Change the current culture to zh-TW.
        Dim zhTW As CultureInfo = CultureInfo.CreateSpecificCulture("zh-TW")
        Thread.CurrentThread.CurrentCulture = zhTW
        ' Define a date.
        Dim date1 As Date = #1/16/2011#

        ' Display the date using the default (Gregorian) calendar.
        Console.WriteLine("Current calendar: {0}",
                          zhTW.DateTimeFormat.Calendar)
        Console.WriteLine(date1.ToString("d"))

        ' Change the current calendar and display the date.
        zhTW.DateTimeFormat.Calendar = New TaiwanCalendar()
        Console.WriteLine("Current calendar: {0}",
                          zhTW.DateTimeFormat.Calendar)
        Console.WriteLine(date1.ToString("d"))
    End Sub
End Module
' The example displays the following output:
'    Current calendar: System.Globalization.GregorianCalendar
'    2011/1/16
'    Current calendar: System.Globalization.TaiwanCalendar
'    100/1/16

以非目前曆法表示日期

若要使用不是特定文化特性的現行曆法來表示日期，您必須呼叫該 Calendar 物件的方法。例如，Calendar.GetYear、Calendar.GetMonth 和 Calendar.GetDayOfMonth 方法會將年、月和日轉換成反映特定曆法的值。

警告

由於某些曆法並非任何文化特性的選擇性曆法，因此使用這些曆法表示日期一定要呼叫曆法方法。所有衍生自 EastAsianLunisolarCalendar、JulianCalendar 和 PersianCalendar 類別的曆法都要這樣做。

下列範例使用 JulianCalendar 物件具現化凱撒曆法的日期 1905 年 1 月 9 日。使用預設曆法 (西曆) 顯示這個日期時，該日期會表示為 1905 年 1 月 22 日。呼叫個別 JulianCalendar 方法即可使用凱撒曆法表示日期。

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      JulianCalendar julian = new JulianCalendar();
      DateTime date1 = new DateTime(1905, 1, 9, julian);

      Console.WriteLine("Date ({0}): {1:d}",
                        CultureInfo.CurrentCulture.Calendar,
                        date1);
      Console.WriteLine("Date in Julian calendar: {0:d2}/{1:d2}/{2:d4}",
                        julian.GetMonth(date1),
                        julian.GetDayOfMonth(date1),
                        julian.GetYear(date1));
   }
}
// The example displays the following output:
//    Date (System.Globalization.GregorianCalendar): 1/22/1905
//    Date in Julian calendar: 01/09/1905

Imports System.Globalization

Module Example
    Public Sub Main()
        Dim julian As New JulianCalendar()
        Dim date1 As New Date(1905, 1, 9, julian)

        Console.WriteLine("Date ({0}): {1:d}",
                          CultureInfo.CurrentCulture.Calendar,
                          date1)
        Console.WriteLine("Date in Julian calendar: {0:d2}/{1:d2}/{2:d4}",
                          julian.GetMonth(date1),
                          julian.GetDayOfMonth(date1),
                          julian.GetYear(date1))
    End Sub
End Module
' The example displays the following output:
'    Date (System.Globalization.GregorianCalendar): 1/22/1905
'    Date in Julian calendar: 01/09/1905

曆法和日期範圍

曆法所支援的最早日期是由該曆法的 Calendar.MinSupportedDateTime 屬性所表示。如果是 GregorianCalendar 類別，該日期是公元 0001 年 1 月 1 日。.NET 中大部分其他曆法都支援較晚的日期。嘗試處理早於曆法所支援最早日期的日期和時間值，會擲回 ArgumentOutOfRangeException 例外狀況。

不過，有一個重要的例外狀況。 DateTime 物件和 DateTimeOffset 物件的預設值 (未初始化的值) 相當於 GregorianCalendar.MinSupportedDateTime 值。如果您嘗試在不支援公元 0001 年 1 月 1 日的曆法中格式化這個日期，且未提供格式規範，則格式化方法會使用 "s" (可排序日期/時間模式) 格式規範，而不是 "G" (一般日期/時間模式) 格式規範。結果，格式化作業並不會擲回 ArgumentOutOfRangeException 例外狀況，而是傳回不支援的日期。下列範例將說明這種情況，當目前文化特性設為日文 (日本) 並採用日本曆法，以及設為阿拉伯文 (埃及) 並採用 Um Al Qura 曆法時，會顯示 DateTime.MinValue 值。另外也會將目前文化特性設為英文 (美國)，並且對每一個 DateTime.ToString(IFormatProvider) 物件呼叫 CultureInfo 方法。在每個案例中，日期是使用可排序日期/時間模式顯示。

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      DateTime dat = DateTime.MinValue;

      // Change the current culture to ja-JP with the Japanese Calendar.
      CultureInfo jaJP = CultureInfo.CreateSpecificCulture("ja-JP");
      jaJP.DateTimeFormat.Calendar = new JapaneseCalendar();
      Thread.CurrentThread.CurrentCulture = jaJP;
      Console.WriteLine("Earliest supported date by {1} calendar: {0:d}",
                        jaJP.DateTimeFormat.Calendar.MinSupportedDateTime,
                        GetCalendarName(jaJP));
      // Attempt to display the date.
      Console.WriteLine(dat.ToString());
      Console.WriteLine();

      // Change the current culture to ar-EG with the Um Al Qura calendar.
      CultureInfo arEG = CultureInfo.CreateSpecificCulture("ar-EG");
      arEG.DateTimeFormat.Calendar = new UmAlQuraCalendar();
      Thread.CurrentThread.CurrentCulture = arEG;
      Console.WriteLine("Earliest supported date by {1} calendar: {0:d}",
                        arEG.DateTimeFormat.Calendar.MinSupportedDateTime,
                        GetCalendarName(arEG));
      // Attempt to display the date.
      Console.WriteLine(dat.ToString());
      Console.WriteLine();

      // Change the current culture to en-US.
      Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture("en-US");
      Console.WriteLine(dat.ToString(jaJP));
      Console.WriteLine(dat.ToString(arEG));
      Console.WriteLine(dat.ToString("d"));
   }

   private static string GetCalendarName(CultureInfo culture)
   {
      Calendar cal = culture.DateTimeFormat.Calendar;
      return cal.GetType().Name.Replace("System.Globalization.", "").Replace("Calendar", "");
   }
}
// The example displays the following output:
//       Earliest supported date by Japanese calendar: 明治 1/9/8
//       0001-01-01T00:00:00
//
//       Earliest supported date by UmAlQura calendar: 01/01/18
//       0001-01-01T00:00:00
//
//       0001-01-01T00:00:00
//       0001-01-01T00:00:00
//       1/1/0001

Imports System.Globalization
Imports System.Threading

Module Example
    Public Sub Main()
        Dim dat As Date = DateTime.MinValue

        ' Change the current culture to ja-JP with the Japanese Calendar.
        Dim jaJP As CultureInfo = CultureInfo.CreateSpecificCulture("ja-JP")
        jaJP.DateTimeFormat.Calendar = New JapaneseCalendar()
        Thread.CurrentThread.CurrentCulture = jaJP
        Console.WriteLine("Earliest supported date by {1} calendar: {0:d}",
                          jaJP.DateTimeFormat.Calendar.MinSupportedDateTime,
                          GetCalendarName(jaJP))
        ' Attempt to display the date.
        Console.WriteLine(dat.ToString())
        Console.WriteLine()

        ' Change the current culture to ar-EG with the Um Al Qura calendar.
        Dim arEG As CultureInfo = CultureInfo.CreateSpecificCulture("ar-EG")
        arEG.DateTimeFormat.Calendar = New UmAlQuraCalendar()
        Thread.CurrentThread.CurrentCulture = arEG
        Console.WriteLine("Earliest supported date by {1} calendar: {0:d}",
                          arEG.DateTimeFormat.Calendar.MinSupportedDateTime,
                          GetCalendarName(arEG))
        ' Attempt to display the date.
        Console.WRiteLine(dat.ToString())
        Console.WRiteLine()

        ' Change the current culture to en-US.
        Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture("en-US")
        Console.WriteLine(dat.ToString(jaJP))
        Console.WriteLine(dat.ToString(arEG))
        Console.WriteLine(dat.ToString("d"))
    End Sub

    Private Function GetCalendarName(culture As CultureInfo) As String
        Dim cal As Calendar = culture.DateTimeFormat.Calendar
        Return cal.GetType().Name.Replace("System.Globalization.", "").Replace("Calendar", "")
    End Function
End Module
' The example displays the following output:
'       Earliest supported date by Japanese calendar: 明治 1/9/8
'       0001-01-01T00:00:00
'       
'       Earliest supported date by UmAlQura calendar: 01/01/18
'       0001-01-01T00:00:00
'       
'       0001-01-01T00:00:00
'       0001-01-01T00:00:00
'       1/1/0001

使用紀元

曆法通常會將日期細分成紀元。不過，.NET 中的 Calendar 類別不支援曆法所定義的每一個紀元，且大部分的 Calendar 類別僅支援單一紀元。只有 JapaneseCalendar 和 JapaneseLunisolarCalendar 類別支援多個紀元。

重要

令和紀元為 JapaneseCalendar 和 JapaneseLunisolarCalendar 中的新紀元，始於 2019 年 5 月 1 日。這項改變對所有使用這些日曆的應用程式都有影響。如需詳細資訊，請參閱下列文章：

在 .NET 中處理日本曆法中的新紀元，此文記載的 .NET 新增功能可以支援多紀元曆法，並且討論處理多紀元曆法時可使用的最佳做法。
Prepare your application for the Japanese era change (讓應用程式準備好因應日本紀元的變更)，本文提供有關在 Windows 系統上測試您的應用程式以確保其已準備好面對紀元變更的資訊。
適用於 .NET Framework 的日本新紀元更新摘要，本文列出與日本新曆法紀元相關、適用於個別 Windows 版本的 .NET Framework 更新，提及支援多紀元的 .NET Framework 新功能，以及包含測試應用程式時要尋找的內容。

大部分曆法中的紀元代表一段相當長的時期。例如，在西曆中，目前紀元跨越超過兩千年。若是 JapaneseCalendar 和 JapaneseLunisolarCalendar，這兩個曆法支援多紀元，則不是這種情況。一個紀元對應至一位天皇的在位時期。支援多紀元會帶來特殊的挑戰，特別是當目前紀元的上限未知時。

紀元和紀元名稱

在 .NET 中，整數代表特定曆法實作支援的紀元，會以反向順序儲存在 Calendar.Eras 陣列中。目前紀元 (即最新時間範圍的紀元) 位於索引零，若是支援多紀元的 Calendar 類別，每個後續索引都會反映前一個紀元。靜態 Calendar.CurrentEra 屬性會定義 Calendar.Eras 陣列中目前紀元的索引，它是一個常數，且其值永遠為零。個別 Calendar 類別也會包含傳回目前紀元值的靜態欄位。下表中列出這些欄位。

曆法類別	目前紀元欄位
ChineseLunisolarCalendar	ChineseEra
GregorianCalendar	ADEra
HebrewCalendar	HebrewEra
HijriCalendar	HijriEra
JapaneseLunisolarCalendar	JapaneseEra
JulianCalendar	JulianEra
KoreanCalendar	KoreanEra
KoreanLunisolarCalendar	GregorianEra
PersianCalendar	PersianEra
ThaiBuddhistCalendar	ThaiBuddhistEra
UmAlQuraCalendar	UmAlQuraEra

對應特定紀元數的名稱可藉由將紀元數傳遞至 DateTimeFormatInfo.GetEraName 或 DateTimeFormatInfo.GetAbbreviatedEraName 方法的方式擷取。下列範例會呼叫這些方法來擷取 GregorianCalendar 類別中紀元支援的相關資訊。此範例會顯示對應至目前紀元第二年 1 月 1 日的西曆日期，以及對應至每個支援日本曆法紀元第二年 1 月 1 日的西曆日期。

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      int year = 2;
      int month = 1;
      int day = 1;
      Calendar cal = new JapaneseCalendar();

      Console.WriteLine("\nDate instantiated without an era:");
      DateTime date1 = new DateTime(year, month, day, 0, 0, 0, 0, cal);
      Console.WriteLine("{0}/{1}/{2} in Japanese Calendar -> {3:d} in Gregorian",
                        cal.GetMonth(date1), cal.GetDayOfMonth(date1),
                        cal.GetYear(date1), date1);

      Console.WriteLine("\nDates instantiated with eras:");
      foreach (int era in cal.Eras) {
         DateTime date2 = cal.ToDateTime(year, month, day, 0, 0, 0, 0, era);
         Console.WriteLine("{0}/{1}/{2} era {3} in Japanese Calendar -> {4:d} in Gregorian",
                           cal.GetMonth(date2), cal.GetDayOfMonth(date2),
                           cal.GetYear(date2), cal.GetEra(date2), date2);
      }
   }
}

Imports System.Globalization

Module Example
    Public Sub Main()
        Dim year As Integer = 2
        Dim month As Integer = 1
        Dim day As Integer = 1
        Dim cal As New JapaneseCalendar()

        Console.WriteLine("Date instantiated without an era:")
        Dim date1 As New Date(year, month, day, 0, 0, 0, 0, cal)
        Console.WriteLine("{0}/{1}/{2} in Japanese Calendar -> {3:d} in Gregorian",
                          cal.GetMonth(date1), cal.GetDayOfMonth(date1),
                          cal.GetYear(date1), date1)
        Console.WriteLine()

        Console.WriteLine("Dates instantiated with eras:")
        For Each era As Integer In cal.Eras
            Dim date2 As Date = cal.ToDateTime(year, month, day, 0, 0, 0, 0, era)
            Console.WriteLine("{0}/{1}/{2} era {3} in Japanese Calendar -> {4:d} in Gregorian",
                              cal.GetMonth(date2), cal.GetDayOfMonth(date2),
                              cal.GetYear(date2), cal.GetEra(date2), date2)
        Next
    End Sub
End Module

此外，"g" 自訂日期和時間格式字串包括曆法的紀元名稱，該名稱為日期和時間的字串表示。如需詳細資訊，請參閱自訂日期和時間格式字串。

使用紀元具現化日期

若是支援多紀元的兩個 Calendar 類別，由特定年、月和月份日期值組成的日期可能會模稜兩可。例如 JapaneseCalendar 支援的所有紀元都有編號 1 的年份。一般而言，如果未指定紀元，日期和時間及曆法方法都會假設這些值屬於目前紀元。 DateTime 和 DateTimeOffset 建構函式確實包含有型別 Calendar 的參數，以及 JapaneseCalendar.ToDateTime 和 JapaneseLunisolarCalendar.ToDateTime 方法。下列範例會具現化一個日期，代表未指定紀元第二年 1 月 1 日。令和紀元為目前紀元時，如果您執行範例，系統會將日期解譯為令和紀元第二年。在 DateTime.ToString(String, IFormatProvider) 方法傳回的字串中，紀元「令和」位於年份之前，並對應至西曆 2020 年 1 月 1 日。 (令和紀元始於西曆 2019 年)。

using System;
using System.Globalization;

public class Example
{
    public static void Main()
    {
        var japaneseCal = new JapaneseCalendar();
        var jaJp = new CultureInfo("ja-JP");
        jaJp.DateTimeFormat.Calendar = japaneseCal;

        var date = new DateTime(2, 1, 1, japaneseCal);
        Console.WriteLine($"Gregorian calendar date: {date:d}");
        Console.WriteLine($"Japanese calendar date: {date.ToString("d", jaJp)}");
    }
}

Imports System.Globalization

Public Module Example
    Public Sub Main()
        Dim japaneseCal = New JapaneseCalendar()
        Dim jaJp = New CultureInfo("ja-JP")
        jaJp.DateTimeFormat.Calendar = japaneseCal

        Dim dat = New DateTime(2, 1, 1, japaneseCal)
        Console.WriteLine($"Gregorian calendar dat: {dat:d}")
        Console.WriteLine($"Japanese calendar dat: {dat.ToString("d", jaJp)}")
    End Sub
End Module

不過，如果變更紀元，此程式碼的意圖就會變得模稜兩可。該日期意圖代表目前紀元第二年，還是意圖代表平成紀元第二年？有兩種方式可以避免這種模稜兩可的情況：

使用預設 GregorianCalendar 類別具現化日期和時間值。然後將日本曆法或日本陰陽曆用於表示日期的字串，如下列範例所示。

using System;
using System.Globalization;

public class Example
{
    public static void Main()
    {
        var japaneseCal = new JapaneseCalendar();
        var jaJp = new CultureInfo("ja-JP");
        jaJp.DateTimeFormat.Calendar = japaneseCal;

        var date = new DateTime(1905, 2, 12);
        Console.WriteLine($"Gregorian calendar date: {date:d}");

        // Call the ToString(IFormatProvider) method.
        Console.WriteLine($"Japanese calendar date: {date.ToString("d", jaJp)}");

        // Use a FormattableString object.
        FormattableString fmt = $"{date:d}";
        Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)}");

        // Use the JapaneseCalendar object.
        Console.WriteLine($"Japanese calendar date: {jaJp.DateTimeFormat.GetEraName(japaneseCal.GetEra(date))}" +
                          $"{japaneseCal.GetYear(date)}/{japaneseCal.GetMonth(date)}/{japaneseCal.GetDayOfMonth(date)}");

        // Use the current culture.
        CultureInfo.CurrentCulture = jaJp;
        Console.WriteLine($"Japanese calendar date: {date:d}");
    }
}
// The example displays the following output:
//   Gregorian calendar date: 2/12/1905
//   Japanese calendar date: 明治38/2/12
//   Japanese calendar date: 明治38/2/12
//   Japanese calendar date: 明治38/2/12
//   Japanese calendar date: 明治38/2/12

Imports System.Globalization

Public Module Example
    Public Sub Main()
        Dim japaneseCal = New JapaneseCalendar()
        Dim jaJp = New CultureInfo("ja-JP")
        jaJp.DateTimeFormat.Calendar = japaneseCal

        Dim dat = New DateTime(1905, 2, 12)
        Console.WriteLine($"Gregorian calendar date: {dat:d}")

        ' Call the ToString(IFormatProvider) method.
        Console.WriteLine($"Japanese calendar date: {dat.ToString("d", jaJp)}")

        ' Use a FormattableString object.
        Dim fmt As FormattableString = $"{dat:d}"
        Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)}")

        ' Use the JapaneseCalendar object.
        Console.WriteLine($"Japanese calendar date: {jaJp.DateTimeFormat.GetEraName(japaneseCal.GetEra(dat))}" +
                          $"{japaneseCal.GetYear(dat)}/{japaneseCal.GetMonth(dat)}/{japaneseCal.GetDayOfMonth(dat)}")

        ' Use the current culture.
        CultureInfo.CurrentCulture = jaJp
        Console.WriteLine($"Japanese calendar date: {dat:d}")
    End Sub
End Module
' The example displays the following output:
'   Gregorian calendar date: 2/12/1905
'   Japanese calendar date: 明治38/2/12
'   Japanese calendar date: 明治38/2/12
'   Japanese calendar date: 明治38/2/12
'   Japanese calendar date: 明治38/2/12

呼叫明確指定紀元的日期和時間方法。這包含下列方法：

JapaneseCalendar 或 JapaneseLunisolarCalendar 類別的 ToDateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32) 方法。
DateTime 或 DateTimeOffset 剖析方法，例如 Parse、TryParse、ParseExact 或 TryParseExact，其中包含要剖析的字串，以及若目前的文化特性是「日文-日本」 ("ja-JP") 且該文化特性的曆法是 JapaneseCalendar 的話，您可選用的 DateTimeStyles 引數。要剖析的字串必須包含紀元。
DateTime 或 DateTimeOffset 剖析方法，其中包含型別 IFormatProvider 的 provider 參數。 provider 必須是代表日文-日本 ("ja-JP") 文化特性且目前曆法為 JapaneseCalendar 的 CultureInfo 物件，或其 Calendar 屬性為 JapaneseCalendar 的 DateTimeFormatInfo 物件。要剖析的字串必須包含紀元。

下列範例使用下列其中三種方法，具現化明治紀元期間的日期和時間，明治紀元始於 1868 年 9 月 8 日，結束於 1912 年 7 月 29 日。

using System;
using System.Globalization;

public class Example
{
    public static void Main()
    {
        var japaneseCal = new JapaneseCalendar();
        var jaJp = new CultureInfo("ja-JP");
        jaJp.DateTimeFormat.Calendar = japaneseCal;

        // We can get the era index by calling DateTimeFormatInfo.GetEraName.
        int eraIndex = 0;

        for (int ctr = 0; ctr < jaJp.DateTimeFormat.Calendar.Eras.Length; ctr++)
           if (jaJp.DateTimeFormat.GetEraName(ctr) == "明治")
              eraIndex = ctr;
        var date1 = japaneseCal.ToDateTime(23, 9, 8, 0, 0, 0, 0, eraIndex);
        Console.WriteLine($"{date1.ToString("d", jaJp)} (Gregorian {date1:d})");

        try {
            var date2 = DateTime.Parse("明治23/9/8", jaJp);
            Console.WriteLine($"{date2.ToString("d", jaJp)} (Gregorian {date2:d})");
        }
        catch (FormatException)
        {
            Console.WriteLine("The parsing operation failed.");
        }

        try {
            var date3 = DateTime.ParseExact("明治23/9/8", "gyy/M/d", jaJp);
            Console.WriteLine($"{date3.ToString("d", jaJp)} (Gregorian {date3:d})");
        }
        catch (FormatException)
        {
            Console.WriteLine("The parsing operation failed.");
        }
    }
}
// The example displays the following output:
//   明治23/9/8 (Gregorian 9/8/1890)
//   明治23/9/8 (Gregorian 9/8/1890)
//   明治23/9/8 (Gregorian 9/8/1890)

Imports System.Globalization

Public Module Example
    Public Sub Main()
        Dim japaneseCal = New JapaneseCalendar()
        Dim jaJp = New CultureInfo("ja-JP")
        jaJp.DateTimeFormat.Calendar = japaneseCal

        ' We can get the era index by calling DateTimeFormatInfo.GetEraName.
        Dim eraIndex As Integer = 0

        For ctr As Integer = 0 To jaJp.DateTimeFormat.Calendar.Eras.Length - 1
            If jaJp.DateTimeFormat.GetEraName(ctr) = "明治" Then eraIndex = ctr
        Next
        Dim date1 = japaneseCal.ToDateTime(23, 9, 8, 0, 0, 0, 0, eraIndex)
        Console.WriteLine($"{date1.ToString("d", jaJp)} (Gregorian {date1:d})")

        Try
            Dim date2 = DateTime.Parse("明治23/9/8", jaJp)
            Console.WriteLine($"{date2.ToString("d", jaJp)} (Gregorian {date2:d})")
        Catch e As FormatException
            Console.WriteLine("The parsing operation failed.")
        End Try

        Try
            Dim date3 = DateTime.ParseExact("明治23/9/8", "gyy/M/d", jaJp)
            Console.WriteLine($"{date3.ToString("d", jaJp)} (Gregorian {date3:d})")
        Catch e As FormatException
            Console.WriteLine("The parsing operation failed.")
        End Try
    End Sub
End Module
' The example displays the following output:
'   明治23/9/8 (Gregorian 9/8/1890)
'   明治23/9/8 (Gregorian 9/8/1890)
'   明治23/9/8 (Gregorian 9/8/1890)

提示

使用支援多紀元的曆法時，請「一律」使用西曆日期具現化日期，或以該曆法為基礎在具現化日期和時間時指定紀元。

為 ToDateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32) 方法指定紀元時，您在曆法的 Eras 屬性中提供紀元的索引。不過，對於紀元可能會變更的曆法而言，這些索引不是常數值；目前紀元位於索引 0，而最舊紀元位於索引 Eras.Length - 1。將新紀元新增至曆法時，先前紀元的索引會增加一個。您可以提供適當的紀元索引，如下所示：

若是目前紀元期間的日期，一律使用曆法的 CurrentEra 屬性。
若是指定紀元期間的日期，請使用 DateTimeFormatInfo.GetEraName 方法擷取對應至指定紀元名稱的索引。這需要代表 ja-JP 文化特性且目前曆法為 JapaneseCalendar 的 CultureInfo 物件。 (這項技巧同樣適用於 JapaneseLunisolarCalendar，因其支援的紀元與 JapaneseCalendar 相同)。上一個範例說明此方法。

曆法、紀元和日期範圍：寬鬆的範圍檢查

就像個別曆法有支援的日期範圍一樣，JapaneseCalendar 和 JapaneseLunisolarCalendar 類別中的紀元也有支援的範圍。之前，.NET 使用嚴格的紀元範圍檢查，以確保特定紀元的日期在該紀元的範圍內。也就是說，如果日期超出指定紀元的範圍，方法會擲回 ArgumentOutOfRangeException。目前，.NET 預設使用寬鬆的範圍檢查。 .NET 所有版本的更新已導入寬鬆的紀元範圍檢查；嘗試具現化特定紀元的日期若超出指定紀元範圍，會「溢位」至後續紀元，而且不會擲回任何例外狀況。

下列範例嘗試具現化昭和紀元第 65 年期間的日期，昭和紀元始於 1926 年 12 月 25 日，結束於 1989 年 1 月 7 日。此日期對應至 1990 年 1 月 9 日，超出 JapaneseCalendar 中的昭和紀元範圍。如範例的輸出所示，此範例顯示的日期是 1990 年 1 月 9 日，在平成紀元第二年期間。

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      var jaJp = new CultureInfo("ja-JP");
      var cal = new JapaneseCalendar();
      jaJp.DateTimeFormat.Calendar = cal;
      string showaEra = "昭和";

      var dt = cal.ToDateTime(65, 1, 9, 15, 0, 0, 0, GetEraIndex(showaEra));
      FormattableString fmt = $"{dt:d}";

      Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)}");
      Console.WriteLine($"Gregorian calendar date: {fmt}");

      int GetEraIndex(string eraName)
      {
         foreach (var ctr in cal.Eras)
            if (jaJp.DateTimeFormat.GetEraName(ctr) == eraName)
               return ctr;

         return 0;
      }
   }
}
// The example displays the following output:
//   Japanese calendar date: 平成2/1/9
//   Gregorian calendar date: 1/9/1990

Imports System.Globalization

Public Module Example
    Dim jaJp As CultureInfo
    Dim cal As Calendar

    Public Sub Main()
        jaJp = New CultureInfo("ja-JP")
        cal = New JapaneseCalendar()
        jaJp.DateTimeFormat.Calendar = cal
        Dim showaEra = "昭和"

        Dim dt = cal.ToDateTime(65, 1, 9, 15, 0, 0, 0, GetEraIndex(showaEra))
        Dim fmt As FormattableString = $"{dt:d}"
        Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)}")
        Console.WriteLine($"Gregorian calendar date: {fmt}")
    End Sub

    Private Function GetEraIndex(eraName As String) As Integer
        For Each ctr As Integer In cal.Eras
            If jaJp.DateTimeFormat.GetEraName(ctr) = eraName Then Return ctr
        Next
        Return 0
    End Function
End Module
' The example displays the following output:
'   Japanese calendar date: 平成2/1/9
'   Gregorian calendar date: 1/9/1990

如果不想要使用寬鬆的範圍檢查，您有多種方式可以還原嚴格的範圍檢查，請依據執行應用程式的 .NET 版本，採取下列適當的做法：

.NET Core：將下列內容新增至 .netcore.runtime.json 設定檔：

"runtimeOptions": {
  "configProperties": {
      "Switch.System.Globalization.EnforceJapaneseEraYearRanges": true
  }
}

.NET Framework 4.6 或更新版本：在 app.config 檔案中設定下列 AppContext 參數：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <runtime>
    <AppContextSwitchOverrides value="Switch.System.Globalization.EnforceJapaneseEraYearRanges=true" />
  </runtime>
</configuration>

.NET Framework 4.5.2 或更早版本：設定下列登錄值：

值

索引鍵 HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext

Entry Switch.System.Globalization.EnforceJapaneseEraYearRanges

類型 REG_SZ

值 true

	值
索引鍵	HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext
Entry	Switch.System.Globalization.EnforceJapaneseEraYearRanges
類型	REG_SZ
值	true

啟用嚴格的範圍檢查後，上述範例會擲回 ArgumentOutOfRangeException 並顯示下列輸出：

Unhandled Exception: System.ArgumentOutOfRangeException: Valid values are between 1 and 64, inclusive.
Parameter name: year
   at System.Globalization.GregorianCalendarHelper.GetYearOffset(Int32 year, Int32 era, Boolean throwOnError)
   at System.Globalization.GregorianCalendarHelper.ToDateTime(Int32 year, Int32 month, Int32 day, Int32 hour, Int32 minute, Int32 second, Int32 millisecond, Int32 era)
   at Example.Main()

代表多紀元曆法中的日期

如果 Calendar 物件支援紀元而且是 CultureInfo 物件的現行曆法，則紀元會包含在完整日期和時間模式、完整日期模式及簡短日期模式之日期和時間值的字串表示中。下列範例顯示目前文化特性為日本 (日文) 且現行曆法為日本曆法時的這些日期模式。

using System;
using System.Globalization;
using System.IO;
using System.Threading;

public class Example
{
   public static void Main()
   {
      StreamWriter sw = new StreamWriter(@".\eras.txt");
      DateTime dt = new DateTime(2012, 5, 1);

      CultureInfo culture = CultureInfo.CreateSpecificCulture("ja-JP");
      DateTimeFormatInfo dtfi = culture.DateTimeFormat;
      dtfi.Calendar = new JapaneseCalendar();
      Thread.CurrentThread.CurrentCulture = culture;

      sw.WriteLine("\n{0,-43} {1}", "Full Date and Time Pattern:", dtfi.FullDateTimePattern);
      sw.WriteLine(dt.ToString("F"));
      sw.WriteLine();

      sw.WriteLine("\n{0,-43} {1}", "Long Date Pattern:", dtfi.LongDatePattern);
      sw.WriteLine(dt.ToString("D"));

      sw.WriteLine("\n{0,-43} {1}", "Short Date Pattern:", dtfi.ShortDatePattern);
      sw.WriteLine(dt.ToString("d"));
      sw.Close();
    }
}
// The example writes the following output to a file:
//    Full Date and Time Pattern:                 gg y'年'M'月'd'日' H:mm:ss
//    平成 24年5月1日 0:00:00
//
//    Long Date Pattern:                          gg y'年'M'月'd'日'
//    平成 24年5月1日
//
//    Short Date Pattern:                         gg y/M/d
//    平成 24/5/1

Imports System.Globalization
Imports System.IO
Imports System.Threading

Module Example
    Public Sub Main()
        Dim sw As New StreamWriter(".\eras.txt")
        Dim dt As Date = #05/01/2012#

        Dim culture As CultureInfo = CultureInfo.CreateSpecificCulture("ja-JP")
        Dim dtfi As DateTimeFormatInfo = culture.DateTimeFormat
        dtfi.Calendar = New JapaneseCalendar()
        Thread.CurrentThread.CurrentCulture = culture

        sw.WriteLine("{0,-43} {1}", "Full Date and Time Pattern:", dtfi.FullDateTimePattern)
        sw.WriteLine(dt.ToString("F"))
        sw.WriteLine()

        sw.WriteLine("{0,-43} {1}", "Long Date Pattern:", dtfi.LongDatePattern)
        sw.WriteLine(dt.ToString("D"))
        sw.WriteLine()

        sw.WriteLine("{0,-43} {1}", "Short Date Pattern:", dtfi.ShortDatePattern)
        sw.WriteLine(dt.ToString("d"))
        sw.WriteLine()
        sw.Close()
    End Sub
End Module
' The example writes the following output to a file:
'    Full Date and Time Pattern:                 gg y'年'M'月'd'日' H:mm:ss
'    平成 24年5月1日 0:00:00
'    
'    Long Date Pattern:                          gg y'年'M'月'd'日'
'    平成 24年5月1日
'    
'    Short Date Pattern:                         gg y/M/d
'    平成 24/5/1

警告

JapaneseCalendar 類別是 .NET 中獨一無二的曆法類別，既支援多紀元期間的日期，又可以是 CultureInfo 物件的目前曆法，明確地說，就是代表日文 (日本) 文化特性的 CultureInfo 物件所屬的目前曆法。

針對所有曆法，"g" 自訂格式規範會在結果字串中包含紀元。下列範例在現行曆法為西曆時，使用 "MM-dd-yyyy g" 自訂格式字串在結果字串中包含紀元。

   DateTime dat = new DateTime(2012, 5, 1);
   Console.WriteLine("{0:MM-dd-yyyy g}", dat);
// The example displays the following output:
//     05-01-2012 A.D.

Dim dat As Date = #05/01/2012#
Console.WriteLine("{0:MM-dd-yyyy g}", dat)
' The example displays the following output:
'     05-01-2012 A.D.

在日期的字串表示不是以現行曆法表示的情況下，Calendar 類別會包含 Calendar.GetEra 方法，該方法可搭配 Calendar.GetYear、Calendar.GetMonth 和 Calendar.GetDayOfMonth 方法用來明確指出日期，以及該日期所屬的紀元。下列範例使用 JapaneseLunisolarCalendar 類別提供圖例。不過請注意，若要在結果字串中包含代表紀元的有意義名稱或縮寫而非整數，必須將 DateTimeFormatInfo 物件具現化，並且讓 JapaneseCalendar 成為現行曆法 (JapaneseLunisolarCalendar 曆法不得為任何文化特性的現行曆法，但在這個案例中，兩個曆法共用相同的紀元)。

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      DateTime date1 = new DateTime(2011, 8, 28);
      Calendar cal = new JapaneseLunisolarCalendar();

      Console.WriteLine("{0} {1:d4}/{2:d2}/{3:d2}",
                        cal.GetEra(date1),
                        cal.GetYear(date1),
                        cal.GetMonth(date1),
                        cal.GetDayOfMonth(date1));

      // Display eras
      CultureInfo culture = CultureInfo.CreateSpecificCulture("ja-JP");
      DateTimeFormatInfo dtfi = culture.DateTimeFormat;
      dtfi.Calendar = new JapaneseCalendar();

      Console.WriteLine("{0} {1:d4}/{2:d2}/{3:d2}",
                        dtfi.GetAbbreviatedEraName(cal.GetEra(date1)),
                        cal.GetYear(date1),
                        cal.GetMonth(date1),
                        cal.GetDayOfMonth(date1));
   }
}
// The example displays the following output:
//       4 0023/07/29
//       平 0023/07/29

Imports System.Globalization

Module Example
    Public Sub Main()
        Dim date1 As Date = #8/28/2011#
        Dim cal As New JapaneseLunisolarCalendar()
        Console.WriteLine("{0} {1:d4}/{2:d2}/{3:d2}",
                          cal.GetEra(date1),
                          cal.GetYear(date1),
                          cal.GetMonth(date1),
                          cal.GetDayOfMonth(date1))

        ' Display eras
        Dim culture As CultureInfo = CultureInfo.CreateSpecificCulture("ja-JP")
        Dim dtfi As DateTimeFormatInfo = culture.DateTimeFormat
        dtfi.Calendar = New JapaneseCalendar()

        Console.WriteLine("{0} {1:d4}/{2:d2}/{3:d2}",
                          dtfi.GetAbbreviatedEraName(cal.GetEra(date1)),
                          cal.GetYear(date1),
                          cal.GetMonth(date1),
                          cal.GetDayOfMonth(date1))
    End Sub
End Module
' The example displays the following output:
'       4 0023/07/29
'       平 0023/07/29

在日本曆法中，紀元第一年稱為元年 (Gannen)。例如，平成紀元的第一年可以描述為平成元年，而不是平成 1 年。若日期和時間格式是下列標準或自訂日期和時間格式字串，當這些字串與使用 JapaneseCalendar 類別代表日文-日本 ("ja-JP") 文化特性的 CultureInfo 物件搭配使用時，.NET 會在格式化作業時採用此慣例：

長日期模式，以「D」標準日期和時間格式字串表示。
完整日期長時間模式，以「F」標準日期和時間格式字串表示。
完整日期短時間模式，以「f」標準日期和時間格式字串表示。
年/月模式，以「Y」或「y」標準日期和時間格式字串表示。
「ggy'年'」或「ggy'年'」自訂日期和時間格式字串。

例如，下列範例會在 JapaneseCalendar 中顯示平成紀元第一年期間的日期。

using System;
using System.Globalization;

public class Example
{
    public static void Main()
    {
         var enUs = new CultureInfo("en-US");
        var japaneseCal = new JapaneseCalendar();
        var jaJp = new CultureInfo("ja-JP");
        jaJp.DateTimeFormat.Calendar = japaneseCal;
        string heiseiEra = "平成";

        var date = japaneseCal.ToDateTime(1, 8, 18, 0, 0, 0, 0, GetEraIndex(heiseiEra));
        FormattableString fmt = $"{date:D}";
        Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)} (Gregorian: {fmt.ToString(enUs)})");

        int GetEraIndex(string eraName)
        {
           foreach (var ctr in japaneseCal.Eras)
              if (jaJp.DateTimeFormat.GetEraName(ctr) == eraName)
                 return ctr;

           return 0;
        }
    }
}
// The example displays the following output:
//    Japanese calendar date: 平成元年8月18日 (Gregorian: Friday, August 18, 1989)

Imports System.Globalization

Module Program
    Dim jaJp As CultureInfo
    Dim japaneseCal As Calendar

    Sub Main()
        Dim enUs = New CultureInfo("en-US")
        japaneseCal = New JapaneseCalendar()
        jaJp = New CultureInfo("ja-JP")
        jaJp.DateTimeFormat.Calendar = japaneseCal
        Dim heiseiEra = "平成"

        Dim dat = japaneseCal.ToDateTime(1, 8, 18, 0, 0, 0, 0, GetEraIndex(heiseiEra))
        Dim fmt As FormattableString = $"{dat:D}"
        Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)} (Gregorian: {fmt.ToString(enUs)})")
    End Sub

    Private Function GetEraIndex(eraName As String) As Integer
        For Each ctr In japaneseCal.Eras
            If jaJp.DateTimeFormat.GetEraName(ctr) = eraName Then
                Return ctr
            End If
        Next
        Return 0
    End Function
End Module
' The example displays the following output:
'    Japanese calendar date: 平成元年8月18日 (Gregorian: Friday, August 18, 1989)

如果不想要在格式化作業中使用此行為，您可以還原先前的行為，即一律將紀元第一年表示為「1」而不是「元年」，請依據 .NET 版本，採取下列適當的做法：

.NET Core：將下列內容新增至 .netcore.runtime.json 設定檔：

"runtimeOptions": {
  "configProperties": {
      "Switch.System.Globalization.FormatJapaneseFirstYearAsANumber": true
  }
}

.NET Framework 4.6 或更新版本：在 app.config 檔案中設定下列 AppContext 參數：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <runtime>
    <AppContextSwitchOverrides value="Switch.System.Globalization.FormatJapaneseFirstYearAsANumber=true" />
  </runtime>
</configuration>

.NET Framework 4.5.2 或更早版本：設定下列登錄值：

值

索引鍵 HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext

Entry Switch.System.Globalization.FormatJapaneseFirstYearAsANumber

類型 REG_SZ

值 true

	值
索引鍵	HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext
Entry	Switch.System.Globalization.FormatJapaneseFirstYearAsANumber
類型	REG_SZ
值	true

在格式化作業中停用元年的支援後，上一個範例會顯示下列輸出：

Japanese calendar date: 平成1年8月18日 (Gregorian: Friday, August 18, 1989)

.NET 也已更新，因此日期和時間剖析作業支援其中包含以「1」或以「元年」表示年份的字串。雖然您不應該這麼做，但您可以還原先前的行為，只將「1」辨識為紀元第一年。請依據 .NET 版本，採取下列適當的做法：

.NET Core：將下列內容新增至 .netcore.runtime.json 設定檔：

"runtimeOptions": {
  "configProperties": {
      "Switch.System.Globalization.EnforceLegacyJapaneseDateParsing": true
  }
}

.NET Framework 4.6 或更新版本：在 app.config 檔案中設定下列 AppContext 參數：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <runtime>
    <AppContextSwitchOverrides value="Switch.System.Globalization.EnforceLegacyJapaneseDateParsing=true" />
  </runtime>
</configuration>

.NET Framework 4.5.2 或更早版本：設定下列登錄值：

值

索引鍵 HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext

Entry Switch.System.Globalization.EnforceLegacyJapaneseDateParsing

類型 REG_SZ

值 true

共用方式為

使用行事曆

.NET 中的曆法

曆法和文化特性

日期和曆法

根據曆法具現化日期

以目前曆法表示日期

以非目前曆法表示日期

曆法和日期範圍

使用紀元

紀元和紀元名稱

使用紀元具現化日期

曆法、紀元和日期範圍：寬鬆的範圍檢查

代表多紀元曆法中的日期

另請參閱

其他資源