特定于移动 AIR 应用程序的 ActionScript API

下列 API 仅在移动设备上的 AIR 应用程序中可用。当前在 Flash Player 或 AIR 的桌面版本中不可用。

屏幕方向 API

屏幕方向 API 允许使用舞台方向和 iPhone：

• Stage.autoOrients — 应用程序是否设置为使舞台随设备旋转自动重新取向。当在 Flash Professional CS5“iPhone 设置”话框中选择“自动方向”选项时，此属性将设置为 true 。（也可以在应用程序描述符文件中将 autoOrients 元素设置为 true 。）请参见 iPhone 应用程序设置 。可通过为 Stage 对象添加 orientationChanging 事件侦听器来取消自动重新定向。调用此事件对象的 preventDefault() 方法可取消自动重新定向。

  在使用“自动方向”时，为获得最佳效果，应按照如下所示设置舞台的 align 属性：

  stage.align = StageAlign.TOP_LEFT; 
  stage.scaleMode = StageScaleMode.NO_SCALE;

• Stage.deviceOrientation — 设备的物理方向。StageOrientation 类定义此属性的值。

• Stage.orientation — 舞台的目前方向。StageOrientation 类定义此属性的值。

• Stage.supportsOrientationChange — 在 iPhone 中设置为 true ，在 AIR 应用程序中设置为 false 。

• Stage.setOrientation() — 设置舞台的方向。此方法包含一个参数，该参数是一个定义新舞台方向的字符串。StageOrientation 类中的常量用于定义此参数的可能值。

• StageOrientation — 定义舞台方向值。例如， StageOrientation.ROTATED_RIGHT 表示舞台相对于设备的默认方向向右旋转。

• StageOrientationEvent — 定义当屏幕方向更改时舞台调度的事件。当用户旋转 iPhone 时发生此事件。有两种类型的事件。当设备旋转时，Stage 调度 orientationChanging 事件。要防止舞台重新取向，则调用 orientationChanging 事件对象的 preventDefault() 方法。舞台重新取向完成后，Stage 将调度 orientationChange 事件。

当前，屏幕方向 API 仅在移动设备上的 AIR 应用程序中可用。如果移动 AIR 应用程序和桌面 AIR 应用程序共享源代码，请使用 Stage.supportsOrientationChange 属性来检查是否支持 API。

以下示例显示如何响应旋转设备的用户：

stage.addEventListener(StageOrientationEvent.ORIENTATION_CHANGE, 
            onOrientationChange); 
 
function onOrientationChange(event:StageOrientationEvent):void 
{ 
    switch (event.afterOrientation) { 
        case StageOrientation.DEFAULT: 
            // re-orient display objects based on 
            // the default (right-side up) orientation. 
            break; 
        case StageOrientation.ROTATED_RIGHT: 
            // Re-orient display objects based on 
            // right-hand orientation. 
            break; 
        case StageOrientation.ROTATED_LEFT: 
            // Re-orient display objects based on 
            // left-hand orientation. 
            break; 
        case StageOrientation.UPSIDE_DOWN: 
            // Re-orient display objects based on 
            // upside-down orientation. 
            break; 
}

在此示例中，出现不同的舞台方向时，将显示注释而不是功能代码。

您可以通过调用 Stage 对象的 setOrientation() 方法来更改舞台的方向。设置方向是一种异步操作。您可以通过侦听 orientationChange 事件来检查取向完成的时间。以下代码显示如何将舞台设置为向右：

stage.addEventListener(StageOrientationEvent.ORIENTATION_CHANGE, 
            onOrientationChange); 
stage.setOrientation(StageOrientation.ROTATED_RIGHT); 
 
function onOrientationChange(event:StageOrientationEvent):void 
{ 
    // Code to handle the new Stage orientation 
}

舞台在旋转时会进行大小调整，并且 Stage 对象将调度 resize 事件。您可以调整显示对象大小，并将其重新定位在舞台上，以响应 resize 事件。

NativeApplication.systemIdleMode 和 SystemIdleMode

借助 NativeApplication.systemIdleMode 属性，您可以阻止 iPhone 进入闲置模式。默认情况下，如果一段时间内没有触摸屏交互，iPhone 将进入闲置模式。闲置模式可以导致屏幕变暗，也可以导致 iPhone 进入锁定模式。此属性可以设置为下列值之一：

仅在移动设备上支持此功能。在桌面操作系统上运行的 AIR 应用程序不支持此功能。对于在桌面上运行的应用程序，设置 NativeApplication.systemIdleMode 属性不起任何作用。

以下代码显示如何禁用 iPhone 闲置模式：

NativeApplication.nativeApplication.systemIdleMode = SystemIdleMode.KEEP_AWAKE;

CameraRoll

借助 CameraRoll 类，您可以向 iPhone 相机胶卷添加图像。 addBitmapData() 方法将向 iPhone 相机胶卷添加图像。此方法包含一个参数 bitmapData 。此参数是 BitmapData 对象，其中包含要添加到相机胶卷的图像。

仅移动设备支持 CameraRoll 功能。在桌面操作系统上运行的 AIR 应用程序不支持此功能。要在运行时查看应用程序是否支持 CamerRoll 功能，请查看 CameraRoll.supportsAddBitmapData 静态属性。

在调用 addBitmapData () 方法之后，CameraRoll 对象将调度下列事件之一：

以下代码将舞台的图像（屏幕捕获）添加到相机胶卷：

if (CameraRoll.supportsAddBitmapData) 
{ 
    var cameraRoll:CameraRoll = new CameraRoll(); 
    cameraRoll.addEventListener(ErrorEvent.ERROR, onCrError); 
    cameraRoll.addEventListener(Event.COMPLETE, onCrComplete); 
    var bitmapData:BitmapData = new BitmapData(stage.stageWidth, stage.stageHeight); 
    bitmapData.draw(stage); 
    cameraRoll.addBitmapData(bitmapData); 
} 
else 
{ 
    trace("not supported."); 
} 
 
function onCrError(event:ErrorEvent):void 
{ 
    // Notify user. 
} 
 
function onCrComplete(event:Event):void 
{ 
    // Notify user. 
}

DisplayObject.cacheAsBitmapMatrix

cacheAsBitmapMatrix 属性是一个 Matrix 对象，用于定义当 cacheAsBitmap 设置为 true 时显示对象的呈现方式。当呈现显示对象的位图版本时，应用程序将此矩阵用作转换矩阵。

设置 cacheAsBitmapMatrix 后，应用程序将保留缓存的位图图像，该图像使用此矩阵（而不是显示矩阵）呈现。（显示矩阵是显示对象的 transform.concatenatedMatrix 的值。）如果此矩阵与显示矩阵不匹配，则根据需要缩放和旋转位图。

仅当 cacheAsBitmapMatrix 的值更改时，设置了 cacheAsBitmapMatrix 的显示对象才重新呈现。位图会适当地缩放或旋转以符合显示矩阵。

cacheAsBitmapMatrix 属性有益于基于 CPU 和基于 GPU 的呈现，但通常对 GPU 呈现更有益。

例如，以下代码使用显示对象的未转换的位图表示形式：

matrix:Matrix = new Matrix(); // creates an identity matrix 
mySprite.cacheAsBitmapMatrix = matrix; 
mySprite.cacheAsBitmap = true;

以下代码使用与当前呈现匹配的位图表示形式：

mySprite.cacheAsBitmapMatrix = mySprite.transform.concatenatedMatrix; 
mySprite.cacheAsBitmap = true;

通常，恒等矩阵 ( new Matrix() ) 或 transform.concatenatedMatrix 就足够了。然而，您可以使用其他矩阵（例如按比例缩小的矩阵）将其他位图上载到 GPU。例如，以下示例应用了一个在 X 轴和 Y 轴上缩放了 0.5 的 cacheAsBitmapMatrix 矩阵。GPU 使用的位图对象较小，但 GPU 会调整其大小以与显示对象的 transform.matrix 属性匹配：

matrix:Matrix = new Matrix(); // creates an identity matrix 
matrix.scale(0.5, 0.5); // scales the matrix 
mySprite.cacheAsBitmapMatrix = matrix; 
mySprite.cacheAsBitmap = true;

通常，选择的矩阵会将显示对象转换为其将在应用程序中的显示大小。例如，如果您的应用程序显示缩小一半的 Sprite 的位图版本，则应使用缩小一半的矩阵。如果您的应用程序显示的 Sprite 大于其当前尺寸，则使用的矩阵应按该系数放大。

对于设置了 cacheAsBitmapMatrix 属性的显示对象的大小，具有实际限制。该限制为 1020 × 1020 像素。对于设置了 cacheAsBitmapMatrix 属性的所有显示对象的像素总数，具有实际限制。该限制大约为四百万像素。

使用 cacheAsBitmapMatrix 和硬件加速时，需要谨记许多注意事项。有必要了解哪些显示对象应设置该属性，而哪些显示对象不应设置该属性。有关使用此属性的重要信息，请参阅 硬件加速 。

您可以使用 GPU 呈现诊断功能来诊断应用程序调试版本中的 GPU 使用情况。有关详细信息，请参阅 调试 iPhone 应用程序 。

网络注意事项

将以下 URL 方案和 nativigateToURL() 函数配合使用会导致文档在外部应用程序中打开：

str = "mailto:test@example.com"; 
var urlReq:URLReq = new URLRequest(str); 
navigateToURL(urlReq);

str = "sms:1-415-555-1212"; 
var urlReq:URLReq = new URLRequest(str); 
navigateToURL(urlReq);

str = "tel:1-415-555-1212"; 
var urlReq:URLReq = new URLRequest(str); 
navigateToURL(urlReq);

iPhone 应用程序可以依赖安装的自签名根证书在安全事务（例如 https 请求）期间进行服务器身份验证。服务器不仅应该发送分支证书，还应该发送与根证书关联的所有中间证书。