SharedObject  - AS3

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

指定給物件之 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 屬性的所有特質，而且如果物件是持續物件，則所有特質都會儲存起來。 如果一個用戶端變更某特質的值，所有用戶端都會立即看到新值。

相關 API 元素

在 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 屬性。

相關 API 元素

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

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

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

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

此共享物件的物件編碼 (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 實體所決定，因此遠端共享物件的這項屬性是唯讀的。

相關 API 元素

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

指定 true 或 false：

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

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

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

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

import flash.net.SharedObject;

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

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

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

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
            }
        }
    }
}

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

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

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

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

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

參數

相關 API 元素

立即將本機上的持續共享物件寫到本機檔案中。 如果您不使用這個方法，則 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。

參數

相關 API 元素

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() 的任何值都無效，或者呼叫失敗，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. 只能存取本機檔案系統。
2. 只能存取網路。
3. 可同時存取網路及本機檔案系統。

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

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

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

參數

  ~ % & \ ; : " ' , < > ? # 
  

傳回 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()。

參數

    ~ % & \ ; :  " ' , > ? ? #

相關 API 元素

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

參數

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

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

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

參數

相關 API 元素

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

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

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

參數

相關 API 元素

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

這個事件具有下列屬性：

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

這個事件具有下列屬性：

相關 API 元素

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

這個事件具有下列屬性：

相關 API 元素