当前位置：首页 > news >正文

HarmonyKit | 鸿蒙开发：API 废弃与迁移策略——从 pushUrl 到 UIContext

news 2026/7/12 23:06:51

HarmonyKit | 鸿蒙开发：API 废弃与迁移策略——从 pushUrl 到 UIContext

引言：废弃不等于删除

鸿蒙 API 的废弃遵循渐进策略：标记@deprecated→ 编译器输出 warning → 数个版本后可能移除。标记为 deprecated 的 API 仍然可用——但建议尽快迁移。

HarmonyKit 遇到了三个废弃 API：router.pushUrl、router.back、promptAction.showToast。迁移成本低——每个受影响的方法只改一行。本文梳理了废弃原因、迁移路径、版本兼容策略，以及如何建立一套通用的 API 废弃监控流程。

项目仓库：https://atomgit.com/VON-/harmony-kit

三个废弃 API 的迁移

router.pushUrl → getUIContext().getRouter().pushUrl()

废弃原因：多窗口场景下全局路由行为不确定。UIContext 绑定路由确保操作作用于正确的窗口。

// 旧写法import{router}from'@kit.ArkUI';router.pushUrl({url:'pages/tools/JsonFormatter'});// 新写法this.getUIContext().getRouter().pushUrl({url:'pages/tools/JsonFormatter'});

迁移的难点不在于"怎么写"，而在于"需要改多少个文件"。HarmonyKit 中router.pushUrl的调用点分布在 11 个文件（主页 Index.ets + 10 个工具页）。如果没有 grep 工具，手动寻找所有调用点很容易遗漏。

router.back → getUIContext().getRouter().back()

// 旧写法router.back();// 新写法this.getUIContext().getRouter().back();

每个工具页的返回按钮只改一行。10 个工具页共改 10 行。

promptAction.showToast → getUIContext().getPromptAction().showToast()

// 旧写法import{promptAction}from'@kit.ArkUI';promptAction.showToast({message:'已复制到剪贴板'});// 新写法this.getUIContext().getPromptAction().showToast({message:'已复制到剪贴板'});

废弃原因类似——全局promptAction在异步场景（setTimeout、Promise 回调）中会丢失 UI 上下文，导致 Toast 无法弹出。UIContext 绑定保证了异步回调中也能正确弹 Toast。

// 异步场景中的差异性// 旧写法：在 setTimeout 中可能无法弹出setTimeout(()=>{promptAction.showToast({message:'异步完成'});// 可能失败！},1000);// 新写法：UIContext 在异步回调中仍然有效constuiContext=this.getUIContext();setTimeout(()=>{uiContext.getPromptAction().showToast({message:'异步完成'});// 总是成功},1000);

关键点在于：this.getUIContext()必须在同步上下文中调用（组件 build 或事件回调中），但获取到的uiContext实例在异步回调中仍然有效。所以在setTimeout/Promise.then中调用uiContext.getPromptAction()安全无虞。

一次性迁移 vs 渐进迁移

HarmonyKit 选择了"一次性迁移"——在一个版本中同时迁移所有三个废弃 API。理由是：

改动量小：三个 API 的调用点共约 15 处，每个只需改一行
风险可控：迁移后的行为在单窗口场景下与之前完全一致
消除技术债：0 warning 的编译输出让后续开发者不再需要关注"这些 warning 要不要处理"

但在更大的项目中，渐进迁移可能是更好的选择。策略如下：

排优先级：按 API 的废弃影响范围排序。全局 API（如 router）影响面广，优先迁移。局部 API（某个组件的私有方法）可以推迟。
分批提交：每批迁移 1-2 个 API，确保没有回归问题。
兼容层：在迁移完成前，可以写一个简单的兼容函数：

// 兼容层示例（迁移过渡期使用）functionsafePushUrl(url:string,context?:UIContext){if(context){context.getRouter().pushUrl({url});}else{// 回退到旧 API（如果仍然可用）router.pushUrl({url});}}

但这种兼容层方案也有代价：它在鼓励继续使用旧 API。更好的做法是"一次迁移，不留后路"——直接在代码中替换为新的 UIContext 写法。

版本兼容矩阵

API	引入	废弃	推荐替代
router.pushUrl	API 9	API 18	UIContext.getRouter().pushUrl
router.back	API 9	API 18	UIContext.getRouter().back
promptAction.showToast	API 9	API 18	UIContext.getPromptAction().showToast