CurrencyFormatter  - AS3

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

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

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

相關 API 元素

所用的實際地區設定之三個字母的 ISO 4217 貨幣代碼。

若在 withCurrencySymbol 參數設為 false 時，使用 format() 方法格式化貨幣金額，將使用此代碼來判斷貨幣符號或字串。

建構函式會根據所使用的實際地區設定，初始化此屬性。若使用後援地區設定，此屬性會反映後援地區設定的偏好、預設貨幣代碼。

預設值為 dependent on the actual locale and operating system。

相關 API 元素

所用實際地區設定的貨幣符號或字串。

若在 withCurrencySymbol 參數設為 true 時，使用 format() 方法格式化貨幣金額，將使用此屬性做為貨幣符號。

建構函式會根據所使用的實際地區設定，初始化此屬性。若使用後援地區設定，此屬性會反映後援地區設定的偏好、預設貨幣符號。

預設值為 dependent on the actual locale and operating system。

相關 API 元素

用來格式化或解析含有小數部分的貨幣金額之小數分隔字元。

此屬性的初始設定，會根據建構格式化程式物件時選取的地區設定而定。

若將某值指派給此屬性，而且沒有錯誤或警告，則 lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

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

預設值為 dependent on the actual locale and operating system。

相關 API 元素

定義格式化貨幣金額時所用的位數字元集。

不同的語言與區域使用不同的字元集來表示數字 0 到 9。此屬性會定義要使用的位數組。

此屬性的值代表十進位位數組中，數字零的 Unicode 值。此屬性的有效值定義於 NationalDigitsType 類別中。

若將某值指派給此屬性，而且沒有錯誤或警告，則 lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

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

預設值為 dependent on the actual locale and operating system。

相關 API 元素

小數分隔符號後可出現的最大位數。

數字會根據此屬性指定的位數，進行四捨五入。四捨五入配置會隨使用者的作業系統而異。

若 trailingZeros 屬性設為 true，數字的小數部份 (小數點後的部分) 會在結尾填補零至此 fractionalDigits 屬性值指定的長度。

若將某值指派給此屬性，而且沒有錯誤或警告，則 lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

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

預設值為 0。

相關 API 元素

說明已格式化貨幣金額字串中，分組分隔符號的位置。

若 useGrouping 屬性設為 true，會使用 groupingPattern 屬性來定義分組分隔符號的位置與樣式。

分組樣式定義為包含數字的字串，這些數字以分號隔開，而且可選擇性以星號結尾。例如："3;2;*"。此字串中的各個數字都代表分組中的位數。分組分隔符號會置於每一組位數前。字串結尾的星號表示要重複使用此位數組別，對字串的其餘部分進行格式化。若沒有星號，表示格式化字串的其餘部分不會有其他組別或分隔符號。

字串中第一個數字代表小數分隔符號向左算起的第一組該有幾位數。後續數字定義向左算起各後續組別中的位數。因此「3;2;*」這個字串表示，第一個分組分隔符號放第一組 3 位數後，其他部分以 2 位數分組。例如：98,76,54,321

下表顯示以不同分組樣式對貨幣金額 123456789.12 進行格式化的結果。分組分隔符號為逗號，小數分隔符號為句號，錢字號 ($) 為貨幣符號。

可定義的分組大小數目有限。在某些作業系統上，分組樣式只能包含兩個數字加上一個星號。其他作業系統可支援最多四個數字和一個星號。對於沒有星號的樣式，有些作業系統只支援一個數字，有些作業系統支援最多三個數字。若超出分組樣式元素上限，會忽略其他元素，並設定 lastOperationStatus 屬性，如下所述。

若將某值指派給此屬性，而且沒有錯誤或警告，則 lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

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

相關 API 元素

用於分組分隔符號的字元或字串。

在 useGrouping 屬性設為 true 時，會在格式化貨幣金額時使用此屬性的值當做分組分隔符號。此屬性的初始設定，會根據建構格式化程式物件時選取的地區設定而定。

若將某值指派給此屬性，而且沒有錯誤或警告，則 lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

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

預設值為 dependent on the actual locale and operating system。

相關 API 元素

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

相關 API 元素

指定若小數分隔符號左邊沒有整數位數，是否要在格式化的貨幣金額中補上開頭的零。

若此屬性設為 true，會在格式化 -1.0 至 1.0 之間的數值時，在小數分隔符號左邊補上零。若此屬性設為 false，則不會包含開頭的零。

例如，若貨幣金額為 0.321，且此屬性設為 true，則格式化後的字串會包含開頭的零。若此屬性設為 false，則不會包含開頭的零。在這種情況下，字串只會包含小數分隔符號，後面接著小數位數，如 $.321。

下表顯示根據此屬性與相關 fractionalDigits 和 trailingZeros 屬性的值，對貨幣金額進行格式化的結果。

若將某值指派給此屬性，而且沒有錯誤或警告，則 lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

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

預設值為 dependent on the actual locale and operating system。

相關 API 元素

表示負值貨幣金額格式化樣式的數值。此樣式定義貨幣金額中，貨幣符號與負號或括弧相對於數字部分的位置。

此屬性的值必須為下表定義的常數之一。

下表摘要負值貨幣金額的可能格式化樣式。若使用 format() 方法對貨幣金額進行格式化：

• 根據傳至 format() 方法的 withCurrencySymbol 參數值，會使用 currencyISOCode 或 currencySymbol 屬性的值取代「¤」符號；
• 以 negativeNumberSymbol 屬性的值取代「-」字元；
• 以傳至 format() 方法的貨幣金額值取代「n」字元。

若將某值指派給此屬性，而且沒有錯誤或警告，則 lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

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

預設值為 dependent on the actual locale and operating system。

相關 API 元素

格式化負值金額時所使用的負號。

對小於零的貨幣金額進行格式化時，會使用此符號搭配負值貨幣格式。並不會用於未包含負號的負值貨幣格式 (例如，包含於括弧中的負值貨幣金額)。

若將某值指派給此屬性，而且沒有錯誤或警告，則 lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

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

預設值為 dependent on the actual locale and operating system。

相關 API 元素

表示正值貨幣金額格式化樣式的數值。此格式定義貨幣金額中，貨幣符號相對於數字部分的位置。

此屬性的值必須為下表定義的常數之一。

下表摘要正值貨幣金額的可能格式化樣式。若使用 format() 方法對貨幣金額進行格式化：

• 根據傳至 format() 方法的 withCurrencySymbol 參數值，會使用 currencyISOCode 或 currencySymbol 屬性的值取代「¤」符號；
• 以傳至 format() 方法的貨幣金額值取代「n」字元。

若將某值指派給此屬性，而且沒有錯誤或警告，則 lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

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

預設值為 dependent on the actual locale and operating system。

相關 API 元素

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

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

相關 API 元素

指定格式化後的貨幣金額是否包含結尾零。

若此屬性設為 true，格式化後的數字小數部分會包含結尾零，補滿至 fractionalDigits 屬性所指定的位數。若此屬性設為 false，則不會顯示結尾零。

例如，若貨幣金額為 123.4，且此屬性設為 true，而 fractionalDigits 屬性設為 3，則格式化後的字串會顯示結尾零，如 $123.400。若此屬性為 false，則字串中不會有結尾零，而只會顯示小數分隔符號，接著非零小數位數 (如 123.4)。

下表顯示根據此屬性與相關 fractionalDigits 和 leadingZero 屬性的值，對貨幣金額進行格式化的結果。

若將某值指派給此屬性，而且沒有錯誤或警告，則 lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

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

預設值為 dependent on the actual locale and operating system。

相關 API 元素

格式化貨幣金額時，啟用分組分隔符號。

若 useGrouping 屬性設為 true，會將位數分組，並以分組分隔字元隔開。例如：$123,456,789

若 useGrouping 屬性設為 false，位數之間就不會有分組或隔開的動作。例如：$123456789

groupingSeparator 屬性會定義做為分組分隔符號的符號。groupingPattern 屬性會定義分組分隔符號之間的位數。

若將某值指派給此屬性，而且沒有錯誤或警告，則 lastOperationStatus 屬性會被設為：

• LastOperationStatus.NO_ERROR

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

相關 API 元素

建構新 CurrencyFormatter 物件，以根據特定地區設定的慣例，格式化代表貨幣金額的數字。

此建構函式會判斷目前的作業系統是否支援要求的地區設定 ID 名稱。若不支援，則會改用後援地區設定。若使用後援地區設定，則 lastOperationStatus 屬性會指示後援類型，而 actualLocaleIDName 屬性會包含後援地區設定 ID 的名稱。

currencySymbol 和 currencyISOCode 等特定屬性，會根據地區設定自動設定。

注意：若使用後援地區設定，則貨幣屬性會設定成預設值，因此 currencySymbol 或 currencyISOCode 屬性可能會得到未預期的值。 建議您先檢查 currencySymbol 和 currencyISOCode 屬性值，再對貨幣金額進行格式化。

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

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

• LastOperationStatus.NO_ERROR

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

• LastOperationStatus.USING_FALLBACK_WARNING
• LastOperationStatus.USING_DEFAULT_WARNING

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

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

相關 API 元素

建立一個字串，代表根據此 CurrencyFormatter 物件的目前屬性來格式化的貨幣金額，目前屬性包括地區設定、貨幣符號與貨幣 ISO 代碼。

依照預設，此方法使用 currencyISOCode 屬性，判斷格式化時要使用的貨幣符號與其他設定。

許多國家與地區對於不同貨幣使用相同的貨幣符號。例如，美國、澳洲、紐西蘭、加拿大和墨西哥等地的貨幣都使用相同的錢字號 ($)。若要格式化的貨幣與使用者當地貨幣不同，建議使用 ISO 代碼作為貨幣字串。您可以使用 formattingWithCurrencySymbolIsSafe() 方法，測試要格式化的貨幣 ISO 代碼是否符合格式化程式的 currencyISOCode 屬性。

此方法可格式化極大和極小的純數。但有效位數受到 Number 資料類型提供之精確度的限制。

參數

相關 API 元素

 
         var cf:CurrencyFormatter = new CurrencyFormatter("fr-CA");  
         
         trace(cf.actualLocaleIDName);               // "fr-CA"  
         trace(cf.currencyISOCode);                // "CAD"
         trace(cf.currencySymbol);                // "$"
         
         trace(cf.format(1254.56));                // "1 254,56 CAD"
         trace(cf.format(1254.56, true));            // "1 254,56 $"
         

 
         var cf:CurrencyFormatter = new CurrencyFormatter(LocaleID.DEFAULT);  
         
         if (cf.formattingWithCurrencySymbolIsSafe("CAD")) {
           trace(cf.actualLocaleIDName);     // "fr-CA French (Canada)"
           trace(cf.format(1254.56, false)); // "1 254,56 $"
         }
         else {
           trace(cf.actualLocaleIDName);     // "en-US English (USA)"
           cf.setCurrency("CAD", "C$")
           trace(cf.format(1254.56, true));  // "C$ 1,254.56"
         }
         

判斷格式化貨幣金額時，可否使用目前指定的貨幣符號。

許多地區和國家使用相同的貨幣符號。若貨幣符號模稜兩可，或貨幣符號或 ISO 代碼由於使用後援地區設定而與預期有異，可使用此方法予以避免。

此方法的常見使用案例，是用來判斷是否顯示當地貨幣符號 (若金額將格式化為使用者預設貨幣)，或更特定的 ISO 代碼字串 (若金額將格式化為使用者預設值以外的其他貨幣)。

此方法會比較 requestedISOCode 參數與 currencyISOCode 屬性，若字串相同，則傳回 true，若不同則傳回 false。若字串相同，則使用 format() 方法並將 withCurrencySymbol 參數設為 true，會得到格式化的貨幣值字串 (含該地區設定的專用貨幣符號)。若此方法傳回 false，則使用 format() 方法並將 withCurrencySymbol 參數設為 true，會導致所用的貨幣符號模稜兩可或錯誤。

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

• LastOperationStatus.NO_ERROR

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

參數

相關 API 元素

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

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

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

• LastOperationStatus.NO_ERROR

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

將字串剖析為貨幣金額與貨幣符號。

解析演算法使用 decimalSeparator 屬性的值，判斷數字的整數與小數部分。它會使用 negativeCurrencyFormat 和 positiveCurrencyFormat 屬性的值，判斷貨幣符號或字串相對於貨幣金額的位置。若金額為負值，則 negativeCurrencyFormat 屬性的值會判斷負號的位置以及是否使用括弧。

若輸入字串中的貨幣符號、負號與數字順序與 negativeCurrencyFormat 和 positiveCurrencyFormat 屬性所分辨出的樣式不符，則：

1. 所傳回 CurrencyParseResult 物件的 value 屬性會設為 NaN。
2. 所傳回 CurrencyParseResult 物件的 currencyString 屬性會設為 null。
3. lastOperationStatus 屬性會設為表示解析失敗的值。

輸入字串可包含空白字元，這些字元在解析時會被忽略。

即使無貨幣符號，也能成功解析。對於與貨幣符號對應的字串部分，不會進行驗證。若無貨幣符號或字串，所傳回 CurrencyParseResult 物件的 currencyString 屬性會被設為空字串。

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

• LastOperationStatus.NO_ERROR

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

參數

相關 API 元素

設定 CurrencyFormatter 物件的 currencyISOCode 和 currencySymbol 屬性。

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

• LastOperationStatus.NO_ERROR

否則不會修改 currencyISOCode 和 currencySymbol 屬性的值，而且 lastOperationStatus 屬性會被設為 LastOperationStatus 類別中所定義的常數之一。

參數

相關 API 元素

此範例會使用以下的地區設定：

• 貨幣格式的預設作業系統 (LocaleID.DEFAULT)
• 日文 (日本)
• 英文 (美國)
• 法文 (法國)

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

1. 建立 CurrencyFormatter 物件
2. 請使用 formattingWithCurrencySymbolIsSafe() 方法，檢查地區設定的預設貨幣是否為歐元 ("EUR")，如果是的話，則使用貨幣符號來格式化此字串。否則，會使用 ISO 代碼來格式化字串。

  
package {
    import flash.display.Sprite;
    import flash.globalization.CurrencyFormatter;
    import flash.globalization.LocaleID;
    
    public class CurrencyFormatterExample1 extends Sprite
    {
        public function CurrencyFormatterExample1():void
        {
            var cf:CurrencyFormatter;
            var amountWithSymbol:String;
            var amountWithISOCode:String
            
            var localeNames:Array = [LocaleID.DEFAULT, "ja-JP", "en-US", "fr-FR"];
            
            for each (var localeName:String in localeNames) 
            {
                cf = new CurrencyFormatter(localeName);
                
                trace('\n' + "LocaleID requested=" + cf.requestedLocaleIDName 
                    + "; actual=" + cf.actualLocaleIDName);
                
                trace("Last Operation Status: " + cf.lastOperationStatus );
                
                trace("Currency ISO Code: " + cf.currencyISOCode);
                
                if (cf.formattingWithCurrencySymbolIsSafe("EUR")) 
                {
                    amountWithSymbol = cf.format(123456789.19, true);
                    trace("Format using Symbol: "+ amountWithSymbol);
                }
                else 
                {
                    amountWithISOCode = cf.format(123456789.19); 
                    trace("Format using ISO Code: " + amountWithISOCode);
                }
            }
        }
    }
}

這個範例會執行以下步驟：

1. 為英文 (美國) 地區設定建立一個 CurrencyFormatter 物件。
2. 使用 parse() 方法來剖析輸入字串。
3. 從產生的 CurrencyParseResult 物件中顯示金額與貨幣字串值。

 
package {
      import flash.display.Sprite;
      import flash.globalization.CurrencyFormatter;
      import flash.globalization.CurrencyParseResult;
      import flash.globalization.LastOperationStatus;
      import flash.globalization.LocaleID;

      public class CurrencyFormatterParseExample extends Sprite
      {
            public function CurrencyFormatterParseExample()
            {
                var cf:CurrencyFormatter = new CurrencyFormatter( "en_US" );
                
                trace("LocaleID requested=" + cf.requestedLocaleIDName 
                    + "; actual=" + cf.actualLocaleIDName);
                trace("Last Operation Status: " + cf.lastOperationStatus );

                var inputString:String = "Dollar 123,567,89,0.254";
                
                var result:CurrencyParseResult = cf.parse(inputString);
                
                if (cf.lastOperationStatus == LastOperationStatus.NO_ERROR ) {
                    trace("Amount value: " + result.value); 
                    trace("Currency string: " + result.currencyString); 
                }
            }
      }
}