Console

Settings

Sign out

Notifications

Alexa

亚马逊应用商店

AWS

文档

Support

My Cases

Console

Vega开发者文档

主页

新手入门

设计和开发

应用发布

参考

支持

启用向后兼容性

开放Beta测试文档 作为预发布开放Beta测试的一项内容，亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代，所描述的这些功能可能会发生变化。有关最新功能的信息，请参阅发布说明。

如果您是首次发布应用，则不存在向后兼容性问题。但是，当您更新应用以使用较新版本的@amazon-devices/系统分布式库并重新提交到亚马逊应用商店时，仍包含这些库的较旧版本的设备将无法安装或更新到您的最新应用版本。

适用于Vega的React Native提供了可选的向后兼容性功能，可让您的应用同时支持这些库的较旧版本和新版本。此功能对于维护广泛用户群和在不同系统版本之间提供一致的体验至关重要。

关于系统分布式库

系统分布式库是JavaScript程序包，始终以@amazon-devices/为前缀，预先安装在设备上，以优化应用大小和加载时间。

由于此类库与向后兼容性有关，在设备收到新的闪存或OTA更新之前，这些库中每个库的版本都是静态的。

当系统分布式库的新版本（例如2.1.0）发布时，适用于Vega的React Native将保持与同一主要版本中先前版本（如2.0.0）的兼容性。

选择加入和选择退出

更新应用时，您可以选择加入或选择退出向后兼容性。

选择退出意味着您的应用将仅支持最新版本的系统分布式库，这可以简化开发和测试。但是，选择退出也意味着您的应用将无法安装在运行这些库的较旧版本的设备上。

选择向后兼容需要额外进行代码和配置更改，但会带来显著的好处：

更广泛的设备支持 - 您的应用可以在系统版本较旧的设备上运行。
访问新功能 - 使用新的库功能，同时保持对较旧版本的支持。
单一应用提交 - 一次部署即可支持多个系统版本。
自动验证 - 系统会在安装前验证兼容性。

有时选择退出向后兼容性也是必要的，例如在引入重大更改的主版本更新期间。对于大多数用例，建议选择向后兼容，以便最大限度扩大应用的覆盖范围。

配置向后兼容性支持

安装兼容性库

运行以下命令可安装库：

已复制到剪贴板。

npm install @amazon-devices/kepler-compatibility

定义兼容性要求

要为应用中使用的库指定向后兼容性，您需要在package.json中的kepler块中，将该库的名称及其needs和wants添加到backwardCompatibility。您还应该将兼容性库添加到dependencies部分。

已复制到剪贴板。

  {
    "name": "MyApp",
    "version": "1.0.0",
    "dependencies": {
      "@amazon-devices/kepler-compatibility": "^0",
      "@amazon-devices/react-native-gesture-handler": "2.4.0"
    },
    "kepler": {
      "backwardCompatibility": {
        "@amazon-devices/react-native-gesture-handler": {
          "needs": "2.0.0", // 支持的最小值
          "wants": "<=2.4.0" // 支持的最大值
        }
      },
      ...
    }
  }

needs - 您的应用可以使用的最低版本。该值必须是精确的semver版本。必须存在该版本才能运行您的应用。如果这些模块在设备上不可用，则无法安装您的应用。
wants - 您的应用可以使用的最高版本。该值应设置为包含needs的semver范围。例如，上述范围内的有效wants为：（<2.5.0、<=2.2.0和^2.0.0）。将此值设置为您在提交时验证为有效的最大值。

在代码中添加版本检查

isPresentOnOS API可帮助您在运行时验证系统上是否安装了所需的库版本，当您的代码依赖于特定较旧版本或需要仅在新版本中提供的功能时，这一点尤其重要。

已复制到剪贴板。

import { isPresentOnOS } from '@amazon-devices/kepler-compatibility';
import * as GestureHandler from '@amazon-devices/react-native-gesture-handler';

// 在这个例子中，这个新功能是在2.2.0中引入的
const supportsNewGesture = useMemo(
  () => isPresentOnOS("@amazon-devices/react-native-gesture-handler", "2.2.0"),
  []
);

function MyComponent() {
  // 在使用新发布的功能之前，检查是否有更新的版本可用
  if (supportsNewGesture) {
    // 使用新的2.2.0功能
    return <GestureHandler.NewFeature />;
  } else {
    // 没有2.2.0版本的设备的回退
    return <GestureHandler.LegacyFeature />;
  }
}

测试和验证

在提交应用之前，请务必在装有您在backwardCompatibility块中所指定系统分布式库较旧版本和新版本的设备上进行全面测试。

测试步骤

使用Vega安装不同的模拟器：使用CLI在较旧版本和新版本上安装设备模拟器，这将有助于模拟预安装的系统分布式库的不同现实场景。
安装应用。
验证应用是否按预期运行，特别注意较旧版本的所有版本检查和回退实现，以确保它们正常运行。

示例

添加对新功能的支持

下面的示例向您展示了如何在@amazon-devices/react-native-gesture-handler的DragGesture中添加对所构想的withNewBehaviors属性的支持。这可让您从旧的PanGesture实现中切换，但保留以前的实现，以保持向后兼容较旧库版本。

已复制到剪贴板。

  import { isAppTargeting } from '@amazon-devices/react-native-kepler';
  import * as GestureHandler from '@amazon-devices/react-native-gesture-handler';

  function DraggableItem() {
    if (isAppTargeting("@amazon-devices/react-native-gesture-handler", "2.1.0")) {
      // 使用2.1.0功能的新实现
      return (
        <GestureHandler.DragGesture
          withNewBehaviors={true}
          onDragStart={handleDragStart}
        >
          <Item />
        </GestureHandler.DragGesture>
      );
    }

    // 2.0.0的回退实现
    return (
      <GestureHandler.PanGesture
        onGestureEvent={handleLegacyDrag}
      >
        <Item />
      </GestureHandler.PanGesture>
    );
  }

故障排除

常见问题

下面列出了一些常见问题及其解决方案。

版本不匹配

问题 - 应用无法在某些设备上安装。
解决方案 - 确认您的needs版本不高于目标设备上提供的版本。

运行时错误

问题 - 功能在某些设备上崩溃。
解决方案 - 确保将所有新功能的使用情况都包含在版本检查中。

测试问题

问题 - 难以跨版本进行测试。
解决方案 - 使用设备模拟器对不同的系统版本进行测试。

采用版本检查的性能最佳实践

请务必在组件生命周期中尽早检查版本。
缓存版本检查结果以避免重复检查。
考虑为经常检查的功能集创建效用函数，如下面的示例所示。

已复制到剪贴板。

  // 效用函数示例
  const featureSupport = {
    hasGestures2_1: null as boolean | null,
  };

  export function getGestureHandlerFeatures() {
    if (featureSupport.hasGestures2_1 === null) {
      featureSupport.hasGestures2_1 = isAppTargeting(
        "@amazon-devices/react-native-gesture-handler",
        "2.1.0"
      );
    }

    return {
      // 根据版本返回受支持功能的对象
      supportsHoverGesture: featureSupport.hasGestures2_1,
      supportsPinchToZoom: featureSupport.hasGestures2_1,
      // 根据需要添加其他功能标记
    };
  }

  // 在应用的组件中使用
  function MyGestureComponent() {
    const features = getGestureHandlerFeatures();
    
    if (features.supportsHoverGesture) {
      return <HoverEnabledComponent />;
    }
    return <StandardComponent />;
  }

Last updated: 2025年10月30日