HarmonyOS 7 实战开发 05：把页面做到可上线状态

李游Leo

940人浏览 · 2026-09-15 11:26:45

李游Leo 鸿蒙领航者 · 2026-09-15 11:26:45 发布

前面四篇把工作台的框架、交互、性能、适配都搞定了，页面看着已经挺像那么回事。但离真正上线还有距离——用户打开应用不能白屏，断网不能直接崩，退出再进来状态不能丢。这篇讲工程收尾的事情，都是细节，但没做好就是没法上线。

很多人开发的时候只顾着功能实现，忽略了异常处理和数据持久化。Demo 阶段没问题，真给用户用，各种奇奇怪怪的问题都来了。这篇就把我们项目上线前做的那些收尾工作讲一讲。

数据持久化架构图

数据持久化：Preferences 存用户偏好

用户上次打开应用时选了哪个导航、滚动到了哪里，这些信息要存下来。下次打开应用直接恢复，不用用户重新操作一遍。

HarmonyOS 提供了 Preferences 轻量存储，适合存小的键值对。我们项目里存了用户的主题选择、默认导航项、上次阅读位置。

下面是封装的 Preferences 工具类，文件位置在 utils/PreferenceUtil.ets：

import preferences from '@ohos.data.preferences';

export class PreferenceUtil {
  private static preferencesInstance: preferences.Preferences | null = null;
  private static readonly STORE_NAME = 'workbench_prefs';

  // 初始化 Preferences
  static async init(context: Context) {
    if (!this.preferencesInstance) {
      this.preferencesInstance = await preferences.getPreferences(
        context,
        this.STORE_NAME
      );
    }
  }

  // 保存选中的导航 ID
  static async saveSelectedNavId(navId: number) {
    await this.preferencesInstance?.put('selected_nav_id', navId);
    await this.preferencesInstance?.flush();
  }

  // 读取选中的导航 ID
  static async getSelectedNavId(): Promise {
    const value = await this.preferencesInstance?.get('selected_nav_id', 0);
    return value as number;
  }

  // 保存上次阅读位置
  static async saveLastReadPosition(itemId: string) {
    await this.preferencesInstance?.put('last_read_item', itemId);
    await this.preferencesInstance?.flush();
  }

  // 清除所有数据（退出登录时用）
  static async clear() {
    await this.preferencesInstance?.clear();
    await this.preferencesInstance?.flush();
  }
}

在 EntryAbility 的 onCreate 里初始化，页面 aboutToAppear 的时候读取。这样用户每次打开应用，都能回到上次离开的位置。

注意：Preferences 是异步的，不要在 build 方法里同步调用。读取数据放在 aboutToAppear 里，读到了再更新 @State，UI 自动刷新。

异常兜底：断网、空数据、加载失败

用户打开应用，网络慢怎么办？接口报错怎么办？列表是空的怎么办？这些情况都要有兜底 UI，不能直接白屏或者崩掉。

我们在 ContentList 组件里做了三态处理：加载中、空数据、错误。之前第二篇讲过思路，这里讲一下具体的异常处理逻辑：

@Component
export struct ContentList {
  @Prop items: ContentItem[] = [];
  @Prop isLoading: boolean = false;
  @Prop errorMsg: string = '';
  onRetry: () => void = () => {};

  build() {
    if (this.isLoading) {
      // 加载中：显示 loading
      this.LoadingView()
    } else if (this.errorMsg) {
      // 错误状态：显示错误信息和重试按钮
      this.ErrorView()
    } else if (this.items.length === 0) {
      // 空数据：显示空状态提示
      this.EmptyView()
    } else {
      // 正常列表
      this.NormalListView()
    }
  }

  @Builder
  LoadingView() {
    Column() {
      LoadingProgress()
        .width(40)
        .height(40)
      Text('加载中...')
        .fontSize(14)
        .fontColor('#999999')
        .margin({ top: 12 })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }

  @Builder
  ErrorView() {
    Column() {
      Text(this.errorMsg)
        .fontSize(14)
        .fontColor('#ff4444')
        .textAlign(TextAlign.Center)
      Button('重新加载')
        .margin({ top: 16 })
        .backgroundColor('#007aff')
        .onClick(() => {
          this.onRetry();
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }

  @Builder
  EmptyView() {
    Column() {
      Text('暂无内容')
        .fontSize(14)
        .fontColor('#999999')
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

这套三态处理看起来简单，但真到线上很重要。我们上线前测试了弱网、断网、接口超时等各种情况，确保每种状态都有友好提示，不会出现白屏或者崩溃。

页面三态处理流程图