FileStream

套件	flash.filesystem
類別	public class FileStream
繼承	FileStream EventDispatcher Object
實作	IDataInput, IDataOutput

執行階段版本:

AIR 1.0

FileStream 物件可用來讀取及寫入檔案。檔案可以藉由呼叫 open() 方法以同步方式開啟，或藉由呼叫 openAsync() 方法以非同步方式開啟。

以非同步方式開啟檔案的好處是當 Adobe AIR 在背景中執行讀取及寫入程序時，可以執行其他程式碼。以非同步方式開啟時，當作業進行時會傳送 progress 事件。

以同步方式所開啟之 File 物件的行為就像 ByteArray 物件；以非同步方式所開啟之檔案的行為就像 Socket 或 URLStream 物件。當 File 物件以同步方式開啟時，呼叫者會在基礎檔案中讀取或寫入要求的資料時暫停。以非同步方式開啟時，任何寫入串流的資料會立即進行緩衝，並在稍後寫入檔案。

無論以同步或非同步方式從檔案讀取，實際的讀取方法都是同步的。在這兩種案例中，都會讀取目前「可用」的資料。不同之處在於，以同步方式讀取時，所有資料隨時都可供使用，而以非同步方式讀取時，資料會隨著資料串流至讀取緩衝區而漸漸變得可用。無論如何，在目前時刻可以透過同步方式讀取的資料是由 bytesAvailable 屬性表示。

處理非同步輸入的應用程式通常會註冊 progress 事件，並在資料變得可用時藉由呼叫讀取方法使用資料。或者，應用程式也可以註冊 complete 事件等待所有資料可用，並在 complete 事件傳送時處理整個資料集。

公用屬性

隱藏繼承公用屬性

顯示繼承公用屬性

	屬性		定義自
		bytesAvailable : uint [唯讀] 會傳回可在輸入緩衝區中讀取之資料的位元組數。	FileStream
		constructor : Object 類別物件的參照或是特定物件實體的建構函數。	Object
		endian : String 資料的位元組順序，會是 Endian 類別的 BIG_ENDIAN 或 LITTLE_ENDIAN 常數。	FileStream
		objectEncoding : uint 指定當使用 readObject() 或 writeObject() 方法來寫入或讀取二進位資料時，要使用 AMF3 或 AMF0 格式。	FileStream
		position : Number 檔案中目前的位置。	FileStream
		readAhead : Number 非同步讀取檔案時，從磁碟讀取的最小資料量。	FileStream

公用方法

隱藏繼承公用方法

顯示繼承公用方法

	方法		定義自
		FileStream() 建立 FileStream 物件。	FileStream
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void 會在 EventDispatcher 物件註冊事件偵聽程式，以便讓偵聽程式收到事件的通知。	EventDispatcher
		close():void 關閉 FileStream 物件。	FileStream
		dispatchEvent(event:Event):Boolean 會將事件傳送到事件流程。	EventDispatcher
		hasEventListener(type:String):Boolean 會檢查 EventDispatcher 物件是否有對特定的事件類型註冊偵聽程式。	EventDispatcher
		hasOwnProperty(name:String):Boolean 指出物件是否有已定義的指定屬性。	Object
		isPrototypeOf(theClass:Object):Boolean 指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。	Object
		open(file:File, fileMode:String):void 以同步方式開啟 FileStream 物件，並指向 file 參數所指定的檔案。	FileStream
		openAsync(file:File, fileMode:String):void 以非同步方式開啟 FileStream 物件，並指向 file 參數所指定的檔案。	FileStream
		propertyIsEnumerable(name:String):Boolean 指出指定的屬性是否存在，以及是否可列舉。	Object
		readBoolean():Boolean 會從檔案串流、位元組串流或位元組陣列讀取 Boolean 值。	FileStream
		readByte():int 會從檔案串流、位元組串流或位元組陣列讀取具有正負號的位元組。	FileStream
		readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void 從檔案串流、位元組串流或位元組陣列，讀取 length 參數所指定的資料位元組數目。	FileStream
		readDouble():Number 會從檔案串流、位元組串流或位元組陣列讀取 IEEE 754 雙精度浮點數。	FileStream
		readFloat():Number 會從檔案串流、位元組串流或位元組陣列讀取 IEEE 754 單精度浮點數。	FileStream
		readInt():int 會從檔案串流、位元組串流或位元組陣列讀取具有正負號的 32 位元整數。	FileStream
		readMultiByte(length:uint, charSet:String):String 使用指定的字元集，從檔案串流、位元組串流或位元組陣列讀取指定長度的多位元組字串。	FileStream
		readObject():* 從檔案串流、位元組串流或位元組陣列讀取物件並以 AMF 序列化格式編碼。	FileStream
		readShort():int 會從檔案串流、位元組串流或位元組陣列讀取具有正負號的 16 位元整數。	FileStream
		readUnsignedByte():uint 會從檔案串流、位元組串流或位元組陣列讀取無正負號的位元組。	FileStream
		readUnsignedInt():uint 會從檔案串流、位元組串流或位元組陣列讀取無正負號的 32 位元整數。	FileStream
		readUnsignedShort():uint 會從檔案串流、位元組串流或位元組陣列讀取無正負號的 16 位元整數。	FileStream
		readUTF():String 從檔案串流、位元組串流或位元組陣列讀取 UTF-8 字串。	FileStream
		readUTFBytes(length:uint):String 從位元組串流或位元組陣列讀取 UTF-8 位元組的序列，並傳回字串。	FileStream
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void 會從 EventDispatcher 物件移除偵聽程式。	EventDispatcher
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 為迴圈作業設定動態屬性的可用性。	Object
		toLocaleString():String 傳回代表此物件的字串，根據地區特定慣例進行格式化。	Object
		toString():String 會傳回指定之物件的字串形式。	Object
		truncate():void 在 FileStream 物件的 position 屬性所指定的位置上截斷檔案。	FileStream
		valueOf():Object 會傳回指定之物件的基本值。	Object
		willTrigger(type:String):Boolean 檢查此 EventDispatcher 物件是否已註冊事件偵聽程式，或者此物件的任何祖系已為特定事件類型註冊事件偵聽程式。	EventDispatcher
		writeBoolean(value:Boolean):void 會寫入 Boolean 值。	FileStream
		writeByte(value:int):void 會寫入位元組。	FileStream
		writeBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void 以 length 指定的長度，從指定的位元組陣列 bytes，將位元組序列從 offset 所指定的位元組 (使用從零開始的索引) 開始寫入檔案串流、位元組串流或位元組陣列。	FileStream
		writeDouble(value:Number):void 會寫入 IEEE 754 雙精度 (64 位元) 浮點數。	FileStream
		writeFloat(value:Number):void 會寫入 IEEE 754 單精度 (32 位元) 浮點數。	FileStream
		writeInt(value:int):void 會寫入 32 位元的具有正負號整數。	FileStream
		writeMultiByte(value:String, charSet:String):void 使用指定的字元集，將多位元組字串寫入檔案串流、位元組串流或位元組陣列。	FileStream
		writeObject(object:*):void 使用 AMF 序列化格式，將物件寫入檔案串流、位元組串流或位元組陣列。	FileStream
		writeShort(value:int):void 會寫入 16 位元整數。	FileStream
		writeUnsignedInt(value:uint):void 會寫入 32 位元的無正負號整數。	FileStream
		writeUTF(value:String):void 將 UTF-8 字串寫入檔案串流、位元組串流或位元組陣列。	FileStream
		writeUTFBytes(value:String):void 會寫入 UTF-8 字串。	FileStream

事件

按一下以瞭解事件的詳細資訊

隱藏繼承事件

顯示繼承事件

	摘要	定義自
activate	[廣播事件] 當 Flash Player 或 AIR 應用程式取得作業系統焦點並成為作用中時傳送。	EventDispatcher
close	表示已藉由明確呼叫 close() 方法關閉串流。	FileStream
complete	指出已到達串流結尾。	FileStream
deactivate	[廣播事件] 當 Flash Player 或 AIR 應用程式失去作業系統焦點並成為非作用中時傳送。	EventDispatcher
ioError	表示非同步檔案 I/O 作業期間發生錯誤。	FileStream
outputProgress	指出緩衝資料已寫入檔案。	FileStream
progress	指出串流上新資料的可用性。	FileStream

屬性詳細資訊

bytesAvailable

屬性

bytesAvailable:uint [唯讀]

執行階段版本:

AIR 1.0

會傳回可在輸入緩衝區中讀取之資料的位元組數。使用者程式碼必須呼叫 bytesAvailable，確定在嘗試以其中一種讀取方法進行讀取之前，具有足夠的資料。

實作
public function get bytesAvailable():uint

endian

屬性

endian:String

執行階段版本:

AIR 1.0

資料的位元組順序，會是 Endian 類別的 BIG_ENDIAN 或 LITTLE_ENDIAN 常數。

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

objectEncoding

屬性

objectEncoding:uint

執行階段版本:

AIR 1.0

指定當使用 readObject() 或 writeObject() 方法來寫入或讀取二進位資料時，要使用 AMF3 或 AMF0 格式。

此值是來自於 ObjectEncoding 類別的常數。根據預設會使用 AMF3 格式。

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

position

屬性

position:Number

執行階段版本:

AIR 1.0

檔案中目前的位置。

以下列任何方式修改此值：

當您明確設定屬性時
當讀取 FileStream 物件時 (使用其中一個讀取方法)
當寫入 FileStream 物件時

位置定義為 Number (而非單位)，以便支援大於 2³² 位元組長度的檔案。這個屬性的值一定是小於 2⁵³ 的整數。如果您將此值設定為分數，則會將值無條件捨去為最接近的整數。

以非同步方式讀取檔案時，如果您設定 position 屬性，則應用程式會以指定位置開始的資料來開始填滿讀取緩衝區，而且 bytesAvailable 屬性可以設定為 0。請等待 complete 事件出現，接著使用讀取方法讀取資料，或是等待 progress 事件並檢查 bytesAvailable 屬性，才使用讀取方法。

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

範例 ( 如何使用本範例 )

下列程式碼示範 FileStream 物件的 position 屬性如何隨著應用程式從檔案讀取資料而更新。

import flash.fileSystem.*;
import flash.utils.ByteArray;
import flash.events.Event;

var sourceFile:File = File.documentsDirectory.resolvePath("Apollo Test/test.txt");
var stream:FileStream = new FileStream();
stream.addEventListener(Event.COMPLETE, readBytes);
stream.openAsync(sourceFile, FileMode.READ);

function readBytes(e:Event):void {
    var bytes:ByteArray = new ByteArray();
    trace("position 0:", stream.position); // 0
    bytes[0] = stream.readByte();
    trace("position 1:", stream.position); // 1
    fileStream.readBytes(bytes, stream.position, 4); 
    trace("position 2:", stream.position); // 5
    stream.close();
}

readAhead

屬性

readAhead:Number

執行階段版本:

AIR 1.0

非同步讀取檔案時，從磁碟讀取的最小資料量。

這個屬性會指定非同步串流嘗試從目前位置開始讀取的資料量。會根據檔案系統分頁大小，以區塊方式讀取資料。因此，若在 8KB (8192 位元組) 的電腦系統上將 readAhead 設定為 9,000，執行階段每次會預先讀取 2 個區塊，亦即 16384 個位元組。這個屬性的預設值為 infinity：根據預設，以非同步方式開啟並進行讀取的檔案會一直讀取至檔案結尾。

從讀取緩衝區中讀取資料，不會變更 readAhead 屬性值。當您從緩衝區中讀取資料時，會讀取新資料以重新填滿讀取緩衝區。

readAhead 屬性對以同步方式開啟的檔案沒有作用。

以非同步方式讀取資料時，FileStream 物件會傳送 progress 事件。在 progress 事件的事件處理常式方法中，檢查是否有所需的位元組數 (藉由檢查 bytesAvailable 屬性)，然後使用讀取方法從讀取緩衝區中讀取資料。

實作
public function get readAhead():Number
public function set readAhead(value:Number):void

範例 ( 如何使用本範例 )

下列程式碼示範如何使用 readAhead 屬性將讀入檔案中的資料量限制為 100 個位元組：

import flash.filesystem.*;

var file:File = File.desktopDirectory.resolvePath("test.txt");
var fileStream:FileStream = new FileStream();
fileStream.readAhead = 100;
fileStream.addEventListener(ProgressEvent.PROGRESS, readProgressHandler)
fileStream.openAsync(file, FileMode.READ);
var results:ByteArray;

function readProgressHandler(event:ProgressEvent):void {
    if (fileStream.bytesAvailable >= 100) {
        fileStream.readBytes(results, 0, 100);
    }
}

建構函式詳細資料

()

建構函式

public function FileStream()

執行階段版本:

AIR 1.0

建立 FileStream 物件。使用 open() 或 openAsync() 方法開啟檔案。

相關 API 元素

open()
openAsync()

方法詳細資訊

close

()

方法

public function close():void

執行階段版本:

AIR 1.0

關閉 FileStream 物件。

在呼叫 close() 方法之後，您就無法讀取或寫入任何資料。如果檔案以非同步方式開啟 (FileStream 物件使用 openAsync() 方法開啟檔案)，則呼叫 close() 方法會使物件傳送 close 事件。

自動關閉應用程式，也會關閉應用程式中與 FileStream 物件關聯的所有檔案。不過，在以非同步開啟且有待寫入資料的所有 FileStream 物件上，最好註冊 closed 事件，然後再關閉應用程式 (以確保資料寫入)。

您可以藉由呼叫 open() 或 openAsync() 方法重複使用 FileStream 物件。這會關閉與 FileStream 物件關聯的任何檔案，但物件不會傳送 close 事件。

針對以非同步方式開啟的 FileStream 物件 (使用 openAsync() 方法)，即使您為 FileStream 物件呼叫 close() 事件並刪除參考該物件的屬性和變數，只要有待處理的作業和待完成的已註冊事件處理常式，FileStream 物件就不會進行記憶體回收。尤其在下列任何狀況下，未參考的 FileStream 物件仍會存在：

在檔案讀取作業中，尚未到達檔案結尾 (而且尚未傳送 complete 事件)。
仍有要寫入的輸出資料，而且輸出相關事件 (如 outputProgress 事件或 ioError 事件) 有已註冊的事件偵聽程式。

事件

close:Event — 以非同步方式開啟的檔案已關閉。

相關 API 元素

open()
close 事件

範例 ( 如何使用本範例 )

下列程式碼會以「非同步」方式開啟 FileStream 物件，並將一個名為 test.txt 的文字檔寫入使用者文件目錄的 Apollo Test 子目錄中。呼叫 FileStream 物件的 close() 方法，會在資料寫入後關閉檔案。

import flash.filesystem.*;
import flash.events.Event;
            
var file:File = File.documentsDirectory;
file = file.resolvePath("Apollo Test/test.txt");
var fileStream:FileStream = new FileStream();
fileStream.openAsync(file, FileMode.WRITE);
fileStream.writeUTFBytes("Hello");
fileStream.addEventListener(Event.CLOSE, fileClosed);
fileStream.close();

function fileClosed(event:Event):void {
    trace("closed");
}

下列程式碼會以「同步」方式開啟 FileStream 物件，並將一個名為 test.txt 的文字檔寫入使用者文件目錄的 Apollo Test 子目錄中。呼叫 FileStream 物件的 close() 方法，會在資料寫入後關閉檔案。

import flash.filesystem.*;
            
var file:File = File.documentsDirectory;
file = file.resolvePath("Apollo Test/test.txt");
var fileStream:FileStream = new FileStream();
fileStream.open(file, FileMode.WRITE);
fileStream.writeUTF("Hello");
fileStream.close();

open

()

方法

public function open(file:File, fileMode:String):void

執行階段版本:

AIR 1.0

以同步方式開啟 FileStream 物件，並指向 file 參數所指定的檔案。

如果 FileStream 物件已開啟，則呼叫此方法會在開啟之前先關閉檔案，而且不會針對先前開啟的檔案傳送進一步的事件 (包括 close)。

在支援檔案鎖定的系統上，以「寫入」或「更新」模式 (FileMode.WRITE 或 FileMode.UPDATE) 開啟的檔案在關閉之前是不可讀取的。

一旦您完成對檔案執行的作業，請呼叫 FileStream 物件的 close() 方法。某些作業系統會限制可同時開啟的檔案數量。

參數

	`file:File` — 指定要開啟之檔案的 File 物件。

	`fileMode:String` — FileMode 類別中定義 FileStream 功能 (如讀取或寫入檔案的能力) 的字串。

擲回值

	`IOError` — 檔案不存在；您沒有開啟檔案的適當權限；您開啟檔案來進行讀取存取，卻沒有讀取權限；或是您開啟檔案來進行寫入存取，卻沒有寫入權限。

	`SecurityError` — 檔案位置位於應用程式目錄中，而且 `fileMode` 參數設定為「附加」、「更新」或「寫入」模式。

相關 API 元素

close()
File
FileMode

範例 ( 如何使用本範例 )

下列程式碼示範如何以同步方式開啟使用者文件目錄 Apollo Test 子目錄中的 test.txt 檔案，然後使用系統字元集做為文字編碼，將檔案讀入字串。

import flash.filesystem.*;

var file:File = File.documentsDirectory;
file = file.resolvePath("Apollo Test/test.txt");
var fileStream:FileStream = new FileStream();
fileStream.open(file, FileMode.READ);
var str:String = fileStream.readMultiByte(file.size, File.systemCharset);
trace(str);
fileStream.close();

openAsync

()

方法

public function openAsync(file:File, fileMode:String):void

執行階段版本:

AIR 1.0

以非同步方式開啟 FileStream 物件，並指向 file 參數所指定的檔案。

如果 FileStream 物件已開啟，則呼叫此方法會在開啟之前先關閉檔案，而且不會針對先前開啟的檔案傳送進一步的事件 (包括 close)。

如果 fileMode 參數設定為 FileMode.READ 或 FileMode.UPDATE，一旦檔案開啟，AIR 就會將資料讀入輸入緩衝區，而且在資料讀入輸入緩衝區時會傳送 progress 和 open 事件。

在支援檔案鎖定的系統上，以「寫入」或「更新」模式 (FileMode.WRITE 或 FileMode.UPDATE) 開啟的檔案在關閉之前是不可讀取的。

一旦您完成對檔案執行的作業，請呼叫 FileStream 物件的 close() 方法。某些作業系統會限制可同時開啟的檔案數量。

參數

	`file:File` — 指定要開啟之檔案的 File 物件。

	`fileMode:String` — FileMode 類別中定義 FileStream 功能 (如讀取或寫入檔案的能力) 的字串。

事件

	`ioError:IOErrorEvent` — 檔案不存在；您沒有開啟檔案的適當權限；您開啟檔案來進行讀取存取，卻沒有讀取權限；或是您開啟檔案來進行寫入存取，卻沒有寫入權限。

	`progress:ProgressEvent` — 當資料讀入輸入緩衝區時傳送 (檔案必須以設定為 `FileMode.READ` 或 `FileMode.UPDATE` 的 `fileMode` 參數開啟。)

	`complete:Event` — 檔案資料已讀入輸入緩衝區。(檔案必須以設定為 `FileMode.READ` 或 `FileMode.UPDATE` 的 `fileMode` 參數開啟。)

擲回值

SecurityError — 檔案位置位於應用程式目錄中，而且 fileMode 參數設定為「附加」、「更新」或「寫入」模式。

範例 ( 如何使用本範例 )

下列程式碼示範如何以非同步方式開啟使用者文件目錄 Apollo Test 子目錄中的 test.txt 檔案，然後使用系統字元集做為文字編碼，將檔案讀入字串。

import flash.filesystem.*;
import flash.events.Event;

var file:File = File.documentsDirectory;
file = file.resolvePath("Apollo Test/test.txt");
var fileStream:FileStream = new FileStream();
fileStream.addEventListener(Event.COMPLETE, fileCompleteHandler)
fileStream.openAsync(file, FileMode.READ);

function fileCompleteHandler(event:Event):void {
    var str:String = fileStream.readMultiByte(fileStream.bytesAvailable, File.systemCharset);
    trace(str);
    fileStream.close();
}

readBoolean

()

方法

public function readBoolean():Boolean

執行階段版本:

AIR 1.0

會從檔案串流、位元組串流或位元組陣列讀取 Boolean 值。讀取單一位元組。若該位元組不為零，即傳回 true，否則傳回 false。

傳回值

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

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

readByte

()

方法

public function readByte():int

執行階段版本:

AIR 1.0

會從檔案串流、位元組串流或位元組陣列讀取具有正負號的位元組。

傳回值

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

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

readBytes

()

方法

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

執行階段版本:

AIR 1.0

從檔案串流、位元組串流或位元組陣列，讀取 length 參數所指定的資料位元組數目。這些位元組會讀入由 bytes 參數指定的 ByteArray 物件中，從 offset 所指定的位置開始。

參數

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

	`offset:uint` (default = `0`) — `bytes` 參數中的偏移值，資料讀取應該會在此處開始。

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

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

readDouble

()

方法

public function readDouble():Number

執行階段版本:

AIR 1.0

會從檔案串流、位元組串流或位元組陣列讀取 IEEE 754 雙精度浮點數。

傳回值

Number — IEEE 754 雙精度浮點數。

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

readFloat

()

方法

public function readFloat():Number

執行階段版本:

AIR 1.0

會從檔案串流、位元組串流或位元組陣列讀取 IEEE 754 單精度浮點數。

傳回值

Number — IEEE 754 單精度浮點數。

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

readInt

()

方法

public function readInt():int

執行階段版本:

AIR 1.0

會從檔案串流、位元組串流或位元組陣列讀取具有正負號的 32 位元整數。

傳回值

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

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

readMultiByte

()

方法

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

執行階段版本:

AIR 1.0

使用指定的字元集，從檔案串流、位元組串流或位元組陣列讀取指定長度的多位元組字串。

參數

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

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

傳回值

String — UTF-8 編碼字串。

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

相關 API 元素

File.systemCharset

readObject

()

方法

public function readObject():*

執行階段版本:

AIR 1.0

從檔案串流、位元組串流或位元組陣列讀取物件並以 AMF 序列化格式編碼。

傳回值

* — 經過還原序列化的物件

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

相關 API 元素

flash.net.registerClassAlias()

readShort

()

方法

public function readShort():int

執行階段版本:

AIR 1.0

會從檔案串流、位元組串流或位元組陣列讀取具有正負號的 16 位元整數。

傳回值

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

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

readUnsignedByte

()

方法

public function readUnsignedByte():uint

執行階段版本:

AIR 1.0

會從檔案串流、位元組串流或位元組陣列讀取無正負號的位元組。

傳回值

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

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

readUnsignedInt

()

方法

public function readUnsignedInt():uint

執行階段版本:

AIR 1.0

會從檔案串流、位元組串流或位元組陣列讀取無正負號的 32 位元整數。

傳回值

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

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

readUnsignedShort

()

方法

public function readUnsignedShort():uint

執行階段版本:

AIR 1.0

會從檔案串流、位元組串流或位元組陣列讀取無正負號的 16 位元整數。

傳回值

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

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

readUTF

()

方法

public function readUTF():String

執行階段版本:

AIR 1.0

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

這個方法類似於 Java^® IDataInput 介面的 readUTF() 方法。

傳回值

String — 以位元組表示之字元所產生的 UTF-8 字串。

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

readUTFBytes

()

方法

public function readUTFBytes(length:uint):String

執行階段版本:

AIR 1.0

從位元組串流或位元組陣列讀取 UTF-8 位元組的序列，並傳回字串。

參數

length:uint — 要讀取的位元組數。

傳回值

String — 指定之長度字元的位元組表示法所產生的 UTF-8 字串。

事件

ioError:IOErrorEvent — 檔案無法讀取或檔案未開啟。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用讀取功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法讀取 (例如，因為檔案遺失)。

	`EOFError` — 為讀取資料指定的位置超過可用的位元組數 (由 `bytesAvailable` 屬性指定)。

truncate

()

方法

public function truncate():void

執行階段版本:

AIR 1.0

在 FileStream 物件之 position 屬性所指定的位置上截斷檔案。

從 position 屬性所指定的位置到檔案結尾的位元組會被刪除。檔案必須開啟供寫入。

擲回值

IllegalOperationError — 檔案未開啟供寫入。

相關 API 元素

position

範例 ( 如何使用本範例 )

下列程式碼會以同步方式開啟使用者文件目錄 Apollo Test 子目錄中的 test.txt 檔案，而且如果檔案的長度超過 100 個字元，則會將檔案的長度修剪為 100 個字元。

import flash.filesystem.*;

var file:File = File.documentsDirectory;
file = file.resolvePath("Apollo Test/test.txt");
var fileStream:FileStream = new FileStream();
fileStream.open(file, FileMode.UPDATE);
if (file.size > 100) {
    fileStream.position = 100;
    fileStream.truncate();
}
fileStream.close();

下列程式碼會以「非同步」方式開啟使用者文件目錄 Apollo Test 子目錄中的 test.txt 檔案，而且如果檔案的長度超過 100 個字元，則會將檔案的長度修剪為 100 個字元。

var file:File = File.documentsDirectory;
file = file.resolvePath("Apollo Test/test.txt");
var fileStream:FileStream = new FileStream();
fileStream.openAsync(file, FileMode.UPDATE);
trace("start", file.size)
if (file.size > 100) {
    fileStream.position = 100;
    fileStream.truncate();
}
fileStream.addEventListener(Event.CLOSE, fileClosed);
fileStream.close();
function fileClosed(event:Event):void {
    trace("closed", file.size); 
}

writeBoolean

()

方法

public function writeBoolean(value:Boolean):void

執行階段版本:

AIR 1.0

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

參數

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

事件

ioError:IOErrorEvent — 您無法寫入檔案 (例如，因為檔案遺失)。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

IOError — 檔案尚未開啟；檔案已開啟，但未使用寫入功能來開啟；或者針對同步作業開啟的檔案 (使用 open() 方法)，檔案無法寫入 (例如，因為檔案遺失)。

writeByte

()

方法

public function writeByte(value:int):void

執行階段版本:

AIR 1.0

會寫入位元組。使用參數的較低 8 位元，而忽略其餘較高 24 位元。

參數

value:int — 整數的位元組值。

事件

ioError:IOErrorEvent — 您無法寫入檔案 (例如，因為檔案遺失)。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

writeBytes

()

方法

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

執行階段版本:

AIR 1.0

以 length 指定的長度，從指定的位元組陣列 bytes，將位元組序列從 offset 所指定的位元組 (使用從零開始的索引) 開始寫入檔案串流、位元組串流或位元組陣列。

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

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

參數

	`bytes:ByteArray` — 要寫入的位元組陣列。

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

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

事件

ioError:IOErrorEvent — 您無法寫入檔案 (例如，因為檔案遺失)。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

writeDouble

()

方法

public function writeDouble(value:Number):void

執行階段版本:

AIR 1.0

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

參數

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

事件

ioError:IOErrorEvent — 您無法寫入檔案 (例如，因為檔案遺失)。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

writeFloat

()

方法

public function writeFloat(value:Number):void

執行階段版本:

AIR 1.0

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

參數

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

事件

ioError:IOErrorEvent — 您無法寫入檔案 (例如，因為檔案遺失)。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

writeInt

()

方法

public function writeInt(value:int):void

執行階段版本:

AIR 1.0

會寫入 32 位元的具有正負號整數。

參數

value:int — 做為具有正負號整數的位元組值。

事件

ioError:IOErrorEvent — 您無法寫入檔案 (例如，因為檔案遺失)。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

writeMultiByte

()

方法

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

執行階段版本:

AIR 1.0

使用指定的字元集，將多位元組字串寫入檔案串流、位元組串流或位元組陣列。

參數

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

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

事件

ioError:IOErrorEvent — 您無法寫入檔案 (例如，因為檔案遺失)。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

相關 API 元素

File.systemCharset

writeObject

()

方法

public function writeObject(object:*):void

執行階段版本:

AIR 1.0

使用 AMF 序列化格式，將物件寫入檔案串流、位元組串流或位元組陣列。

參數

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

事件

ioError:IOErrorEvent — 您無法寫入檔案 (例如，因為檔案遺失)。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

相關 API 元素

flash.net.registerClassAlias()

writeShort

()

方法

public function writeShort(value:int):void

執行階段版本:

AIR 1.0

會寫入 16 位元整數。使用參數的較低 16 位元，而忽略其餘較高 16 位元。

參數

value:int — 整數的位元組值。

事件

ioError:IOErrorEvent — 您無法寫入檔案 (例如，因為檔案遺失)。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

writeUnsignedInt

()

方法

public function writeUnsignedInt(value:uint):void

執行階段版本:

AIR 1.0

會寫入 32 位元的無正負號整數。

參數

value:uint — 做為無正負號整數的位元組值。

事件

ioError:IOErrorEvent — 您無法寫入檔案 (例如，因為檔案遺失)。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

writeUTF

()

方法

public function writeUTF(value:String):void

執行階段版本:

AIR 1.0

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

參數

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

事件

ioError:IOErrorEvent — 您無法寫入檔案 (例如，因為檔案遺失)。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

	`RangeError` — 如果字串的長度大於 65535 個字元。

	`IOError` — 檔案尚未開啟；檔案已開啟，但未使用寫入功能來開啟；或者針對同步作業開啟的檔案 (使用 `open()` 方法)，檔案無法寫入 (例如，因為檔案遺失)。

writeUTFBytes

()

方法

public function writeUTFBytes(value:String):void

執行階段版本:

AIR 1.0

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

參數

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

事件

ioError:IOErrorEvent — 您無法寫入檔案 (例如，因為檔案遺失)。此事件只會針對開啟來進行非同步作業的檔案 (使用 openAsync() 方法) 傳送。

擲回值

事件詳細資訊

close

事件

事件物件類型: flash.events.Event
屬性 Event.type = flash.events.Event.CLOSE

執行階段版本:

AIR 1.0

表示已藉由明確呼叫 close() 方法關閉串流。

Event.CLOSE 常數會定義 close 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`target`	其連線已關閉的物件。

相關 API 元素

close()

complete

事件

事件物件類型: flash.events.Event
屬性 Event.type = flash.events.Event.COMPLETE

執行階段版本:

AIR 1.0

指出已到達串流結尾。

Event.COMPLETE 常數會定義 complete 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`target`	已完成載入的網路物件。

相關 API 元素

position

ioError

事件

事件物件類型: flash.events.IOErrorEvent
屬性 IOErrorEvent.type = flash.events.IOErrorEvent.IO_ERROR

執行階段版本:

AIR 1.0

表示非同步檔案 I/O 作業期間發生錯誤。

定義 ioError 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`errorID`	與特定錯誤相關聯的參考號碼 (僅限 AIR)。
`target`	遭遇輸入/輸出錯誤的網路物件。
`text`	要顯示為錯誤訊息的文字。

outputProgress

事件

事件物件類型: flash.events.OutputProgressEvent
屬性 OutputProgressEvent.type = flash.events.OutputProgressEvent.OUTPUT_PROGRESS

執行階段版本:

AIR 1.0

指出緩衝資料已寫入檔案。

定義 outputProgress 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`bytesPending`	在偵聽程式處理事件時，要寫入的剩餘位元組數。
`bytesTotal`	如果寫入程序成功，最後將會寫入的位元組總數。
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`target`	回報進度的 FileStream 物件。

progress

事件

事件物件類型: flash.events.ProgressEvent
屬性 ProgressEvent.type = flash.events.ProgressEvent.PROGRESS

執行階段版本:

AIR 1.0

指出串流上新資料的可用性。

定義 progress 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`bytesLoaded`	在偵聽程式處理事件時，載入的項目或位元組數目。
`bytesTotal`	如果載入程序成功時，最終將載入的項目或位元組總數。
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`target`	回報進度的物件。

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

FileStream - AS3

類別 x

bytesAvailable

endian

objectEncoding

position

readAhead

FileStream

close

open

openAsync

readBoolean

readByte

readBytes

readDouble

readFloat

readInt

readMultiByte

readObject

readShort

readUnsignedByte

readUnsignedInt

readUnsignedShort

readUTF

readUTFBytes

truncate

writeBoolean

writeByte

writeBytes

writeDouble

writeFloat

writeInt

writeMultiByte

writeObject

writeShort

writeUnsignedInt

writeUTF

writeUTFBytes

close

complete

ioError

outputProgress

progress