ByteArray

套件	flash.utils
類別	public class ByteArray
繼承	ByteArray Object
實作	IDataInput, IDataOutput
子類別	ByteArrayAsset

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

ByteArray 類別會提供方法和屬性，好讓讀取、寫入及使用二進位資料的動作最佳化。

注意： ByteArray 類別適用於需要在位元組層級存取資料的進階開發人員。

記憶體內的資料是位元組的封裝陣列 (資料類型的最緊密壓縮形式)，不過 ByteArray 類別的實體可由標準的 [] (陣列存取) 運算子加以操作。使用相似於 URLStream 與 Socket 類別中的方法，也可將此實體當做記憶體內的檔案，以進行讀取和寫入。

此外，也支援 zlib、deflate 和 lzma 壓縮與解壓縮，以及 Action Message Format (AMF) 物件序列化。

ByteArray 會將它的 shareable 屬性設定為 true，以便在多個 Worker 實體之間共用它的後備記憶體。

ByteArray 類別的可能用法包括下列各項：

建立自訂通訊協定以連線至伺服器。
撰寫您自己的 URLEncoder/URLDecoder。
撰寫您自己的 AMF/Remoting 封包。
使用資料類型最佳化您的資料大小。
使用從檔案載入的二進位資料。

檢視範例

公用屬性

隱藏繼承公用屬性

顯示繼承公用屬性

	屬性		定義自
		bytesAvailable : uint [唯讀] 可從位元組陣列中的目前位置讀取到陣列結尾之資料的位元組數。	ByteArray
		constructor : Object 類別物件的參照或是特定物件實體的建構函數。	Object
		defaultObjectEncoding : uint [靜態] 代表針對 ByteArray 類別加以編碼的預設物件，以便用於新的 ByteArray 實體。	ByteArray
		endian : String 變更或讀取資料的位元組順序，可能是 Endian.BIG_ENDIAN 或 Endian.LITTLE_ENDIAN。	ByteArray
		length : uint ByteArray 物件的長度，以位元組為單位。	ByteArray
		objectEncoding : uint 用來決定在從 ByteArray 實體寫入或讀取資料時，應該使用 ActionScript 3.0、ActionScript 2.0 還是 ActionScript 1.0 格式。	ByteArray
		position : uint 會將 ByteArray 物件的檔案指標移動或返回到目前的位置 (以位元組為單位)。	ByteArray
		shareable : Boolean 指定位元組陣列的基礎記憶體是否為可共用。	ByteArray

公用方法

隱藏繼承公用方法

顯示繼承公用方法

	方法		定義自
		ByteArray() 會建立代表位元組之封裝陣列的 ByteArray 實體，如此您便可以使用此類別中的方法和屬性，讓資料的儲存與串流最佳化。	ByteArray
		atomicCompareAndSwapIntAt(byteIndex:int, expectedValue:int, newValue:int):int 在單一不可分割的作業中，請比較這個位元組陣列中的整數值與其他整數值，如果相符，請將那些位元組替換為其他值。	ByteArray
		atomicCompareAndSwapLength(expectedLength:int, newLength:int):int 在單一不可分割的作業中，請比較這個位元組陣列的長度與提供的值，如果相符，請變更這個位元組陣列的長度。	ByteArray
		clear():void 清除位元組陣列的內容，然後將 length 與 position 屬性重設為 0。	ByteArray
		compress(algorithm:String):void 壓縮位元組陣列。	ByteArray
		deflate():void 使用 deflate 壓縮演算法來壓縮位元組陣列。	ByteArray
		hasOwnProperty(name:String):Boolean 指出物件是否有已定義的指定屬性。	Object
		inflate():void 使用 deflate 壓縮演算法來解壓縮位元組陣列。	ByteArray
		isPrototypeOf(theClass:Object):Boolean 指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。	Object
		propertyIsEnumerable(name:String):Boolean 指出指定的屬性是否存在，以及是否可列舉。	Object
		readBoolean():Boolean 會從位元組串流讀取 Boolean 值。	ByteArray
		readByte():int 會從位元組串流讀取具有正負號的位元組。	ByteArray
		readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void 會從位元組串流讀取資料位元組的數目 (由 length 參數指定)。	ByteArray
		readDouble():Number 會從位元組串流讀取 IEEE 754 雙精度 (64 位元) 浮點數。	ByteArray
		readFloat():Number 會從位元組串流讀取 IEEE 754 單精度 (32 位元) 浮點數。	ByteArray
		readInt():int 會從位元組串流讀取具有正負號的 32 位元整數。	ByteArray
		readMultiByte(length:uint, charSet:String):String 會使用指定的字元集，從位元組串流讀取指定之長度的多位元組字串。	ByteArray
		readObject():* 會從位元組陣列讀取物件，並以 AMF 序列化格式編碼。	ByteArray
		readShort():int 會從位元組串流讀取具有正負號的 16 位元整數。	ByteArray
		readUnsignedByte():uint 會從位元組串流讀取無正負號的位元組。	ByteArray
		readUnsignedInt():uint 會從位元組串流讀取無正負號的 32 位元整數。	ByteArray
		readUnsignedShort():uint 會從位元組串流讀取無正負號的 16 位元整數。	ByteArray
		readUTF():String 會從位元組串流讀取 UTF-8 字串。	ByteArray
		readUTFBytes(length:uint):String 會從位元組串流讀取由 length 參數指定的 UTF-8 位元組序列，並傳回字串。	ByteArray
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 為迴圈作業設定動態屬性的可用性。	Object
		toJSON(k:String):* 提供可覆寫的方法，用於自訂 ByteArray 物件中值的 JSON 編碼。	ByteArray
		toLocaleString():String 傳回代表此物件的字串，根據地區特定慣例進行格式化。	Object
		toString():String 會將位元組陣列轉換為字串。	ByteArray
		uncompress(algorithm:String):void 會解壓縮位元組陣列。	ByteArray
		valueOf():Object 會傳回指定之物件的基本值。	Object
		writeBoolean(value:Boolean):void 會寫入 Boolean 值。	ByteArray
		writeByte(value:int):void 會將位元組寫入位元組串流。	ByteArray
		writeBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void 會從指定的位元組陣列 bytes，將 length 個位元組的序列，從 offset (從零開始的索引) 個位元組之後開始寫入至位元組串流。	ByteArray
		writeDouble(value:Number):void 會將 IEEE 754 雙精度 (64 位元) 浮點數寫入位元組串流。	ByteArray
		writeFloat(value:Number):void 會將 IEEE 754 單精度 (32 位元) 浮點數寫入位元組串流。	ByteArray
		writeInt(value:int):void 會將具有正負號的 32 位元整數寫入位元組串流。	ByteArray
		writeMultiByte(value:String, charSet:String):void 會使用指定的字元集，將多位元組字串寫入位元組串流。	ByteArray
		writeObject(object:*):void 會使用 AMF 序列化格式，將物件寫入位元組陣列。	ByteArray
		writeShort(value:int):void 會將 16 位元整數寫入位元組串流。	ByteArray
		writeUnsignedInt(value:uint):void 會將無正負號的 32 位元整數寫入位元組串流。	ByteArray
		writeUTF(value:String):void 會將 UTF-8 字串寫入位元組串流。	ByteArray
		writeUTFBytes(value:String):void 會將 UTF-8 字串寫入位元組串流。	ByteArray

屬性詳細資訊

bytesAvailable

屬性

bytesAvailable:uint [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

可從位元組陣列中的目前位置讀取到陣列結尾之資料的位元組數。

每次存取 ByteArray 物件時，將 bytesAvailable 屬性搭配讀取方法一起使用，即可確保會讀取到有效的資料。

實作
public function get bytesAvailable():uint

defaultObjectEncoding

屬性

defaultObjectEncoding:uint

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

代表針對 ByteArray 類別加以編碼的預設物件，以便用於新的 ByteArray 實體。當您建立新的 ByteArray 實體時，該實體上的編碼會以 defaultObjectEncoding 的值開始。 defaultObjectEncoding 屬性會初始化為 ObjectEncoding.AMF3。

從二進位資料寫入或讀取物件時，會使用 objectEncoding 值來決定應該使用 ActionScript 3.0、ActionScript2.0 或 ActionScript 1.0 格式。此值是來自於 ObjectEncoding 類別的常數。

實作
public static function get defaultObjectEncoding():uint
public static function set defaultObjectEncoding(value:uint):void

endian

屬性

endian:String

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

變更或讀取資料的位元組順序，可能是 Endian.BIG_ENDIAN 或 Endian.LITTLE_ENDIAN。預設值為 BIG_ENDIAN。

實作
public function get endian():String
public function set endian(value:String):void

相關 API 元素

Endian 類別

length

屬性

length:uint

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

ByteArray 物件的長度，以位元組為單位。

如果長度設定為大於目前長度的值，便會在位元組陣列右側填入零。

如果長度設定為小於目前長度的值，位元組陣列便會被截斷。

實作
public function get length():uint
public function set length(value:uint):void

objectEncoding

屬性

objectEncoding:uint

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

用來決定在從 ByteArray 實體寫入或讀取資料時，應該使用 ActionScript 3.0、ActionScript 2.0 還是 ActionScript 1.0 格式。此值是來自於 ObjectEncoding 類別的常數。

實作
public function get objectEncoding():uint
public function set objectEncoding(value:uint):void

position

屬性

position:uint

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會將 ByteArray 物件的檔案指標移動或返回到目前的位置 (以位元組為單位)。這是下一次呼叫讀取方法開始讀取，或是呼叫寫入方法開始寫入的點。

實作
public function get position():uint
public function set position(value:uint):void

shareable

屬性

shareable:Boolean

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11.5, AIR 3.5

指定位元組陣列的基礎記憶體是否為「可共用」。對於可共用的位元組陣列，所有 Worker 中參考位元組陣列的所有 ByteArray 實體會使用相同的基礎記憶體。預設值為 false，指出基礎記憶體並未在 Worker 間共用。

這個屬性也會影響執行階段如何處理這個位元組陣列 (如果它是使用 Worker.setSharedProperty() 方法或 MessageChannel.send() 方法傳遞至 Worker)：

不可共用：如果這個屬性是 false，當位元組陣列傳遞至 Worker 時，執行階段就會建立位元組陣列的完整複本，包括配置記憶體的子片段，以便在其中儲存重複的位元組陣列內容
可共用：如果這個屬性是 true，當位元組陣列傳遞至 Worker 時，執行階段就會針對原始 ByteArray 實體與為第二個 Worker 建立的新 ByteArray 實體兩者的內容，使用與儲存緩衝區相同的基礎記憶體。在本質上，兩個 ByteArray 實體都包含相同基礎位元組陣列的參考。

同時從多個 Worker 存取共用位元組陣列的能力，可能會造成不想要的情形，例如兩個 Worker 同時操作位元組陣列的基礎記憶體。您可以使用數種機制來控制共用記憶體的存取：

ByteArray 類別的 atomicCompareAndSwapIntAt() 和 atomicCompareAndSwapLength() 方法所提供的比較後替換機制
Mutex 和 Condition 類別 (在 flash.concurrent 套件中) 所使用的專用機制

將這個屬性設定為 true 只會影響用來將這個位元組陣列傳遞至 Worker 的後續程式碼。任何已經傳遞至 Worker 的位元組陣列版本，都會以個別版本的形式繼續存在。

如果您將這個屬性設定為 false，但先前為 true 時，位元組陣列的基礎記憶體就會立即複製到系統記憶體的新片段。從那之後，這個 ByteArray 實體就會使用新的基礎記憶體。因此，這個位元組陣列的基礎記憶體便不再與其他 Worker 共用，即使先前共用過。如果您之後將這個位元組陣列傳遞至 Worker，則會複製它的基礎記憶體，就像任何 shareable 屬性為 false 的 ByteArray 物件一樣。

預設值為 false。

實作
public function get shareable():Boolean
public function set shareable(value:Boolean):void

建構函式詳細資料

()

建構函式

public function ByteArray()

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會建立代表位元組之封裝陣列的 ByteArray 實體，如此您便可以使用此類別中的方法和屬性，讓資料的儲存與串流最佳化。

方法詳細資訊

atomicCompareAndSwapIntAt

()

方法

public function atomicCompareAndSwapIntAt(byteIndex:int, expectedValue:int, newValue:int):int

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11.5, AIR 3.5

在單一不可分割的作業中，請比較這個位元組陣列中的整數值與其他整數值，如果相符，請將那些位元組替換為其他值。

這個方法的用途是要搭配其基礎記憶體在多個 Worker 之間共用的位元組陣列一起使用 (ByteArray 實體的 shareable 屬性為 true)。它會執行下列一連串步驟：

從 byteIndex 引數中指定的索引 (以位元組為單位) 開始，讀取這個位元組陣列中的整數值
比較這個位元組陣列中的實際值與 expectedValue 引數中所傳遞的值
如果兩個值相等，就會將 newValue 引數中的值寫入位元組陣列中 byteIndex 參數所指定的位置，並且傳回先前包含在那些位元組中的值 (步驟 1 中讀取的值)
或者，位元組陣列中的內容不會變更，並且方法會傳回從位元組陣列讀取到的實際值

所有步驟都是在一個不可分割的硬體交易中執行的。這可保證沒有其他 Worker 的作業會在比較後替換作業期間變更位元組陣列的內容。

參數

	`byteIndex:int` — 從中讀取要比較之整數的索引位置 (位元組)，以及將 `newValue` 值寫入其中的索引位置 (如果比較結果相符)。這個值必須是 4 的倍數。

	`expectedValue:int` — 應與位於指定索引的位元組陣列內容相符的值

	`newValue:int` — 取代位於指定索引的位元組陣列內容的新值 (如果比較結果相符)

傳回值

int — 如果比較結果相符，則為位於指定之位置的先前值，或者如果實際值與預期值不符，則為位元組陣列中的實際值

擲回值

ArgumentError — 因為 byteIndex 值不是 4 的倍數，或者它是負數

相關 API 元素

ByteArray.shareable 屬性
Worker 類別

atomicCompareAndSwapLength

()

方法

public function atomicCompareAndSwapLength(expectedLength:int, newLength:int):int

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11.5, AIR 3.5

在單一不可分割的作業中，請比較這個位元組陣列的長度與提供的值，如果相符，請變更這個位元組陣列的長度。

這個方法的用途是要搭配其基礎記憶體在多個 Worker 之間共用的位元組陣列一起使用 (ByteArray 實體的 shareable 屬性為 true)。它會執行下列作業：

讀取 ByteArray 實體的整數 length 屬性
將長度與 expectedLength 引數中傳遞的值相比較
如果兩個值相等，就會將位元組陣列的長度變更為以 newLength 參數傳遞的值，如此，可能會增加或縮減位元組陣列的大小
或者，不會變更位元組陣列

所有步驟都是在一個不可分割的硬體交易中執行的。這可保證沒有其他 Worker 的作業會在比較後調整大小作業期間變更位元組陣列的內容。

參數

	`expectedLength:int` — ByteArray 的預期 `length` 屬性值。如果指定的值與實際值相符，則會變更位元組陣列的長度。

	`newLength:int` — 位元組陣列的新長度值 (如果比較成功)

傳回值

int — ByteArray 的先前 length 值，無論是否已變更

相關 API 元素

ByteArray.shareable 屬性
Worker 類別

clear

()

方法

public function clear():void

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.5, Flash Lite 4

清除位元組陣列的內容，然後將 length 與 position 屬性重設為 0。呼叫此方法會明確地釋放 ByteArray 實體所佔用的記憶體。

compress

()

方法

public function compress(algorithm:String):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9

壓縮位元組陣列。壓縮整個位元組陣列。呼叫之後，ByteArray 的 length 屬性會設定為新的長度。 position 屬性設定為位元組陣列的結束。

請傳遞值 (定義於 CompressionAlgorithm 類別中) 做為 algorithm 參數，以指定壓縮演算法。支援的演算法包括下列：

zlib 壓縮資料格式於 http://www.ietf.org/rfc/rfc1950.txt 中說明。

deflate 壓縮演算法於 http://www.ietf.org/rfc/rfc1951.txt 中說明。

LZMA 壓縮演算法於 http://www.7-zip.org/7z.html 中說明。

有數種壓縮格式使用 deflate 壓縮演算法，如 zlib、gzip、一些 zip 實作等等。使用其中一個壓縮格式來壓縮資料時，除了儲存原始資料的壓縮版本之外，壓縮格式資料 (例如，.zip 檔) 還會包含中繼資料資訊。各種檔案格式中所含中繼資料類型的一些範例包含檔案名稱、檔案修改日期/時間、原始檔案大小、選擇性註解、總和檢查碼資料等等。

例如，在使用 zlib 演算法來壓縮 ByteArray 時，則產生的 ByteArray 會以特定格式結構化。有些位元組會包含有關壓縮資料的中繼資料，而有些位元組會包含原始 ByteArray 資料的實際壓縮版本。如 zlib 壓縮資料格式規格所定義，這些位元組 (即包含原始資料壓縮版本的部分) 是使用 deflate 演算法壓縮的。因此，這些位元組形同對原始 ByteArray 呼叫 compress(air.CompressionAlgorithm.DEFLATE) 之後的結果。不過，compress(air.不過，(CompressionAlgorithm.ZLIB) 的結果包含額外的中繼資料，而 compress(CompressionAlgorithm.DEFLATE) 的結果只包含原始 ByteArray 資料的壓縮版本而已。

若要使用 deflate 格式來壓縮特定格式 (如 gzip 或 zip) 的 ByteArray 實體資料，不能只呼叫 compress(CompressionAlgorithm.DEFLATE)。您必須依照壓縮格式規格，包括適當的中繼資料以及使用 deflate 格式所取得的壓縮資料，來建立結構化的 ByteArray。同樣的，若要對使用如 gzip 或 zip 等格式壓縮的資料進行解碼，不能只在該資料上呼叫 uncompress(CompressionAlgorithm.DEFLATE)。您必須先將中繼資料與壓縮資料分開，然後使用 deflate 格式，對壓縮資料進行解壓縮。

參數

algorithm:String (default = NaN) — 壓縮時使用的壓縮演算法。有效值定義為 CompressionAlgorithm 類別的常數。預設為使用 zlib 格式。呼叫 compress(CompressionAlgorithm.DEFLATE) 的效果如同呼叫 deflate() 方法。Flash Player 11.3 和 AIR 3.3 已新增對 LZMA 演算法的支援。您必須具備那些播放程式版本或更新版本，才能使用 LZMA 壓縮。

deflate

()

方法

public function deflate():void

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.5, Flash Lite 4

使用 deflate 壓縮演算法來壓縮位元組陣列。壓縮整個位元組陣列。

呼叫之後，ByteArray 的 length 屬性會設定為新的長度。 position 屬性設定為位元組陣列的結束。

deflate 壓縮演算法於 http://www.ietf.org/rfc/rfc1951.txt 中說明。

若要使用 deflate 格式來壓縮特定格式 (如 gzip 或 zip) 的 ByteArray 實體資料，不能只呼叫 deflate()。您必須依照壓縮格式規格，包括適當的中繼資料以及使用 deflate 格式所取得的壓縮資料，來建立結構化的 ByteArray。同樣的，若要對使用 gzip 或 zip 等格式壓縮的資料進行解碼，不能只對資料呼叫 inflate()。您必須先將中繼資料與壓縮資料分開，然後使用 deflate 格式，對壓縮資料進行解壓縮。

相關 API 元素

inflate()

inflate

()

方法

public function inflate():void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 10

使用 deflate 壓縮演算法來解壓縮位元組陣列。位元組陣列必須已經使用相同的演算法來壓縮。

呼叫之後，ByteArray 的 length 屬性會設定為新的長度。 position 屬性會設定為 0。

deflate 壓縮演算法於 http://www.ietf.org/rfc/rfc1951.txt 中說明。

若要對使用 deflate 壓縮演算法格式 (如 gzip 或 zip 格式) 壓縮的資料進行解碼，不能只對包含壓縮形式資料的 ByteArray 呼叫 inflate()。首先，您必須將以壓縮資料格式一部分的方式包含在內的中繼資料與實際壓縮資料分開。如需詳細資訊，請參閱 compress() 方法說明。

擲回值

IOError — 此資料並非有效的壓縮資料，不是以壓縮時所使用的相同壓縮演算法來壓縮。

相關 API 元素

deflate()

readBoolean

()

方法

public function readBoolean():Boolean

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組串流讀取 Boolean 值。會讀取單一位元組。若該位元組不為零，則會傳回 true；否則傳回 false。

傳回值

Boolean — 如果位元組不為零，則會傳回 true，否則會傳回 false。

擲回值

EOFError — 沒有足夠的資料可供讀取。

readByte

()

方法

public function readByte():int

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組串流讀取具有正負號的位元組。

傳回的值介於 -128 到 127 的範圍之間。

傳回值

int — 介於 -128 與 127 之間的整數。

擲回值

EOFError — 沒有足夠的資料可供讀取。

readBytes

()

方法

public function readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組串流讀取資料位元組的數目 (由 length 參數指定)。位元組會讀取入由 bytes 參數所指定的 ByteArray 物件，並從 offset 所指定的位置開始，將這些位元組寫入目的 ByteArray。

參數

	`bytes:ByteArray` — 要將資料讀入的 ByteArray 物件。

	`offset:uint` (default = `0`) — 應將所讀取資料寫入的 `bytes` 偏移量 (位置)。

	`length:uint` (default = `0`) — 要讀取的位元組數。預設值為 0，會讀取所有可用的資料。

擲回值

	`EOFError` — 沒有足夠的資料可供讀取。

	`RangeError` — 提供的偏移量加上長度後的值大於單位的最大值。

readDouble

()

方法

public function readDouble():Number

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組串流讀取 IEEE 754 雙精度 (64 位元) 浮點數。

傳回值

Number — 雙精度 (64 位元) 浮點數。

擲回值

EOFError — 沒有足夠的資料可供讀取。

readFloat

()

方法

public function readFloat():Number

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組串流讀取 IEEE 754 單精度 (32 位元) 浮點數。

傳回值

Number — 單精度 (32 位元) 浮點數。

擲回值

EOFError — 沒有足夠的資料可供讀取。

readInt

()

方法

public function readInt():int

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組串流讀取具有正負號的 32 位元整數。

傳回的值介於 -2147483648 到 2147483647 的範圍之間。

傳回值

int — 介於 -2147483648 與 2147483647 之間的 32 位元具有正負號整數。

擲回值

EOFError — 沒有足夠的資料可供讀取。

readMultiByte

()

方法

public function readMultiByte(length:uint, charSet:String):String

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會使用指定的字元集，從位元組串流讀取指定之長度的多位元組字串。

參數

	`length:uint` — 所要讀取之位元組串流的位元組數。

	`charSet:String` — 代表字元集之字串，該字元集用於解譯位元組。可能的字元集字串包括 `"shift-jis"`、`"cn-gb"`、`"iso-8859-1"`，以及其他等等。如需完整清單，請參閱「支援的字元集」。注意：如果目前的系統無法辨識 `charSet` 參數值，則應用程式會使用系統的預設字碼頁當做字元集。例如，`charSet` 參數的值 (如同在 `myTest.readMultiByte(22, "iso-8859-01")`) 使用 `01` 取代 `1` 在您的開發系統上可能是可行的，但在其他系統可能不可行。在其他系統上，應用程式將會使用系統的預設字碼頁。

傳回值

String — UTF-8 編碼字串。

擲回值

EOFError — 沒有足夠的資料可供讀取。

readObject

()

方法

public function readObject():*

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組陣列讀取物件，並以 AMF 序列化格式編碼。

傳回值

* — 已還原序列化的物件。

擲回值

EOFError — 沒有足夠的資料可供讀取。

相關 API 元素

flash.net.registerClassAlias()

readShort

()

方法

public function readShort():int

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組串流讀取具有正負號的 16 位元整數。

傳回的值介於 -32768 到 32767 的範圍之間。

傳回值

int — 介於 -32768 與 32767 之間的 16 位元具有正負號整數。

擲回值

EOFError — 沒有足夠的資料可供讀取。

readUnsignedByte

()

方法

public function readUnsignedByte():uint

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組串流讀取無正負號的位元組。

傳回的值介於 0 到 255 的範圍之間。

傳回值

uint — 介於 0 與 255 之間的 32 位元無正負號整數。

擲回值

EOFError — 沒有足夠的資料可供讀取。

readUnsignedInt

()

方法

public function readUnsignedInt():uint

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組串流讀取無正負號的 32 位元整數。

傳回的值介於 0 到 4294967295 的範圍之間。

傳回值

uint — 介於 0 與 4294967295 之間的 32 位元無正負號整數。

擲回值

EOFError — 沒有足夠的資料可供讀取。

readUnsignedShort

()

方法

public function readUnsignedShort():uint

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組串流讀取無正負號的 16 位元整數。

傳回的值介於 0 到 65535 的範圍之間。

傳回值

uint — 介於 0 與 65535 之間的 16 位元無正負號整數。

擲回值

EOFError — 沒有足夠的資料可供讀取。

readUTF

()

方法

public function readUTF():String

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組串流讀取 UTF-8 字串。會假定此字串的前置詞為無正負號的短整數，以指示以位元組為單位的長度。

傳回值

String — UTF-8 編碼字串。

擲回值

EOFError — 沒有足夠的資料可供讀取。

相關 API 元素

flash.utils.IDataInput.readUTF()

readUTFBytes

()

方法

public function readUTFBytes(length:uint):String

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從位元組串流讀取由 length 參數指定的 UTF-8 位元組序列，並傳回字串。

參數

length:uint — 無正負號的短整數，指出 UTF-8 位元組的長度。

傳回值

String — 字串，由指定之長度的 UTF-8 位元組所構成。

擲回值

EOFError — 沒有足夠的資料可供讀取。

toJSON

()

方法

public function toJSON(k:String):*

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 3, Flash Lite 4

提供可覆寫的方法，用於自訂 ByteArray 物件中值的 JSON 編碼。

JSON.stringify() 方法會在周遊的每個物件上尋找 toJSON() 方法。如果找到 toJSON() 方法，JSON.stringify() 就會在每次遇到值時呼叫方法，以便傳入與值配對的索引鍵。

ByteArray 提供的 toJSON() 預設實作只會傳回類別的名稱。由於任何 ByteArray 的內容都需要解譯，因此，想要將 ByteArray 物件匯出至 JSON 的用戶端必須提供自己的實作。提供的方式是，重新定義類別原型上的 toJSON() 方法。

toJSON() 方法可以傳回任何類型的值。如果傳回物件，stringify() 就會遞迴至該物件。如果 toJSON() 傳回字串，stringify() 不會遞迴，而是繼續它的周遊。

參數

k:String — JSON.stringify() 在這個物件周遊中所遇到索引鍵值配對的索引鍵

傳回值

* — 類別名稱字串。

相關 API 元素

Object
Object.prototype

toString

()

方法

public function toString():String

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會將位元組陣列轉換為字串。如果陣列中的資料是以 Unicode 位元組順序標記開始，應用程式在轉換為字串時便會遵循該標記。如果 System.useCodePage 設定為 true，應用程式便會在轉換時將陣列中的資料當成是目前系統字碼頁中的資料來處理。

傳回值

String — 位元組陣列的字串形式。

uncompress

()

方法

public function uncompress(algorithm:String):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會解壓縮位元組陣列。呼叫之後，ByteArray 的 length 屬性會設定為新的長度。 position 屬性會設定為 0。

位元組陣列必須已經使用與不壓縮相同的演算法來壓縮。請傳遞值 (定義於 CompressionAlgorithm 類別中) 做為 algorithm 參數，以指定不壓縮演算法。支援的演算法包括下列：

zlib 壓縮資料格式於 http://www.ietf.org/rfc/rfc1950.txt 中說明。

deflate 壓縮演算法於 http://www.ietf.org/rfc/rfc1951.txt 中說明。

LZMA 壓縮演算法於 http://www.7-zip.org/7z.html 中說明。

若要對使用 deflate 壓縮演算法 (如 gzip 或 zip 格式) 格式壓縮的資料進行解碼，不能只在包含壓縮形式資料的 ByteArray 上呼叫 uncompress(CompressionAlgorithm.DEFLATE)。首先，您必須將以壓縮資料格式一部分的方式包含在內的中繼資料與實際壓縮資料分開。如需詳細資訊，請參閱 compress() 方法說明。

參數

algorithm:String (default = NaN) — 解壓縮時使用的壓縮演算法。這必須是壓縮資料時所使用的相同壓縮演算法。有效值定義為 CompressionAlgorithm 類別的常數。預設為使用 zlib 格式。Flash Player 11.3 和 AIR 3.3 已新增對 LZMA 演算法的支援。您必須具備那些播放程式版本或更新版本，才能使用 LZMA。

擲回值

IOError — 此資料並非有效的壓縮資料，不是以壓縮時所使用的相同壓縮演算法來壓縮。

writeBoolean

()

方法

public function writeBoolean(value:Boolean):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會寫入 Boolean 值。會根據 value 參數寫入單一位元組；如果為 true 則為 1，如果為 false 則為 0。

參數

value:Boolean — Boolean 值，用以決定寫入的位元組。如果此參數為 true，此方法便會寫入 1；如果為 false，此方法便會寫入 0。

writeByte

()

方法

public function writeByte(value:int):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會將位元組寫入位元組串流。

會使用此參數的低 8 位元。會忽略高的 24 位元。

參數

value:int — 32 位元整數。會將低 8 位元寫入位元組串流中。

writeBytes

()

方法

public function writeBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會從指定的位元組陣列 bytes，將 length 個位元組的序列，從 offset (從零開始的索引) 個位元組之後寫入至位元組串流。

如果省略 length 參數，便會使用 0 的預設長度；從 offset 位置開始寫入整個緩衝區。如果也省略 offset 參數，便會寫入整個緩衝區。

如果 offset 或 length 超出範圍，這兩者便會固定至 bytes 陣列的開頭與結尾。

參數

	`bytes:ByteArray` — ByteArray 物件。

	`offset:uint` (default = `0`) — 從零開始的索引，指出要在陣列中開始寫入的位置。

	`length:uint` (default = `0`) — 無正負號的整數，指出要在緩衝區中寫入的長度。

writeDouble

()

方法

public function writeDouble(value:Number):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會將 IEEE 754 雙精度 (64 位元) 浮點數寫入位元組串流。

參數

value:Number — 雙精度 (64 位元) 浮點數。

writeFloat

()

方法

public function writeFloat(value:Number):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會將 IEEE 754 單精度 (32 位元) 浮點數寫入位元組串流。

參數

value:Number — 單精度 (32 位元) 浮點數。

writeInt

()

方法

public function writeInt(value:int):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會將具有正負號的 32 位元整數寫入位元組串流。

參數

value:int — 要寫入位元組串流的整數。

writeMultiByte

()

方法

public function writeMultiByte(value:String, charSet:String):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會使用指定的字元集，將多位元組字串寫入位元組串流。

參數

	`value:String` — 要寫入的字串值。

	`charSet:String` — 表示要使用之字元集的字串。可能的字元集字串包括 `"shift-jis"`、`"cn-gb"`、`"iso-8859-1"`，以及其他等等。如需完整清單，請參閱「支援的字元集」。

writeObject

()

方法

public function writeObject(object:*):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會使用 AMF 序列化格式，將物件寫入位元組陣列。

參數

object:* — 要序列化的物件。

相關 API 元素

flash.net.registerClassAlias()

writeShort

()

方法

public function writeShort(value:int):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會將 16 位元整數寫入位元組串流。會使用此參數的低 16 位元。會忽略高的 16 位元。

參數

value:int — 32 位元整數，其中低 16 位元會寫入位元組串流。

writeUnsignedInt

()

方法

public function writeUnsignedInt(value:uint):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會將無正負號的 32 位元整數寫入位元組串流。

參數

value:uint — 要寫入位元組串流的無正負號整數。

writeUTF

()

方法

public function writeUTF(value:String):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會將 UTF-8 字串寫入位元組串流。會先寫入 UTF-8 字串的長度 (以位元組為單位，16 位元整數)，後面緊接著表示字串之字元的位元組。

參數

value:String — 要寫入的字串值。

擲回值

RangeError — 如果長度大於 65535 的話。

writeUTFBytes

()

方法

public function writeUTFBytes(value:String):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會將 UTF-8 字串寫入位元組串流。類似 writeUTF() 方法，但是 writeUTFBytes() 不以 16 位元長度的字做為字串前置詞。

參數

value:String — 要寫入的字串值。

範例如何使用本範例

ByteArrayExample.as

下列範例會使用 ByteArrayExample 類別，將 Boolean 和 pi 的雙精度浮點表示法寫入到位元組陣列。這是透過下列步驟完成：

宣告新的 ByteArray 物件實體 byteArr。
寫入與 Boolean false 相等的位元組值，然後檢查長度並將它讀回。
寫入數學 pi 值的相等雙精度浮點值。
讀回寫入位元組陣列之九個位元組中的每一個位元組。

注意： 當針對某個位元組呼叫 trace() 時，它會列印儲存於位元組陣列中的相同十進位位元組值。

請注意程式碼區段會如何加入到結尾來檢查是否有檔案結尾錯誤，以確保不會讀取超過位元組串流結尾的資料。

package {
    import flash.display.Sprite;
    import flash.utils.ByteArray;
    import flash.errors.EOFError;

    public class ByteArrayExample extends Sprite {        
        public function ByteArrayExample() {
            var byteArr:ByteArray = new ByteArray();

            byteArr.writeBoolean(false);
            trace(byteArr.length);            // 1
            trace(byteArr[0]);            // 0

            byteArr.writeDouble(Math.PI);
            trace(byteArr.length);            // 9
            trace(byteArr[0]);            // 0
            trace(byteArr[1]);            // 64
            trace(byteArr[2]);            // 9
            trace(byteArr[3]);            // 33
            trace(byteArr[4]);            // 251
            trace(byteArr[5]);            // 84
            trace(byteArr[6]);            // 68
            trace(byteArr[7]);            // 45
            trace(byteArr[8]);            // 24
            
            byteArr.position = 0;

            try {
                trace(byteArr.readBoolean() == false); // true
            } 
            catch(e:EOFError) {
                trace(e);           // EOFError: Error #2030: End of file was encountered.
            }
            
            try {
                trace(byteArr.readDouble());        // 3.141592653589793
            }
            catch(e:EOFError) {
                trace(e);           // EOFError: Error #2030: End of file was encountered.
            }
            
            try {
                trace(byteArr.readDouble());
            } 
            catch(e:EOFError) {
                trace(e);            // EOFError: Error #2030: End of file was encountered.
            }
        }
    }
}

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

ByteArray - AS3

類別 x

bytesAvailable

defaultObjectEncoding

endian

length

objectEncoding

position

shareable

ByteArray

atomicCompareAndSwapIntAt

atomicCompareAndSwapLength

clear

compress

deflate

inflate

readBoolean

readByte

readBytes

readDouble

readFloat

readInt

readMultiByte

readObject

readShort

readUnsignedByte

readUnsignedInt

readUnsignedShort

readUTF

readUTFBytes

toJSON

toString

uncompress

writeBoolean

writeByte

writeBytes

writeDouble

writeFloat

writeInt

writeMultiByte

writeObject

writeShort

writeUnsignedInt

writeUTF

writeUTFBytes