开发者控制台

Windows兼容性指南

Windows兼容性指南

如果您是现有应用的开发者,希望修复特定问题,请参阅Windows故障排除索引

如果您是新应用或现有Android应用的开发者,并希望确保应用与适用于Android™️的Windows子系统兼容,或者如果您是亚马逊应用商店的新手,并想要了解如何将应用移植到Windows 11设备,请浏览以下主题。

要将您的Android应用移植到Windows 11,首先请查看以下主题。

升级到Android 13 - 适用于Android™️的Windows子系统基于Android 13。请更新您的应用以符合Android 13的要求。
主题: 分区存储


为Windows构建 - 了解如何处理特定于Windows的用例。
主题: 输入控件 | 图形 | 窗口管理和大小调整 | 摄像头功能 | 支持x86 ABI架构


处理不支持的功能 - 了解如何处理不支持的功能,包括硬件或软件服务依赖项。
主题: 常用功能 - 不支持 | 常用功能 - 有限支持 | 禁用不支持的广告SDK | 处理不支持的Google Play服务 | 有条件地禁用不支持的功能 | 不支持的功能列表


升级到Android 13

主题: 分区存储

适用于Android™️的Windows子系统基于Android 13。如果您的应用是针对旧版本Android而构建,请升级应用以使其与Android 13功能兼容。

Android开发者文档提供了有关Android不同版本之间区别的重要信息。请查看以下指南,以便过渡到Android 13。

如果您的应用需要文件访问权限,Android 10及更高版本上的特定功能可能会影响您的应用在这些Android版本上的行为,其中包括适用于Android™️的Windows子系统。与文件访问相关的问题通常由分区存储引起。为防止应用遇到文件访问问题,请遵循以下指南。

分区存储

在适用于Android™️的Windows子系统上测试应用时,出现的文件存储问题通常由分区存储引起。分区存储是一项Android功能,在Android 10中引入并在Android 11中强制执行。使用分区存储,应用只能访问其在外部存储上的特定目录以及其所创建的媒体。有关分区存储的更多信息,请参阅有关Android存储用例和最佳实践的Android开发者指南。

↑ 返回顶部


为Windows构建

主题: 输入控件 | 图形 | 窗口管理和大小调整 | 摄像头功能 | 支持x86 ABI架构

为了给用户提供愉悦的使用体验,您的应用需要能够在大屏幕、有窗口的环境中运行,例如适用于Android™️的Windows子系统。在此环境中,可能存在您不需要在移动设备上处理的其他细节问题。请考虑以下主题。如果此处未列出您需要帮助解决的问题,请访问亚马逊开发者论坛寻求开发者社区的帮助。

输入控件

如果应用原本是为Android或其他触摸屏移动设备设计的,那么此类应用可能无法有效处理键盘和鼠标输入。要让应用与非触摸屏Windows设备上可用的输入控件兼容,请遵循本节中的指南。

键盘输入

有关键盘输入设计的注意事项,请参阅有关输入支持的Android开发者指南。有关如何处理键盘输入的详细信息,请参阅以下Android开发者指南:

为了帮助您提供优先考虑键盘的体验,可以使用以下代码检查设备是否配备了键盘:

 

已复制到剪贴板。

private boolean isKeyboardConnected() {
    return getResources().getConfiguration().keyboard == Configuration.KEYBOARD_QWERTY;
}

 

已复制到剪贴板。

private fun isKeyboardConnected(): Boolean {
    return resources.configuration.keyboard == Configuration.KEYBOARD_QWERTY
}

Android框架可能无法自动处理一些Windows应用和游戏常用控件,而您的应用应该能够处理这些控件。在构建与Windows设备兼容的移动应用时,请考虑如何处理以下键盘输入。

  • 回车键
  • 箭头键导航
  • Tab键导航
  • 基于Ctrl键的快捷方式(例如,Ctrl-C用于复制,Ctrl-V用于粘贴)
  • 更改所选项的突出显示颜色
  • W、A、S和D键用于游戏中的移动
  • 空格键用于游戏中的跳跃

示例: 允许玩家在游戏中按Ctrl-J做出特殊动作。

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
    switch (keyCode) {
        ...
        case KeyEvent.KEYCODE_J:
            if (event.isCtrlPressed()) {
                superJumpCombo();
            } 
        ...
        default:
            return super.onKeyUp(keyCode, event);
    }
}
override fun onKeyUp(keyCode: Int, event: KeyEvent): Boolean {
    return when (keyCode) {
        ...
        KeyEvent.KEYCODE_J -> {
            if (event.isCtrlPressed) {
                superJumpCombo()
            } 
            true
        }
        ...
        else -> super.onKeyUp(keyCode, event)
    }
}

鼠标输入

默认情况下,适用于Android™️的Windows子系统会将鼠标左键单击转换为虚拟触控事件,将鼠标滚轮滚动转换为轻扫事件。这样做是为了让大多数面向不会处理鼠标输入的触摸屏构建的应用具有兼容性。对于其他鼠标操作,请更新代码以处理特定的输入。请考虑实现以下操作:

  • 右键单击
  • 拖放
  • 工具提示和悬停文本
  • 悬停效果

按照Android开发者指南学习如何处理鼠标输入:

禁用输入模拟

要让您的应用从鼠标或触摸板接收原始事件并提供更好的硬件支持,请在适用于Android™️的Windows子系统中禁用输入模拟。要禁用鼠标和触摸板模拟,请在应用清单中指定android.hardware.type.pc

<uses-feature android:name="android.hardware.type.pc" android:required="false" />

通过在清单中声明android.hardware.type.pc,您的应用指明,它被设计成可直接处理以下事件:

图形

为了使用户在Windows电脑上运行应用时获得最佳体验,请支持更大的屏幕并在应用中使用增强的图形。请按照以下建议来改善用户在Windows上使用您应用时的体验。

OpenGL ES版本。 适用于Android™️的Windows子系统支持OpenGL ES 1.1、2.0和3.0。目前不支持OpenGL ES 3.1及更高版本。

最大帧速率。 应用在Windows电脑上运行时的帧速率可能会高于在移动设备上运行时的帧速率。要在Windows上实现最佳体验,请将最大帧速率设置为60 FPS或更高,或者取消最大帧速率限制。

用户界面缩放。 确保所有用户界面元素的大小都适合更大的屏幕。建议HUD占屏幕面积小于20%。

宽高比。 要在更大的设备上实现最佳体验,请支持多种宽高比,包括16:9、16:10和3:2。

窗口管理和大小调整

在适用于Android™️的Windows子系统上,应用始终以多窗口模式打开,并且可以由用户调整大小。用户还可以使用Windows的操作让应用窗口贴靠在屏幕的边缘或角落。这些功能可能会导致用户在Windows上使用您的应用时,获得有别于移动设备的体验。

如果您的应用在调整大小时无法正常运行,您可以将应用配置为保持固定的大小或方向,而不考虑显示器大小或设备方向。但是,建议启用多窗口支持,以便在各种尺寸的设备之间实现更好的兼容性。

在适用于Android™️的Windows子系统上,如果应用的方向固定,或者不可调整大小,并且其最大或最小宽高比与设备显示屏的宽高比不一致,则会使用宽银幕边框或黑边框渲染该应用。根据您的应用,您可能希望在应用清单中使用以下一些配置设置来控制应用的方向和大小调整。

  • android:resizeableActivity: 使用该属性来指定对于多窗口模式的支持。有关基于API级别的具体行为,请参阅resizeableActivity的Android文档。
  • android:screenOrientation: 使用该属性来指定应用的方向。要使用该属性,必须将resizeableActivity设置为false。有关该属性的更多详细信息,请参阅screenOrientation的Android文档。
  • android:maxAspectRatio: 使用该属性来指定您的应用支持的最大宽高比。要使用该属性,必须将resizeableActivity设置为false。有关该属性的更多详细信息,请参阅maxAspectRatio的Android开发者文档。
  • android:minAspectRatio: 使用该属性来指定您的应用支持的最小宽高比。要使用该属性,必须将resizeableActivity设置为false。有关该属性的更多详细信息,请参阅minAspectRatio的Android开发者文档。

宽银幕边框和黑边框

当内容的宽高比与包含该内容的显示屏不一致时,无法调整大小的应用可能会出现宽银幕边框或黑边框。在宽银幕边框中,原始内容的宽度大于用户查看该内容时使用的显示屏。为了保持内容的宽高比并查看全宽内容,会在内容顶部和底部添加条形。

白色方框,顶部和底部带有蓝色条形
宽银幕边框

在黑边框中,原始内容的宽度小于用户查看该内容时使用的显示屏。为了保持宽高比,会在两侧添加条形。

白色方框,左右两侧带有蓝色条形
黑边框

添加的条形可以采用浅色或深色主题,具体取决于系统设置。宽银幕边框和黑边框会在对应用进行贴靠、最大化或手动调整大小等操作时出现。

多窗口模式

应用在适用于Android™️的Windows子系统上运行时,会以多窗口模式打开。这可能会导致进行应用最小化、设备屏幕锁定或唤醒处于睡眠状态的电脑等操作时出现问题。

为了防止出现问题,请务必使用正确的窗口机制。有关如何支持窗口机制的详细信息,请参阅有关多窗口支持的Android开发者指南。您还必须处理与多窗口模式相关的活动生命周期,以确保正确保存和加载应用状态。有关详细信息,请参阅有关多窗口模式下的活动生命周期的Android开发者指南。

大小调整的其他注意事项

要让您的移动应用与Windows设备的窗口管理和大小调整功能兼容,请考虑以下主题。

  • 初始启动大小 - 设置应用启动时的显示大小和方向
  • 窗户尺寸
    • 内容边界 - 避免内容被截断或不可访问
    • 任意形状大小调整 - 支持窗口大小调整
  • 屏幕方向 - 考虑支持竖屏和横屏模式

有关每个主题的更多详细信息,请参阅有关窗口管理的Android开发者指南。

摄像头功能

如果您的应用会使用摄像头并且支持Windows设备,请遵循以下指南。

  • 在尝试使用设备的摄像头之前,使用Android的CameraManager API来检查是否有可用的摄像头设备。和移动设备不同,Windows设备可能带有一个摄像头、多个摄像头或是一个外部摄像头,也可能没有摄像头。亚马逊应用商店建议处理针对每种可能出现的情况进行处理。
  • 检查Windows设备的摄像头支持哪些预览尺寸,然后使用这些尺寸拍照和显示预览。
  • 在笔记本电脑等横屏设备上测试应用的方向,并相应地调整旋转角度。
  • 如果遇到“Your hardware doesn't support this application(您的硬件不支持此应用)”错误,则Assets/Plugins/Android/lib/armeabi文件夹中可能存在旧版原生库。构建原生库时,默认情况下会创建x86、armeabi、armeabi-v7a等库的输出。Unity 5.x已经放弃支持armeabi,因此为避免出现此错误,请勿在Unity 5.x或更高版本中使用armeabi。

有关如何在应用中支持摄像头的更多详细信息,请参阅有关摄像头方向的Android开发者文档。

支持x86 ABI架构

大多数Windows设备使用基于x86的英特尔或AMD处理器。适用于Android™️的Windows子系统使用英特尔Bridge Technology在基于x86的处理器上模拟Arm®应用。模拟层会产生性能开销。因此,要实现最佳性能,请同时提交x86-64和Arm64架构的应用。有关如何支持x86 ABI架构的详细信息,请参阅有关如何包含x86 ABI架构的Android开发者指南。

↑ 返回顶部

处理不支持的功能

主题: 常用功能 - 不支持 | 常用功能 - 有限支持 | 禁用不支持的广告SDK | 处理不支持的Google Play服务 | 有条件地禁用不支持的功能 | 不支持的功能列表

某些功能和服务在移动设备上可用,但在适用于Android™️的Windows子系统上不可用,或者可能仅受到有限的支持。当您的应用在Windows上运行时,如果请求使用不支持的功能和服务,则会失败。本节将介绍如何处理应用中不支持的功能。

要检查某个功能或API是否不受支持,可以直接访问此处的不支持功能列表:

适用于Android™️的Windows子系统目前不支持一些系统功能,包括Wi-Fi管理、亮度和声音控制。如果应用具有这些功能之一并在Windows上进行测试,则在尝试控制或访问该功能时可能会遇到问题。要确认某个功能是否不受支持,请参阅不支持的功能

适用于Android™️的Windows子系统上的应用不得更改Windows系统设置。如果应用尝试切换设备的Wi-Fi或声音,则会失败。

如果这些系统依赖项是应用的主要功能,亚马逊应用商店建议等到这些功能受支持后再尝试支持Windows设备。如果这些是应用中的次要功能,在支持Windows设备之前请确保妥善处理异常。

请按照以下建议处理不支持的功能:

  • 对于所有不受适用于Android™️的Windows子系统支持的功能,请在应用清单中的<uses-feature>声明中添加android: required="false"。这仅适用于应用清单中已经声明的功能。例如,要禁用NFC,您的代码可能会如下所示:
    <uses-feature android:name="android.hardware.nfc" android:required="false"/>
    
  • 如果应用中一些功能所依赖的硬件和软件功能不受适用于Android™️的Windows子系统支持,请禁用这些功能。如果使用和移动应用中相同的APK,请使用条件逻辑来禁用适用于Android™️的Windows子系统不支持的功能。有关更多详细信息,请参阅有条件地禁用不支持的功能

常用功能 - 不支持

适用于Android™️的Windows子系统目前不支持以下功能。

自定义Wi-Fi热点。 如果应用会创建自定义热点来托管基于局域网的游戏或传输文件,则该功能可能无法正常运行,因为适用于Android™️的Windows子系统不支持Wi-Fi热点。但是,如果运行应用的设备位于同一个网络上,则应用应该能够创建主机。

连接的音频设备。 在适用于Android™️的Windows子系统上,应用无法检测到连接的音频设备,例如入耳式耳机或头戴式耳机。如果应用需要耳机,并且您使用isAudioConnected方法进行强制验证,请在适用于Android™️的Windows子系统上跳过或忽略此强制验证。

系统声音设置。 适用于Android™️的Windows子系统目前不支持在应用内控制系统声音设置(例如音量)。要优化应用中的声音设置,请参阅有关使用固定音量设备的Android开发者指南。

常用功能 - 有限支持

目前,适用于Android™️的Windows子系统对以下功能提供有限支持。

Wi-Fi。 适用于Android™️的Windows子系统使用虚拟Wi-Fi接口,无法直接显示Wi-Fi信号。如果应用扫描Wi-Fi信号,则会看不到可用的Wi-Fi网络。适用于Android™️的Windows子系统目前不支持Wi-Fi热点和Wi-Fi Direct等其他Wi-Fi功能。如果应用依赖于Wi-Fi扫描或其他Wi-Fi管理功能,则请勿支持Windows设备,因为这些功能会无法运行。

本地网络连接。 如果您的应用能够连接到在同一网络上运行该应用的其他设备,则此功能受支持,但必须启用适用于Android™️的Windows子系统上的高级网络设置。

视频数字版权管理。 支持Widevine L3 DRM和Clearkey DRM。适用于Android™️的Windows子系统不支持Widevine L1、L2和其他视频DRM格式(例如PlayReady)。

音频录制。 适用于Android™️的Windows子系统支持麦克风录音。然而,目前不支持系统音频录制。

请禁用不支持的广告SDK

如果应用会使用广告SDK,那么请务必在Windows上测试应用。要开始在Windows上测试您的应用,请遵循微软的测试和调试指南。

一些广告SDK与适用于Android™️的Windows子系统不兼容。如果广告SDK不兼容,则广告可能无法投放,这可能会导致应用出现问题。如果您的广告SDK会导致任何意外行为,请按照以下指南将其禁用。

  • 禁用所有移动广告单元,包括横幅、插页式广告和广告奖励(这会为观看广告的用户授予应用内奖励)。以下示例所示的方法可以根据广告是否可用来有条件地设置布局。

    boolean adsDisabled = "Subsystem for Android(TM)".equals(Build.MODEL);
    
    if (adsDisabled) {
        setContentView(R.layout.layoutNoAds);
    } else {
        setContentView(R.layout.layoutWithAds);
    }
    
    val adsDisabled = "Subsystem for Android(TM)" == Build.MODEL
    
    if (adsDisabled) {
        setContentView(R.layout.layoutNoAds)
    } else {
        setContentView(R.layout.layoutWithAds)
    }
    
  • 请禁用应用中依赖广告奖励的功能。例如,如果用户必须单击某个按钮观看广告才能获得奖励,请禁用或移除该按钮。
  • 如果使用和移动应用中相同的APK,请使用条件逻辑来仅针对适用于Android™️的Windows子系统进行这些更改。

处理不支持的Google Play服务

Google Play服务不适用于适用于Android™️的Windows子系统。如果您的应用使用Google Play服务,请确保您有启动备选服务的逻辑,或者在服务不可用时优雅降级。请遵循以下指南。

Cloud Messaging 如果您在应用中同时实现了Firebase Cloud Messaging (FCM)和Amazon Device Messaging (ADM),请使用逻辑检查ADM是否可用,并在ADM可用时使用它。有关详细信息,请参阅ADM文档中的Gracefully degrade if ADM is unavailable(在ADM不可用的情况下优雅降级)。

应用内购买 如果您在应用中同时实现了Google应用内结算(IAB)和亚马逊应用内购买(IAP),请使用逻辑检查亚马逊IAP是否可用,并在亚马逊IAP可用时使用它。有关详细信息,请参阅实现在Google Play Billing和IAP之间进行调解的逻辑

地图。 谷歌地图和Amazon Maps不适用于适用于Android™️的Windows子系统。对于Windows,请务必更新您的应用以优雅降级。

有条件地禁用不支持的功能

在有条件地禁用不支持的功能时,应尽可能检查功能是否可用,而不是使用设备检测。这样一来,您就可以维护通用代码库,同时为应用支持多种设备类型。

要检查硬件或软件功能是否可用,请使用Android PackageManager API中的hasSystemFeature()方法。以下示例展示了如何检测设备有没有可用的加速度计。

PackageManager packageManager = context.getPackageManager();
boolean hasAccelerometer = packageManager.hasSystemFeature(PackageManager.FEATURE_SENSOR_ACCELEROMETER);

if (hasAccelerometer) {
  // 此设备上的加速度计可用。
} else {
  // 加速度计*不*可用。请禁用该功能。
}
val packageManager: PackageManager = context.packageManager
val hasAccelerometer: Boolean = packageManager.hasSystemFeature(PackageManager.FEATURE_SENSOR_ACCELEROMETER)

if (hasAccelerometer) {
  // 此设备上的加速度计可用。
} else {
  // 加速度计*不*可用。请禁用该功能。
}

请尽可能使用前一个示例来检测特定功能。如果无法检查特定功能是否可用,请使用以下代码。

if ("Subsystem for Android(TM)".equals(Build.MODEL)) {
  // 应用可在Windows Subsystem for Android上运行
} else {
  // 应用*不可*在Windows Subsystem for Android上运行
}
if ("Subsystem for Android(TM)" == Build.MODEL) {
  // 应用可在Windows Subsystem for Android上运行
} else {
  // 应用*不可*在Windows Subsystem for Android上运行
}

不支持的功能列表

这些列表列出了适用于Android™️的Windows子系统目前不支持的功能。

不支持的硬件功能
硬件功能 应用功能描述
android.hardware.bluetooth 使用蓝牙连接到其他设备;
此功能在WSA中看似可用,但目前不起作用
android.hardware.bluetooth_le 使用蓝牙连接到其他使用低功耗无线电的设备;
此功能在WSA中看似可用,但目前不起作用
android.hardware.camera.autofocus 在摄像头上使用自动对焦
android.hardware.camera.flash 在摄像头上使用闪光灯
android.hardware.camera.level.full 在摄像头上使用FULL级别图像采集支持
android.hardware.consumerir 使用红外(IR)
android.hardware.nfc 使用近场通信(NFC)
android.hardware.nfc.hce 使用NFC卡模拟(已弃用)
android.hardware.sensor.accelerometer 使用加速度计(检测设备方向)
android.hardware.sensor.barometer 使用气压计(检测气压)
android.hardware.sensor.compass 使用指南针(确定方向)
android.hardware.sensor.gyroscope 使用陀螺仪(检测旋转和扭动)
android.hardware.sensor.light 使用光传感器
android.hardware.sensor.magneticfield 使用磁场传感器
android.hardware.sensor.orientation 使用方向传感器
android.hardware.sensor.pressure 使用压力传感器
android.hardware.sensor.proximity 使用接近传感器
android.hardware.sensor.stepcounter 使用计步器
android.hardware.sensor.stepdetector 使用步测器
android.hardware.sensor.temperature 使用温度传感器
android.hardware.telephony 使用电话功能,包括无线电和数据通信服务
android.hardware.telephony.cdma 使用码分多址(CDMA)网络
android.hardware.telephony.gsm 使用全球移动通信系统(GSM)网络
android.hardware.type.automotive 使用汽车设备屏幕用户界面
android.hardware.type.television 使用电视屏幕用户界面(已弃用)
android.hardware.usb.accessory 作为USB配件连接;
此功能在WSA中看似可用,但目前不起作用
android.hardware.usb.host 作为USB主机连接;
此功能在WSA中看似可用,但目前不起作用
不支持的软件功能
软件功能 应用功能描述
android.software.app_widgets 在主屏幕上使用应用小组件;
WSA显示此功能可用,但目前始终处于关闭状态
android.software.device_admin 使用设备策略管理
android.software.home_screen 取代设备的主屏幕
android.software.input_methods 使用InputMethodService中定义的自定义输入法
android.software.leanback 使用电视屏幕用户界面
android.software.live_tv 流式传输电视直播
android.software.live_wallpaper 使用动画壁纸
android.software.managed_users 允许二级用户和受管理的个人资料
android.software.midi 连接到MIDI设备
android.software.sip 使用会话发起协议(SIP),支持视频会议和即时消息
android.software.sip.voip 使用互联网语音传输协议(VoIP),支持双向视频会议
亚马逊网页应用 网页应用
不支持的API
API 替代方案
Google Play应用内结算 使用亚马逊应用内购买API。
请参阅迁移指南
Google Cloud Messaging 使用Amazon Device Messaging。
请参阅迁移指南
谷歌地图 无。适用于Android™️的Windows子系统不支持。

↑ 返回顶部



Last updated: 2023年9月13日