羽球场边工具 HarmonyOS 元服务实战（06）：链接失败时的本地回退体验

外部交接失败时页面不应失去控制

场边工具在交接到关联应用前，计分、排阵和算钱入口仍然应留在当前页面。链接不可用时，最差的体验是系统弹窗消失后用户不知道该继续做什么；本地回退把信息放回触发动作附近。

openLink 的 Promise 只说明请求是否被接收，真正的目标处理结果还会进入 completionHandler。两个通道分别处理同步异常和完成回调失败，避免只覆盖其中一种失败形态。

请求接受和目标处理完成是两段状态

this.showJumpFailure = false; context.openLink(MAIN_APP_LINK, { appLinkingOnly: false, hideFailureTipDialog: true, parameters: { target: 'toolbox', source: 'quickBadmintonTools' }, completionHandler });

发起跳转前先清除旧提示，失败后写入固定的、面向用户的文案并打开本地提示状态。页面没有销毁当前工具卡片，用户关闭提示后仍可继续计分或选择其他工具。

失败提示如何回到当前页面

onRequestFailure(elementName, message): void { owner.jumpFailureMessage = '主应用链接暂不可用，请稍后重试'; owner.showJumpFailure = true; }

hideFailureTipDialog 让页面承担统一的异常表达，而不是与系统默认提示叠加。这个选择不会把失败吞掉：日志保留 element 和 message，界面保留可见的继续路径。

同步异常与回调失败共用同一出口

回退区域只依赖 showJumpFailure 与 jumpFailureMessage 两个状态，关闭动作只复位本地状态，不再触发一次链接请求。这样网络恢复与再次尝试由用户明确发起。

为什么要隐藏系统默认失败弹窗

.catch((error: BusinessError) => { this.jumpFailureMessage = '主应用链接暂不可用，请稍后重试'; this.showJumpFailure = true; });

场边工具在交接到关联应用前，计分、排阵和算钱入口仍然应留在当前页面。链接不可用时，最差的体验是系统弹窗消失后用户不知道该继续做什么；本地回退把信息放回触发动作附近。

hideFailureTipDialog 让页面承担统一的异常表达，而不是与系统默认提示叠加。这个选择不会把失败吞掉：日志保留 element 和 message，界面保留可见的继续路径。

用不可达交接结果检查回退界面

if (this.showJumpFailure) { Text(this.jumpFailureMessage) Text('知道了').onClick(() => this.showJumpFailure = false) }

回退区域只依赖 showJumpFailure 与 jumpFailureMessage 两个状态，关闭动作只复位本地状态，不再触发一次链接请求。这样网络恢复与再次尝试由用户明确发起。

openLink 的 Promise 只说明请求是否被接收，真正的目标处理结果还会进入 completionHandler。两个通道分别处理同步异常和完成回调失败，避免只覆盖其中一种失败形态。

关键实现片段

import { router } from '@kit.ArkUI'; import { bundleManager, common, CompletionHandler } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { hilog } from '@kit.PerformanceAnalysisKit'; import { AppColors, AppSizes, AppText } from '../common/Theme'; import { Routes } from '../common/Routes'; const DOMAIN: number = 0x0000; const JUMP_TAG: string = 'MainAppJump'; const MAIN_APP_LINK: string = 'https://kuqideharmonyos.drcn.agconnect.link/2m4d'; @Entry @Component struct Index { @State recommendationExpanded: boolean = false; @State showJumpFailure: boolean = false; @State jumpFailureMessage: string = '主应用链接暂不可用，请稍后重试'; openMainApp(): void { const context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; const owner: Index = this; this.showJumpFailure = false; const completionHandler: CompletionHandler = { onRequestSuccess(elementName: bundleManager.ElementName, message: string): void { hilog.info(DOMAIN, JUMP_TAG, 'OpenLink completion success, message: %{public}s, element: %{public}s', message, JSON.stringify(elementName)); }, onRequestFailure(elementName: bundleManager.ElementName, message: string): void { hilog.error(DOMAIN, JUMP_TAG, 'OpenLink completion failure, message: %{public}s, element: %{public}s', message, JSON.stringify(elementName)); owner.jumpFailureMessage = '主应用链接暂不可用，请稍后重试'; owner.showJumpFailure = true; } }; hilog.info(DOMAIN, JUMP_TAG, 'Open main app aggregate link click, uri: %{public}s', MAIN_APP_LINK); context.openLink(MAIN_APP_LINK, { appLinkingOnly: false, hideFailureTipDialog: true, parameters: { target: 'toolbox', source: 'quickBadmintonTools' }, completionHandler: completionHandler }) .then(() => { hilog.info(DOMAIN, JUMP_TAG, 'OpenLink request accepted.'); }) .catch((error: BusinessError) => { hilog.error(DOMAIN, JUMP_TAG, 'Failed to open main app aggregate link, code: %{public}d, message: %{public}s', error.code, error.message); this.jumpFailureMessage = '主应用链接暂不可用，请稍后重试'; this.showJumpFailure = true; }); } toggleRecommendation(): void { this.recommendationExpanded = !this.recommendationExpanded; } @Builder HeroSection() { Row() { Column() { Text('羽球场边工具') .fontSize(38) .fontWeight(FontWeight.Bold) .fontColor(AppColors.WHITE) .width('100%'); Text('计分、排阵、算钱，开场前少一点手忙脚乱') .fontSize(AppText.BODY) .fontColor(AppColors.WHITE) .opacity(0.92) .margin({ top: AppSizes.GAP_SM }) .width('100%'); } .layoutWeight(1) .alignItems(HorizontalAlign.Start); Image($r('app.media.startIcon')) .width(136)

请求接受和目标处理完成是两段状态、失败提示如何回到当前页面与同步异常与回调失败共用同一出口共同约束了这条处理链：输入先被归类，计算或异步调用只在定义的入口发生，页面随后读取一个明确的结果。把这些判断分散在按钮回调里会让一次重进、一次重复点击或一次失败返回都变成难以定位的差异。

为什么要隐藏系统默认失败弹窗不是事后补上的提示，而是模型在边界条件下仍然要给出的答案。用户只需要看到可继续的操作，模块内部则保留足够的状态来解释为什么当前结果是这样。

实施取舍

发起跳转前先清除旧提示，失败后写入固定的、面向用户的文案并打开本地提示状态。页面没有销毁当前工具卡片，用户关闭提示后仍可继续计分或选择其他工具。

回退区域只依赖 showJumpFailure 与 jumpFailureMessage 两个状态，关闭动作只复位本地状态，不再触发一次链接请求。这样网络恢复与再次尝试由用户明确发起。

外部交接失败时页面不应失去控制所对应的数据不应依赖临时文本或视图顺序。将事实保留为字段、记录或令牌，能够让同一动作在再次进入页面后得到一致的解释，也为后续把能力收敛为轻量组件留下稳定边界。

操作验证

回退区域只依赖 showJumpFailure 与 jumpFailureMessage 两个状态，关闭动作只复位本地状态，不再触发一次链接请求。这样网络恢复与再次尝试由用户明确发起。

在验证过程中，先观察初始状态，再执行唯一的主题动作，最后回读结果区或系统状态。若输入不满足条件，页面应给出可理解的分支；若条件恢复，用户可以从当前页面再次发起操作，而不需要退出并重新建立上下文。

更多系统能力可参考 HarmonyOS 开发者文档。

规则落到界面之前

外部交接失败时页面不应失去控制不是展示层的装饰语，而是决定输入如何进入状态、状态如何产生结果的约束。场边工具在交接到关联应用前，计分、排阵和算钱入口仍然应留在当前页面。链接不可用时，最差的体验是系统弹窗消失后用户不知道该继续做什么；本地回退把信息放回触发动作附近。

失败提示如何回到当前页面需要把可复算的数据留在模型里：发起跳转前先清除旧提示，失败后写入固定的、面向用户的文案并打开本地提示状态。页面没有销毁当前工具卡片，用户关闭提示后仍可继续计分或选择其他工具。

为什么要隐藏系统默认失败弹窗要求页面把正常路径与异常路径放到同一个可观察范围中。回退区域只依赖 showJumpFailure 与 jumpFailureMessage 两个状态，关闭动作只复位本地状态，不再触发一次链接请求。这样网络恢复与再次尝试由用户明确发起。

当用户重复点击、修改输入或离开后再回来时，结果应当来自已定义的状态和规则，而不是依赖某一次组件渲染的偶然顺序。

状态变化应可复盘，结果应可解释，并且能在下一次操作时继续被用户使用。每一次状态迁移都应保留足够的业务语义：用户能看懂当前结果，维护者能从输入、规则和结果之间还原处理过程。把边界条件写成明确分支，能够避免异常发生时把旧结果误当成新结果，也让后续扩展不必回到页面里寻找隐式判断。