【鸿蒙生态共建】一文说明兼容版本、目标版本和编译版本的区别与应用实践-《精通HarmonyOS NEXT ：鸿蒙App开发入门与项目化实战》读者福利 - 详解

在早期的DevEco Studio版本（如v5.0）中，创建的工程没有配置targetSdkVersion（目标SDK版本）。当使用DevEco Stodio版本及之后的版本（如v5.1）打开之前创建的工程，编译时有WARN提示。

> hvigor WARN: The project has not explicitly set the 'targetSdkVersion' version at build-profile.json5. It is recommended to configure it. 

在DevEco Studio 5.0.5版本之后，新创建的项目，才默认有targetSdkVersion配置项，在《精通HarmonyOS NEXT ：鸿蒙App开发入门与项目化实战》这本书中，没有对targetSdkVersion及相关的配置进行相关的介绍。个人刚接触时也有些不太理解targetSdkVersion（目标SDK版本）与compileSdkVersion（编译SDK版本）及compatibleSdkVersion（兼容SDK版本）的关系。

本篇内容是《精通HarmonyOS NEXT ：鸿蒙App开发入门与项目化实战》这本书第五章内容的延续，是咱这本书读者的福利，在本篇内容会介绍compileSdkVers（编译SDK版本）、targetSdkVersion（目标SDK版本）和compatibleSdkVersion（兼容SDK版本）这三项影响应用兼容性的关键信息，以帮助读者以最合适方式指定目标设备并有效的使用系统提供的API，欢迎大家一同来深入的解，甚至可以当作面试题来学习。

打个广告，对本书感兴趣的同学可以点击以下链接进行购买，或者了解我的班级参加 班级共同学习，点击链接可进入（华为官方活动）

• 机械工业出版社官方京东旗舰店
• 机械工业出版社京东自营旗舰店
• 机械工业出版社官方当当旗舰店

​

往期福利：

1. 【页面路由导航】三步实现页面跳转的完整示例-《精通HarmonyOS NEXT ：鸿蒙App开发入门与项目化实战》读者福利
2. 【鸿蒙生态共建】一文10个示例讲懂鸿蒙系统ArkTS中的null与undefined的区别与应用-《精通HarmonyOS NEXT ：鸿蒙App开发入门与项目化实战》读者福利
3. 【鸿蒙生态共建】一文两表三实例讲清async函数与普通函数的区别-《精通HarmonyOS NEXT ：鸿蒙App开发入门与项目化实战》读者福利
4. 【鸿蒙生态共建】一文说清基础类型数据的非预期输入转换与兜底-《精通HarmonyOS NEXT ：鸿蒙App开发入门与项目化实战》读者福利

1: 基本定义：

1.1:API版本取值定义：

在了解本篇内容之前，先了解在HarmonyOS系统中API版本取值的格式，为M.S.F(N) Stage，如：5.1.0(18)， 其中：

• M取值为1-99，表示API大版本更新。
• S和F取值都为0-99，表示API小版本更新。
• N为OpenHarmony底座的API level，取值为1-99。
• Stage为当前SDK的发布阶段，仅在SDK的版本号中可见，取值为CanaryN/BetaN/[Release]， N为正整数，Release版本发布时可省略Release。

1.2:compileSdkVers、targetSdkVersion和compatibleSdkVersion定义：

compileSdkVers、targetSdkVersion和compatibleSdkVersion在项目的/build-profile.json5中设置，影响应用兼容性的关键信息。定义及说明如下表中所示：

如简介所述，开发应用时使用的SDK版本决定了API能力范围以及具体的API行为。在应用开发过程中，有如下SDK版本属性：

SDK版本属性	源码工程中配置项 （build-profile.json5文件中）	应用打包后的对应字段 （module.json5文件中）	说明
编译应用的SDK版本	compileSdkVersion	compileSdkVersion	编译应用工程的SDK版本，该字段决定了应用开发过程中联想的API范围和使用的工具链版本。 取值默认为DevEco Studio自带的SDK版本，如需显示配置，只能配置为当前DevEco Studio自带的SDK版本。
应用运行的目标SDK版本	targetSdkVersion	targetAPIVersion	应用运行的目标SDK版本。针对系统侧进行API版本隔离的变更，应用在终端设备上运行时会呈现以targetSdkVersion版本为目标版本的行为。 例如当前设备API版本为5.0.2(14)，而运行在该设备上的某应用targetSdkVersion配置为5.0.1(13)，则经过API版本隔离的变更会以5.0.1(13)版本的API行为呈现。在5.0.2(14)发生的API变更不会影响该应用在当前设备的实际表现。 如果应用工程中未填写该字段，则在应用包中该字段默认填写为编译该应用的SDK版本号。 强烈建议开发者在应用工程build-profile.json5中配置targetSdkVersion字段，如果开发者未配置该字段，则该字段取值默认为compileSdkVersion的值。
应用运行的最低SDK版本	compatibleSdkVersion	minAPIVersion	应用运行要求的最低SDK版本。运行该应用的终端设备系统搭载的API版本不能低于该字段的值，低于则无法安装。 该字段版本值不能高于目标SDK版本。 可将compatibleSdkVersion的值设置为较小值，从而可在更低版本的系统上安装该应用，但应用是否能在compatibleSdkVersion对应系统版本上面正常运行，需要开发者针对无法在compatibleSdkVersion版本使用的API进行兼容性判断保护。

1.2.1: 三者取值关系：

 三者关为 compatibleSdkVersion <= targetSdkVersion <= compileSdkVersion. 当在工程配置中不符合此规则时，会报错。

* Try the following:

  > Configure the API version according to the rule of compatibleSdkVersion <= targetSdkVersion <= compileSdkVersion.

2: compileSdkVersion信息

上节的表格中提到，compileSdkVersion是编译应用工程的SDK版本，该字段决定了应用开发过程中联想的API范围和使用的工具链版本。取值默认为DevEco Studio自带的SDK版本，如需显示配置，只能配置为当前DevEco Studio自带的SDK版本。默认项目的/build-profile.json5中也是没有显示的设置该项的信息。

1.1: 如何查看compileSdkVersion信息

如果需要查看compileSdkVersion信息，主要分为两步：

首先先查看DevEco Studio 的版本，在DevEco Studio 关于查看版本，截图如下。

之后在https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/overview-allversion中查看DevEco Studio 对应的版本，如下图，DevEco Studio  5.1.1 Release对应的SDK API版本为5.1.1（19）

2.2: 如何设置compileSdkVersion信息

如需要显示的设置compileSdkVersion信息，在项目的/build-profile.json5中，增加"compileSdkVersion": "5.0.1(13)"，注意5.0.1(13)要与DevEdo Studio的API版本相同，否则会报错，如下所示。

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compileSdkVersion": "5.0.1(13)",

当配置与DevEco Studio的API版本不同时的报错提示

3: targetSdkVersion信息

targetSdkVersion的设置方式，与compileSdkVersion相同，在项目的/build-profile.json5中，增加"targetSdkVersion": "5.0.1(13)"，注意5.0.1(13)要可根据需要进行配置

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "targetSdkVersion": "5.0.1(13)",

对应的截图如下：

3.1:targetSdkVersion信息配置实践

在第一小节中，以文字的方式对targetSdkVersion进行说明。“例如当前设备API版本为5.0.2(14)，而运行在该设备上的某应用targetSdkVersion配置为5.0.1(13)，则经过API版本隔离的变更会以5.0.1(13)版本的API行为呈现。在5.0.2(14)发生的API变更不会影响该应用在当前设备的实际表现。”光看文字很难理解，在实际的研发时应该如何实施，下面举个例示例说明一下。

在官方的文档中，getKeyboardAvoidMode接口返回值在 5.1.0（API 18）版本进行了变更，也就是说在实际开发时，需要注意变更带来的影响。

我们先在EntryAbility的onWindowStageCreate方法中增加以下实现

onWindowStageCreate(windowStage: window.WindowStage): void {
  console.info('俩毛豆 Ability onWindowStageCreate');
  windowStage.loadContent('pages/Index', (err) => {
    let keyboardAvoidMode = windowStage.getMainWindowSync().getUIContext().getKeyboardAvoidMode();
    console.info('俩毛豆 ' + JSON.stringify(keyboardAvoidMode));
  });
}

指定targetSdkVersion 为 5.0.1(13)编译，并在API 14（小于API18即可）的设备上运行输出的日志为：

指定targetSdkVersion 为 5.0.1(13)编译，并在API 20（大于等于API18即可）的设备上运行输出的日志为：

看起来没有什么变化，指定targetSdkVersion 为5.1.0(18)编译，并在API 14（小于API18即可）的设备上运行输出的日志为，还是没什么变化：

指定targetSdkVersion 为 5.1.0(18)编译，并在API 18（大于等于API18即可）的设备上运行输出的日志为，这时该函数返回的值就不同了，故代码处理的逻辑上也需要分别的处理：

可以看出，对于targetSdkVersion的设定，会影响API执行的结果。这时再看官方的文字说明，是不是就更容易理解了，“例如当前设备API版本为5.0.2(14)，而运行在该设备上的某应用targetSdkVersion配置为5.0.1(13)，则经过API版本隔离的变更会以5.0.1(13)版本的API行为呈现。在5.0.2(14)发生的API变更不会影响该应用在当前设备的实际表现。”

4: compatibleSdkVersion信息

在上一节的例子中，可以看出，项目是可以在低于API 18的系统中运行，也可以在高于API 18的系统中运行，是因为最低的运行API版本的设置，受compatibleSdkVersion的配置项影响。即compatibleSdkVersion决定了项目产出的App可以在那些SDK版本的设备中运行。

compatibleSdkVersion信息默认在项目的/build-profile.json5中，如下所示。

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.1(13)",

当该值设定一个较高的版本，如5.1.0(18) 这时targetSdkVersion也需要进行对应的升级。当使用在低版本的系统中运行App时会报错，“compatibleSdkVersion and releaseType of the app do not match the apiVersion and releaseType on the device.”，当App上线之后，在低于5.1.0(18)的系统中也是无法安装，在应用商店中也无法搜索到。

5: API兼容

在实际的研发中，如需要存在API需要在不同的运行系统版本中进行兼容，可以使用以下的代码进行兼容性的判断。

console.info('俩毛豆 deviceInfo.distributionOSApiVersion ' + JSON.stringify(deviceInfo.distributionOSApiVersion));
// 兼容性判断，50100是由新接口的since字段M*10000+F*100+S转换而来
if (deviceInfo.distributionOSApiVersion >= 50100) {
  // 调用5.1.0(18)的API新接口
  console.info('俩毛豆 调用5.1.0(18)的API新接口');
} else {
  // 降级方案
  console.info('俩毛豆 调用降级方案');
}

对应的该代码在API 14（5.0.2），和API 18（5.1.0）的系统中输出的日志为。结合3.1小节的内容，当需要使用高阶API的特性，又需要兼容低版本的设备可使用该方案来保证在低版本的设备中，不执行高阶的API或者对于同一API区别参数或返回值。

总结: 

在本篇的内容中，介绍了targetSdkVersion（目标SDK版本）与compileSdkVersion（编译SDK版本）及compatibleSdkVersion（兼容SDK版本）的关系及实践应用。

这三个配置项，在App研发生命周期会经常性的更改，也会受大环境的影响。合理的配置，会帮助App即可支持新的技术特性，又可以覆盖更广的用户群体，这也是本篇内容的核心价值之一。

最后再打下广告，对本书感兴趣的同学可以点击以下链接进行购买，或者了解我的班级参加 班级共同学习，点击链接可进入（华为官方活动）

• 机械工业出版社官方京东旗舰店
• 机械工业出版社京东自营旗舰店
• 机械工业出版社官方当当旗舰店

​