【鸿蒙生态共建】鸿蒙6适配-API变化与兼容(2.UI交互与基础能力篇)--《精通HarmonyOS NEXT ：鸿蒙App开发入门与项目化实战》读者福利

作者：俩毛豆日期：2025/10/15

HarmonyOS开发者版本6.0.0（API 20）Release（鸿蒙6）在2005年9月25日正式发布。相对于HarmonyOS 5.0版本增加了多项新能力及对已有能力的优化。同时也有部分API进行了变更。

本篇内容是《精通HarmonyOS NEXT ：鸿蒙App开发入门与项目化实战》这本书整体内容的延续，是咱这本书读者的福利，内容以本书的示例作为基础，适配鸿蒙6过程中，所需要完成的调整。并将这些调整记录分享给大家，本篇内容主要介绍与UI交互与基础能力的鸿蒙6兼容适配。

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

往期福利：

1: 第7章示例源码：'px2fp'/'vp2px'/'px2vp'/'px2lpx' has been deprecated.

界页UI相关的研发中，经常性使用vp2px或px2vp等接口用于计算单位的转换。在早期的API版本中，vp2px、px2vp等接口是ArkUI的全局接口，该接口已经标为废弃，不推荐使用。当UI实例不明确时，使用默认屏幕的虚拟像素比进行转换，可能会存在转换后结果与预期不一致的情况。

在DevEco Studio 6中编译出提示警告，如下图所示：

现阶段，UIContext的vp2px、px2vp等接口为推荐的替代接口，能保证调用时UI实例已经创建，并返回正确的结果。

UIContext实例调用vp2px,px2vp等接口的方式，在API 12版本开始生效，如果是纯血鸿蒙的App，可以直接使用下面的方法进行API的升级。

在UIAbility中调用：在onWindowStageCreate的方法里，执行windowStage.loadContent之后，可以通过windowStage.getMainWindowSync().getUIContext();获取UIContext实例，之后再使用UIContext实例调用vp2px或px2vp。
在自定义组件中调用：通过this.getUIContext(); 获取UIContext实例，之后再使用UIContext实例调用vp2px或px2vp。
在其它模块中调用：根据模块的调用关系，确定使用的UIContext实例，将该实例用为参数传入模块内，通过该实例调用vp2px或px2vp。

2: 第7章示例：display.getDefaultDisplaySync(),Function may throw exceptions. Special handling is required.

在鸿蒙系统中，App可以通过display.getDefaultDisplaySync()获取默认的dispaly。常见的写法为先使用一变量对获取的display存储，之后再对其相关信息进行操作，示例如下：

const ScreenInfo = display.getDefaultDisplaySync(); const displayHeight = ScreenInfo.height; const displayWidth = ScreenInfo.width;

在DevEco Studio 6.0版本以编译上述代码时会提示警告Function may throw exceptions. Special handling is required.如下图所示

将上述代码增加try catch，警告即可解除。

try { const ScreenInfo = display.getDefaultDisplaySync(); const displayHeight = ScreenInfo.height; const displayWidth = ScreenInfo.width; } catch (error) { hilog.info(0x0000, '俩毛豆', '%{public}s', getDefaultDisplaySync error Cause: ${JSON.stringify(error)}); }

3:第8章示例：'decodeWithStream' has been deprecated.（非流式解码）

Uint8Array 是常用的数据格式，通常用于网络请求，文件读取。因为数据的组织是8位Uint的Array，里面存的是数字，在开发调试时不是很方便。

在实际的使用时，也需要对其进行解码，转为具体的字符。

decodeWithStream方法在从API version 9开始支持，从API version 12开始废弃，官方建议使用decodeToString替代，当使用decodeWithStream时，编译会报警告如下图所示。decodeToString方法在API 12开始支持，仅支持HarmonyOS NEXT的App，可以直接升级了。

下面的代码为使用decodeToString进行非流式解码的代码示例

// 原内容，俩毛豆，是不是不易查看 let uint8Data = new Uint8Array( [228,191,169,230,175,155,232,177,134]);

// 使用decodeToString let textDecoderOptions: util.TextDecoderOptions = { fatal: false, ignoreBOM : true } let decodeToStringOptions: util.DecodeToStringOptions = { stream: false }; let textDecoder = util.TextDecoder.create('utf-8', textDecoderOptions); let decodeToStr = textDecoder.decodeToString(uint8Data, decodeToStringOptions); console.info("tran decodeToString = " + decodeToStr); // tran decodeToString = 俩毛豆

对应的输出日志截图

4:第9章示例：geoLocationManager.on/off Function may throw exceptions. Special handling is required.

通过geoLocationManager.on/off('locationChange')可开启/关闭位置变化订阅，并发起定位请求。但是会产生异常， Function may throw exceptions. Special handling is required.如下所示。

规避该警告的方式，需要对geoLocationManager.on/off增加try...catch。如下代码所示。

continuousRequest() { let request: geoLocationManager.ContinuousLocationRequest= { 'interval': 1, 'locationScenario': geoLocationManager.UserActivityScenario.NAVIGATION } let locationCallback = (location:geoLocationManager.Location):void => { console.log('BULocaltionManager locationChange data: ' + JSON.stringify(location)); }; try { geoLocationManager.on('locationChange', request, locationCallback); } catch (err) { console.info("BULocaltionManager continuousRequest errCode:" + JSON.stringify(err)); } }

stopCRequest() { try { geoLocationManager.off('locationChange'); } catch (err) { console.error("errCode:" + err.code + ", message:" + err.message); } }

5: 第10章示例：'decodeWithStream' has been deprecated.（流式解码）

在研发过程中，网络通信、文件操作等场景通常需要使用数据流的方式进行数据处理。decodeWithStream方法为此提供了高效的流式解码能力，支持对分块到达的二进制数据进行实时解码。在网络数据流传输、大文件分块读取及分布式设备通信等场景中发挥关键作用，通过逐块解码的方式显著提升处理效率，降低内存消耗，确保数据处理的实时性和系统性能。

decodeWithStream方法在从API version 9开始支持，从API version 12开始废弃，官方建议使用decodeToString替代，当使用decodeWithStream时，编译会报警告如下图所示。decodeToString方法在API 12开始支持，仅支持HarmonyOS NEXT的App，可以直接升级了。

下面的代码为使用decodeToString方法及decodeToString进行流式解码的代码示例

// 下面的代码模拟从网络或文件流中分三次接收的数据块，使用decodeToString进行解码。 // 中文"俩毛豆"的UTF-8编码：[228,191,169,230,175,155,232,177,134] const dataChunks: Uint8Array[] = [ // "俩" 的完整字节 + "毛" 的部分字节 (230) new Uint8Array([228, 191, 169, 230]), // "毛" 的剩余字节 (175 155) + "豆" 的部分字节 (232) new Uint8Array([175, 155, 232]), // "豆" 的剩余字节 (177 134) new Uint8Array([177, 134]) ];

// 创建解码器配置 let textDecoderOptions: util.TextDecoderOptions = { fatal: false, // 遇到无效字节不抛出异常 ignoreBOM: true // 忽略字节顺序标记 };

// 创建解码操作配置 - 使用流模式 let decodeToStringOptions: util.DecodeToStringOptions = { stream: true // 启用流式处理 };

// 创建UTF-8解码器实例 let textDecoder = util.TextDecoder.create('utf-8', textDecoderOptions); let finalResult = ''; console.log("开始流式解码...");

// 模拟分三次接收并处理数据 for (let i = 0; i < dataChunks.length; i++) { console.log(处理第${i + 1}个数据块，字节数: ${dataChunks[i].length}); console.log([数据块${i + 1}十六进制: [${Array.from(dataChunks[i]).map(b => b.toString(16)).join(', ')}]](function toString() { [native code] }));

// 解码当前数据块 let partialResult = textDecoder.decodeToString( dataChunks[i] as Uint8Array, decodeToStringOptions );

console.log(第${i + 1}次解码结果: "${partialResult}"); console.log("---");

// 累积结果 if (partialResult) { finalResult += partialResult; } }

// 处理完成后，需要调用一次非流式解码以确保所有缓存数据被处理 let flushOptions: util.DecodeToStringOptions = { stream: false // 关闭流模式，刷新缓冲区 };

// 传入空数据来刷新解码器 let flushResult = textDecoder.decodeToString( new Uint8Array(0) as Uint8Array, flushOptions ); if (flushResult) { console.log(刷新缓冲区得到: "${flushResult}"); finalResult += flushResult; } console.log(最终解码结果: "${finalResult}"); // 输出: "俩毛豆"

执行结果日志如下：

总结:

本文针对《精通HarmonyOS NEXT ：鸿蒙App开发入门与项目化实战》读者提供鸿蒙6.0兼容适配方案，重点解决5个关键API变更：1）废弃的vp2px/px2vp单位转换接口需改用UIContext实例调用；2）display.getDefaultDisplaySync()需增加try-catch异常处理；3）废弃的decodeWithStream编解码接口需升级为decodeToString；4）geoLocationManager.on/off需封装异常捕获；5）流式解码需采用新的分块处理

《【鸿蒙生态共建】鸿蒙6适配-API变化与兼容(2.UI交互与基础能力篇)--《精通HarmonyOS NEXT ：鸿蒙App开发入门与项目化实战》读者福利》是转载文章，点击查看原文。

上一篇：告别异常继承树：从 NopException 的设计看“组合”模式如何重塑错误处理

下一篇：什么是断言？