flash.utils - 詳細資料 Adobe ActionScript® 3 (AS3 ) API 參考

flash.utils 套件包含各種可用來計時程式碼執行、擷取類別和物件資訊，以及轉換反斜線字元的套件層級函數。

公用方法

	函數		定義自
		clearInterval(id:uint):void 會取消指定的 setInterval() 呼叫。	flash.utils
		clearTimeout(id:uint):void 會取消指定的 setTimeout() 呼叫。	flash.utils
		describeType(value:*):XML 會產生 XML 物件，以說明命名為方法之參數的 ActionScript 物件。	flash.utils
		escapeMultiByte(value:String):String 會根據 System.useCodePage 的值，傳回編碼為 UTF-8 或系統字碼頁之輸入字串的逸出副本。	flash.utils
		getDefinitionByName(name:String):Object 會傳回 name 參數所指定之類別的類別物件參照。	flash.utils
		getQualifiedClassName(value:*):String 會傳回物件的完整類別名稱。	flash.utils
		getQualifiedSuperclassName(value:*):String 會傳回物件 (由 value 參數指定) 之基底類別的完整限定類別名稱。	flash.utils
		getTimer():int 用於計算相對時間。	flash.utils
		setInterval(closure:Function, delay:Number, ... arguments):uint 依指定的間隔 (以毫秒為單位) 執行函數。	flash.utils
		setTimeout(closure:Function, delay:Number, ... arguments):uint 會在指定的延遲時間 (以毫秒為單位) 之後執行指定的函數。	flash.utils
		unescapeMultiByte(value:String):String 會根據 System.useCodePage 的值，傳回透過系統字碼頁或 UTF-8 解碼之輸入字串的不逸出副本。	flash.utils

函數詳細資訊

clearInterval

()

函數

public function clearInterval(id:uint):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9

會取消指定的 setInterval() 呼叫。

參數

id:uint — setInterval() 呼叫的 ID，您要將其設定為變數，如下所示：

相關 API 元素

setInterval()

範例 ( 如何使用本範例 )

下列範例會使用 setInterval() 方法建立計時間隔，在固定的一秒鐘間隔之後呼叫 myRepeatingFunction() 方法。

每一個 myRepeatingFunction 方法呼叫都會遞增 counter 屬性，而當它等於 stopCount 屬性時，會使用 intervalId 屬性 (它是之前建立之間隔的參照 ID) 呼叫 clearInterval() 方法。

package {
    import flash.display.Sprite;
    import flash.utils.*;

    public class ClearIntervalExample extends Sprite {
        private var intervalDuration:Number = 1000; // duration between intervals, in milliseconds
        private var intervalId:uint;
        private var counter:uint     = 0;
        private var stopCount:uint     = 3;
        
        public function ClearIntervalExample() {
            intervalId = setInterval(myRepeatingFunction, intervalDuration, "Hello", "World");
        }

        public function myRepeatingFunction():void {
            trace(arguments[0] + " " + arguments[1]);

            counter++;
            if(counter == stopCount) {
                trace("Clearing Interval");
                clearInterval(intervalId);    
            }
        }
    }
}

clearTimeout

()

函數

public function clearTimeout(id:uint):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9

會取消指定的 setTimeout() 呼叫。

參數

id:uint — setTimeout() 呼叫的 ID，您要將其設定為變數，如下所示：

相關 API 元素

setTimeout()

範例 ( 如何使用本範例 )

下列範例會使用 setTimeout() 方法，在指定的延遲期間之後呼叫另一個方法。

這裡會建立迴圈以進行一百萬次的計數。如果系統可以在少於一秒鐘的時間內處理這個要求，clearTimeout() 將會移除 setTimeout() 要求，而且將不會呼叫 myDelayedFunction()。

package {
    import flash.display.Sprite;
    import flash.utils.*;

    public class ClearTimeoutExample extends Sprite {
        private var delay:Number = 1000; // delay before calling myDelayedFunction
        private var intervalId:uint;
        private var count:uint = 1000000;
        
        public function ClearTimeoutExample() {
            intervalId = setTimeout(myDelayedFunction, delay);
            startCounting();
        }

        public function startCounting():void {
            var i:uint = 0;
            do {
                if(i == count-1) {
                    clearTimeout(intervalId);
                    trace("Your computer can count to " + count + " in less than " + delay/1000 + " seconds.");    
                }
                i++;
            } while(i < count)            
        }
        
        public function myDelayedFunction():void {
            trace("Time expired.");
        }
    }
}

describeType

()

函數

public function describeType(value:*):XML

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會產生 XML 物件，以說明命名為方法之參數的 ActionScript 物件。這個方法會實作 ActionScript 語言的「反射」程式設計概念。

如果 value 參數是某個類型的實體，傳回的 XML 物件便會包含該類型的所有實體屬性，但不包含任何靜態屬性。您可以在剖析 XML 物件時，檢查 <type> 標籤的 isStatic 特質值 (當 value 為某類型的實體時，此值會是 false)，以便檢查這個條件。

若要取得某類型的靜態屬性，請將該類型本身傳遞為 value 參數。傳回的 XML 物件不只會包含該類型的靜態屬性，也會包含所有的實體屬性。實體屬性會置於名為 <factory> 之標籤內的巢狀結構中，以便與靜態屬性有所區分。在此情況下，<type> 標籤的 isStatic 特質會是 true。

注意：如果您只需要通過物件的繼承階層架構，而不需要 describeType() 所提供的其他資訊，請改用 getQualifiedClassName() 與 getQualifiedSuperclassName() 函數。

下表說明 describeType() 所產生 XML 物件的一些標籤和特質 (所有傳回的類別和介面名稱都是完整格式)：

標籤	特質	說明
`<type>`		XML 物件的根標籤。
	name	ActionScript 物件之資料類型的名稱。
	base	ActionScript 物件之定義類別的直接父類別。如果 ActionScript 物件是類別物件，此值便會是 `Class`。
	isDynamic	如果 ActionScript 物件的定義類別為動態類別，則為 `true`，否則為 `false`。如果 ActionScript 物件是類別物件，此值會是 `true`，因為 Class 類別是動態類別。
	isFinal	如果 ActionScript 物件的定義類別是最終類別，則為 `true`，否則為 `false`。
	isStatic	如果 ActionScript 物件是類別物件或建構函數，則為 `true`，否則為 `false`。這個特質名為 `isStatic`，因為如果其值為 `true`，任何不在 `factory` 標籤之巢狀結構內的標籤都會是靜態的。
`<extendsClass>`		ActionScript 物件之定義類別的每個父類別，都有個別的 `extendsClass` 標籤。
	type	ActionScript 物件之定義類別所延伸的父類別名稱。
`<implementsInterface>`		ActionScript 物件之定義類別或其任何父類別所實作的每個介面，都有個別的 `implementsInterface` 標籤。
	type	ActionScript 物件之定義類別所實作的介面名稱。
`<accessor>`		存取子是由 getter 與 setter 函數定義的屬性。
	name	存取子的名稱。
	access	屬性的存取權限。可能的值包括 `readonly`、`writeonly` 及 `readwrite`。
	type	屬性的資料類型。
	declaredBy	包含相關聯之 getter 或 setter 函數的類別。
`<constant>`		常數是以 `const` 陳述式定義的屬性。
	name	常數的名稱。
	type	常數的資料類型。
`<方法>`		方法是宣告為類別定義之一部分的函數。
	name	方法的名稱。
	declaredBy	包含方法定義的類別。
	returnType	方法之傳回值的資料類型。
`<parameter>`		方法所定義的每個參數，都有個別的 `parameter` 標籤。此標籤永遠都會位於 `<method>` 標籤內的巢狀結構中。
	index	數字，對應於參數在方法之參數清單中的出現順序。第一個參數具有 1 這個值。
	type	參數的資料類型。
	optional	如果此參數為選擇性，則為 `true`，否則為 `false`。
`<variable>`		變數是以 `var` 陳述式定義的屬性。
	name	變數的名稱。
	type	變數的資料類型。
`<factory>`		如果 ActionScript 物件是類別物件或建構函數，則所有的實體屬性與方法都會以巢狀方式位於此標籤中。如果 `<type>` 標籤的 `isStatic` 特質為 `true`，所有不在 `<factory>` 標籤之巢狀結構內的屬性與方法都會是靜態屬性。這個標籤只會在 ActionScript 物件是類別物件或建構函數時出現。

參數

value:* — 需要類型說明的物件。任何可能傳遞至此方法的 ActionScript 值，包括所有可用的 ActionScript 類型、物件實體、基本類型 (如 uint) 及類別物件。

傳回值

XML — XML 物件，含有傳入為參數之物件的詳細資料。此物件提供關於物件的下列資訊：

物件的類別
類別的特質
從類別至其基底類別的繼承樹狀結構
類別所實作的介面
類別的已宣告實體屬性
類別的已宣告靜態屬性
類別的實體方法
類別的靜態方法
類別、名稱、參數的數目、傳回類型及參數類型的每個方法

注意： describeType() 只會顯示公用屬性與方法，而不會顯示私用、套件內部或自訂命名空間內的屬性與方法。

範例 ( 如何使用本範例 )

package {
    import flash.display.Sprite;
    import flash.utils.describeType;
    
    public class DescribeTypeExample extends Sprite {
        public function DescribeTypeExample() {
            var child:Sprite = new Sprite();
            var description:XML = describeType(child);
            trace(description..accessor.@name.toXMLString());
        }
    }
}

escapeMultiByte

()

函數

public function escapeMultiByte(value:String):String

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會根據 System.useCodePage 的值，傳回編碼為 UTF-8 或系統字碼頁之輸入字串的逸出副本。使用 System.useCodePage 可讓執行階段存取以本機字碼頁編碼的舊版內容，但是只能在使用該舊版字碼頁的系統上。例如，以 Shift-JIS 編碼的日文資料，將只能在使用日文預設字碼頁的作業系統上，適當地進行逸出與不逸出。

參數

value:String — 要逸出的字串。

傳回值

String — 輸入字串的逸出副本。如果 System.useCodePage 為 true，逸出的字串會以系統字碼頁進行編碼。如果 System.useCodePage 為 false，逸出的字串會以 UTF-8 進行編碼。例如，如果 System.useCodePage 為 false，則輸入字串 "Crüe" 將會在所有系統上逸出為 "Cr%C3%BCe"。如果 system.useCodePage 為 true，並且系統使用的是拉丁字碼頁，則 "Crüe" 會逸出為 "Cr%FCe"。如果系統使用不包含 'ü' 字母的非拉丁字碼頁，結果便可能會是 "Cr?e"。不逸出 "Cr%C3%BCe"，並將 System.useCodePage 設定為 true ，便會在不同的系統上產生不良結果，例如在拉丁系統上產生 "CrÃ¼e"。同樣地，不逸出 "Cr%FCe" 並將 System.useCodePage 設定為 false，則可能會根據系統的字碼頁，而產生 "Cre"、"Cr?e" 或其他的變化。

getDefinitionByName

()

函數

public function getDefinitionByName(name:String):Object

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會傳回 name 參數所指定之類別的類別物件參照。

參數

name:String — 類別的名稱。

傳回值

Object — 會傳回 name 參數所指定之類別的類別物件參照。

擲回值

ReferenceError — 具有指定之名稱的公用定義不存在。

範例 ( 如何使用本範例 )

下列範例會使用 GetDefinitionByNameExample 類別，在舞台上建立橘黃色方形。這是透過下列步驟完成：

宣告變數，設定背景顏色為橘色以及大小為 80 像素。這些變數稍後將用於繪製正方形。
在此建構函式中，會將 Class 類型的變數 ClassReference 指定給 Sprite。
會實體化名為 instance 的 ClassReference 實體。
由於 instance 依照傳址方式為 Sprite 物件，所以可以繪製一個方形，並使用可供 Sprite 使用的方法將此方形加入到顯示清單中。

package {
    import flash.display.DisplayObject;
    import flash.display.Sprite;
    import flash.utils.getDefinitionByName;

    public class GetDefinitionByNameExample extends Sprite {
        private var bgColor:uint = 0xFFCC00;
        private var size:uint = 80;

        public function GetDefinitionByNameExample() {
            var ClassReference:Class = getDefinitionByName("flash.display.Sprite") as Class;
            var instance:Object = new ClassReference();
            instance.graphics.beginFill(bgColor);
            instance.graphics.drawRect(0, 0, size, size);
            instance.graphics.endFill();
            addChild(DisplayObject(instance));
        }
    }
}

getQualifiedClassName

()

函數

public function getQualifiedClassName(value:*):String

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會傳回物件的完整類別名稱。

參數

value:* — 需要完整限定類別名稱的物件。任何可能傳遞至此方法的 ActionScript 值，包括所有可用的 ActionScript 類型、物件實體、基本類型 (如 uint) 及類別物件。

傳回值

String — 包含完整限定類別名稱的字串。

getQualifiedSuperclassName

()

函數

public function getQualifiedSuperclassName(value:*):String

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會傳回物件 (由 value 參數指定) 之基底類別的完整類別名稱。這個函數能提供比 describeType() 更快的方式來擷取基底類別名稱，不過無法提供 describeType() 所能提供的所有資訊。

在使用此函數擷取類別的名稱之後，您就能使用 getDefinitionByName() 函數將此類別名稱轉換成類別參照。

注意：這個函數會將本身限制在實體階層架構，而 describeType() 函數則會在 value 參數是資料類型時，使用類別物件階層架構。對資料類型呼叫 describeType()，便會傳回以類別物件階層架構為根據的父類別，其中所有的類別物件都繼承自 Class。不過，getQualifiedSuperclassName() 函數則會忽略此類別物件階層架構，並傳回以更熟悉之實體階層架構為根據的父類別。例如，儘管在技術上 String 類別物件會繼承自 Class，但是呼叫 getQualifiedSuperclassName(String) 還是會傳回 Object。換句話說，不論您使用類型的實體或是該類型本身，結果都相同。

參數

value:* — 任何值。

傳回值

String — 完整基底類別名稱，不存在基底類別時則為 null。

getTimer

()

函數

public function getTimer():int

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

用於計算相對時間。對於處理 ActionScript 3.0 的 Flash 執行階段，這個方法會傳回自從 ActionScript 3.0 (AVM2) 的 Flash 執行階段虛擬機器啟動後的毫秒數。對於處理 ActionScript 2.0 的 Flash 執行階段，這個方法會傳回 Flash 執行階段開始初始化之後的毫秒數。Flash 執行階段使用兩個虛擬機器處理 ActionScript。AVM1 是用於執行 ActionScript 1.0 與 2.0 的 ActionScript 虛擬機器。AVM2 是用於執行 ActionScript 3.0 的 ActionScript 虛擬機器。AVM1 的 getTimer() 方法行為與 AVM2 的行為不同。

如需有關日曆日期 (timestamp) 的資訊，請參閱 Date 物件。

傳回值

int — 自從執行階段初始化 (當處理 ActionScript 2.0 時) 後，或自從虛擬機器啟動後 (當處理 ActionScript 3.0 時) 的毫秒數。如果執行階段開始播放某個 SWF 檔，另一個 SWF 檔則在稍後載入，傳回的值便會相對於首次載入 SWF 檔時的值。

相關 API 元素

flash.display.AVM1Movie
Date 類別

範例 ( 如何使用本範例 )

下列範例會使用 GetTimerExample 類別來取得及列印執行階段初始化以來所經過的毫秒數。

package {
    import flash.utils.getTimer;
    import flash.display.Sprite;

    public class GetTimerExample extends Sprite {
        public function GetTimerExample() {
            var duration:uint = getTimer();
            trace("duration: " + duration);
        }
    }
}

setInterval

()

函數

public function setInterval(closure:Function, delay:Number, ... arguments):uint

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9

依指定的間隔 (以毫秒為單位) 執行函數。

與其使用 setInterval() 方法，請考慮建立具有指定之間隔的 Timer 物件，並使用 0 做為 repeatCount 參數 (如此會設定計時器重複無限次)。

如果您想要使用 clearInterval() 方法取消 setInterval() 呼叫，請務必將 setInterval() 呼叫指定成變數，以供 clearInterval() 函數稍後參考。若非呼叫 clearInterval() 函數來取消 setInterval() 呼叫，將不會對含有設定逾時結束項函數的物件進行記憶體回收處理。

參數

	`closure:Function` — 要執行的函數名稱。請勿包含引號或括號，也不要指定要呼叫之函數的參數。例如，請使用 `functionName`，而非 `functionName()` 或 `functionName(param)`。

	`delay:Number` — 間隔，以毫秒為單位。

	`... arguments` — 選擇性的引數清單，會傳遞至結束函數。

傳回值

uint — 計時程序的唯一數字識別碼。使用此識別碼呼叫 clearInterval() 方法即可取消程序。

相關 API 元素

clearInterval()

範例 ( 如何使用本範例 )

下列範例會使用 setInterval() 方法建立計時間隔，在固定的一秒鐘間隔之後呼叫 myRepeatingFunction() 方法。

package {
    import flash.display.Sprite;
    import flash.utils.*;

    public class SetIntervalExample extends Sprite {
        private var intervalDuration:Number = 1000; // duration between intervals, in milliseconds
        
        public function SetIntervalExample() {
            var intervalId:uint = setInterval(myRepeatingFunction, intervalDuration, "Hello", "World");
        }

        public function myRepeatingFunction():void {
            trace(arguments[0] + " " + arguments[1]);
        }
    }
}

setTimeout

()

函數

public function setTimeout(closure:Function, delay:Number, ... arguments):uint

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9

會在指定的延遲時間 (以毫秒為單位) 之後執行指定的函數。

與其使用這個方法，請考慮建立具有指定之間隔的 Timer 物件，並使用 1 做為 repeatCount 參數 (如此會設定計時器只執行一次)。

如果您想要使用 clearTimeout() 方法取消 setTimeout() 呼叫，請務必將 setTimeout() 呼叫指定成變數，以供 clearTimeout() 函數稍後參考。若非呼叫 clearTimeout() 函數來取消 setTimeout() 呼叫，將不會對含有設定逾時結束項函數的物件進行記憶體回收處理。

參數

	`closure:Function` — 要執行的函數名稱。請勿包含引號或括號，也不要指定要呼叫之函數的參數。例如，請使用 `functionName`，而非 `functionName()` 或 `functionName(param)`。

	`delay:Number` — 直到函數執行之前的延遲時間，以毫秒為單位。

	`... arguments` — 選擇性的引數清單，會傳遞至結束函數。

傳回值

uint — 計時程序的唯一數字識別碼。使用此識別碼呼叫 clearTimeout() 方法即可取消程序。

相關 API 元素

clearTimeout()

範例 ( 如何使用本範例 )

下列範例會使用 setTimeout() 方法，在指定的延遲期間之後呼叫另一個方法。

package {
    import flash.display.Sprite;
    import flash.utils.*;

    public class SetTimeoutExample extends Sprite {
        private var delay:Number = 1000; // delay before calling myDelayedFunction
        
        public function SetTimeoutExample() {
            var intervalId:uint = setTimeout(myDelayedFunction, delay, "Hello", "World");
        }

        public function myDelayedFunction():void {
            trace(arguments[0] + " " + arguments[1]);
        }
    }
}

unescapeMultiByte

()

函數

public function unescapeMultiByte(value:String):String

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會根據 System.useCodePage 的值，傳回透過系統字碼頁或 UTF-8 解碼之輸入字串的不逸出副本。使用 System.useCodePage 可讓執行階段存取以本機字碼頁編碼的舊版內容，但是只能在使用該舊版字碼頁的系統上。例如，以 Shift-JIS 編碼的日文資料，將只能在使用日文預設字碼頁的作業系統上，適當地進行逸出與不逸出。

參數

value:String — 不逸出的字串。

傳回值

String — 輸入字串的不逸出副本。如果 System.useCodePage 為 true，便會透過系統字碼頁解碼逸出的字串。如果 System.useCodePage 為 false，便會透過 UTF-8 解碼逸出的字串。例如，若輸入字串為 "Crüe" 且 System.useCodePage 為 false，在所有系統上的結果都會是 "CrÃ¼e"。如果 System.useCodePage 為 true，而且輸入字串是 "Cr%FCe" 且系統使用拉丁字碼頁，則結果也會是 "CrÃ¼e"。不逸出 "Cr%C3%BCe"，並將 System.useCodePage 設定為 true，便會在不同的系統上產生不良結果，例如在拉丁系統上產生 "CrÃÂ¼e"。同樣地，不逸出 "Cr%FCe" 並將 System.useCodePage 設定為 false，則可能會根據系統的字碼頁，而產生 "Cre"、"Cr?e" 或其他的變化。

法律聲明 | 線上隱私權政策

套件 flash.utils

類別 x

clearInterval

clearTimeout

describeType

escapeMultiByte

getDefinitionByName

getQualifiedClassName

getQualifiedSuperclassName

getTimer

setInterval

setTimeout

unescapeMultiByte