加载外部数据

加载外部数据的许多 API 使用 URLRequest 类来定义所需网络请求的属性。

借助 URLLoader 类，您可以向服务器发送请求并访问返回的信息。您也可以使用 URLLoader 类来访问允许访问本地文件的上下文中（例如 Flash Player 只能与本地文件系统内容交互的沙箱和 AIR 应用程序沙箱）的本地文件系统上的文件。URLLoader 类以文本、二进制数据或 URL 编码变量形式从 URL 下载数据。URLLoader 类调度的事件包括 complete 、 httpStatus 、 ioError 、 open 、 progress 和 securityError 等。

URLLoader 类为 XMLHttpRequest 类提供了替代项。您可以使用两种类中任意一种通过 HTTP 请求下载数据。

下载完成之前，下载的数据不可用。可通过侦听要调度的 progress 事件监视下载进度（已加载字节数和总字节数）。但是，如果文件加载足够快，可能不调度 progress 事件。成功下载文件后，将调度 complete 事件。通过设置 URLLoader dataFormat 属性，您可以以文本、原始二进制数据或 URLVariables 对象格式接收数据。

URLLoader.load() 方法（并且可能 URLLoader 类的构造函数）使用单个参数， request ，该参数是 URLRequest 对象。URLRequest 对象包含所有用于单一 HTTP请求的信息，例如目标 URL、请求方法（ GET 或 POST ）、其他标题信息和 MIME 类型。

例如，若要将 XML 数据包上载到服务器端脚本，可以使用以下代码：

var secondsUTC = new Date().time; 
var dataXML = (new DOMParser()).parseFromString( "<time>" + secondsUTC + "</time>", "application/xml" ); 
var request = new air.URLRequest("http://www.example.com/time.cfm"); 
request.contentType = "text/xml"; 
request.data = dataXML; 
request.method = air.URLRequestMethod.POST; 
var loader = new air.URLLoader(); 
loader.load(request);

上一个代码片断创建包含要发送到服务器的 XML 包的名为 dataXML 的 XML 文档。此示例将 URLRequest contentType 属性设置为 "text/xml" 并将 XML 文档分配给 URLRequest data 属性。最后，示例创建 URLLoader 对象并通过使用 load() 方法将请求发送到远程脚本。

数据到达时，URLStream 类将提供对下载的数据的访问。并且 URLStream 类还允许在完成下载前关闭流。下载的数据以原始二进制数据的形式提供。

当从 URLStream 对象读取数据时，使用 bytesAvailable 属性确定在读取数据之前是否提供了足够的数据。当您尝试阅读的数据比可用数据多时，将引发 EOFError 异常。

构建动态应用程序时，从外部文件或从服务器端脚本加载数据会很有用。这样，您不必编辑或重新编译应用程序，即可生成动态应用程序。例如，如果您要构建一个“每日提示”应用程序，就可以编写一个服务器端脚本，该脚本每天从数据库检索一次随机提示并将其保存到文本文件。然后，应用程序可以加载静态文本文件的内容，而不必每次查询数据库。

下面的片断创建 URLRequest 和 URLLoader 对象，用于加载外部文本文件 params.txt 的内容：

var request = new air.URLRequest("params.txt"); 
var loader = new air.URLLoader(); 
loader.load(request);

var request = new air.URLRequest("http://www.example.com/sendfeedback.cfm"); 
request.method = air.URLRequestMethod.POST;

在运行时加载的外部文档 params.txt 包含以下数据：

monthNames=January,February,March,April,May,June,July,August,September,October,November,December&dayNames=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday

该文件包含两个参数，即 monthNames 和 dayNames 。每个参数包含一个逗号分隔列表，该列表被分析为字符串。可以使用 String.split() 方法将此列表拆分为数组。

不要将保留字或语言构造作为外部数据文件中的变量名称，因为这样做会使代码的读取和调试变得更困难。

function completeHandler(event) 
{ 
    var loader2 = URLLoader(event.target); 
    air.trace(loader2.data); 
}

如果远程文档包含名称-值对，则可以通过传入加载文件的内容，使用 URLVariables 类来分析数据，如下所示：

function completeHandler(event) 
{ 
    var loader2 = event.target; 
    var variables = new air.URLVariables(loader2.data); 
    air.trace(variables.dayNames); 
}

外部文件中的各个名称-值对都创建为 URLVariables 对象中的一个属性。在上面的代码范例中，变量对象中的各个属性都被视为字符串。如果名称-值对的值是一个项目列表，则可以通过调用 String.split() 方法将字符串转换为数组，如下所示：

var dayNameArray = variables.dayNames.split(",");

如果从外部文本文件加载数值数据，可使用顶级函数（如 parseInt() 、 parseFloat() 和 Number() ）将这些值转换为数值。

无需将远程文件的内容作为字符串加载和新建 URLVariables 对象，您可以将 URLLoader.dataFormat 属性设置为在 URLLoaderDataFormat 类中找到的静态属性之一。 URLLoader.dataFormat 属性有以下三个可能的值：

• URLLoaderDataFormat.BINARY — URLLoader.data 属性包含 ByteArray 对象中存储的二进制数据。

• URLLoaderDataFormat.TEXT — URLLoader.data 属性包含 String 对象中的文本。

• URLLoaderDataFormat.VARIABLES — URLLoader.data 属性包含 URLVariables 对象中存储的 URL 编码的变量。

下面的代码演示了如何通过将 URLLoader.dataFormat 属性设置为 URLLoaderDataFormat.VARIABLES ，从而自动将加载的数据分析为 URLVariables 对象：

var request = new air.URLRequest("http://www.example.com/params.txt"); 
var variables = new air.URLLoader(); 
variables.dataFormat = air.URLLoaderDataFormat.VARIABLES; 
variables.addEventListener(air.Event.COMPLETE, completeHandler); 
try 
{ 
    variables.load(request); 
}  
catch (error) 
{ 
    air.trace("Unable to load URL: " + error); 
} 
 
function completeHandler(event) 
{ 
    var loader = event.target; 
    air.trace(loader.data.dayNames); 
}

如以下示例所示，从外部文件加载 XML 与加载 URLVariables 相同。可以创建 URLRequest 实例和 URLLoader 实例，然后使用它们下载远程 XML 文档。文件完全下载后，将调度 complete 事件， trace() 函数将该文件的内容输出到命令行。

 
var request = new air.URLRequest("http://www.example.com/data.xml"); 
var loader = new air.URLLoader(); 
loader.addEventListener(air.Event.COMPLETE, completeHandler); 
loader.load(request); 
 
function completeHandler(event) 
{ 
    var dataXML = event.target.data; 
    air.trace(dataXML); 
}

除了加载外部数据文件，还可以使用 URLVariables 类将变量发送到服务器端脚本并处理服务器的响应。这是非常有用的，例如，如果您正在编写游戏，想要将用户的得分发送到服务器以计算是否应添加到高分列表中，甚至想要将用户的登录信息发送到服务器以进行验证。服务器端脚本可以处理用户名和密码，向数据库验证用户名和密码，然后返回用户提供的凭据是否有效的确认。

下面的片断创建一个名为 variables 的 URLVariables 对象，该对象创建称为 name 的新变量。接下来，创建一个 URLRequest 对象，该对象指定变量要发送到的服务器端脚本的 URL。然后，设置 URLRequest 对象的 method 属性，以便将变量作为 HTTP POST 请求发送。为了将 URLVariables 对象添加到 URL 请求，需要将 URLRequest 对象的 data 属性设置为早先创建的 URLVariables 对象。最后，创建 URLLoader 实例并调用 URLLoader.load() 方法，此方法用于启动该请求。

var variables = new air.URLVariables("name=Franklin"); 
var request = new air.URLRequest(); 
request.url = "http://www.[yourdomain].com/greeting.cfm"; 
request.method = air.URLRequestMethod.POST; 
request.data = variables; 
var loader = new air.URLLoader(); 
loader.dataFormat = URLLoaderDataFormat.VARIABLES; 
loader.addEventListener(Event.COMPLETE, completeHandler); 
try 
{ 
    loader.load(request); 
} 
catch (error) 
{ 
    air.trace("Unable to load URL"); 
} 
 
function completeHandler(event) 
{ 
    air.trace(event.target.data.welcomeMessage); 
}

下面的代码包含上面的示例中使用的 Adobe ColdFusion® greeting.cfm 文档的内容：

<cfif NOT IsDefined("Form.name") OR Len(Trim(Form.Name)) EQ 0> 
    <cfset Form.Name = "Stranger" /> 
</cfif> 
<cfoutput>welcomeMessage=#UrlEncodedFormat("Welcome, " & Form.name)# 
</cfoutput>