# APILevelAdapt
**Repository Path**: wustcat404/APILevelAdapt
## Basic Information
- **Project Name**: APILevelAdapt
- **Description**: API兼容性示例demo
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 3
- **Created**: 2025-12-05
- **Last Updated**: 2025-12-13
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 实现多API版本兼容
## 项目介绍
本项目演示在 HarmonyOS 多版本环境下，如何在同一套代码中实现 API 能力探测与优雅降级，进而实现优雅的 API 兼容策略，覆盖 ArkTS层与Native层两类典型场景：
1. **ArkTS（UI 层）**：通过 `deviceInfo.sdkApiVersion` / `deviceInfo.distributionOSApiVersion` 判断系统版本，选择高版本新特性或低版本替代实现。
2. **Native（NAPI/C++ 层）**：
- 通过 `dlopen + dlsym` 对动态库符号进行探测，判断某个系统 API 是否存在，从而避免低版本调用导致崩溃。
- 通过OH_GetDistributionOSApiVersion()获取ISV发行版系统api版本并判断系统版本，选择高版本新特性或低版本特性替代实现。
## 效果图预览
| 首页 | 滚动场景 | 音频音量场景 |
| :------------------------------------------: | :------------------------------------------: | :------------------------------------------: |
| 
| 
| 
|
## 使用说明
1. 将独立的应用示例工程导入DevEco Studio进行编译构建及运行调试。
2. 安装运行后，即可在设备上查看应用示例运行效果，以及进行相关调试。
## 工程目录
```
├──entry/src/main/cpp
│ ├──classdef
│ │ ├──include
│ │ │ ├──ArkUIBaseNode.h // 组件树操作的基类
│ │ │ ├──ArkUINode.h // 通用组件的封装
│ │ │ ├──ArkUIButtonNode.h // 实现按钮组件的封装类
│ │ │ └──NativeModuleInstance.h // ArkUI在Native侧模块的封装接口
│ │ └──src
│ │ ├──ArkUIBaseNode.cpp // 组件树操作的基类
│ │ ├──ArkUINode.cpp // 通用组件的封装
│ │ ├──ArkUIButtonNode.cpp // 实现按钮组件的封装类
│ │ └──NativeModuleInstance.cpp // ArkUI在Native侧模块的封装接口
│ ├──function
│ │ ├──include
│ │ │ ├──IntegratingWithArkts.h // 接入ArkTS界面
│ │ │ └──NativeEntry.h // 管理Native组件生命周期
│ │ └──src
│ │ └──IntegratingWithArkts.cpp // 接入ArkTS界面
│ └──types
│ │ └──libentry
│ │ ├──Index.d.ts // Native侧接口导出声明文件
│ │ └──oh-package.json5
│ ├──CMakeLists.txt // cmake配置文件
│ └──napi_init.cpp // 接口映射、模块注册
├──entry/src/main/ets // 代码区
│ ├──contants
│ │ └──CommonConstants.ets // 常量类
│ ├──entryability
│ │ └──EntryAbility.ets // 程序入口类
│ ├──entrybackupability
│ │ └──EntryBackupAbility.ets // 应用数据备份和恢复类
│ ├──pages
│ │ ├──ActionBarScene.ets // HdsActionBar组件版本兼容示例展示页
│ │ ├──AudioVolumeScene.ets // 音频音量场景兼容示例展示页
│ │ ├──ButtonDisplayScene.ets // Button组件版本兼容示例展示页
│ │ ├──Index.ets // 首页
│ │ ├──MarqueeDisplayScene.ets // 走马灯场景兼容性示例展示页
│ │ └──ScrollScene.ets // 滚动场景兼容示例展示页
│ └──utils
│ └──Logger.ets // 日志工具类
└──entry/src/main/resources // 应用资源目录
```
## 实现说明
本项目采用三类兼容策略：**版本判断**、**能力探测**和**安全装配**，确保应用在不同HarmonyOS版本上优雅运行。
### ArkTS层兼容
- **API版本分支**：通过`deviceInfo.sdkApiVersion`或`deviceInfo.distributionOSApiVersion`判断，选择高版本API或降级实现
- *ActionBar示例*：API 6.0.0+(60000)使用HdsActionBar，低版本用基础组件模拟
- *Text/Marquee*：仅在API 18+启用跑马灯效果
- **特性按需装配**：Scroll组件通过"特性规格表"动态注册API 12/18/20的不同能力，使用WeakSet避免重复绑定
### Native层兼容
- **版本阈值判断**：使用`OH_GetDistributionOSApiVersion()`与预设阈值(如50101对应5.1.1)选择不同UI枚举值
- **动态符号探测**：通过`dlopen/dlsym`检测系统库符号是否存在，避免低版本调用崩溃
- **严格生命周期管理**：Native节点创建与销毁严格配对，防止资源泄漏
## 相关权限
不涉及
## 约束与限制
1. 本示例仅支持标准系统上运行，支持设备：华为手机。
2. HarmonyOS系统：HarmonyOS 6.0.0及以上。
3. DevEco Studio版本：DevEco Studio 6.0.0及以上。
4. HarmonyOS SDK版本：HarmonyOS 6.0.0 SDK及以上。