DateTimeFormatter  - AS3

此 DateTimeFormatter 物件所使用的實際地區設定 ID 名稱。

根據作業系統與 requestedLocaleIDName 參數傳送到 Collator() 建構函式的值，此值有三種可能性。

1. 若要求的地區設定不是 LocaleID.DEFAULT，而且作業系統支援要求的地區設定，則傳回的名稱會與 requestedLocaleIDName 屬性相同。
2. 若使用 LocaleID.DEFAULT 當作建構函式 requestedLocaleIDName 參數的值，則會使用使用者作業系統指定的目前地區設定名稱。LocaleID.DEFAULT 值會將使用者的自訂設定保留於作業系統中。即使兩個地區設定 ID 名稱是相同的，傳送明確的值作為 requestedLocaleIDName 參數所得的結果，也未必與使用 LocaleID.DEFAULT 相同。使用者可能在自己的電腦上已有自訂的地區設定，若要求明確的地區設定 ID 名稱而不是使用 LocaleID.DEFAULT 的話，您的應用程式不會擷取這些自訂設定。
3. 若系統不支援建構函式所指定的 requestedLocaleIDName，則會提供後援地區設定 ID 名稱。

相關 API 元素

此 DateTimeFormatter 物件執行之上一個作業的狀態。只要呼叫此類別的建構函式或方法，或設定其他屬性，就會設定 lastOperationStatus 屬性。如需可能的值，請參閱各方法的說明。

相關 API 元素

傳送到此 DateTimeFormatter 物件建構函式的所要求地區設定 ID 名稱。

若使用 LocaleID.DEFAULT 值，則傳回的名稱會是 "i-default"。若採用後援地區設定，則所用的實際地區設定可能與要求的地區設定不同。您可以使用 actualLocaleIDName 屬性擷取實際地區設定名稱。

相關 API 元素

建構新 DateTimeFormatter 物件，以根據指定地區設定的慣例和所提供的日期與時間格式樣式，格式化日期與時間。日期和時間樣式用來設定預先定義的日期和時間格式化樣式，地區設定會根據作業系統樣式而有所不同。

此建構函式會判斷目前的作業系統是否支援要求的地區設定 ID 名稱。若不支援，則會改用後援地區設定。您可以從 actualLocaleIDName 屬性判斷後援地區設定 ID 的名稱。

若 requestedLocaleIDName、dateStyle 或 timeStyle 其中一個參數使用後援，則會設定 lastOperationStatus 屬性指示後援類型。

若要根據使用者目前作業系統的偏好設定進行格式化，請將 requestedLocaleIDName 參數中的 LocaleID.DEFAULT 值傳送到建構函式。

當建構函式被呼叫並成功完成時，lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

若要求的地區設定 ID 名稱無法使用，則 lastOperationStatus 會被設為下列之一：

• LastOperationStatus.USING_FALLBACK_WARNING
• LastOperationStatus.USING_DEFAULT_WARNING

否則，lastOperationStatus 屬性會被設為 LastOperationStatus 類別中定義的常數之一。

如需有關上方列出的警告以及 lastOperationStatus 屬性的其他可能值的詳細資訊，請參閱 LastOperationStatus 類別的說明。

相關 API 元素

針對解譯為使用者本地時間 (使用 Date 物件的本地時間組件，如：date、day, fullYear、hours、minutes、month 和 seconds) 的 Date 物件，格式化顯示字串。會使用此 DateTimeFormatter 實體中指定的地區設定 ID 和日期與時間樣式慣例，或自訂日期與時間樣式，完成格式化動作。

當此方法被呼叫並成功完成時，lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

否則，lastOperationStatus 屬性會被設為 LastOperationStatus 類別中定義的常數之一。

參數

相關 API 元素

根據 dateStyle、timeStyle 或 date time 樣式，針對解譯為 UTC 時間 (使用 Date 物件的 UTC 組件，如：dateUTC、dayUTC、fullYearUTC、hoursUTC、minutesUTC、monthUTC 和 secondsUTC) 的 Date 物件，格式化顯示字串。會使用此 DateTimeFormatter 實體中指定的地區設定 ID 和日期與時間樣式慣例，或自訂日期與時間樣式，完成格式化動作。

當此方法被呼叫並成功完成時，lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

否則，lastOperationStatus 屬性會被設為 LastOperationStatus 類別中定義的常數之一。

參數

相關 API 元素

列出此類別支援的所有地區設定 ID 名稱。

若目前的作業系統不支援此類別，此方法會傳回 null 值。

當此方法被呼叫並成功完成時，lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

否則，lastOperationStatus 屬性會被設為 LastOperationStatus 類別中定義的常數之一。

相關 API 元素

取得此 DateTimeFormatter 實體的日期樣式。日期樣式是用來從作業系統擷取預先定義的日期格式化樣式。DateTimeFormatter() 建構函式、setDateTimeStyles() 方法或 setDateTimePattern() 方法，都可設定日期樣式值。

當此方法被呼叫並成功完成時，lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

否則，lastOperationStatus 屬性會被設為 LastOperationStatus 類別中定義的常數之一。

相關 API 元素

傳回此 DateTimeFormatter 物件用來格式化日期與時間的樣式字串。

可使用下列三種方式設定此樣式：

1. 透過建構函式中所用的 dateStyle 和 timeStyle 參數
2. 透過 setDateTimeStyles() 方法
3. 透過 setDateTimePattern() 方法。

如需樣式語法的說明，請參閱 setDateTimePattern() 方法。

當此方法被呼叫並成功完成時，lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

否則，lastOperationStatus 屬性會被設為 LastOperationStatus 類別中定義的常數之一。

相關 API 元素

傳回對應到此地區設定和月曆系統中每週第一天的整數。0 值對應到星期日、1 對應到星期一，依此類推，6 對應到星期六。

當此方法被呼叫並成功完成時，lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

否則，lastOperationStatus 屬性會被設為 LastOperationStatus 類別中定義的常數之一。

相關 API 元素

擷取包含目前月曆系統月份名稱的當地語系化字串清單。清單中第一個元素是年中第一個月份的名稱。

當此方法被呼叫並成功完成時，lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

否則，lastOperationStatus 屬性會被設為 LastOperationStatus 類別中定義的常數之一。

參數

相關 API 元素

取得此 DateTimeFormatter 實體的時間樣式。時間樣式是用來從作業系統擷取預先定義的時間格式化樣式。DateTimeFormatter() 建構函式、setDateTimeStyles() 方法或 setDateTimePattern() 方法，都可設定時間樣式值。

當此方法被呼叫並成功完成時，lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

否則，lastOperationStatus 屬性會被設為 LastOperationStatus 類別中定義的常數之一。

相關 API 元素

擷取包含目前月曆系統星期別名稱的當地語系化字串清單。清單中的第一個元素代表「星期日」的名稱。

當此方法被呼叫並成功完成時，lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

否則，lastOperationStatus 屬性會被設為 LastOperationStatus 類別中定義的常數之一。

參數

相關 API 元素

設定此 DateTimeFormatter 物件用來格式化日期與時間的樣式字串。

可使用下列三種方式設定格式化日期所用的樣式：

1. 透過建構函式中所用的 dateStyle 和 timeStyle 參數
2. 透過 setDateTimeStyles() 方法
3. 透過此 setDateTimePattern() 方法。

此方法有個副作用，就是會覆寫此 DateTimeFormatter 物件的目前時間與日期樣式，並將其設為值 DateTimeStyle.CUSTOM。

定義如何格式化日期和時間的樣式字串。樣式包含的字母序列，會在格式化字串中被取代為日期和時間值。例如，在樣式「yyyy/MM」中，「yyyy」字元會被取代為四位數年份，接著「/」字元，「MM」會被取代為二位數月份。

樣式中使用的許多字母都可重複多次，以產生不同輸出，如下表所說明。

若序列超出樣式支援的字母數上限，會對應回該樣式字母支援的最長序列。例如：

• MMMMMM 會被取代為 MMMM
• dddd 會被取代為 dd
• EEEEEEE 會被取代為 EEEE
• aa 會被取代為 a
• hhh 會被取代為 hh
• mmmm 會被取代為 mm

理論上，樣式最多可包含 255 個字元，但有些平台的限制更為嚴格。若樣式超出樣式字元限制，lastOperationStatus 屬性會設為值 LastOperationStatus.PATTERN_SYNTAX_ERROR。

並非所有作業系統都支援所有可能的樣式。若有平台不支援某樣式，則會使用後援樣式，並設定 lastOperationStatus 屬性以指示使用後援。若無法提供合理的後援樣式，則會使用空字串，並設定 lastOperationStatus 屬性以表示不支援該樣式。

下表說明有效樣式字母及其意義。

當此方法被呼叫並成功完成時，lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

否則，lastOperationStatus 屬性會被設為 LastOperationStatus 類別中定義的常數之一。

參數

相關 API 元素

設定此 DateTimeFormatter 實體的日期和時間樣式。日期和時間樣式可用來設定預先定義的日期和時間格式化樣式，地區設定會根據作業系統樣式而有所不同。此方法會取代使用 DateTimeFormatter() 建構函式或 setDateTimePattern() 方法所設定的樣式。同時會根據所設定的樣式，更新日期和時間樣式。

當此方法被呼叫並成功完成時，lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

否則，lastOperationStatus 屬性會被設為 LastOperationStatus 類別中定義的常數之一。

參數

相關 API 元素

本範例使用下列地區設定：英文 (美國)、法文 (法國)、西班牙文 (西班牙)。

此範例會為清單中的每一個地區設定執行以下動作：

1. 使用預設樣式 (dateStyle 為 long，timeStyle 為 long) 建立 DateTimeFormatter 物件
2. 使用預設的完整日期樣式，設定目前日期和時間的格式。
3. 使用 DateTimeStyle.NONE 和 DateTimeStyle.SHORT 常數，變更成只有時間的簡短日期樣式。
4. 使用只有時間的簡短日期樣式，設定目前日期和時間的格式。

package {
    import flash.display.Sprite;
    import flash.globalization.DateTimeFormatter;
    import flash.globalization.DateTimeStyle;
    
    public class DateTimeFormatterExample extends Sprite
    {    
        private var localeList:Array = new Array("en-US", "fr-FR", "es-ES");
    
        public function DateTimeFormatterExample()
        {
            var date:Date = new Date();
            
            for each (var locale:String in localeList) {
                var dtf:DateTimeFormatter = new DateTimeFormatter(locale);
                trace('\n' + "LocaleID requested=" + dtf.requestedLocaleIDName 
                    + "; actual=" + dtf.actualLocaleIDName);
            
                var longDate:String = dtf.format(date);
                trace(longDate + " (" + dtf.getDateTimePattern() + ")");
            
                dtf.setDateTimeStyles(DateTimeStyle.NONE, DateTimeStyle.SHORT);
                var shortDate:String = dtf.format(date);
                trace(shortDate + " (" + dtf.getDateTimePattern() + ")");
            }        
        }
    }
}

此範例會為清單中的每一個地區設定執行以下動作：

1. 建立三個輸入以及輸出文字欄位。
2. 使用美國英文地區設定來建立 DateTimeFormatter 物件。
3. 呼叫 configureTextField() 函數，它會設定文字欄位的位置和大小以及將偵聽程式加到 patternField 物件。
4. 當使用者在 patternField 文字欄位輸入樣式後，textInputHandler 函數會使用該樣式來設定日期和時間的格式，並在輸出文字欄位中顯示結果和 lastOperationStatus 值。

 
package {  
    import flash.display.Sprite;
    import flash.events.Event;
    import flash.globalization.DateTimeFormatter;
    import flash.text.*;
    
    public class DateTimePatternExample extends Sprite
    {    
        private var patternField:TextField = new TextField();
        private var resultField:TextField = new TextField();
        private var statusField:TextField = new TextField();
           private var date:Date = new Date();
         private var dtf:DateTimeFormatter = new DateTimeFormatter("en-US");           
         
        private function configureTextField():void
        {
            patternField.type = TextFieldType.INPUT;
            patternField.width = 300;
            patternField.height = 20;
            patternField.background = true;
            patternField.border = true;
            
            resultField.y = 40;
            resultField.width = 300;
            resultField.height = 20;
            
            statusField.y = 80;
            statusField.width = 300;
            statusField.height = 20;

            addChild(patternField);
            addChild(resultField);
            addChild(statusField);
            patternField.addEventListener(Event.CHANGE,textInputHandler);
        }

        private function textInputHandler(event:Event):void
        {                 
            dtf.setDateTimePattern(patternField.text);
            statusField.text = dtf.lastOperationStatus;
            resultField.text = dtf.format(date);
        }

        public function DateTimePatternExample()
        {
            configureTextField();    
        }
    }
}