SharedObject  - AS3

表示对其调用回调方法的对象。默认对象为 this。您可以将此客户端属性设置为其它对象，并对此对象调用回调方法。

赋给对象的 data 属性 (property) 的属性 (attribute) 集合；可以共享和存储这些属性 (attribute)。每个特性都可以是任何 ActionScript 或 JavaScript 类型的对象（数组、数字、布尔值、字节数组、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 属性 (property) 的所有属性 (attribute)，共享对象包含以下信息：

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

注意：切勿将值直接赋给共享对象的 data 属性，如同在 so.data = someValue 中一样；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 属性 (property) 的所有属性 (attribute) 可供连接到共享对象的所有客户端使用；如果永久保留这些对象，则会保存所有属性 (attribute)。如果一个客户端更改了属性的值，所有客户端可以立即看到新的值。

相关 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 编码，并可与旧内容交互。本地共享对象创建后，将无法更改现有本地共享对象的 objectEncoding 值，通过设置 SharedObject.defaultObjectEncoding。

为了以每个对象为基础设置对象编码，而不是为 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 个字节，则即使它开始时要小得多，也为 minDiskSpace 传递 500。如果 Flash 要求用户为该共享对象分配磁盘空间，它将要求 500 个字节。在用户分配了请求的空间量之后，当以后尝试对齐该对象时（只要其大小不超过 500 个字节），Flash 将无需要求更多的空间。

在用户响应此对话框后，则会再次调用此方法。将调度 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 的共享对象，则该共享对象不会与位于 www.yourCompany.com/photoshoot.swf 的 SWF 文件所创建的另一个名为 portfolio 的对象冲突，这是因为这两个 SWF 文件源于不同的目录。

虽然 localPath 参数是可选的，但是您应该考虑该参数的用途，特别是其它 SWF 文件需要访问共享对象时。如果共享对象中的数据特定于一个不会移动到其它位置的 SWF 文件，则使用默认值将会解决问题。如果其它 SWF 文件需要访问共享对象，或如果创建共享对象的 SWF 文件以后将发生移动，则此参数的值将影响共享对象的可访问性。例如，如果在 localPath 设置为等于 SWF 文件完整路径的默认值时创建一个共享对象，那么其它任何 SWF 文件都将无法访问该共享对象。如果您以后将原始的 SWF 文件移动到另一个位置，那么，即便是该 SWF 文件也将无法访问已经存储在共享对象中的数据。

为避免意外限制对共享对象的访问，请使用 localpath 参数。允许级别最高的方法是将 localPath 设置为 /（斜杠），这样做可使域中的所有 SWF 文件都可访问该共享对象，但会增加与域中其它共享对象发生名称冲突的可能性。限制级别较高的方法是向 localPath 追加 SWF 文件完整路径中的文件夹名。例如，对于位于 www.myCompany.com/apps/stockwatcher.swf 的 SWF 文件创建的 portfolio 共享对象，可以将 localPath 参数设置为/、/apps 或 /apps/stockwatcher.swf。您必须确定哪种方法能为您的应用程序提供最佳的灵活性。

在使用此方法时，请考虑以下安全模型：

• 无法跨沙箱边界访问共享对象。
• 用户可通过使用“Flash Player 设置”对话框或“设置管理器”来限制共享对象访问。默认情况下，应用程序可在每个域创建高达 100 KB 数据的共享对象。管理员和用户还可限制写入文件系统的能力。

假定您将要播放的 SWF 文件内容发布为本地文件（本地安装的 SWF 文件或 EXE 文件）而且，您需要从多个本地 SWF 文件访问某个特定的共享对象。在这种情况下，请注意：对于本地文件而言，可能会使用两个不同位置来存储共享对象。所用的域取决于为创建该共享对象的本地文件授予的安全权限。本地文件可以具有三种不同级别的权限：

1. 仅能访问本地文件系统。
2. 仅能访问网络。
3. 既能访问网络，也能访问本地文件系统。

可以访问本地文件系统（1 级或 3 级）的本地文件将其共享对象存储在一个位置。无法访问本地文件系统（2 级）的本地文件将其共享对象存储在另一位置。

可以在包含 SWF 内容的 HTML 页中设置 object 和 embed 标签的 allowNetworking 参数，防止 SWF 文件使用此方法。

有关详细信息，请参阅 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 元素

向连接到远程共享对象的所有客户端广播一条消息（包括发送该消息的客户端）。要处理并响应该消息，请创建一个附加到共享对象的回调函数。

参数

通知服务器共享对象中的属性值已更改。此方法将属性标记为 dirty，这表明属性已更改。

可以调用 SharedObject.setProperty() 为共享对象创建属性。

SharedObject.setProperty() 方法实现了 setDirty()。大多数情况下，例如，当属性的值为 String 或 Number 等原始类型时，您可以调用 setProperty() 而不是调用 setDirty()。然而，如果属性值是一个包含其自己的属性的对象，则调用 setDirty() 以表示该对象中的值的更改时间。

参数

相关 API 元素

更新共享对象中某个属性的值，并通知服务器该属性的值已更改。setProperty() 方法明确地将属性标签为已更改或 dirty。

有关远程共享对象的详细信息，请参阅 Flash Media Server 文档。

注意：SharedObject.setProperty() 方法实现了 setDirty() 方法。大多数情况下，例如当属性的值为 String 或 Number 等原始类型时，应使用 setProperty()，而不使用 setDirty。然而，当某个属性的值是一个包含其自身属性的对象时，则使用 setDirty() 来表示该对象中的值的更改时间。通常，最好调用 setProperty() 而不要调用 setDirty()，因为 setProperty() 只在值被更改的时候更新属性值，而 setDirty() 则强制所有订阅客户端进行同步。

参数

相关 API 元素

在异步引发异常（即来自本机异步代码）时调度。

此事件具有以下属性：

在 SharedObject 实例报告其状态或错误条件时调度。netStatus 事件包含 info 属性，该属性为包含事件特定信息（例如，连接尝试是否成功或共享对象是否被成功写入本地磁盘）的信息对象。

此事件具有以下属性：

相关 API 元素

在服务器更新了远程共享对象后调度。

此事件具有以下属性：

相关 API 元素