套件 | flash.net |
類別 | public class SharedObject |
繼承 | SharedObject EventDispatcher Object |
語言版本: | ActionScript 3.0 |
執行階段版本: | AIR 1.0, Flash Player 9, Flash Lite 4 |
使用共享物件可執行下列動作:
-
維護本機持續性。 這是使用共享物件最簡單的方法,而且不需要 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 元素
屬性 | 定義自 | ||
---|---|---|---|
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 | ||
會針對本機共享物件,清除所有資料並從磁碟中刪除共享物件。 | SharedObject | ||
會關閉遠端共享物件與伺服器之間的連線。 | SharedObject | ||
透過指定的 NetConnection 物件連線到伺服器上的遠端共享物件。 | SharedObject | ||
會將事件傳送到事件流程。 | EventDispatcher | ||
立即將本機上的持續共享物件寫到本機檔案中。 | SharedObject | ||
[靜態]
傳回只有目前用戶端可使用的本機持續共享物件的參考。 | SharedObject | ||
getRemote(name:String, remotePath:String = null, persistence:Object = false, secure:Boolean = false):SharedObject [靜態]
傳回 Flash Media Server 上多個用戶端可存取之共享物件的參考。 | SharedObject | ||
會檢查 EventDispatcher 物件是否有對特定的事件類型註冊偵聽程式。 | EventDispatcher | ||
指出物件是否有已定義的指定屬性。 | Object | ||
指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。 | Object | ||
指出指定的屬性是否存在,以及是否可列舉。 | Object | ||
會從 EventDispatcher 物件移除偵聽程式。 | EventDispatcher | ||
廣播訊息給連接到遠端共享物件的所有用戶端,包括原先傳送訊息的用戶端。 | SharedObject | ||
向伺服器指出共享物件的屬性值已變更。 | SharedObject | ||
更新共享物件中的屬性值,並向伺服器指出,屬性值已變更。 | SharedObject | ||
為迴圈作業設定動態屬性的可用性。 | Object | ||
傳回代表此物件的字串,根據地區特定慣例進行格式化。 | Object | ||
會傳回指定之物件的字串形式。 | Object | ||
會傳回指定之物件的基本值。 | Object | ||
檢查此 EventDispatcher 物件是否已註冊事件偵聽程式,或者此物件的任何祖系已為特定事件類型註冊事件偵聽程式。 | EventDispatcher |
事件 | 摘要 | 定義自 | ||
---|---|---|---|---|
[廣播事件] 當 Flash Player 或 AIR 應用程式取得作業系統焦點並成為作用中時傳送。 | EventDispatcher | |||
會在以非同步方式 (亦即,從原生非同步程式碼) 擲出例外時傳送。 | SharedObject | |||
[廣播事件] 當 Flash Player 或 AIR 應用程式失去作業系統焦點並成為非作用中時傳送。 | EventDispatcher | |||
在 SharedObject 實體回報其狀態或錯誤情況時傳送。 | SharedObject | |||
於伺服器更新遠端共享物件時傳送。 | SharedObject |
client | 屬性 |
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 元素
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 元素
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 實體所決定。
|
相關 API 元素
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
範例 ( 如何使用本範例 )
"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 實體有效且已連線,而且已經在伺服器上成功建立遠端共享物件。
|
相關 API 元素
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 — 下列任一值:
|
擲回值
Error — Flash Player 無法將共享物件寫入磁碟。 如果使用者已永遠不允許此網域的物件進行本機資訊儲存,就可能會發生這項錯誤。
注意:本機內容一律可以將協力廠商網域 (不是目前瀏覽器網址列的網域) 的共享物件寫入磁碟,即使不允許使用協力廠商網域將共享物件寫入磁碟也是一樣。 |
相關 API 元素
範例 ( 如何使用本範例 )
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 傳遞,此參數值就會產生下列影響:
如果 SWF 檔是透過非 HTTPS 連線傳遞,而您嘗試將這個參數設為 下圖顯示 |
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 ) — 指定共享物件之資料屬性的特質是本機存放、遠端存放或兩者皆是。 此參數也會指定將在本機儲存共享物件的位置。 可接受的值如下:
注意:如果使用者選擇永遠不允許在此網域進行本機儲存,則物件就不會儲存在本機,即使已指定存放的本機路徑亦然。 如需詳細資訊,請參閱此類別的說明。 | |
secure:Boolean (default = false ) — 會決定此共享物件的存取權限是否受限於透過 HTTPS 連線傳遞的 SWF 檔。 如需詳細資訊,請參閱 getLocal 方法項目中 secure 參數的說明。
|
SharedObject — 物件的參照,此物件可在多重用戶端之間共享。
|
擲回值
Error — Flash Player 不能建立或找到共享物件。 如果您為 remotePath 和 persistence 參數指定不存在的路徑,就可能會發生這項錯誤。
|
相關 API 元素
send | () | 方法 |
public function send(... arguments):void
語言版本: | ActionScript 3.0 |
執行階段版本: | AIR 1.0, Flash Player 9, Flash Lite 4 |
廣播訊息給連接到遠端共享物件的所有用戶端,包括原先傳送訊息的用戶端。 若要處理和回應訊息,請建立附加到共享物件的回呼函數。
參數
... arguments — 一或多個引數:識別訊息的字串、一或多個處理常式函數的名稱 (以附加到共享物件) 以及任何類型的選擇性參數。 處理常式名稱的深度只能有一層 (也就是,不能採用父/子的形式),而且是相對於共享物件。 引數會經過序列化,並透過連線傳送,而且接收的處理常式會以相同的順序接收到引數。 如果某個參數是圓形物件 (例如,圓形的連結清單),序列化程式就會正確地處理參照。
注意: 請勿使用內建的詞彙做為函數名稱。 例如, |
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 元素
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 元素
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 元素
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 元素
"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; } } }
Tue Jun 12 2018, 03:47 PM Z