ADOBE AIR HTML 开发人员指南®®上次更新 2011/10/13 法律声明 法律声明 有关法律声明，请参阅 http://help.adobe.com/zh_CN/legalnotices/index.html。iii 上次更新 2011/10/13 目录 第 1 章 : 关于 HTML 环境 HTML 环境概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 AIR 和 WebKit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 第 2 章 : 在 AIR 中进行 HTML 和 JavaScript 编程 创建基于 HTML 的 AIR 应用程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 示例应用程序和安全启示 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 避免与安全相关的 JavaScript 错误 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 通过 JavaScript 访问 AIR API 类 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 关于 AIR 中的 URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 在 HTML 中嵌入 SWF 内容 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 在 HTML 页中使用 ActionScript 库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 转换 Date 和 RegExp 对象 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 跨脚本访问不同安全沙箱中的内容 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 第 3 章 : 处理 AIR 中与 HTML 相关的事件 HTMLLoader 事件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 AIR 类 - 事件处理与 HTML DOM 中其他事件处理的不同之处 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Adobe AIR 事件对象 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 使用 JavaScript 处理运行时事件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 第 4 章 : 为 AIR HTML 容器编写脚本 HTMLLoader 对象的显示属性 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 访问 HTML 历史记录列表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 设置在加载 HTML 内容时使用的用户代理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 设置用于 HTML 内容的字符编码 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 为 HTML 内容定义类似于浏览器的用户界面 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 第 5 章 : 使用矢量 矢量基础知识 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 创建矢量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 向矢量中插入元素 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 检索值和删除矢量元素 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Vector 对象的属性和方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 示例：使用需要矢量的 AIR API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 第 6 章 : AIR 安全性 AIR 安全性基础知识 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 安装和更新 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Adobe AIR 中的 HTML 安全性 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63ivADOBE AIR HTML 开发人员指南 目录 上次更新 2011/10/13 通过脚本访问不同域中的内容 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 写入磁盘 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 安全使用不受信任的内容 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 开发人员的最佳安全做法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 代码签名 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 第 7 章 : 使用 AIR 本机窗口 AIR 中的本机窗口的基础知识 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 创建窗口 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 管理窗口 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 侦听窗口事件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 显示全屏窗口 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 第 8 章 : AIR 中的显示屏幕 AIR 中的显示屏幕的基础知识 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 枚举屏幕 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 第 9 章 : 使用菜单 菜单基础知识 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 创建本机菜单 (AIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 关于 HTML 中的上下文菜单 (AIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 显示弹出本机菜单 (AIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 处理菜单事件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 本机菜单示例：窗口和应用程序菜单 (AIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 使用 MenuBuilder 框架 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 第 10 章 : AIR 中的任务栏图标 关于任务栏图标 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 停靠栏图标 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 系统任务栏图标 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Window 任务栏图标和按钮 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 第 11 章 : 使用文件系统 使用 AIR 文件系统 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 第 12 章 : AIR 中的拖放 HTML 中的拖放 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 将数据拖出 HTML 元素 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 将数据拖入 HTML 元素 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 示例：覆盖默认的 HTML 拖入行为 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 在非应用程序 HTML 沙箱中处理文件放置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 放置文件释放 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160vADOBE AIR HTML 开发人员指南 目录 上次更新 2011/10/13 第 13 章 : 复制和粘贴 复制粘贴基础知识 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 读取和写入系统剪贴板 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 AIR 中的 HTML 复制和粘贴 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 剪贴板数据格式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 第 14 章 : 在 AIR 中使用本地 SQL 数据库 关于本地 SQL 数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 创建和修改数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 操作 SQL 数据库数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 使用同步和异步数据库操作 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 对 SQL 数据库使用加密 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 使用 SQL 数据库的策略 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 第 15 章 : 加密的本地存储区 将数据添加到加密本地存储区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 访问加密的本地存储区中的数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 从加密的本地存储区中删除数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 第 16 章 : 使用字节数组 读取并写入 ByteArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 ByteArray 示例：读取 .zip 文件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 第 17 章 : 在 AIR 中添加 PDF 内容 检测 PDF 功能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 加载 PDF 内容 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 编写 PDF 内容的脚本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 对 AIR 中的 PDF 内容的已知限制 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 第 18 章 : 处理声音 声音处理基础知识 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 了解声音体系结构 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 加载外部声音文件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 处理嵌入的声音 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 处理声音流文件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 处理动态生成的音频 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 播放声音 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 处理声音元数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 访问原始声音数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 捕获声音输入 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248viADOBE AIR HTML 开发人员指南 目录 上次更新 2011/10/13 第 19 章 : 客户端系统环境 客户端系统环境基础知识 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 使用 System 类 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 使用 Capabilities 类 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 第 20 章 : AIR 应用程序的调用和终止 应用程序调用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 捕获命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 用户登录时调用 AIR 应用程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 从浏览器调用 AIR 应用程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 应用程序终止 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 第 21 章 : 处理 AIR 运行时和操作系统信息 管理文件关联 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 获取运行时版本和修补级别 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 检测 AIR 功能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 跟踪用户当前状态 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 第 22 章 : 套接字 TCP 套接字 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 UDP 套接字 (AIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 IPv6 地址 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 第 23 章 : HTTP 通信 加载外部数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 Web 服务请求 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 在其他应用程序中打开 URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 向服务器发送 URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 第 24 章 : 与其他 Flash Player 和 AIR 实例通信 关于 LocalConnection 类 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 在两个应用程序之间发送消息 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 连接到不同域中的内容和 AIR 应用程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 第 25 章 : 针对 JavaScript 开发人员的 ActionScript 基础知识 ActionScript 和 JavaScript 之间的差异：概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 ActionScript 3.0 数据类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 ActionScript 3.0 类、包和命名空间 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 ActionScript 3.0 函数中的必需参数和默认值 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 ActionScript 3.0 事件侦听器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 第 26 章 : 本地数据库中的 SQL 支持 支持的 SQL 语法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 数据类型支持 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310viiADOBE AIR HTML 开发人员指南 目录 上次更新 2011/10/13 第 27 章 : SQL 错误详细消息、 ID 和参数1 上次更新 2011/10/13 第 1 章 : 关于 HTML 环境 Adobe AIR 1.0 和更高版本 AIR 和 Safari Web 浏览器均使用 WebKit (www.webkit.org) 分析、布局和呈现 HTML 和 JavaScript 内容。AIR 的内置主 机类和对象为传统上与桌面应用程序关联的功能提供了一个 API。这些功能包括读取和写入文件以及管理窗口。 Adobe AIR 还继承了 Adobe® Flash® Player 的 API，其中包括声音和二进制套接字等功能。 重要说明：Adobe AIR 运行时的新版本可能包含 WebKit 的更新版本。AIR 新版本中的 WebKit 更新可能会对已部署的 AIR 应用程序造成意外更改。这些更改可能会影响应用程序中 HTML 内容的行为或外观。例如， WebKit 呈现中的改进或更正可 能会更改应用程序用户界面中元素的布局。为此，我们强烈建议您在应用程序中提供一个更新机制。如果因 AIR 中包含的 WebKit 版本发生更改而需要更新应用程序， AIR 更新机制可提示用户安装应用程序的新版本。 下表列出了所使用的 WebKit 版本与 AIR 中使用的 WebKit 版本相同的 Safari Web 浏览器版本： 您始终可以通过检查由 HTMLLoader 对象返回的默认用户代理字符串来确定 WebKit 的已安装版本： air.trace( window.htmlLoader.userAgent ); 请记住，AIR 中使用的 WebKit 版本与开放源版本不同。AIR 中不支持某些功能，并且 AIR 版本可以包括在相应 WebKit 版 本中尚不可用的安全性和错误修复功能。请参阅 第 13 页的 “AIR 中不支持的 WebKit 功能 ”。 在 HTML 内容中使用 AIR API 是完全可选的。您可以完全使用 HTML 和 JavaScript 编写 AIR 应用程序。大多数现有 HTML 应用程序只需少量更改即可运行（假定它们使用的 HTML、 CSS、 DOM 和 JavaScript 功能与 WebKit 兼容）。 AIR 授予您对应用程序外观的完全控制权限。您可以使应用程序的外观类似于本机桌面应用程序。还可以关闭由操作系统提供 的窗口镶边，并实现您自己的用于移动窗口、调整窗口大小和关闭窗口的控件。您甚至可以在没有窗口的情况下运行。 由于 AIR 应用程序直接在桌面上运行，且具有对文件系统的完全访问权限，因此，对应的安全模型比典型 Web 浏览器的安全 模型更加严格。在 AIR 中，只有从应用程序安装目录加载的内容才会被放置到应用程序沙箱 中。应用程序沙箱具有最高级别 的权限，且允许访问 AIR API。AIR 根据其他内容的来源将这些内容放置到隔离沙箱中。从文件系统加载的文件放置到本地沙 箱中。使用 http: 或 https: 协议从网络加载的文件则根据远程服务器的域放置到相应沙箱中。禁止这些非应用程序沙箱中的内 容访问任何 AIR API，且其运行方式与在典型 Web 浏览器中几乎一样。 如果应用 Alpha、缩放或透明度设置，则 AIR 中的 HTML 内容不显示 SWF 或 PDF 内容。有关详细信息，请参阅第 42 页的 “ 在 HTML 页中加载 SWF 或 PDF 内容时的注意事项 ” 和第 76 页的 “ 窗口透明度 ”。 更多帮助主题 Webkit DOM 参考 Safari HTML 参考 Safari CSS 参考 www.webkit.org AIR 版本 Safari 版本 1.0 2.04 1.1 3.04 1.5 4.0 测试版 2.0 4.03 2.5 4.03 2.6 4.03 2.7 4.03 3 5.0.32ADOBE AIR HTML 开发人员指南 关于 HTML 环境 上次更新 2011/10/13 HTML 环境概述 Adobe AIR 1.0 和更高版本 Adobe AIR 使用 HTML 渲染器、文档对象模型和 JavaScript 解释程序提供与浏览器完全相似的 JavaScript 环境。 JavaScript 环境通过 AIR HTMLLoader 类表示。在 HTML 窗口中，HTMLLoader 对象包含所有 HTML 内容，而该对象 又包含在 NativeWindow 对象中。通过 NativeWindow 对象，应用程序可以为用户桌面上显示的本机操作系统窗口的属性和 行为撰写脚本。 关于 JavaScript 环境及其与 AIR 主机之间的关系 Adobe AIR 1.0 和更高版本 下图演示了 JavaScript 环境和 AIR 运行时环境的关系。虽然只显示了一个本机窗口，但是一个 AIR 应用程序可以包含多个窗 口。（并且一个窗口可以包含多个 HTMLLoader 对象。） JavaScript 环境具有其自己的 Document 和 Window 对象。JavaScript 代码可以通过 runtime、nativeWindow 和 htmlLoader 属性与 AIR 运行时环 境交互。 ActionScript 代码可以通过 HTMLLoader 对象的 window 属性与 JavaScript 环境交互，该属性是对 JavaScript Window 对象的引用。此外， ActionScript 和 JavaScript 对象均可以侦听由 AIR 和 JavaScript 对象调度的事件。 runtime 属性提供了对 AIR API 类的访问权限，使您可以新建 AIR 对象和访问类（也称为静态）成员。若要访问 AIR API， 请向 runtime 属性添加该类的名称和包。例如，若要创建 File 对象，您将使用以下语句： var file = new window.runtime.filesystem.File(); AIR 䖤㸠ᯊ⦃๗ NativeWindow HTMLLoader JavaScript ⦃๗ window window document body h1 div p table head htmlLoader nativeWindow 䖤㸠ᯊ3ADOBE AIR HTML 开发人员指南 关于 HTML 环境 上次更新 2011/10/13 注： AIR SDK 提供了一个 JavaScript 文件，即 AIRAliases.js，该文件为最常用的 AIR 类定义了更便于使用的别名。导入该文 件时，您可以使用 air.Class 简短形式替换 window.runtime.package.Class。例如，您可以使用 new air.File() 创建 File 对象。 NativeWindow 对象提供了用于控制桌面窗口的属性。您可以使用 window.nativeWindow 属性从 HTML 页内部访问包含的 NativeWindow 对象。 HTMLLoader 对象提供了用于控制内容的加载方式和呈现方式的属性、方法和事件。您可以使用 window.htmlLoader 属性从 HTML 页内部访问父 HTMLLoader 对象。 重要说明： 仅当作为应用程序的一部分安装的页作为顶级文档加载时，该页才具有 htmlLoader、 nativeWindow 或 runtime 属 性。将文档加载到 frame 或 iframe 中时不会添加这些属性。（只要子文档与父文档位于相同安全沙箱中，子文档即可访问父文 档的这些属性。例如，加载到 frame 中的文档可以使用 parent.runtime 访问其父级的 runtime 属性。） 关于安全性 Adobe AIR 1.0 和更高版本 AIR 根据原始域在安全沙箱中执行所有代码。应用程序内容限制为从应用程序安装目录加载的内容，该内容放置到应用程序 沙 箱中。只有在此沙箱中运行的 HTML 和 JavaScript 才能访问运行时环境和 AIR API。同时，在页 load 事件的所有处理函数返 回之后，将在应用程序沙箱中阻止 JavaScript 的大多数动态计算和执行操作。 通过将应用程序页加载到 frame 或 iframe 中，并对 frame 设置特定于 AIR 的 sandboxRoot 和 documentRoot 属性，可以将该 应用程序页映射到非应用程序沙箱中。通过将 sandboxRoot 值设置为实际远程域，您可以使沙箱中的内容跨脚本访问该域中的 内容。当加载远程内容或撰写远程内容脚本时（例如，在 mash-up 应用程序中），使用上述方法映射页非常有用。 允许应用程序和非应用程序内容相互跨脚本访问的另一方法是创建沙箱桥，这也是向 AIR API 授予非应用程序内容访问权限 的唯一方法。使用父级到子级 桥，子 frame、 iframe 或窗口中的内容能够访问在应用程序沙箱中定义的指定方法和属性。反 之，使用子级到父级 桥，应用程序内容能够访问在子级的沙箱中定义的指定方法和属性。通过设置窗口对象的 parentSandboxBridge 和 childSandboxBridge 属性可以建立沙箱桥。有关详细信息，请参阅 第 63 页的 “Adobe AIR 中的 HTML 安全性 ” 以及 第 10 页的 “HTML frame 和 iframe 元素 ”。 关于插件和嵌入对象 Adobe AIR 1.0 和更高版本 AIR 支持 Adobe® Acrobat® 插件。用户必须安装有 Acrobat 或 Adobe® Reader® 8.1 （或更高版本）才能显示 PDF 内容。 HTMLLoader 对象提供了用于查看用户系统是否可以显示 PDF 的属性。 SWF 文件内容也可以在 HTML 环境中显示，但 AIR 中构建有此功能，因此无需使用外部插件。 AIR 中不支持任何其他 WebKit 插件。 更多帮助主题 第 63 页的 “Adobe AIR 中的 HTML 安全性 ” 第 4 页的 “HTML 沙箱 ” 第 10 页的 “HTML frame 和 iframe 元素 ” 第 8 页的 “JavaScript Window 对象 ” 第 5 页的 “XMLHttpRequest 对象 ” 第 231 页的 “ 在 AIR 中添加 PDF 内容 ”4ADOBE AIR HTML 开发人员指南 关于 HTML 环境 上次更新 2011/10/13 AIR 和 WebKit Adobe AIR 1.0 和更高版本 Adobe AIR 中使用开放源代码 WebKit 引擎，该引擎也用于 Safari Web 浏览器。 AIR 添加了若干扩展功能，以便允许访问 运行时类和对象，并增强了安全性。此外， WebKit 自身还针对 HTML、CSS 和 JavaScript 添加了 W3C 标准中不包括的功 能。 此处仅包含 AIR 新增功能和最显著的 WebKit 扩展功能；有关非标准 HTML、 CSS 和 JavaScript 的其他文档，请参阅 www.webkit.org 和 developer.apple.com。有关标准信息，请参阅 W3C 网站。 Mozilla 还提供了有关 HTML、 CSS 和 DOM 主题的重要一般参考 （当然， WebKit 引擎不同于 Mozilla 引擎）。 AIR 中的 JavaScript Flash Player 9 和更高版本， Adobe AIR 1.0 和更高版本 AIR 对通用 JavaScript 对象的典型行为进行了若干更改。其中，很多更改都是为了在 AIR 中更方便地编写安全应用程序。同 时，这些行为差异表示某些通用 JavaScript 编码模式和使用这些模式的现有 Web 应用程序在 AIR 中可能始终不会按预期方式 执行。有关更正这些问题类型的信息，请参阅第 20 页的 “ 避免与安全相关的 JavaScript 错误 ”。 HTML 沙箱 Adobe AIR 1.0 和更高版本 AIR 根据内容的原始位置将该内容放置到隔离沙箱中。沙箱规则与大多数 Web 浏览器实现的具有相同原始位置的策略一致， 并且与 Adobe Flash Player 实现的沙箱规则一致。此外， AIR 还提供了一个包含并保护应用程序内容的新应用程序 沙箱类 型。有关在开发 AIR 应用程序时可能遇到的沙箱类型的详细信息，请参阅安全性沙箱。 只有在应用程序沙箱中运行的 HTML 和 JavaScript 才能访问运行时环境和 AIR API。但同时，出于安全原因，动态计算和执 行各种形式的 JavaScript 在应用程序沙箱内大幅受限。无论您的应用程序实际上是否从服务器直接加载信息，这些限制都将发 挥作用。（即使是文件内容、粘贴的字符串和直接用户输入也可能不可靠。） 页内容的原始位置确定要将该内容放置到哪个沙箱。只能将从应用程序目录（ app: URL 方案引用的安装目录）加载的内容放 置到应用程序沙箱中。从文件系统加载的内容则放置到与本地文件系统内容交互的 沙箱或受信任的本地 沙箱中，以便访问本地 文件系统上的内容（而不是远程内容），并与其进行交互。从网络加载的内容则放置到与其原始域对应的远程沙箱中。 若要使应用程序页与远程沙箱中的内容自由交互，则可以将该页映射到远程内容所在的相同域中。例如，如果编写显示 Internet 服务的映射数据的应用程序，则可以将加载和显示该服务内容的应用程序页映射到该服务域中。用于将页映射到远程 沙箱和域的属性是 frame 和 iframe HTML 元素的新增属性。 若要使非应用程序沙箱中的内容安全地使用 AIR 功能，则可以设置父沙箱桥。若要使应用程序内容安全地调用其他沙箱中的内 容的方法并访问其属性，则可以设置子沙箱桥。此处所述的安全性意味着远程内容不能意外获取对未明确公开的对象、属性或 方法的引用。通过沙箱桥只能传递简单数据类型、函数和匿名对象。但是，您仍然必须避免明确公开潜在的危险函数。例如， 如果公开的接口允许远程内容读取或写入用户系统中任意位置的文件，则可能会使远程内容严重危害用户。 JavaScript eval() 函数 Adobe AIR 1.0 和更高版本 完成加载页之后，将在应用程序沙箱中限制使用 eval() 函数。在某些情况下允许使用该函数，以便可以安全地分析 JSON 格式 数据，但是，生成可执行语句的任何计算将生成错误。第 65 页的 “ 对不同沙箱中的内容的代码限制 ” 介绍了允许使用 eval() 函 数的情况。 5ADOBE AIR HTML 开发人员指南 关于 HTML 环境 上次更新 2011/10/13 函数构造函数 Adobe AIR 1.0 和更高版本 在应用程序沙箱中，可以在完成加载页之前使用函数构造函数。在所有页 load 事件处理函数完成之后，无法创建新的函数。 加载外部脚本 Adobe AIR 1.0 和更高版本 应用程序沙箱中的 HTML 页无法使用 script 标签从应用程序目录外部加载 JavaScript 文件。为使应用程序中的页能够从应用 程序目录外部加载脚本，必须将该页映射到非应用程序沙箱。 XMLHttpRequest 对象 Adobe AIR 1.0 和更高版本 AIR 提供了应用程序可用于执行数据请求的 XMLHttpRequest (XHR) 对象。下面的示例演示简单数据请求： xmlhttp = new XMLHttpRequest(); xmlhttp.open("GET", "http:/www.example.com/file.data", true); xmlhttp.onreadystatechange = function() { if (xmlhttp.readyState == 4) { //do something with data... } } xmlhttp.send(null); 与浏览器不同，AIR 允许在应用程序沙箱中运行的内容请求任何域中的数据。对于包含 JSON 字符串的 XHR 结果，除非该结 果还包含可执行代码，否则可以计算出该结果的数据对象。如果 XHR 结果中存在可执行语句，则会引发错误，且计算尝试失 败。 若要防止从远程源意外注入代码，在完成加载页之前执行同步 XHR 时将返回空结果。异步 XHR 将始终在加载页之后返回。 默认情况下， AIR 阻止在非应用程序沙箱中执行跨域 XMLHttpRequest。应用程序沙箱中的父窗口可以选择在包含非应用程 序沙箱内容的子 frame 中允许跨域请求，方法是在包含非应用程序沙箱内容的 frame 或 iframe 元素中将 AIR 添加的 allowCrossDomainXHR 属性设置为 true： 由于 sandboxRoot 属性重新映射 www.example.com 地址的根 URL，因此所有请求都将从应用程序目录加载，而不是从远程 服务器加载。无论请求是派生自页导航还是 XMLHttpRequest，都将重新映射这些请求。6ADOBE AIR HTML 开发人员指南 关于 HTML 环境 上次更新 2011/10/13 若要避免意外阻止对远程服务器的数据请求，请将 sandboxRoot 映射到远程 URL 的子目录，而不是根目录。该目录不一定存 在。例如，若要允许从远程服务器加载对 www.example.com 的请求，而不是从应用程序目录加载，请将上面的 iframe 更改 为以下内容： ui.html 页可以使用以下脚本标签从本地的 sandbox 文件夹加载 javascript 文件： 它还可以使用以下脚本标签从远程服务器的目录加载内容： sandboxRoot URL 将遮盖远程服务器上位于相同 URL 中的所有内容。在上例中，您不能访问位于 www.example.com/local/ （或其子目录中）中的任何远程内容，因为 AIR 会将请求重新映射到本地应用程序目录：无论是页面导航、 XMLHttpRequest 还是采用其他内容加载手段所派生的请求，都会重新映射。 设置沙箱桥接口 Adobe AIR 1.0 和更高版本 如果应用程序沙箱中的内容必须访问非应用程序沙箱中的内容所定义的属性或方法，或者如果非应用程序内容必须访问应用程 序沙箱中的内容所定义的属性或方法，则可以使用沙箱桥。使用任何子级文档的 window 对象的 childSandboxBridge 和 parentSandboxBridge 属性可创建沙箱桥。 建立子级沙箱桥 Adobe AIR 1.0 和更高版本 childSandboxBridge 属性允许子级文档向父级文档中的内容公开接口。若要公开接口，需将 childSandbox 属性设置为子级文档 中的函数或对象。然后，可以从父级文档中的内容访问该对象或函数。以下示例显示了子级文档中运行的脚本如何向其父级文 档公开包含函数和属性的对象： var interface = {}; interface.calculatePrice = function(){ return ".45 cents"; } interface.storeID = "abc" window.childSandboxBridge = interface; 如果此子级内容加载到 iframe （分配的 ID 为 “child”），则可以通过读取 frame 的 childSandboxBridge 属性从父级内容来访 问接口： var childInterface = document.getElementById("child").contentWindow.childSandboxBridge; air.trace(childInterface.calculatePrice()); //traces ".45 cents" air.trace(childInterface.storeID)); //traces "abc"32ADOBE AIR HTML 开发人员指南 在 AIR 中进行 HTML 和 JavaScript 编程 上次更新 2011/10/13 建立父级沙箱桥 Adobe AIR 1.0 和更高版本 parentSandboxBridge 属性允许父级文档向子级文档中的内容公开接口。若要公开接口，父级文档需将子级文档的 parentSandbox 属性设置为父级文档中定义的函数或对象。然后，可以从子级文档中的内容访问该对象或函数。以下示例显示 了父级 frame 中运行的脚本如何向其子级文档公开包含函数的对象： var interface = {}; interface.save = function(text){ var saveFile = air.File("app-storage:/save.txt"); //write text to file } document.getElementById("child").contentWindow.parentSandboxBridge = interface; 使用此接口，子级 frame 中的内容可以将文本保存到名为 save.txt 的文件，但对文件系统不具备任何其他访问权利。子级内容 可以调用 save 函数，如下所示： var textToSave = "A string."; window.parentSandboxBridge.save(textToSave); 应用程序内容向其他沙箱公开的接口应越窄越好。应考虑到非应用程序内容本身并不可靠，因为它可能遭到意外或恶意代码注 入。必须采取适当的防护措施，以防止误用通过父级沙箱桥公开的接口。 在页面加载过程中访问父级沙箱桥 Adobe AIR 1.0 和更高版本 为了使子级文档中的脚本能够访问父级沙箱桥，必须先设置沙箱桥，然后才能运行脚本。创建新页 DOM 之后，在分析任何脚 本或添加 DOM 元素之前，Window、frame 和 iframe 对象将调度 dominitialize 事件。可以使用 dominitialize 事件按照适当 的页面构造顺序尽早建立沙箱桥，以便页面中定义的所有脚本均能访问该沙箱桥。 以下示例说明如何创建父级沙箱桥，以响应从子级 frame 调度的 dominitialize 事件： 以下 child.html 文档说明子级内容如何访问父级沙箱桥：33ADOBE AIR HTML 开发人员指南 在 AIR 中进行 HTML 和 JavaScript 编程 上次更新 2011/10/13 若要侦听子级窗口（而非框架）上的 dominitialize 事件，必须将侦听器添加到通过 window.open() 函数创建的新子级 window 对象： var childWindow = window.open(); childWindow.addEventListener("dominitialize", engageBridge()); childWindow.document.location = "http://www.example.com/air/child.html"; 在这种情况下，无法将应用程序内容映射到非应用程序沙箱。只有在从应用程序目录外部加载 child.html 时，此方法才有用。 仍可将窗口中的应用程序内容映射到非应用程序沙箱，但必须首先加载一个中间页，在中间页中使用框架来加载子级文档并将 其映射到所需的沙箱。 如果使用 HTMLLoader 类的 createRootWindow() 函数来创建窗口，则新窗口不是从中调用 createRootWindow() 的文档的子 级。因此，无法从调用窗口建立到加载到新窗口中的非应用程序内容的沙箱桥。而是必须在新窗口中加载一个中间页，在中间 页中使用框架来加载子级文档。这样，就可以在新窗口的父级文档与加载到框架中的子级文档之间建立沙箱桥。34 上次更新 2011/10/13 第 3 章 : 处理 AIR 中与 HTML 相关的事件 Adobe AIR 1.0 和更高版本 利用事件处理系统，程序员可以十分方便地响应用户输入和系统事件。 Adobe® AIR® 事件模型不仅方便，而且符合标准。事件 模型基于文档对象模型 (DOM) 第 3 级事件规范，是业界标准的事件处理体系结构，为程序员提供了强大而直观的事件处理工 具。 HTMLLoader 事件 Adobe AIR 1.0 和更高版本 HTMLLoader 对象调度以下 Adobe® ActionScript® 3.0 事件： AIR 类 - 事件处理与 HTML DOM 中其他事件处理的不同之处 Adobe AIR 1.0 和更高版本 HTML DOM 提供了几种不同的方法来处理事件： • 在 HTML 元素的开始标签中定义 on 事件处理函数，如下所示： • 回调函数属性，例如： document.getElementById("myDiv").onclick 事件 说明 htmlDOMInitialize 在创建 HTML 文档时调度，调度时未分析任何脚本或未将 DOM 节点添加到页面。 complete 在为响应加载操作而创建 HTML DOM 后，紧接在 HTML 页面中的 onload 事件后调度。 htmlBoundsChanged 在 contentWidth 和 / 或 contentHeight 属性发生了变化时调度。 locationChange 在 HTMLLoader 的 location 属性发生了变化时调度。 locationChanging 由于用户导航、 JavaScript 调用或重定向，在 HTMLLoader 的位置发生变化前调度。当您 调用 load()、loadString()、reload()、historyGo()、historyForward() 或 historyBack() 方法 时未调度 locationChanging 事件。 调用所调度事件对象的 preventDefault() 方法会取消导航。 如果系统浏览器中打开某个链接，则不会调度 locationChanging 事件，因为 HTMLLoader 不会改变位置。 scroll 只要 HTML 引擎更改滚动位置，便会调度此事件。 Scroll 事件的引发可能是由于导航到页 面中的锚记链接（ # 链接），也可能是由于调用 window.scrollTo() 方法。在文本输入或文本 区域中输入文本也可能会引发 scroll 事件。 uncaughtScriptException 当在 HTMLLoader 中发生 JavaScript 异常，并且在 JavaScript 代码中未捕获到该异常时 调度。 35ADOBE AIR HTML 开发人员指南 处理 AIR 中与 HTML 相关的事件 上次更新 2011/10/13 • 您使用 addEventListener() 方法注册的事件侦听器，如下所示： document.getElementById("myDiv").addEventLister("click", clickHandler) 不过，由于运行时对象不会出现在 DOM 中，因此您只能通过调用 AIR 对象的 addEventListener() 方法来添加事件侦听器。 与在 JavaScript 中一样，由 AIR 对象调度的事件可以与默认行为关联起来。（默认行为 是 AIR 作为特定事件的正常后果而执 行的动作。） 由运行时对象调度的事件对象是 Event 类或其某一个子类的实例。事件对象不但存储有关特定事件的信息，还包含便于操作此 事件对象的方法。例如，如果 AIR 在异步读取文件时检测到 I/O 错误事件，则会创建用来表示该特定 I/O 错误事件的事件对象 （IOErrorEvent 类的实例）。 无论何时编写事件处理函数代码，该代码都采用相同的基本结构： function eventResponse(eventObject) { // Actions performed in response to the event go here. } eventTarget.addEventListener(EventType.EVENT_NAME, eventResponse); 此代码完成两项任务。首先，它定义一个处理函数，这是指定为响应事件而要执行的动作的方法。接下来，它调用源对象的 addEventListener() 方法，实际上就是为指定事件订阅该函数，以便当该事件发生时，执行处理函数动作。当事件实际发生时， 事件目标将检查其向事件侦听器注册的所有函数和方法的列表。然后，它依次调用每个函数或方法，同时将事件对象作为参数 传递。 默认行为 Adobe AIR 1.0 和更高版本 开发人员通常负责编写响应事件的代码。但在某些情况下，行为通常与某一事件关联，使得 AIR 会自动执行该行为，除非开发 人员添加了取消该行为的代码。由于 AIR 会自动表现该行为，因此这类行为称为默认行为。 例如，当用户单击应用程序窗口的关闭框时，普遍期待窗口关闭，因此该行为被内置到 AIR 中。如果您不希望该默认行为发 生，可以使用事件处理系统来取消它。当用户单击某个窗口的关闭框时，表示该窗口的 NativeWindow 对象将调度 closing 事 件。若要防止运行时关闭该窗口，您必须调用已调度的事件对象的 preventDefault() 方法。 并非所有默认行为都可以被阻止。例如，当 FileStream 对象将数据写入某个文件时，运行时将生成 OutputProgressEvent 对 象。无法阻止的默认行为是：用新数据更新该文件的内容。 许多类型的事件对象没有关联的默认行为。例如，在读取了 MP3 文件中的足量数据后， Sound 对象会调度 id3 事件以提供 ID3 信息，但没有与其关联的默认行为。 Event 类及其子类的 API 文档列出了每一类型的事件，并说明所有关联的默认行为， 以及是否可以阻止该行为。 注： 默认行为仅与运行时直接调度的事件对象关联，对于通过 JavaScript 以编程方式调度的事件对象，不存在默认行为。例 如，可以使用 EventDispatcher 类的方法调度事件对象，然而调度事件并不会触发默认行为。 事件流 Adobe AIR 1.0 和更高版本 在 AIR 中运行的 SWF 文件内容使用 ActionScript 3.0 显示列表体系结构来显示可视内容。ActionScript 3.0 显示列表为在父 级显示对象和子级显示对象之间传播的 SWF 文件内容中的内容和事件（如鼠标单击事件）提供父子关系。 HTML DOM 有 它自己的只遍历 DOM 元素的独立事件流。当为 AIR 编写基于 HTML 的应用程序时，您主要是使用 HTML DOM 而不是 ActionScript 3.0 显示列表，因此您通常可以忽略 AIR 参考文档中出现的有关事件阶段的信息。 36ADOBE AIR HTML 开发人员指南 处理 AIR 中与 HTML 相关的事件 上次更新 2011/10/13 Adobe AIR 事件对象 Adobe AIR 1.0 和更高版本 在事件处理系统中，事件对象有两个主要用途。首先，事件对象通过将特定事件的有关信息存储在一组属性中来表示实际事 件。其次，事件对象包含一组方法，可用于操作事件对象和影响事件处理系统的行为。 AIR API 定义了 Event 类，该类用作 AIR API 类调度的所有事件对象的基类。Event 类定义所有事件对象共有的一组基本属 性和方法。 若要使用 Event 对象，务必要先了解 Event 类的属性和方法以及 Event 类的子类存在的原因。 了解 Event 类的属性 Adobe AIR 1.0 和更高版本 Event 类定义了提供有关事件的重要信息的多个只读属性和常量。以下项尤为重要： • Event.type 描述事件对象表示的事件的类型。 • Event.cancelable 是一个布尔值，用于报告与事件关联的默认行为（如果有）是否可以取消。 • 事件流信息包含在其余的属性中，仅当在 AIR 中的 SWF 内容中使用 ActionScript 3.0 时才有用。 事件对象类型 Adobe AIR 1.0 和更高版本 每个事件对象都有关联的事件类型。数据类型以字符串值的形式存储在 Event.type 属性中。知道事件对象的类型是非常有用 的，这样您的代码就可以区分不同类型的对象。例如，下面的代码注册一个 fileReadHandler() 侦听器函数以响应 myFileStream 调度的 complete 事件： myFileStream.addEventListener(Event.COMPLETE, fileReadHandler); AIR Event 类定义许多类常量（如 COMPLETE、CLOSING 和 ID3），以表示运行时对象调度的事件的类型。这些常量列在 针 对 HTML 开发人员的 Adobe AIR API 参考的 “Event 类 ” 页面中。 事件常量提供了引用特定事件类型的简便方法。使用常量（而不是字符串值）可帮助您更快地识别拼写错误。如果您的代码中 拼错了某个常量名，则 JavaScript 分析器将捕获到该错误。而如果您拼错了事件字符串，将会为永远都不会调度的一种事件注 册事件处理函数。因此，在添加事件侦听器时，建议使用下面的代码： myFileStream.addEventListener(Event.COMPLETE, htmlRenderHandler); 而不是使用： myFileStream.addEventListener("complete", htmlRenderHandler); 默认行为信息 Adobe AIR 1.0 和更高版本 代码可通过访问 cancelable 属性来检查是否可以阻止任何给定事件对象的默认行为。cancelable 属性保存着一个布尔值，用于指 示是否可以阻止默认行为。您可以使用 preventDefault() 方法阻止或取消与少量事件关联的默认行为。有关详细信息，请参阅 第 37 页的 “ 取消事件默认行为 ”。37ADOBE AIR HTML 开发人员指南 处理 AIR 中与 HTML 相关的事件 上次更新 2011/10/13 了解 Event 类的方法 Adobe AIR 1.0 和更高版本 有三种类别的 Event 类方法： • 实用程序方法：可以创建事件对象的副本或将其转换为字符串。 • 事件流方法：用于从事件流中删除事件对象（主要是在运行时的 SWF 内容中使用 ActionScript 3.0 时使用，请参阅第 35 页的 “ 事件流 ”）。 • 默认行为方法：可阻止默认行为或检查是否已阻止默认行为。 Event 类实用程序方法 Adobe AIR 1.0 和更高版本 Event 类有两个实用程序方法。clone() 方法用于创建事件对象的副本。toString() 方法用于生成事件对象属性的字符串表示形式 以及它们的值。 取消事件默认行为 Adobe AIR 1.0 和更高版本 与取消默认行为有关的两个方法是 preventDefault() 方法和 isDefaultPrevented() 方法。调用 preventDefault() 方法可取消与事件 关联的默认行为。使用 isDefaultPrevented() 方法可检查是否已对事件对象调用 preventDefault()。 preventDefault() 方法仅在可以取消事件的默认行为时才起作用。您可以通过查阅 API 文档，或通过检查事件对象的 cancelable 属性，来检查事件是否有可以取消的行为。 取消默认行为对事件对象通过事件流的进度没有影响。使用 Event 类的事件流方法可以从事件流中删除事件对象。 Event 类的子类 Adobe AIR 1.0 和更高版本 对于很多事件， Event 类中定义的一组公共属性已经足够了。然而，要表示其他事件，则需要使用 Event 类中未提供的属性。 AIR API 为这些事件定义了 Event 类的几个子类。 每个子类提供了对该类别的事件唯一的附加属性和事件类型。例如，与鼠标输入相关的事件提供了描述发生事件时鼠标所在位 置的属性。同样， InvokeEvent 类也增加了一些属性，这些属性包含执行调用的文件的文件路径，以及在调用命令行期间作为 形参传递的所有实参。 Event 子类频繁定义用来表示与该子类关联的事件类型的其他常量。例如， FileListEvent 类定义表示 directoryListing 和 selectMultiple 事件类型的常量。 使用 JavaScript 处理运行时事件 Adobe AIR 1.0 和更高版本 运行时类支持使用 addEventListener() 方法添加事件处理函数。若要为某个事件添加处理函数，请调用调度该事件的对象的 addEventListener() 方法，同时提供事件类型和处理函数。例如，若要侦听用户单击标题栏上的窗口关闭按钮时调度的 closing 事件，请使用下面的语句：38ADOBE AIR HTML 开发人员指南 处理 AIR 中与 HTML 相关的事件 上次更新 2011/10/13 window.nativeWindow.addEventListener(air.NativeWindow.CLOSING, handleWindowClosing); addEventListener() 方法的 type 参数为字符串，但 AIR API 为所有运行时事件类型定义了常量。与使用字符串版本相比，使用 这些常量可帮助您更快地找到在 type 参数中输入的拼写错误。 创建事件处理函数 Adobe AIR 1.0 和更高版本 下面的代码创建一个简单的 HTML 文件，用于显示有关主窗口位置的信息。一个名为 moveHandler() 的处理函数侦听主窗口 的 move 事件（由 NativeWindowBoundsEvent 类定义）。
当用户移动此窗口时， textarea 元素会显示此窗口的更新的 X 位置和 Y 位置： 请注意，事件对象作为实参传递给 moveHandler() 方法。利用 event 参数，处理函数可以检查事件对象。在此示例中，使用事 件对象的 type 属性报告该事件为 move 事件。 注： 指定 listener 参数时，不要使用括号。例如，在下面对 addEventListener() 方法的调用中，指定 moveHandler() 函数时没有 使用括号：addEventListener(Event.MOVE, moveHandler)。 addEventListener() 方法包括三个其他参数，在针对 HTML 开发人员的 Adobe AIR API 参考中进行了介绍；这些参数为 useCapture、 priority 和 useWeakReference。39ADOBE AIR HTML 开发人员指南 处理 AIR 中与 HTML 相关的事件 上次更新 2011/10/13 删除事件侦听器 Adobe AIR 1.0 和更高版本 可以使用 removeEventListener() 方法删除不再需要的事件侦听器。建议删除将不再使用的所有侦听器。必需的参数包括 eventName 和 listener 参数，这些参数与 addEventListener() 方法的必需参数相同。 删除执行导航的 HTML 页面中的事件侦听器 Adobe AIR 1.0 和更高版本 当 HTML 内容进行导航时，或者因包含 HTML 内容的窗口关闭而丢弃这些 HTML 内容时，不会自动删除引用已卸载的页面 中对象的事件侦听器。当对象向已卸载的处理函数调度事件时，会显示下面的错误消息：“ 应用程序尝试引用不再处于已加载 状态的 HTML 页面中的 JavaScript 对象。”(The application attempted to reference a JavaScript object in an HTML page that is no longer loaded.) 为避免出现此错误，请在 HTML 页面退出之前删除其中的 JavaScript 事件侦听器。如果发生页面导航（在 HTMLLoader 对 象中），请在 window 对象的 unload 事件发生期间删除事件侦听器。 例如，下面的 JavaScript 代码删除 uncaughtScriptException 事件的事件侦听器： window.onunload = cleanup; window.htmlLoader.addEventListener('uncaughtScriptException', uncaughtScriptException); function cleanup() { window.htmlLoader.removeEventListener('uncaughtScriptException', uncaughtScriptExceptionHandler); } 为避免在关闭包含 HTML 内容的窗口时发生错误，请调用 cleanup 函数以响应 NativeWindow 对象 (window.nativeWindow) 的 closing 事件。例如，下面的 JavaScript 代码删除 uncaughtScriptException 事件的事件侦听器： window.nativeWindow.addEventListener(air.Event.CLOSING, cleanup); function cleanup() { window.htmlLoader.removeEventListener('uncaughtScriptException', uncaughtScriptExceptionHandler); } 为了防止发生此错误，您还可以在事件侦听器运行时将其删除（如果该事件只需要处理一次）。例如，下面的 JavaScript 代码 通过调用 HTMLLoader 类的 createRootWindow() 方法创建一个 html 窗口，并为 complete 事件添加一个事件侦听器。在调用 complete 事件处理函数时，它会使用 removeEventListener() 函数删除它自己的事件侦听器： var html = runtime.flash.html.HTMLLoader.createRootWindow(true); html.addEventListener('complete', htmlCompleteListener); function htmlCompleteListener() { html.removeEventListener(complete, arguments.callee) // handler code.. } html.load(new runtime.flash.net.URLRequest("second.html")); 如果删除不需要的事件侦听器，则还会使系统垃圾回收器能回收与这些侦听器关联的任何内存空间。 40ADOBE AIR HTML 开发人员指南 处理 AIR 中与 HTML 相关的事件 上次更新 2011/10/13 检查有无现有的事件侦听器 Adobe AIR 1.0 和更高版本 hasEventListener() 方法用于检查某个对象是否存在事件侦听器。 没有侦听器的错误事件 Adobe AIR 1.0 和更高版本 异常（而不是事件）是在运行时类中处理错误的主要机制。不过，异常处理对异步操作（例如加载文件）不起作用。如果在异 步操作过程中发生错误，则运行时会调度一个错误事件对象。如果您不为该错误事件创建侦听器，则 AIR Debug Launcher 将 显示包含有关该错误的信息的对话框。 大多数错误事件都基于 ErrorEvent 类，并且都有一个名为 text 的属性，此属性用于存储描述性错误消息。异常属于 StatusEvent 类，此类具有一个 level 属性，而不是 text 属性。当 level 属性的值为 error 时， StatusEvent 被视为错误事件。 错误事件不会导致应用程序停止运行。它仅以一个对话框的形式显示在 AIR Debug Launcher 中。它根本不会在运行时中运 行的已安装 AIR 应用程序中显示。41 上次更新 2011/10/13 第 4 章 : 为 AIR HTML 容器编写脚本 Adobe AIR 1.0 和更高版本 在 Adobe® AIR® 中，HTMLLoader 类用作 HTML 内容的容器。此类提供了许多属性和方法，用于控制 HTML 内容的行为 和外观。此外，该类还为加载 HTML 内容并与之交互以及管理历史记录等任务定义了相关属性和方法。 HTMLHost 类为 HTMLLoader 定义了一组默认行为。在创建 HTMLLoader 对象时，未提供任何 HTMLHost 实现。因 此，当 HTML 内容触发某一默认行为时（如更改窗口位置或窗口标题），不会发生任何变化。可以对 HTMLHost 类进行扩 展，为您的应用程序定义所需的行为。 对于 AIR 创建的 HTML 窗口，提供了 HTMLHost 的默认实现。通过将 defaultBehavior 参数设置为 true 来创建新的 HTMLHost 对象，并使用新创建的 HTMLHost 对象设置 HTMLLoader 对象的 htmlHost 属性，可以将默认 HTMLHost 实现分配给其他 HTMLLoader 对象。 HTMLHost 类只能使用 ActionScript 进行扩展。在基于 HTML 的应用程序中，可以导入包含 HTMLHost 类的实现的已编 译 SWF 文件。使用 window.htmlLoader 属性分配主机类实现： HTMLLoader 对象的显示属性 Adobe AIR 1.0 和更高版本 HTMLLoader 对象继承 Adobe® Flash® Player Sprite 类的显示属性。例如，可以调整大小、移动、隐藏和更改背景颜色，也 可以应用滤镜、遮罩、缩放和旋转等高级效果。在应用效果时，应考虑对易读性的影响。在应用某些效果时，无法显示加载到 HTML 页中的 SWF 和 PDF 内容。 HTML 窗口包含用于呈现 HTML 内容的 HTMLLoader 对象。此对象被限制在窗口区域内，因此，更改尺寸、位置、旋转 或缩放系数并不一定能得到令人满意的结果。 基本显示属性 Adobe AIR 1.0 和更高版本 通过 HTMLLoader 的基本显示属性，可以定位控件在其父显示对象中的位置，设置大小以及显示或隐藏控件。不应更改 HTML 窗口的 HTMLLoader 对象的这些属性。 基本属性包括： 属性 备注 x、 y 定位对象在其父容器中的位置。 width、 height 更改显示区域的尺寸。 visible 控制对象及所其包含的所有内容的可见性。42ADOBE AIR HTML 开发人员指南 为 AIR HTML 容器编写脚本 上次更新 2011/10/13 在 HTML 窗口外部，HTMLLoader 对象的 width 和 height 属性的默认值为 0。必须设置宽度和高度才能看到加载的 HTML 内容。HTML 内容根据 HTMLLoader 大小进行绘制，并根据内容中的 HTML 和 CSS 属性进行布置。更改 HTMLLoader 大小会重新填充内容。 在向新的 HTMLLoader 对象（ width 仍设置为 0）中加载内容时，使用 contentWidth 和 contentHeight 属性设置 HTMLLoader 的显示宽度和高度是一种很不错的做法。此项技术适用于根据 HTML 和 CSS 流规则进行布置时具有合理的最 小宽度的页。不过，在缺少 HTMLLoader 提供的合理宽度时，有些页会生成窄而长的布局。 注： 当更改 HTMLLoader 对象的宽度和高度时， scaleX 和 scaleY 值不会发生更改，大多数其他类型的显示对象也存在此现 象。 HTMLLoader 内容的透明度 Adobe AIR 1.0 和更高版本 HTMLLoader 对象的 paintsDefaultBackground 属性（默认情况下为 true）确定 HTMLLoader 对象是否绘制不透明背景。 当 paintsDefaultBackground 为 false 时，背景是透明的。显示对象容器或 HTMLLoader 对象下的其他显示对象在 HTML 内容 的前景元素后是可见的。 如果 body 元素或 HTML 文档的任何其他元素指定了背景颜色（例如，使用 style="background-color:gray"），则 HTML 的该 部分背景是不透明的，并使用指定的背景颜色呈现。如果设置了 HTMLLoader 对象的 opaqueBackground 属性，并且 paintsDefaultBackground 为 false，则为 opaqueBackground 设置的颜色是可见的。 注： 可以使用透明的 PNG 格式的图形为 HTML 文档中的元素提供 Alpha 混合背景。不支持对 HTML 元素设置不透明样式。 缩放 HTMLLoader 内容 Adobe AIR 1.0 和更高版本 在对 HTMLLoader 对象进行缩放时，缩放系数应避免超过 1.0。如果对 HTMLLoader 对象进行放大，则 HTMLLoader 内 容中的文本将以特定的分辨率呈现，从而产生像素化效果。 在 HTML 页中加载 SWF 或 PDF 内容时的注意事项 Adobe AIR 1.0 和更高版本 在以下情况下，加载到 HTMLLoader 对象中的 SWF 和 PDF 内容将消失： • HTMLLoader 对象的缩放系数不为 1.0。 • 将 HTMLLoader 对象的 alpha 属性设置为 1.0 之外的值。 • 旋转 HTMLLoader 内容。 如果删除出错的属性设置并删除活动滤镜，可重新显示内容。 此外，运行时无法在透明窗口中显示 PDF 内容。如果将 object 或 embed 标签的 wmode 参数设置为 opaque 或 transparent， 则运行时仅显示在 HTML 页中嵌入的 SWF 内容。因为 wmode 的默认值是 window，所以在透明窗口中不显示 SWF 内容，除 非明确设置 wmode 参数。 注： 在早于 AIR 1.5.2 的版本中，无论使用哪种 wmode 值，都不显示在 HTML 中嵌入的 SWF。 有关在 HTMLLoader 中加载这些类型的媒体的详细信息，请参阅第 26 页的 “ 在 HTML 中嵌入 SWF 内容 ” 和第 231 页的 “ 在 AIR 中添加 PDF 内容 ”。43ADOBE AIR HTML 开发人员指南 为 AIR HTML 容器编写脚本 上次更新 2011/10/13 高级显示属性 Adobe AIR 1.0 和更高版本 HTMLLoader 类继承了一些可用于生成特殊效果的方法。通常，这些效果在用于 HTMLLoader 显示时存在一些限制，但对 于生成过渡或其他临时效果会非常有用。例如，如果显示一个对话窗口来收集用户输入内容，则可以在用户关闭对话之前模糊 显示主窗口。同样，在关闭窗口时可以淡出显示。 高级显示属性包括： 下面的示例说明如何设置 filters 数组使整个 HTML 模糊显示： var blur = new window.runtime.flash.filters.BlurFilter(); var filters = [blur]; window.htmlLoader.filters = filters; 注： 在基于 HTML 的应用程序中，通常不使用 Sprite 和 BlurFilter 等显示对象类。它们未在 针对 HTML 开发人员的 Adobe AIR API 参考中列出，在 AIRAliases.js 文件中也没有别名。有关这些类的文档，请参阅用于 Adobe Flash Platform 的 ActionScript 3.0 参考。 访问 HTML 历史记录列表 Adobe AIR 1.0 和更高版本 在 HTMLLoader 对象中加载新页时，运行时将为该对象维护一份历史记录列表。历史记录列表对应于 HTML 页中的 window.history 对象。 HTMLLoader 类包含以下属性和方法，可用于操作 HTML 历史记录列表： 属性 限制 alpha 会降低 HTML 内容的易读性 filters 在 HTML 窗口中，外部效果沿窗口边缘剪裁 graphics 使用图形命令绘制的形状显示在 HTML 内容下方（包括默认背景） 。 paintsDefaultBackground 属性必须为 false，绘制的形状才可见。 opaqueBackground 不更改默认背景的颜色。paintsDefaultBackground 属性必须为 false，此颜色层才 可见。 rotation 矩形 HTMLLoader 区域的各个角会沿窗口边缘剪裁。不显示 HTML 内容中加载的 SWF 和 PDF 内容。 scaleX、 scaleY 当缩放系数大于 1 时，会呈现像素化效果。不显示 HTML 内容中加载的 SWF 和 PDF 内容。 transform 会降低 HTML 内容的易读性。 HTML 显示会沿窗口边缘剪裁。如果转换涉及旋 转、缩放或倾斜，则不显示 HTML 内容中加载的 SWF 和 PDF 内容。 类成员 说明 historyLength 历史记录列表的总长度，包括向后和向前的条目。 historyPosition 历史记录列表中的当前位置。位于此位置之前的历史记录项表示 “ 向后 ” 导航，位于此位置之后的项表示 “ 向前 ” 导 航。 getHistoryAt() 返回与历史记录列表中指定位置的历史记录条目对应的 URLRequest 对象。 44ADOBE AIR HTML 开发人员指南 为 AIR HTML 容器编写脚本 上次更新 2011/10/13 历史记录列表中的项目作为 HTMLHistoryItem 类型的对象存储。 HTMLHistoryItem 类包含下列属性： 设置在加载 HTML 内容时使用的用户代理 Adobe AIR 1.0 和更高版本 HTMLLoader 类具有 userAgent 属性，通过该属性可以设置 HTMLLoader 使用的用户代理字符串。需在调用 load() 方法之 前设置 HTMLLoader 对象的 userAgent 属性。如果对 HTMLLoader 实例设置此属性，则不 使用传递给 load() 方法的 URLRequest 的 userAgent 属性。 通过设置 URLRequestDefaults.userAgent 属性，可以设置应用程序域中所有 HTMLLoader 对象使用的默认用户代理字符串。 URLRequestDefaults 静态属性作为默认属性应用于所有 URLRequest 对象，不只是与 HTMLLoader 对象的 load() 方法一 起使用的 URLRequest 对象。设置 HTMLLoader 的 userAgent 属性将覆盖 URLRequestDefaults.userAgent 默认设置。 如果既未为 HTMLLoader 对象的 userAgent 属性设置用户代理值，也未为 URLRequestDefaults.userAgent 设置用户代理值， 则将使用默认的 AIR 用户代理值。此默认值随着运行时操作系统（如 Mac OS 或 Windows）、运行时语言和运行时版本而变 化，如下面两个示例所示： • "Mozilla/5.0 (Macintosh; U; PPC Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko) AdobeAIR/1.0" • "Mozilla/5.0 (Windows; U; en) AppleWebKit/420+ (KHTML, like Gecko) AdobeAIR/1.0" 设置用于 HTML 内容的字符编码 Adobe AIR 1.0 和更高版本 HTML 页通过包括 meta 标签可以指定其使用的字符编码，如下所示： meta http-equiv="content-type" content="text/html" charset="ISO-8859-1"; 通过设置 HTMLLoader 对象的 textEncodingOverride 属性覆盖页面设置，确保使用特定的字符编码： window.htmlLoader.textEncodingOverride = "ISO-8859-1"; 使用 HTMLLoader 对象的 textEncodingFallback 属性，指定当 HTML 页未指定字符编码设置时要对 HTMLLoader 内容使 用的字符编码： window.htmlLoader.textEncodingFallback = "ISO-8859-1"; historyBack() 如果可能，在历史记录列表中向后导航。 historyForward() 如有可能，请在历史记录列表中向前导航。 historyGo() 在浏览器历史记录中按指示的步数导航。如果为正数，则向前导航；如果为负数，则向后导航。导航到零将重新加载 页面。如果指定的位置超出末尾位置，则将导航到列表末尾。 属性 说明 isPost 如果 HTML 页包括 POST 数据，则设置为 true。 originalUrl 在进行任何重定向之前， HTML 页的原始 URL。 title HTML 页的标题。 url HTML 页的 URL。 类成员 说明45ADOBE AIR HTML 开发人员指南 为 AIR HTML 容器编写脚本 上次更新 2011/10/13 textEncodingOverride 属性将覆盖 HTML 页中的设置。并且 textEncodingOverride 属性和 HTML 页中的设置将覆盖 textEncodingFallback 属性。 需在加载 HTML 内容之前设置 textEncodingOverride 属性或 textEncodingFallback 属性。 为 HTML 内容定义类似于浏览器的用户界面 Adobe AIR 1.0 和更高版本 JavaScript 提供了多个 API 来控制显示 HTML 内容的窗口。在 AIR 中，可以通过实现自定义 HTMLHost 类覆盖这些 API。 重要说明： 使用 ActionScript 只能创建 HTMLHost 类的自定义实现。在 HTML 页中，可以导入和使用包含自定义实现的已 编译 ActionScript (SWF) 文件。有关将 ActionScript 库导入 HTML 的详细信息，请参阅第 28 页的 “ 在 HTML 页中使用 ActionScript 库 ”。 关于扩展 HTMLHost 类 Adobe AIR 1.0 和更高版本 AIR HTMLHost 类控制以下 JavaScript 属性和方法： • window.status • window.document.title • window.location • window.blur() • window.close() • window.focus() • window.moveBy() • window.moveTo() • window.open() • window.resizeBy() • window.resizeTo() 在使用 new HTMLLoader() 创建 HTMLLoader 对象时，不会启用所列的 JavaScript 属性或方法。HTMLHost 类提供了这些 JavaScript API 的类似于浏览器的默认实现。还可以扩展 HTMLHost 类以自定义行为。若要创建支持默认行为的 HTMLHost 对象，请在 HTMLHost 构造函数中将 defaultBehaviors 参数设置为 true： var defaultHost = new HTMLHost(true); 在 AIR 中，使用 HTMLLoader 类的 createRootWindow() 方法创建 HTML 窗口时，将自动分配支持默认行为的 HTMLHost 实例。可以通过向 HTMLLoader 的 htmlHost 属性分配不同的 HTMLHost 实现来更改主机对象行为，也可以 分配 null 以禁用整个功能。 注： AIR 将默认的 HTMLHost 对象分配给为基于 HTML 的 AIR 应用程序创建的初始窗口以及使用 JavaScript 的 window.open() 方法的默认实现创建的所有窗口。46ADOBE AIR HTML 开发人员指南 为 AIR HTML 容器编写脚本 上次更新 2011/10/13 示例：扩展 HTMLHost 类 Adobe AIR 1.0 和更高版本 下面的示例说明如何通过扩展 HTMLHost 类来自定义 HTMLLoader 对象影响用户界面的方式： Flex 示例： 1 创建一个 HTMLHost 类的扩展类（子类）。 2 覆盖新类的方法以处理用户界面相关设置中的更改。例如，以下 CustomHost 类定义调用 window.open() 和更改 window.document.title 的行为。调用 window.open() 将在新窗口中打开 HTML 页，更改 window.document.title （包括 HTML 页的 元素的设置）将设置该窗口的标题。 package { import flash.html.*; import flash.display.StageScaleMode; import flash.display.NativeWindow; import flash.display.NativeWindowInitOptions; public class CustomHost extends HTMLHost { import flash.html.*; override public function createWindow(windowCreateOptions:HTMLWindowCreateOptions):HTMLLoader { var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); var bounds:Rectangle = new Rectangle(windowCreateOptions.x, windowCreateOptions.y, windowCreateOptions.width, windowCreateOptions.height); var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, windowCreateOptions.scrollBarsVisible, bounds); htmlControl.htmlHost = new HTMLHostImplementation(); if(windowCreateOptions.fullscreen){ htmlControl.stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; } return htmlControl; } override public function updateTitle(title:String):void { htmlLoader.stage.nativeWindow.title = title; } } } 3 在包含 HTMLLoader 的代码（不是新建的 HTMLHost 子类的代码）中，创建新类的对象。将新对象分配给 HTMLLoader 的 htmlHost 属性。以下 Flex 代码使用上一步中定义的 CustomHost 类：47ADOBE AIR HTML 开发人员指南 为 AIR HTML 容器编写脚本 上次更新 2011/10/13 <?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" applicationComplete="init()"> <mx:Script> <![CDATA[ import flash.html.HTMLLoader; import CustomHost; private function init():void { var html:HTMLLoader = new HTMLLoader(); html.width = container.width; html.height = container.height; var urlReq:URLRequest = new URLRequest("Test.html"); html.htmlHost = new CustomHost(); html.load(urlReq); container.addChild(html); } ]]> </mx:Script> <mx:UIComponent id="container" width="100%" height="100%"/> </mx:WindowedApplication> 若要测试此处所述的代码，请将具有以下内容的 HTML 文件放在应用程序目录下： <html> <head> <title>Test window.open('Test.html')