SharedObject - Adobe ActionScript® 3 (AS3 ) API 參考

套件	flash.net
類別	public class SharedObject
繼承	SharedObject EventDispatcher Object

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

您可以使用 SharedObject 類別，在使用者電腦或伺服器上讀取並儲存有限的資料量。共享物件會提供多個用戶端 SWF 檔和物件 (保存在本機電腦或遠端伺服器中) 之間的即時資料共享。本機共享物件與瀏覽器 Cookie 很類似，而遠端共享物件則與即時資料傳輸裝置很類似。若要使用遠端共享物件，您需要 Adobe Flash Media Server。

使用共享物件可執行下列動作：

維護本機持續性。這是使用共享物件最簡單的方法，而且不需要 Flash Media Server。例如，您可以呼叫 SharedObject.getLocal()，在應用程式中 (例如，具有記憶體的計算機) 建立共享物件。當使用者關閉此計算機時，Flash Player 就會將共享物件中的最後一個值儲存在使用者的電腦中。下次執行此計算機時，它就會包含先前儲存的值。或者，如果您在計算機應用程式關閉前將共享物件的屬性設定為 null，則下一次執行該應用程式時，應用程式便會以沒有任何值的方式開啟。維護本機存放的另一個範例，就是追蹤結構複雜之網站的使用者偏好設定或其他資料，例如使用者在新聞網站上讀取文章的記錄。您可以透過追蹤這項資訊，顯示已讀取的文章，以便與尚未閱讀的新文章做區分。將這個資訊儲存在使用者的電腦上，可以減少伺服器的負擔。
在 Flash Media Server 上儲存和共享資料。共享物件可以將資料儲存在伺服器上，供其他用戶端擷取。例如，呼叫 SharedObject.getRemote() 可建立持續在伺服器上的遠端共享物件 (例如電話清單)。每當用戶端變更共享物件時，目前與該物件連線或稍後連線的所有用戶端都可以使用修改過的資料。如果物件在本機也是持續的，而且用戶端在未連線到伺服器的情況下變更資料，則資料會在用戶端下一次連線到該物件時複製到遠端共享物件。
即時共享資料。共享物件可以在多重用戶端之間即時共享資料。例如，您可以開啟遠端共享物件，裡面儲存連線到該物件的所有用戶端都看得見的聊天室中目前連線的使用者清單。當使用者進入或離開聊天室時，就會更新此物件，而且連線至此物件的所有用戶端都能看到已變更的聊天室使用者清單。

若要建立本機共享物件，請呼叫 SharedObject.getLocal()。若要建立遠端共享物件，請呼叫 SharedObject.getRemote()。

應用程式關閉時，會將共享物件清除或寫入磁碟。您也可以呼叫 flush() 方法，將資料明確寫入磁碟。

本機磁碟空間考量。 本機共享物件有一些限制，是您在設計應用程式時必須加以考量的重點。有時候，SWF 檔可能會無法寫入本機共享物件，而有時候，儲存在本機共享物件的資料可能會在您不知情的情況下遭到刪除。 Flash Player 使用者可以管理在個別的網域或是所有網域中可用的磁碟空間。所以當使用者減少可用的磁碟空間時，可能會將某些本機共享物件刪除。 Flash Player 使用者也具有隱私權控制項，可用來避免協力廠商網域 (位於目前瀏覽器位址列以外的網域) 讀取或寫入本機共享物件。另請注意，從 AIR 3.3 開始，Mac OS 上本機共享物件的位置已變更，因此，如果您升級至 3.3 命名空間，可能看起來就像物件遺失了。

注意：在本機電腦上儲存和執行的 SWF 檔 (不是來自遠端伺服器) 可以隨時將協力廠商共享物件寫入磁碟。如需有關協力廠商共享物件的詳細資訊，請參閱 Flash Player「說明」中的全域儲存設定面板。

您最好檢查與磁碟空間和使用者隱私權控制相關的失敗。在呼叫 getLocal() 及 flush() 時執行這些檢查：

SharedObject.getLocal()—呼叫此方法失敗 (例如當使用者已停用協力廠商共享物件，而且 SWF 檔的網域與瀏覽器位址列中的網域不符) 時，Flash Player 就會擲回例外。
SharedObject.flush()—呼叫此方法失敗時，Flash Player 就會擲回例外。如果呼叫成功，它會傳回 SharedObjectFlushStatus.FLUSHED。需要額外的儲存空間時，則會傳回 SharedObjectFlushStatus.PENDING。 Flash Player 會提示使用者允許增加儲存空間，以便在本機儲存資料。之後便傳送 netStatus 事件，其中包含資訊物件，指出清除作業成功或失敗。

如果您的 SWF 檔嘗試建立或修改本機共享物件，請確定您的 SWF 檔至少具有 215 像素的寬度，以及至少 138 像素的高度，這也是顯示用來提示使用者增加其本機共享物件儲存區限制之對話方塊所需的最小尺寸。如果您的 SWF 檔小於這些尺寸，而且需要增加儲存限制，SharedObject.flush() 就會失敗，並傳回 SharedObjectFlushedStatus.PENDING 和傳送 netStatus 事件。

遠端共享物件： 使用 Flash Media Server，您可以建立和使用遠端共享物件，供連接到應用程式的所有用戶端即時共享。當一個用戶端變更遠端共享物件的屬性時，該屬性對所有連接的用戶端而言都已變更。您可以使用遠端共享物件讓用戶端 (例如多人遊戲中的玩家) 保持同步。

每個遠端共享物件都有一個 data 屬性，它是用屬性儲存資料的「物件」。呼叫 setProperty() 可變更資料物件的屬性。伺服器會更新屬性、傳送 sync 事件並將屬性傳回連接的用戶端。

您可以選擇將遠端共享物件設為持續存在用戶端或伺服器上，或兩者。根據預設，Flash Player 會儲存最大 100K 的本機持續遠端共享物件。當您嘗試儲存更大的物件時，Flash Player 會顯示「本機儲存」對話方塊，讓使用者能夠允許或拒絕於本機儲存共享物件。請確定您的「舞台」大小至少是 215 x 138 像素；這是 Flash 顯示對話方塊時要求的最小尺寸。

如果使用者選取「允許」，伺服器會儲存共享物件，並傳送 code 屬性為 SharedObject.Flush.Success 的 netStatus 事件。如果使用者選取「拒絕」，則伺服器不會儲存共享物件，而且會傳送 code 屬性為 SharedObject.Flush.Failed 的 netStatus 事件。

檢視範例

相關 API 元素

flush()
getLocal()
netStatus

公用屬性

隱藏繼承公用屬性

顯示繼承公用屬性

	屬性		定義自
		client : Object 指出要針對其叫用回呼方法的物件。	SharedObject
		constructor : Object 類別物件的參照或是特定物件實體的建構函數。	Object
		data : Object [唯讀] 指定給物件之 data 屬性的特質集合，您可以共享並儲存這些屬性。	SharedObject
		defaultObjectEncoding : uint [靜態] 在 SWF 檔中建立之所有本機共享物件的預設物件編碼 (AMF 版本)。	SharedObject
		fps : Number [唯寫] 會指定每秒將用戶端針對共享物件所做的變更傳送至伺服器的次數。	SharedObject
		objectEncoding : uint 此共享物件的物件編碼 (AMF 版本)。	SharedObject
		preventBackup : Boolean [靜態] 指定本機共享物件是否將備份到 iOS 雲端備份服務上。	SharedObject
		size : uint [唯讀] 共享物件的目前大小，以位元組為單位。	SharedObject

公用方法

隱藏繼承公用方法

顯示繼承公用方法

	方法		定義自
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void 會在 EventDispatcher 物件註冊事件偵聽程式，以便讓偵聽程式收到事件的通知。	EventDispatcher
		clear():void 會針對本機共享物件，清除所有資料並從磁碟中刪除共享物件。	SharedObject
		close():void 會關閉遠端共享物件與伺服器之間的連線。	SharedObject
		connect(myConnection:NetConnection, params:String = null):void 透過指定的 NetConnection 物件連線到伺服器上的遠端共享物件。	SharedObject
		dispatchEvent(event:Event):Boolean 會將事件傳送到事件流程。	EventDispatcher
		flush(minDiskSpace:int = 0):String 立即將本機上的持續共享物件寫到本機檔案中。	SharedObject
		getLocal(name:String, localPath:String = null, secure:Boolean = false):SharedObject [靜態] 傳回只有目前用戶端可使用的本機持續共享物件的參考。	SharedObject
		getRemote(name:String, remotePath:String = null, persistence:Object = false, secure:Boolean = false):SharedObject [靜態] 傳回 Flash Media Server 上多個用戶端可存取之共享物件的參考。	SharedObject
		hasEventListener(type:String):Boolean 會檢查 EventDispatcher 物件是否有對特定的事件類型註冊偵聽程式。	EventDispatcher
		hasOwnProperty(name:String):Boolean 指出物件是否有已定義的指定屬性。	Object
		isPrototypeOf(theClass:Object):Boolean 指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。	Object
		propertyIsEnumerable(name:String):Boolean 指出指定的屬性是否存在，以及是否可列舉。	Object
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void 會從 EventDispatcher 物件移除偵聽程式。	EventDispatcher
		send(... arguments):void 廣播訊息給連接到遠端共享物件的所有用戶端，包括原先傳送訊息的用戶端。	SharedObject
		setDirty(propertyName:String):void 向伺服器指出共享物件的屬性值已變更。	SharedObject
		setProperty(propertyName:String, value:Object = null):void 更新共享物件中的屬性值，並向伺服器指出，屬性值已變更。	SharedObject
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 為迴圈作業設定動態屬性的可用性。	Object
		toLocaleString():String 傳回代表此物件的字串，根據地區特定慣例進行格式化。	Object
		toString():String 會傳回指定之物件的字串形式。	Object
		valueOf():Object 會傳回指定之物件的基本值。	Object
		willTrigger(type:String):Boolean 檢查此 EventDispatcher 物件是否已註冊事件偵聽程式，或者此物件的任何祖系已為特定事件類型註冊事件偵聽程式。	EventDispatcher

事件

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

隱藏繼承事件

顯示繼承事件

	摘要	定義自
activate	[廣播事件] 當 Flash Player 或 AIR 應用程式取得作業系統焦點並成為作用中時傳送。	EventDispatcher
asyncError	會在以非同步方式 (亦即，從原生非同步程式碼) 擲出例外時傳送。	SharedObject
deactivate	[廣播事件] 當 Flash Player 或 AIR 應用程式失去作業系統焦點並成為非作用中時傳送。	EventDispatcher
netStatus	在 SharedObject 實體回報其狀態或錯誤情況時傳送。	SharedObject
sync	於伺服器更新遠端共享物件時傳送。	SharedObject

屬性詳細資訊

client

屬性

client:Object

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

指出要針對其叫用回呼方法的物件。預設物件為 this。您可以將 client 屬性設定為其他物件，然後就會針對該物件叫用回呼方法。

實作
public function get client():Object
public function set client(value:Object):void

擲回值

TypeError — client 屬性必須設定為非 null 物件。

data

屬性

data:Object [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

指定給物件之 data 屬性的特質集合，您可以共享並儲存這些屬性。每個特質都可以是任何 ActionScript 或 JavaScript 類型的物件：Array、Number、Boolean、ByteArray、XML 等等。例如，下列程式碼行會指定共享物件中的各類不同的值：

     var items_array:Array = new Array(101, 346, 483);
     var currentUserIsAdmin:Boolean = true;
     var currentUserName:String = "Ramona";
     
     var my_so:SharedObject = SharedObject.getLocal("superfoo");
     my_so.data.itemNumbers = items_array;
     my_so.data.adminPrivileges = currentUserIsAdmin;
     my_so.data.userName = currentUserName;
     
     for (var prop in my_so.data) {
       trace(prop+": "+my_so.data[prop]);
     }

如果物件是持續性的，則會儲存共享物件之 data 屬性的所有特質，而共享物件會包含下列資訊：

     userName: Ramona
     adminPrivileges: true
     itemNumbers: 101,346,483

注意：請不要像在 so.data = someValue 中一樣，將值直接指定給共享物件的 data 屬性，Flash Player 會忽略這些指定。

若需要刪除本機共享物件的特質，請使用如 delete so.data.attributeName 的程式碼；將本機共享物件特質設定為 null 或 undefined 則不會刪除特質。

若需要為共享物件建立「私用」值—也就是當使用物件時，只能讓用戶端實體使用，而在關閉時也不會和物件一起儲存的值—請建立名稱不是 data 的屬性來儲存它們，如下列範例所示：

     var my_so:SharedObject = SharedObject.getLocal("superfoo");
     my_so.favoriteColor = "blue";
     my_so.favoriteNightClub = "The Bluenote Tavern";
     my_so.favoriteSong = "My World is Blue";
     
     for (var prop in my_so) {
       trace(prop+": "+my_so[prop]);
     }

共享物件包含下列資料：

     favoriteSong: My World is Blue
     favoriteNightClub: The Bluenote Tavern
     favoriteColor: blue
     data: [object Object]

對於搭配伺服器一起使用的遠端共享物件，連接到該共享物件的所有用戶端都可以使用 data 屬性的所有特質，而且如果物件是持續物件，則所有特質都會儲存起來。如果一個用戶端變更某特質的值，所有用戶端都會立即看到新值。

實作
public function get data():Object

相關 API 元素

getLocal()

defaultObjectEncoding

屬性

defaultObjectEncoding:uint

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

在 SWF 檔中建立之所有本機共享物件的預設物件編碼 (AMF 版本)。當本機共享物件寫入磁碟時，SharedObject.defaultObjectEncoding 屬性就會指出應該使用哪個 Action Message Format 版本：ActionScript 3.0 格式 (AMF3) 或 ActionScript 1.0 或 2.0 格式 (AMF0)。

如需物件編碼的詳細資訊，包括本機和遠端共享物件編碼之間的差異，請參閱 objectEncoding 屬性的說明。

SharedObject.defaultObjectEncoding 的預設值會設定為使用 ActionScript 3.0 格式 (AMF3)。如果您想要寫入 ActionScript 2.0 或 1.0 SWF 檔可讀取的本機共享物件，請在建立任何本機共享物件之前，於指令碼的開頭將 SharedObject.defaultObjectEncoding 設定為使用 ActionScript 1.0 或 ActionScript 2.0 格式 flash.net.ObjectEncoding.AMF0。如此一來，之後建立的所有本機共享物件都會使用 AMF0 編碼，而且可以與舊版內容互動。在建立本機共享物件之後，您就無法透過設定 SharedObject.defaultObjectEncoding，變更現有本機共享物件的 objectEncoding 值。

若要根據每個物件 (而非針對 SWF 檔建立的所有共享物件) 設定物件編碼，請改為設定本機共享物件的 objectEncoding 屬性。

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

相關 API 元素

objectEncoding 屬性
ObjectEncoding 類別

fps

屬性

fps:Number [唯寫]

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會指定每秒將用戶端針對共享物件所做的變更傳送至伺服器的次數。

當您想要控制用戶端與伺服器之間的流量時，請使用此方法。例如，如果用戶端與伺服器之間的連線相當慢，您可能會想要將 fps 設定為較低的值。反之，如果將用戶端連線至多使用者應用程式。在該應用程式中，反應時間又特別重要，那麼您可能會想要將 fps 設定為較高的值。

設定 fps 將觸發 sync 事件並將所有的變更傳送至伺服器進行更新。如果您想自行更新伺服器，請將 fps 設定為 0。

在送出 sync 事件之前，並不會將變更傳送至伺服器。也就是說，如果伺服器的回應時間很慢，將更新傳送至伺服器的頻率會比此屬性中指定的值還低。

實作
public function set fps(value:Number):void

objectEncoding

屬性

objectEncoding:uint

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

此共享物件的物件編碼 (AMF 版本)。當本機共享物件寫入磁碟時，objectEncoding 屬性就會指出應該使用哪個 Action Message Format 版本：ActionScript 3.0 格式 (AMF3) 或 ActionScript 1.0 或 2.0 格式 (AMF0)。

物件編碼的處理方式會因共享物件是本機或遠端而不同。

本機共享物件：您可以取得或設定本機共享物件的 objectEncoding 屬性值。 objectEncoding 的值會影響「寫入」此本機共享物件所用的格式。如果此本機共享物件必須可讓 ActionScript 2.0 或 1.0 SWF 檔讀取，請將 objectEncoding 設定為 ObjectEncoding.AMF0。如此一來，即使物件編碼在撰寫時設定為 AMF3，Flash Player 仍然可以讀取 AMF0 本機共享物件。也就是說，如果使用此屬性的預設值 ObjectEncoding.AMF3，您的 SWF 檔仍然可以讀取由 ActionScript 2.0 或 1.0 SWF 檔建立的共享物件。
遠端共享物件：連線至伺服器時，遠端共享物件就會從相關聯的 NetConnection 實體 (用來連線至遠端共享物件的實體) 繼承其 objectEncoding 設定。未連線至伺服器時，遠端共享物件會從相關聯的 NetConnection 實體繼承 defaultObjectEncoding 設定。由於遠端共享物件的 objectEncoding 屬性值是由 NetConnection 實體所決定，因此遠端共享物件的這項屬性是唯讀的。

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

擲回值

ReferenceError — 您嘗試針對遠端共享物件設定 objectEncoding 屬性值。遠端共享物件的這項屬性是唯讀的，因為其值是由相關聯的 NetConnection 實體所決定。

preventBackup

屬性

preventBackup:Boolean

語言版本:

ActionScript 3.0

執行階段版本:

AIR 3.7

指定本機共享物件是否將備份到 iOS 雲端備份服務上。

指定 true 或 false：

true - 防止所有本機共享物件備份到 iOS 雲端備份服務上。
false (預設值) - 本機共享物件將備份到 iOS 雲端備份服務上。

這個屬性只適用於本機共享物件，並且僅供 iOS 使用。

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

size

屬性

size:uint [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

共享物件的目前大小，以位元組為單位。

Flash 會利用逐步執行其資料屬性的方式計算共享物件的大小；物件的屬性越多，它需要用來估計其大小的時間就越長。估計物件大小可能會花費許多處理時間，因此，除非您有特定的需要，否則請避免使用這個方法。

實作
public function get size():uint

範例 ( 如何使用本範例 )

下列程式碼會使用 id "thehobbit" 來建立 SharedObject 物件。並將名為 username 的屬性加入至 SharedObject 物件的資料屬性。然後，會追蹤 size 屬性，該屬性會傳回指定的值。


import flash.net.SharedObject;

// if these get copied or not
var mySo:SharedObject = SharedObject.getLocal("thehobbit");
mySo.data.username = "bilbobaggins";
trace(mySo.size); // 55

方法詳細資訊

clear

()

方法

public function clear():void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會針對本機共享物件，清除所有資料並從磁碟中刪除共享物件。共享物件的參照仍然會處於使用中狀態，不過會刪除其資料屬性。

對於搭配 Flash Media Server 一起使用的遠端共享物件，clear() 會使物件中斷連線，並清除所有資料。如果物件是本機持續共享物件，這個方法也會將共享物件從磁碟上刪除。共享物件的參照仍然會處於使用中狀態，不過會刪除其資料屬性。

範例 ( 如何使用本範例 )

下列程式碼將使用 hostName 的 id 值建立 (接著執行擷取) SharedObject 物件。並將名為 username 的屬性加入至 SharedObject 物件的資料屬性。最後呼叫 clear() 方法，清除已加入資料物件 (在這個範例中，就是單一屬性 username) 的全部資訊。


package {
    import flash.net.SharedObject;

    public class SharedObject_clear {
        private var hostName:String = "yourDomain";
        private var username:String = "yourUsername";

        public function SharedObject_clear() {
            var mySo:SharedObject = SharedObject.getLocal(hostName);
            if(mySo.data.username == null) {
                mySo.data.username = username;
                trace("set: " + mySo.data.username); // yourUsername
            }
            else {
                mySo.clear();
                trace("cleared: " + mySo.data.username); // undefined
            }
        }
    }
}

close

()

方法

public function close():void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會關閉遠端共享物件與伺服器之間的連線。如果遠端共享物件是本機存放，使用者就可以在呼叫此方法之後，對該物件的本機副本進行變更。下次使用者連線至遠端共享物件時，對本機物件所做的任何變更就會傳送至伺服器。

connect

()

方法

public function connect(myConnection:NetConnection, params:String = null):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

透過指定的 NetConnection 物件連線到伺服器上的遠端共享物件。請在呼叫 getRemote() 後使用這個方法。連線成功時，會傳送 sync 事件。

嘗試使用遠端共享物件前，應先檢查有無錯誤，請使用 try..catch..finally 陳述式。然後，偵聽和處理 sync 事件，之後再對共享物件進行變更。於本機進行的任何變更 (傳送 sync 事件之前) 可能會遺失。

呼叫 connect() 可連線到遠端共享物件，例如：

     var myRemoteSO:SharedObject = SharedObject.getRemote("mo", myNC.uri, false);
     myRemoteSO.connect(myNC);

參數

	`myConnection:NetConnection` — 使用 Real-Time Messaging Protocol (RTMP) 的 NetConnection 物件，例如用來與 Flash Media Server 進行通訊的 NetConnection 物件。

	`params:String` (default = `null`) — 字串，定義傳遞到伺服器上的遠端共享物件的訊息。無法搭配 Flash Media Server 一起使用。

擲回值

Error — Flash Player 無法連線至指定的遠端共享物件。請確認 NetConnection 實體有效且已連線，而且已經在伺服器上成功建立遠端共享物件。

flush

()

方法

public function flush(minDiskSpace:int = 0):String

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

立即將本機上的持續共享物件寫到本機檔案中。如果您不使用這個方法，則 Flash Player 會在共享物件工作階段結束時—亦即，當 SWF 檔關閉、當共享物件由於不再有任何參照而變成無意義字元，或者當您呼叫 SharedObject.clear() 或 SharedObject.close() 時，將共享物件寫入檔案中。

如果這個方法傳回 SharedObjectFlushStatus.PENDING，則 Flash Player 會顯示對話方塊，要求使用者增加這個網域的物件可用的磁碟空間量。若要讓共享物件在未來儲存時能夠增加空間，避免傳回 PENDING 值，請傳遞值做為 minDiskSpace 的值。當 Flash Player 嘗試寫入檔案時，它會尋找傳遞給 minDiskSpace 的位元組數目，而不會尋找剛好足夠儲存目前共享物件大小的空間。

例如，如果您預期共享物件會成長到 500 位元組的上限，即使一開始的數字可能會小很多，但還是請傳遞 500 給 minDiskSpace。如果 Flash 要求使用者配置共享物件的磁碟空間，它會要求 500 個位元組。在使用者配置所要求的空間量以後，Flash 不需要為了將來想要對齊物件而要求更大的空間 (只要空間大小不超過 500 個位元組)。

等使用者回應對話方塊後，重新呼叫一次這個方法。這時會傳送 netStatus 事件，其 code 屬性為 SharedObject.Flush.Success 或 SharedObject.Flush.Failed。

參數

minDiskSpace:int (default = 0) — 必須配置給此物件的最小磁碟空間，以位元組為單位。

傳回值

String — 下列任一值：

SharedObjectFlushStatus.PENDING：使用者已經允許這個網域的物件進行本機資訊儲存，但配置的空間量不足以儲存此物件。 Flash Player 會提示使用者預留更多空間。若要在儲存時預留空間，讓共享空間能夠成長，進而防止 SharedObjectFlushStatus.PENDING 傳回值，請傳遞值給 minDiskSpace。
SharedObjectFlushStatus.FLUSHED：共享物件已經成功寫入本機磁碟的檔案。

擲回值

Error — Flash Player 無法將共享物件寫入磁碟。如果使用者已永遠不允許此網域的物件進行本機資訊儲存，就可能會發生這項錯誤。

注意：本機內容一律可以將協力廠商網域 (不是目前瀏覽器網址列的網域) 的共享物件寫入磁碟，即使不允許使用協力廠商網域將共享物件寫入磁碟也是一樣。

相關 API 元素

clear()

範例 ( 如何使用本範例 )

下列程式碼將使用 hostName 的 id 值建立 (接著執行擷取) SharedObject 物件。並將名為 username 的屬性加入至 SharedObject 物件的資料屬性。然後呼叫 flush() 方法以檢查是否傳回字串 pending，或是 true 或 false 的 boolean 值。您必須注意，所有已開啟的 SharedObject 實體都會在每次關閉 Flash Player 的目前實體時自動清除。

package {
    import flash.net.SharedObject;

    public class SharedObject_flush {
        private var hostName:String = "yourDomain";
        private var username:String = "yourUsername";

        public function SharedObject_flush() {
            var mySo:SharedObject = SharedObject.getLocal(hostName);
            mySo.data.username = username;
            var flushResult:Object = mySo.flush();
            trace("flushResult: " + flushResult);
            trace(mySo.data.username); // yourUsername
        }
    }
}

getLocal

()

方法

public static function getLocal(name:String, localPath:String = null, secure:Boolean = false):SharedObject

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

傳回只有目前用戶端可使用的本機持續共享物件的參考。如果沒有共享物件，這個方法會建立一個共享物件。如果傳遞給 getLocal() 的任何值都無效，或者呼叫失敗，Flash Player 就會擲回例外。

下列程式碼會說明如何將傳回的共享物件參照指定給變數：

var so:SharedObject = SharedObject.getLocal("savedData");

注意：如果使用者選擇永遠不允許在此網域進行本機儲存，則物件就不會儲存在本機，即使已指定 localPath 的值亦然。這個規則的例外是本機內容。本機內容一律可以將協力廠商網域 (不是目前瀏覽器網址列的網域) 的共享物件寫入磁碟，即使不允許使用協力廠商網域將共享物件寫入磁碟也是一樣。

為了避免名稱衝突，Flash 會檢查建立共享物件之 SWF 檔的位置。例如，若是位於 www.myCompany.com/apps/stockwatcher.swf 的 SWF 檔建立名為 portfolio 的共享物件，此共享物件便不會和另一個名為 portfolio 的物件 (由位於 www.yourCompany.com/photoshoot.swf 的 SWF 檔所建立) 相衝突，因為這兩個 SWF 檔來自不同的目錄。

雖然 localPath 是選擇性的參數，您還是應該注意其用法，特別是當其他 SWF 檔需要存取共享物件時。如果共享物件的資料是專屬某個 SWF 檔，且該檔案不會被移到其他位置，這個時候就可以使用預設值。如果其他 SWF 檔需要存取共享物件，或是稍後會將建立此共享物件的 SWF 檔移到它處，則此參數值將影響此共享物件可存取的方式。例如，假使您建立某個共享物件，並將其 localPath 設定為 SWF 檔的完整路徑預設值，則其他任何 SWF 檔都不能存取該共享物件。如果您稍後將原來的 SWF 檔移到其他位置，則即使該 SWF 檔也無法存取已經儲存在共享物件中的資料。

若要避免不慎對共享物件的存取造成限制，請使用 localpath 參數。最大的允許方式就是將 localPath 參數設為 / (斜線)，這樣可以讓網域中所有的 SWF 檔使用此共享物件，但這會增加與網域中其他共享物件產生名稱衝突的可能性。更嚴謹的方式就是附加含有資料夾名稱 (SWF 檔所在的完整路徑格式) 的 localPath。例如，若為 SWF 檔 (位於 www.myCompany.com/apps/stockwatcher.swf) 所建立的 portfolio 共享物件，您就可以將 localPath 參數設定為 /、/apps 或 /apps/stockwatcher.swf。您必須決定哪個方法可以為應用程式提供最佳的彈性。

使用此方法時，必須考慮下列安全性模型：

無法在多個安全執行程序界限中存取共享物件。
使用者可以使用「Flash Player 設定」對話方塊或「設定管理員」，限制存取共享物件。根據預設，應用程式最多可以在每個網域建立 100 KB 資料的共享物件。系統管理員及使用者也可以限制寫入檔案系統的能力。

假設您將要播放的 SWF 檔內容發佈成本機檔案 (本機安裝的 SWF 檔或 EXE 檔)，而且需要從一個以上的本機 SWF 檔存取特定的共享物件。在這種情況下，請注意，若為本機檔案，則可能會使用兩個不同的位置來儲存共享物件。使用的網域將視授與建立共享物件的本機檔案之安全性權限而定。本機檔案具有三種不同層級的權限：

只能存取本機檔案系統。
只能存取網路。
可同時存取網路及本機檔案系統。

具有本機檔案系統存取權限的本機檔案 (層級 1 或 3) 會在同一個位置儲存其共享物件。沒有本機檔案系統存取權限的本機檔案 (層級 2) 會在其他位置儲存其共享物件。

您可以拒絕 SWF 檔使用這個方法，方式是在包含 SWF 內容的 HTML 網頁中，設定 object 和 embed 標籤的 allowNetworking 參數。

如需詳細資訊，請參閱「Flash Player 開發人員中心」主題：「安全性」。

參數

	`name:String` — 物件名稱。該名稱可以包含正斜線 (`/`)；例如，`work/addresses` 就是合法的名稱。共享物件的名稱中不允許有空格，也不允許有下列字元： ~ % & \ ; : " ' , < > ? #

	`localPath:String` (default = `null`) — 建立共享物件之 SWF 檔的完整或部分路徑，並決定將在本機儲存共享物件的位置。如果您並未指定此參數，就會使用完整路徑。

	`secure:Boolean` (default = `false`) — 會決定此共享物件的存取權限是否受限於透過 HTTPS 連線傳遞的 SWF 檔。如果 SWF 檔是透過 HTTPS 傳遞，此參數值就會產生下列影響：如果這個參數設為 `true`，Flash Player 會建立新的安全共享物件，或取得現有之安全共享物件的參照。而這個安全的共享物件只能透過由 HTTPS 傳遞的 SWF 檔來讀取或寫入，方法是呼叫 `secure` 參數設為 `true` 的 `SharedObject.getLocal()`。如果此參數設定為 `false`，Flash Player 就會建立新的共享物件，或取得現有共享物件 (可由透過非 HTTPS 連線傳遞的 SWF 檔讀取或寫入) 的參照。如果 SWF 檔是透過非 HTTPS 連線傳遞，而您嘗試將這個參數設為 `true`，則建立新的共享物件 (或存取之前建立的安全共享物件) 會失敗且會傳回 `null`。不管參數的值為何，建立的共享物件會針對網域的允許磁碟空間總數而定。下圖顯示 `secure` 參數的用法：

傳回值

SharedObject — 本機存放共享物件的參照，此物件只有目前的用戶端才可以使用。如果 Flash Player 不能建立或找到共享物件 (例如，如果已指定 localPath 卻沒有此目錄存在)，這個方法就會擲回例外。

擲回值

Error — Flash Player 無法基於任何理由建立共享物件。如果禁止協力廠商 Flash 內容所建立及儲存的存放共享物件 (不適用於本機內容)，就可能會發生這項錯誤。使用者可以在「設定管理員」的「全域儲存設定」面板 (位於 http://www.adobe.com/support/documentation/tw/flashplayer/help/settings_manager03.html) 中，禁止使用協力廠商的存放共享物件。

getRemote

()

方法

 public static function getRemote(name:String, remotePath:String = null, persistence:Object = false, secure:Boolean = false):SharedObject

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

傳回 Flash Media Server 上多個用戶端可存取之共享物件的參考。如果沒有遠端共享物件，這個方法會建立一個共享物件。

若要建立遠端共享物件，請呼叫 getRemote()，然後呼叫 connect() 將遠端共享物件連線到伺服器，如下所示：

     var nc:NetConnection = new NetConnection();
     nc.connect("rtmp://somedomain.com/applicationName");
     var myRemoteSO:SharedObject = SharedObject.getRemote("mo", nc.uri, false);
     myRemoteSO.connect(nc);

若要確認共享物件的本機和遠端副本是否同步，請偵聽並處理 sync 事件。要共用這個物件的所有用戶端必須傳送相同的值給 name 和 remotePath 參數。

若要建立只有目前用戶端可以使用的共享物件，請使用 SharedObject.getLocal()。

參數

	`name:String` — 遠端共享物件的名稱。該名稱可以包含正斜線 (/)。例如，work/addresses 就是有效的名稱。共享物件的名稱中不允許有空格，也不允許有下列字元： ~ % & \ ; : " ' , > ? ? #

	`remotePath:String` (default = `null`) — 共享物件將要儲存在其中之伺服器的 URI。這個 URI 必須與傳遞到 `connect()` 方法的 NetConnection 物件的 URI 相同。

	`persistence:Object` (default = `false`) — 指定共享物件之資料屬性的特質是本機存放、遠端存放或兩者皆是。此參數也會指定將在本機儲存共享物件的位置。可接受的值如下： `false` 值會指定共享物件不會存放在用戶端或伺服器上。值為 `true` 會指定共享物件只會存放在伺服器上。若為共享物件的完整或部分本機路徑，則表示共享物件會存放在用戶端和伺服器上。在用戶端上，此物件會儲存在指定的路徑中；而在伺服器上，此物件則會儲存在應用程式目錄的子目錄中。注意：如果使用者選擇永遠不允許在此網域進行本機儲存，則物件就不會儲存在本機，即使已指定存放的本機路徑亦然。如需詳細資訊，請參閱此類別的說明。

	`secure:Boolean` (default = `false`) — 會決定此共享物件的存取權限是否受限於透過 HTTPS 連線傳遞的 SWF 檔。如需詳細資訊，請參閱 `getLocal` 方法項目中 `secure` 參數的說明。

傳回值

SharedObject — 物件的參照，此物件可在多重用戶端之間共享。

擲回值

Error — Flash Player 不能建立或找到共享物件。如果您為 remotePath 和 persistence 參數指定不存在的路徑，就可能會發生這項錯誤。

相關 API 元素

connect()
getLocal()

send

()

方法

public function send(... arguments):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

廣播訊息給連接到遠端共享物件的所有用戶端，包括原先傳送訊息的用戶端。若要處理和回應訊息，請建立附加到共享物件的回呼函數。

參數

... arguments — 一或多個引數：識別訊息的字串、一或多個處理常式函數的名稱 (以附加到共享物件) 以及任何類型的選擇性參數。處理常式名稱的深度只能有一層 (也就是，不能採用父/子的形式)，而且是相對於共享物件。引數會經過序列化，並透過連線傳送，而且接收的處理常式會以相同的順序接收到引數。如果某個參數是圓形物件 (例如，圓形的連結清單)，序列化程式就會正確地處理參照。

注意：請勿使用內建的詞彙做為函數名稱。例如，myRemoteSO.send("close") 將會失敗。

setDirty

()

方法

public function setDirty(propertyName:String):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

向伺服器指出共享物件的屬性值已變更。這個方法會將屬性標記為不正確，表示已變更。

呼叫 SharedObject.setProperty() 以建立共享物件的屬性。

SharedObject.setProperty() 方法會實作 setDirty()。在大部份情況下 (例如當屬性值為 String 或 Number 等基本類型時)，您可以呼叫 setProperty()，來取代呼叫 setDirty()。不過，當屬性值是包含本身自有屬性的物件時，請呼叫 setDirty() 以指出物件內值變更的時間。

參數

propertyName:String — 已變更之屬性的名稱。

相關 API 元素

SharedObject.data (用戶端屬性)
setProperty()

setProperty

()

方法

public function setProperty(propertyName:String, value:Object = null):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

更新共享物件中的屬性值，並向伺服器指出，屬性值已變更。 setProperty() 方法會將屬性明確標記為已變更或不正確。

如需有關遠端共享物件的詳細資訊，請參閱 Flash Media Server 文件。

注意：SharedObject.setProperty() 方法會實作 setDirty() 方法。在大部份情況下，例如當屬性值為 String 或 Number 等基本類型時，您就必須使用 setProperty() (而不是 setDirty)。不過，當屬性值為包含本身屬性的物件時，請使用 setDirty() 指出物件內的值變更的時間。一般而言，呼叫 setProperty() 而非 setDirty() 會是比較好的方式，因為只有當該值已變更時，setProperty() 才會更新屬性值，而 setDirty() 則會強制同步化所有訂閱的用戶端。

參數

	`propertyName:String` — 共享物件中的屬性名稱。

	`value:Object` (default = `null`) — 屬性值 (ActionScript 物件)，或 `null` (刪除屬性)。

相關 API 元素

SharedObject.data (用戶端屬性)

事件詳細資訊

asyncError

事件

事件物件類型: flash.events.AsyncErrorEvent
屬性 AsyncErrorEvent.type = flash.events.AsyncErrorEvent.ASYNC_ERROR

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會在以非同步方式 (亦即，從原生非同步程式碼) 擲回例外時傳送。

AsyncErrorEvent.ASYNC_ERROR 常數會定義 asyncError 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`target`	傳送該事件的物件。
`error`	觸發事件的錯誤。

netStatus

事件

事件物件類型: flash.events.NetStatusEvent
屬性 NetStatusEvent.type = flash.events.NetStatusEvent.NET_STATUS

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

在 SharedObject 實體回報其狀態或錯誤情況時傳送。 netStatus 事件含有 info 屬性，此屬性為資訊物件，其中包含事件的相關特定資訊，例如連線嘗試是否成功，或者共享物件是否已順利寫入本機磁碟。

定義 type 屬性值 (netStatus 事件物件)。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`info`	物件，其中包含描述該物件狀態或錯誤情況的屬性。
`target`	回報其狀態的 NetConnection 或 NetStream 物件。

相關 API 元素

flash.events.NetStatusEvent.info

sync

事件

事件物件類型: flash.events.SyncEvent
屬性 SyncEvent.type = flash.events.SyncEvent.SYNC

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

於伺服器更新遠端共享物件時傳送。

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

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`changeList`	陣列，其中含有描述該陣列狀態的屬性。
`target`	伺服器已經更新的 SharedObject 實體。

相關 API 元素

getRemote()

範例如何使用本範例

SharedObjectExample.as

下列程式碼將使用 ID "application-name" 建立 (接著執行擷取) 共享物件。在按一下「儲存」按鈕後，saveValue() 方法會嘗試將屬性 savedValue 儲存為 SharedObject 物件的 data 屬性。 Flash Player 是否必須要求儲存資料的權限，依使用者對呼叫 onFlushStatus() 方法被賦予的允許或拒絕權限而定。在按一下「清除」按鈕後，clearValue() 方法會刪除儲存在 savedValue 中的值；下次載入 SWF 檔案後，所擷取的值將是 undefined。

package {
    import flash.display.Sprite;
    import flash.events.MouseEvent;
    import flash.events.NetStatusEvent;
    import flash.net.SharedObject;
    import flash.net.SharedObjectFlushStatus;
    import flash.text.TextField;
    import flash.text.TextFieldAutoSize;
    import flash.text.TextFieldType;
    
    public class SharedObjectExample extends Sprite {
        
        private var mySo:SharedObject;
        
        public function SharedObjectExample() {
            buildUI();
            saveBtn.addEventListener(MouseEvent.CLICK, saveValue);
            clearBtn.addEventListener(MouseEvent.CLICK, clearValue);
            
            mySo = SharedObject.getLocal("application-name");
            output.appendText("SharedObject loaded...\n");
            output.appendText("loaded value: " + mySo.data.savedValue + "\n\n");
        }

         private function saveValue(event:MouseEvent):void {
            output.appendText("saving value...\n");
            mySo.data.savedValue = input.text;
            
            var flushStatus:String = null;
            try {
                flushStatus = mySo.flush(10000);
            } catch (error:Error) {
                output.appendText("Error...Could not write SharedObject to disk\n");
            }
            if (flushStatus != null) {
                switch (flushStatus) {
                    case SharedObjectFlushStatus.PENDING:
                        output.appendText("Requesting permission to save object...\n");
                        mySo.addEventListener(NetStatusEvent.NET_STATUS, onFlushStatus);
                        break;
                    case SharedObjectFlushStatus.FLUSHED:
                        output.appendText("Value flushed to disk.\n");
                        break;
                }
            }
            output.appendText("\n");
        }
        
        private function clearValue(event:MouseEvent):void {
            output.appendText("Cleared saved value...Reload SWF and the value should be \"undefined\".\n\n");
            delete mySo.data.savedValue;
        }
        
        private function onFlushStatus(event:NetStatusEvent):void {
            output.appendText("User closed permission dialog...\n");
            switch (event.info.code) {
                case "SharedObject.Flush.Success":
                    output.appendText("User granted permission -- value saved.\n");
                    break;
                case "SharedObject.Flush.Failed":
                    output.appendText("User denied permission -- value not saved.\n");
                    break;
            }
            output.appendText("\n");

            mySo.removeEventListener(NetStatusEvent.NET_STATUS, onFlushStatus);
        }
        
        // UI elements
        private var inputLbl:TextField;
        private var input:TextField;
        private var output:TextField;
        private var saveBtn:Sprite;
        private var clearBtn:Sprite;
    
        private function buildUI():void {
            // input label
            inputLbl = new TextField();
            addChild(inputLbl);
            inputLbl.x = 10;
            inputLbl.y = 10;
            inputLbl.text = "Value to save:";
            
            // input TextField
            input = new TextField();
            addChild(input);
            input.x = 80;
            input.y = 10;
            input.width = 100;
            input.height = 20;
            input.border = true;
            input.background = true;
            input.type = TextFieldType.INPUT;
            
            // output TextField
            output = new TextField();
            addChild(output);
            output.x = 10;
            output.y = 35;
            output.width = 250;
            output.height = 250;
            output.multiline = true;
            output.wordWrap = true;
            output.border = true;
            output.background = true;
            
            // Save button
            saveBtn = new Sprite();
            addChild(saveBtn);
            saveBtn.x = 190;
            saveBtn.y = 10;
            saveBtn.useHandCursor = true;
            saveBtn.graphics.lineStyle(1);
            saveBtn.graphics.beginFill(0xcccccc);
            saveBtn.graphics.drawRoundRect(0, 0, 30, 20, 5, 5);
            var saveLbl:TextField = new TextField();
            saveBtn.addChild(saveLbl);
            saveLbl.text = "Save";
            saveLbl.selectable = false;
            
            // Clear button
            clearBtn = new Sprite();
            addChild(clearBtn);
            clearBtn.x = 230;
            clearBtn.y = 10;
            clearBtn.useHandCursor = true;
            clearBtn.graphics.lineStyle(1);
            clearBtn.graphics.beginFill(0xcccccc);
            clearBtn.graphics.drawRoundRect(0, 0, 30, 20, 5, 5);
            var clearLbl:TextField = new TextField();
            clearBtn.addChild(clearLbl);
            clearLbl.text = "Clear";
            clearLbl.selectable = false;
        }
    }
}

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

SharedObject - AS3

類別 x

client

data

defaultObjectEncoding

fps

objectEncoding

preventBackup

size

clear

close

connect

flush

getLocal

getRemote

send

setDirty

setProperty

asyncError

netStatus

sync