文档开发者中心
我的
|

HarmonyOS

HarmonyOS 应用如何设计一套统一的用户反馈与错误提示机制?

HarmonyOS 应用如何设计一套统一的用户反馈与错误提示机制?

「操作失败了」「为什么没反应」「这个提示看不懂」——这类反馈是用户投诉里占比很高的一类。问题不在于提示不够多,而在于**每个模块各写各的**:同样一个网络失败,在下单页说「请求超时」,在设置页说「网络异常」,在个人页干脆什么都不提示。

这篇聊聊怎么把提示做成一套统一机制。

一、先区分「错误」的三种类型

用户看到的所有提示,本质上只有三种类型,处理方式完全不同:

• **操作成功**:需要明确反馈,让用户确认动作生效了 • **操作失败但可恢复**:需要说明原因 + 提供下一步操作(重试、换个方式) • **操作不可用**:需要明确告知当前不能做,并给出替代路径或原因

很多模块的提示之所以混乱,是因为把第二类当成了第三类处理——网络失败直接弹「不可用」,用户就只能干瞪眼。

二、提示的文案要「可执行」

一条好的错误提示应该包含三个要素:

**发生了什么**(用用户能理解的语言,不用内部术语) **为什么**(简要归因,不要甩锅给用户) **接下来怎么办**(明确的下一步)

对比一下:

• ❌ 「请求失败,错误码 40001」 • ✅ 「提交失败:账号余额不足,请先充值后重试」

前者对用户零信息量,后者用户知道该干什么。我们内部的做法是**错误提示的文案由错误码映射表统一维护**,业务代码只负责抛出错误码,不自己拼文案。

映射表的维护还有一条纪律:**新增错误码必须同时补文案和用户可执行的下一步**,缺一不予合并。这条纪律是靠 Code Review 卡住的。

三、表现形式要按严重程度分级

不是所有提示都用弹窗。我们的分级标准:

| 级别 | 形式 | 使用场景 | |---|---|---| | 提示级 | 轻提示(Toast) | 操作成功、轻微提醒,自动消失 | | 阻塞级 | 弹窗 | 必须用户确认或选择的失败 | | 页面级 | 空状态 / 错误页 | 整个区域不可用,需要引导重试 | | 全局级 | 顶部条 | 影响全局但可继续操作的状态(如网络断开) |

我们踩过的坑是**用 Toast 承载了阻塞级信息**。Toast 会自动消失,用户还没看清就消失了,尤其是错误文案比较长的时候。更糟的是有些团队用 Toast 提示「余额不足」,用户根本来不及反应。

规则很简单:**凡是用户必须做点什么才能继续的,就不能用 Toast**。

四、错误要能追溯到原始上下文

对用户展示的是简化的文案,但对开发者必须保留完整信息。我们的错误对象包含:

• 错误码(业务语义) • 原始异常(技术细节) • 发生时的上下文(哪个操作、哪个页面、关键参数) • 用户可读文案

界面上只展示用户可读文案,但完整信息会随日志上报。这条设计让我们在排查时能拿到完整现场,而用户又不会看到一堆技术术语。

关键的一点是**上下文要在错误发生的时刻采集**,而不是在 catch 块里临时拼。临时拼的上下文经常缺关键信息(比如当时的输入值、当时的页面栈)。

五、不要重复提示同一件事

用户连续触发同一个失败时,不要弹三次一样的提示。我们的做法是加一个「去重窗口」:相同错误码在 N 秒内只提示一次。

同时也要处理**队列**问题:如果短时间内有多个不同的错误发生,不要把弹窗一个个排队弹给用户,那会变成干扰。规则是:**同一时刻只展示最重要的那个,其余合并成一条汇总提示**。

六、网络类错误要统一处理

网络错误是最高频的错误类型,也是最容易各模块各写各的。

我们把它收敛到一个网络层统一处理:

网络层识别出「不可达、超时、服务端错误」等类型,转换为统一的错误码 业务层拿到的是统一的错误类型,可以直接判断是「可重试」还是「不可重试」 展示层根据错误类型决定表现形式:可重试的给「重试」按钮,不可重试的给具体说明

这样业务代码里就不会出现「if (error.message.includes('timeout'))」这种脆弱的判断。

七、给提示文案做可观测

提示文案是用户直接接触的内容,值得单独埋点:

• 哪个错误码被触发的次数最多 • 用户在看到提示后是否重试、是否成功 • 哪些提示被频繁关闭或忽略

我们通过「提示曝光 → 用户动作 → 最终结果」的漏斗,能发现很多隐藏问题。比如某个提示被触发了上万次,但重试后成功率只有 3%,那说明真正的问题不是错误本身,而是**用户本来就不该走到那个分支**。

总结

统一提示机制的关键是:**错误分三类、文案可执行、形式按严重度分级、错误可追溯、同类提示要去重、网络错误统一收敛、文案本身可观测。**

这件事的收益比看起来大——它既能降低用户的困惑和投诉,也能通过「提示漏斗」反过来发现业务流程里的设计问题。投入的却是很小的成本:一张错误码到文案的映射表,加上一层统一的选择逻辑。

点赞
收藏
回复
2
分享
举报
浏览22 发布于6天前广东
全部评论
最多点赞
最新发布
最早发布

补一个实现时很关键的边界:统一的是错误语义和展示策略,不宜让网络层直接持有全局Toast或弹窗入口。否则页面退出、多窗口或自动重试时,提示会落到错误页面,甚至重复弹出。

可以把链路拆成:
底层返回技术结果 → 业务层判断操作结果 → 当前界面的反馈协调器选择表现形式。
错误对象保留code、operationId、作用域、是否可恢复、用户动作和traceId;展示文案用本地资源键映射,原始异常留在脱敏诊断中。未知错误也要有默认分支,不能把服务端message直接显示给用户。

去重键建议至少包含“操作/对象 + 错误码 + 窗口/页面”,而不只是错误码。同样的余额不足,两个不同订单不能因为时间接近就吞掉后一笔的反馈;同一操作在网络层、业务层和页面各catch一次,也只允许一个明确的展示责任方。

异步结果到达时先校验页面会话或请求代次。用户取消、切换账号、已离开页面的旧请求,仍可记录结果,但通常不应再把阻塞框弹到当前页面。结果未知(例如提交超时)也不能直接提示“未提交,请再次提交”:先查询最终状态,必要重试沿用原幂等键,避免用户按提示产生重复操作。

HarmonyOS侧,PromptAction应从对应UIContext的getPromptAction获取。官方接口强调与UI上下文关联;服务层只发语义事件,由仍有效的界面上下文展示,不把一个窗口的UIContext做成永久全局单例。

验收可覆盖:同一请求三层捕获只提示一次、两笔独立操作不被错误合并、旧页面回调不抢当前页面、多窗口各自反馈、取消不报失败,以及重试确实能推进业务。再补屏幕朗读与大字体检查,不能只确认肉眼看到Toast就算完整反馈。以上为设计建议,未在你的工程运行。
官方PromptAction及UIContext使用:
https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-promptaction/

2楼回复于6天前 来自湖北
AI 生成内容,仅供参考

在 HarmonyOS 应用中落地一套统一的用户反馈与错误提示机制,核心思路是把「错误产生 → 统一错误模型 → 分级分发 → 展示与上报」收敛为一条独立链路,业务模块只负责抛出带上下文的统一错误对象,不自行拼文案、不自行选弹窗形式。下面结合 ArkTS/ArkUI 的实际能力,给出完整的设计方案与可运行示例。

一、整体架构

错误从产生到用户看到提示,建议按下面的链路收敛:

业务或网络层发生错误

统一错误模型
错误码+原始异常+上下文

错误码映射表
查用户文案与级别

提示管理器
去重+按级别分发

提示级 Toast

阻塞级 AlertDialog

页面级 空状态

全局级 顶部条

日志与埋点上报
保留完整现场

对应到 HarmonyOS 的技术选型:

分层 职责 推荐能力
错误模型 统一错误对象,携带错误码、原始异常、发生上下文 自定义 class,配合 BusinessError
映射表 错误码到「用户文案 + 下一步 + 严重级别」的映射 Map + 静态目录类
提示管理器 去重窗口、按级别分发、日志上报 UIContext.getPromptAction()、UIContext.showAlertDialog()
网络层收敛 把 BusinessError 转成统一错误码 @kit.NetworkKit 的 http 模块
可观测 提示曝光与用户动作埋点 @kit.PerformanceAnalysisKit 的 hilog / hiAppEvent

二、统一错误模型与映射表

业务代码只抛错误码,文案全部由映射表维护。新增错误码必须同时补齐「用户文案 + 可执行下一步 + 严重级别」,否则映射表查询会走兜底逻辑,在 Code Review 中可直接卡住。

收起
自动换行
深色代码主题
复制
// common/AppError.ets
// 错误码:全应用统一维护,业务语义命名
export enum ErrCode {
  NET_TIMEOUT = 1001,        // 网络超时
  NET_UNREACHABLE = 1002,    // 网络不可达
  SERVER_ERROR = 1003,       // 服务端错误
  BALANCE_INSUFFICIENT = 2001, // 余额不足
  SUBMIT_FAILED = 2002,      // 提交失败
  FEATURE_UNAVAILABLE = 3001 // 功能暂不可用
}

// 提示级别:决定展示形式
export enum PromptLevel {
  TOAST = 0,   // 提示级:自动消失
  DIALOG = 1,  // 阻塞级:必须用户确认或选择
  PAGE = 2,    // 页面级:整区域不可用,引导重试
  GLOBAL = 3   // 全局级:顶部条,可继续操作
}

// 错误元数据:用户文案 + 可执行下一步 + 级别 + 是否可重试
export interface ErrorMeta {
  userMessage: string
  actionHint: string
  level: PromptLevel
  retryable: boolean
}

// 统一错误对象:对用户只暴露 userMessage,对开发者保留完整现场
export class AppError {
  readonly code: ErrCode
  readonly rawMessage: string   // 原始技术信息,仅用于日志
  readonly context: string      // 发生时的上下文:哪个操作、哪个页面、关键参数
  readonly occurredAt: number

  constructor(code: ErrCode, rawMessage: string, context: string) {
    this.code = code
    this.rawMessage = rawMessage
    this.context = context
    this.occurredAt = Date.now()
  }

  // 用户可读文案:从映射表获取,业务代码不自行拼接
  userMessage(): string {
    return ErrorCatalog.meta(this.code).userMessage
  }
}

// 错误码映射表:文案统一维护的唯一入口
export class ErrorCatalog {
  private static table: Map<ErrCode, ErrorMeta> = ErrorCatalog.build()

  private static build(): Map<ErrCode, ErrorMeta> {
    const t: Map<ErrCode, ErrorMeta> = new Map()
    const timeout: ErrorMeta = {
      userMessage: '网络连接超时',
      actionHint: '请检查网络后重试',
      level: PromptLevel.DIALOG,
      retryable: true
    }
    const unreachable: ErrorMeta = {
      userMessage: '当前网络不可用',
      actionHint: '请检查网络连接后重试',
      level: PromptLevel.DIALOG,
      retryable: true
    }
    const serverError: ErrorMeta = {
      userMessage: '服务暂时不可用',
      actionHint: '我们正在抢修,请稍后重试',
      level: PromptLevel.DIALOG,
      retryable: true
    }
    const balance: ErrorMeta = {
      userMessage: '提交失败:账号余额不足',
      actionHint: '请先充值后重试',
      level: PromptLevel.DIALOG,
      retryable: false
    }
    const submitFail: ErrorMeta = {
      userMessage: '提交失败,请稍后重试',
      actionHint: '',
      level: PromptLevel.TOAST,
      retryable: true
    }
    const unavailable: ErrorMeta = {
      userMessage: '该功能暂不可用',
      actionHint: '可先使用其他功能,我们正在加急恢复',
      level: PromptLevel.PAGE,
      retryable: false
    }
    t.set(ErrCode.NET_TIMEOUT, timeout)
    t.set(ErrCode.NET_UNREACHABLE, unreachable)
    t.set(ErrCode.SERVER_ERROR, serverError)
    t.set(ErrCode.BALANCE_INSUFFICIENT, balance)
    t.set(ErrCode.SUBMIT_FAILED, submitFail)
    t.set(ErrCode.FEATURE_UNAVAILABLE, unavailable)
    return t
  }

  // 查询元数据,未登记的错误码走兜底,避免用户看到裸错误码
  static meta(code: ErrCode): ErrorMeta {
    const meta: ErrorMeta | undefined = this.table.get(code)
    if (meta !== undefined) {
      return meta
    }
    const fallback: ErrorMeta = {
      userMessage: '操作失败,请稍后重试',
      actionHint: '',
      level: PromptLevel.TOAST,
      retryable: true
    }
    return fallback
  }
}

两个关键点:一是上下文在错误发生时刻采集并随对象携带,而不是在 catch 块里临时拼,保证排查时有完整现场;二是文案三要素(发生了什么、为什么、怎么办)全部落在映射表里,业务代码无法绕开。

三、提示管理器:分级分发与去重

提示管理器负责两件事:按严重级别选择展示形式;对同一错误码做去重窗口控制。凡是用户必须做点什么才能继续的,一律走弹窗,不用 Toast。

收起
自动换行
深色代码主题
复制
// common/FeedbackManager.ets
import { UIContext, PromptAction } from '@kit.ArkUI'
import { hilog } from '@kit.PerformanceAnalysisKit'
import { AppError, ErrCode, PromptLevel, ErrorCatalog } from './AppError'

export class FeedbackManager {
  // 去重窗口:记录每个错误码最近一次提示时间
  private static lastShownAt: Map<ErrCode, number> = new Map()
  private static readonly DEDUP_MS: number = 3000

  // 统一入口:所有错误提示都从这里走
  static showError(ui: UIContext, err: AppError, onRetry?: () => void): void {
    const now: number = Date.now()
    const last: number = this.lastShownAt.get(err.code) ?? 0
    if (now - last < this.DEDUP_MS) {
      return // 去重窗口内不重复提示
    }
    this.lastShownAt.set(err.code, now)

    const meta = ErrorCatalog.meta(err.code)
    const prompt: PromptAction = ui.getPromptAction()
    switch (meta.level) {
      case PromptLevel.TOAST:
        // 提示级:轻微提醒,自动消失
        prompt.showToast({ message: meta.userMessage, duration: 2500 })
        break
      case PromptLevel.DIALOG:
        // 阻塞级:必须用户确认,可重试的给重试按钮
        ui.showAlertDialog({
          title: meta.userMessage,
          message: meta.actionHint,
          autoCancel: false,
          confirm: {
            value: meta.retryable ? '重试' : '知道了',
            action: () => {
              if (meta.retryable && onRetry !== undefined) {
                onRetry()
              }
            }
          }
        })
        break
      default:
        // PAGE / GLOBAL 级由页面状态或全局组件承接,这里只做日志
        break
    }
    // 完整现场随日志上报:错误码 + 原始异常 + 上下文 + 时间
    hilog.error(0x0000, 'Feedback',
      `code=${err.code} raw=${err.rawMessage} ctx=${err.context} at=${err.occurredAt}`)
  }

  // 操作成功的统一反馈入口
  static showSuccess(ui: UIContext, message: string): void {
    ui.getPromptAction().showToast({ message: message, duration: 2000 })
  }
}

四、网络层统一收敛

网络错误是最高频也最容易各写各的一类,收敛原则是:网络层识别异常类型并转换为统一错误码,业务层拿到的永远是 AppError,直接判断可否重试,不再出现对错误消息文本的脆弱判断。

收起
自动换行
深色代码主题
复制
// common/NetClient.ets
import { http } from '@kit.NetworkKit'
import { BusinessError } from '@kit.BasicServicesKit'
import { AppError, ErrCode } from './AppError'

// 把底层 BusinessError 转换为统一错误码
function mapNetError(err: BusinessError, context: string): AppError {
  // http 模块错误码在 2300000 段,按类型归并
  if (err.code === 2300003 || err.code === 2300006 || err.code === 2300028) {
    return new AppError(ErrCode.NET_TIMEOUT, `code=${err.code} msg=${err.message}`, context)
  }
  return new AppError(ErrCode.NET_UNREACHABLE, `code=${err.code} msg=${err.message}`, context)
}

// 统一请求入口:context 在调用点采集,保证现场完整
export async function getJson(url: string, context: string): Promise<string> {
  const httpInst: http.HttpRequest = http.createHttp()
  try {
    const resp: http.HttpResponse = await httpInst.request(url, {
      method: http.RequestMethod.GET,
      connectTimeout: 10000,
      readTimeout: 10000,
      expectDataType: http.HttpDataType.STRING
    })
    if (resp.responseCode >= 500) {
      throw new AppError(ErrCode.SERVER_ERROR, `http ${resp.responseCode}`, context)
    }
    if (resp.responseCode >= 400) {
      throw new AppError(ErrCode.SUBMIT_FAILED, `http ${resp.responseCode}`, context)
    }
    const body: string = typeof resp.result === 'string' ? resp.result : ''
    return body
  } catch (e) {
    if (e instanceof AppError) {
      throw e // 统一错误直接透传
    }
    throw mapNetError(e as BusinessError, context)
  } finally {
    httpInst.destroy()
  }
}

五、页面侧使用示例

页面级错误用状态驱动渲染空状态页,阻塞级和提示级交给提示管理器,业务代码只写一次 try-catch。

收起
自动换行
深色代码主题
复制
// pages/DemoPage.ets
import { AppError, PromptLevel, ErrorCatalog } from '../common/AppError'
import { FeedbackManager } from '../common/FeedbackManager'
import { getJson } from '../common/NetClient'

@Entry
@Component
struct DemoPage {
  // 页面级错误状态:整区域不可用时渲染错误页
  @State pageError: AppError | null = null
  @State isLoading: boolean = false

  private async loadOrder(): Promise<void> {
    this.isLoading = true
    try {
      // 上下文在发起请求的时刻采集
      const body: string = await getJson('https://www.example.com/order', 'DemoPage.loadOrder')
      this.pageError = null
      FeedbackManager.showSuccess(this.getUIContext(), '下单成功')
    } catch (e) {
      if (e instanceof AppError) {
        const meta = ErrorCatalog.meta(e.code)
        if (meta.level === PromptLevel.PAGE) {
          this.pageError = e // 页面级:交给错误状态页
        } else {
          // 阻塞级/提示级:统一管理器分发,重试回调重新触发加载
          FeedbackManager.showError(this.getUIContext(), e, () => {
            this.loadOrder()
          })
        }
      }
    } finally {
      this.isLoading = false
    }
  }

  build() {
    Column({ space: 12 }) {
      if (this.pageError !== null) {
        // 页面级错误:空状态 + 引导,而不是弹窗
        Column({ space: 8 }) {
          Text('加载失败')
            .fontSize(18)
          Text(this.pageError.userMessage())
            .fontColor('#666666')
          Button('重新加载')
            .onClick(() => {
              this.loadOrder()
            })
        }
        .width('100%')
        .padding(32)
      } else {
        Text('订单内容区域')
          .fontSize(16)
      }
      Button('提交订单')
        .onClick(() => {
          this.loadOrder()
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

六、补充说明

关于 Toast 的使用边界,showToast 的 duration 取值区间为 1500ms 到 10000ms,但长文案场景不要依赖加长 Toast 解决——用户往往来不及看完,凡是需要用户做出动作才能继续的信息必须走弹窗。另外 Toast 不支持应用退至后台后继续展示,后台提醒需改用 Notification Kit 的本地通知。

关于弹窗的细节,showAlertDialog 默认会抢占焦点,如果页面存在正在输入的文本框,弹窗会导致键盘收起、打断用户操作。这类场景可通过自定义弹窗并设置 focusable: false 避免抢焦点。

关于可观测性,提示曝光、用户是否点击重试、重试是否成功这条漏斗,可以用 @kit.PerformanceAnalysisKit 中的 hiAppEvent 打自定义事件,配合 hilog 输出的完整错误现场(错误码、原始异常、发生上下文),即可支撑「哪个错误码触发最多、重试成功率多低」这类分析,反过来发现业务流程设计问题。

关于全局级顶部条(如网络断开提示),建议用一个常驻的自定义组件监听统一错误总线(可用 AppStorage 或 emitter 事件做载体),只在 GLOBAL 级别错误出现时渲染,避免与页面级错误状态互相干扰。

这套机制的维护成本就是一张映射表加一层分发逻辑,收益是全应用提示的文案、形式、去重、上报全部一致,排查问题时也能拿到完整现场。

展开全部
1楼回复于6天前 来自广东
写回答
新增插入模板功能
一键使用模板,快速填写内容,轻松发帖~
知道了
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。

我要发帖子

了解社区公约,与您携手共创和谐专业的开发者社区。