1. 项目概述：当游戏遇见万能卡片

最近在HarmonyOS 3.1上折腾一个挺有意思的东西：把游戏的关键信息，比如角色状态、资源数量、离线收益，甚至是一键快捷操作，直接做成一个“万能卡片”放在桌面上。这可不是简单的应用图标，而是一个能实时刷新、可交互的“游戏信息窗口”。想象一下，你不用打开游戏App，在桌面划一下，就能看到体力恢复了多少、今日任务还剩几个、甚至能直接领取每日登录奖励，这种体验对于手游玩家来说，无疑是效率和沉浸感的双重提升。

这个“游戏万能卡片”项目，本质上是在探索HarmonyOS原子化服务能力与游戏场景深度结合的可能性。HarmonyOS的万能卡片提供了应用信息外显和轻量交互的入口，而游戏，尤其是那些注重日常运营、拥有丰富状态信息的游戏，恰恰是这种能力的绝佳应用场景。它解决的不仅仅是“少点一次图标”的便捷性问题，更深层次的是，它试图将游戏的核心循环（登录、资源收集、任务完成）与系统的日常使用流无缝整合，让游戏体验变得更“无感”和“即时”。

无论你是HarmonyOS应用开发者，想为自己的游戏产品增加一个吸引用户的亮点功能；还是对鸿蒙生态开发感兴趣的爱好者，想学习如何利用原子化服务能力；亦或是单纯觉得这个点子很酷，想了解其背后的技术实现，这篇内容都将为你拆解从设计思路到代码实现的完整路径。我会基于一个假设的“冒险者日记”卡牌养成游戏场景，带你一步步实现一个功能完备的游戏万能卡片。

2. 核心设计思路与架构选型

在动手写代码之前，理清设计思路和选择合适的技术架构至关重要。这决定了卡片的稳定性、性能以及未来的可扩展性。

2.1 需求场景分析与卡片形态定义

首先，我们需要明确这个游戏卡片要展示什么，以及用户能做什么。以“冒险者日记”为例，我梳理了以下几个核心场景：

  1. 状态总览 ：用户最关心角色的当前状态。卡片上需要清晰展示玩家昵称、等级、体力值/精力值、主要货币（金币、钻石）数量。这些信息需要实时或准实时更新。
  2. 快捷操作 ：提供最高频的“一键式”操作。例如，一键领取所有可领取的邮件奖励、一键完成每日签到、一键使用体力药剂。这些操作能极大减少用户打开完整App的动机。
  3. 进度提示 ：提示用户即将完成或已错过的关键事项。比如，今日日常任务完成进度（3/5）、副本挑战次数剩余、限时活动倒计时。这能有效提升用户粘性和日活。
  4. 个性化与装饰 ：允许用户选择喜欢的角色立绘作为卡片背景，或者展示当前使用的角色头像，增加卡片的归属感和美观度。

基于这些场景，我决定设计两种尺寸的卡片：

  • 2x2（小尺寸） ：专注于核心状态和1个最关键的快捷操作（如领取体力）。信息密度高，适合作为桌面监控小部件。
  • 2x4（中尺寸） ：展示更全面的信息，包括状态、2-3个快捷操作和进度提示。这是主力卡片尺寸。

2.2 技术架构：为什么选择“FA模型+Service Ability+数据管理”？

HarmonyOS提供了多种开发范式，对于万能卡片，目前主流且功能完整的是基于FA（Feature Ability）模型的实现。这里我详细解释一下选型理由和整体架构。

整体架构图（文字描述） ： 整个系统由三大部分组成：

  1. UI层（卡片提供方） ：即 FormAbility ，它负责卡片的UI布局渲染和与用户的直接交互。它本身不处理复杂逻辑或网络请求。
  2. 逻辑层（服务提供方） ：即 Service Ability ，它是一个在后台运行、无界面的能力。它负责所有重逻辑：向游戏服务器请求数据、进行本地数据处理、管理定时更新任务。 FormAbility 通过 IPC （进程间通信）调用 Service Ability 的方法来获取数据和执行操作。
  3. 数据层 ：包括 轻量级偏好数据库 用于存储卡片实例信息、用户配置（如选择的角色皮肤）和缓存从服务器获取的游戏数据，以减少网络请求和提升加载速度。

为什么这么设计？

  • 职责分离与性能 ：卡片UI需要快速响应，如果让 FormAbility 直接去请求网络，在弱网环境下会导致卡片长时间白屏或卡死，体验极差。将耗时操作剥离到后台Service，能保证UI线程的流畅。
  • 生命周期管理 ：卡片可能会被用户移除，但后台定时更新任务（如每隔30分钟同步一次游戏数据）需要持续。 Service Ability 可以独立于卡片UI存在，更好地管理这些后台任务。
  • 数据一致性 ：多个同款卡片（比如用户添加了2个相同游戏的卡片）应该共享同一份数据源。通过一个中心化的 Service Ability 管理数据，可以保证所有卡片看到的信息是一致的。

注意 ：虽然Stage模型是鸿蒙未来的方向，并且功能更强大，但在万能卡片的生态成熟度和资料丰富度上，FA模型目前仍是更稳妥的选择，特别是对于需要兼容较早HarmonyOS 3.1版本的开发。本项目基于FA模型实现。

2.3 开发环境与前置准备

在开始编码前，请确保你的环境已就绪：

  1. IDE ：安装DevEco Studio 3.1或更高版本。建议从官网下载，确保SDK完整。
  2. SDK ：在DevEco Studio中，确保已安装HarmonyOS 3.1.0 (API 9) 或对应的SDK。
  3. 项目创建 ：新建一个 Empty Ability 项目，选择 FA 模型， Java 语言（本文以Java为例，JS/ArkTS原理相通）。
  4. 权限声明 ：在 config.json 中提前声明可能用到的网络权限、获取设备信息等权限。 
    "reqPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  },
  {
    "name": "ohos.permission.GET_NETWORK_INFO"
  }
]
  5. 模拟器或真机 ：准备一个HarmonyOS 3.1的手机或模拟器用于调试。卡片开发强烈建议使用真机，因为涉及桌面交互，模拟器可能支持不完整。

3. 核心实现步骤拆解

接下来，我们进入具体的实现环节。我会按照开发流程，逐一拆解关键步骤。

3.1 卡片配置与布局设计

卡片的所有静态信息都在 resources/base/profile/ 目录下的 form_config.json 文件中定义。这是卡片的“身份证”和“蓝图”。

{
  "forms": [
    {
      "name": "game_widget",
      "description": "$string:game_widget_description", // 描述信息
      "src": "./js/widget/pages/index/index", // JS卡片的页面路径，如果是Java卡片则是ability的路径
      "uiSyntax": "hml", // 使用HML+CSS+JS的类Web开发范式
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "colorMode": "auto",
      "isDefault": true,
      "updateEnabled": true, // 启用更新
      "scheduledUpdateTime": "10:30", // 定时更新时间，每天
      "updateDuration": 1, // 更新频率，1为每天
      "defaultDimension": "2*2", // 默认尺寸
      "supportDimensions": ["2*2", "2*4"] // 支持的尺寸
    }
  ]
}

关键点解析 ：

  • updateEnabled 和 scheduledUpdateTime ：这配置了卡片的 定时更新 。系统会在每天指定的时间（如10:30）触发卡片更新。但这对于游戏卡片远远不够，我们还需要更频繁的 主动更新 ，这需要后面在代码中调用 updateForm 接口实现。
  • supportDimensions ：这里定义了支持的尺寸。我们需要为 2*2 和 2*4 分别创建对应的布局文件。

布局文件设计 ： 在 resources/base/profile/ 目录下，为每个尺寸创建对应的 .hml 、 .css 、 .js 文件。例如 game_widget_2x2.hml 。

  • HML（结构） ：使用基础的 div 、 text 、 image 组件搭建。重点是为每个需要动态更新的元素（如体力值文本、按钮）绑定一个 id 或数据字段。 
    <!-- game_widget_2x2.hml 片段 -->
<div class="container">
    <image src="{{cardBackground}}" class="bg-image"></image>
    <div class="header">
        <text class="player-name">{{playerName}}</text>
        <text class="player-level">Lv.{{playerLevel}}</text>
    </div>
    <div class="stats">
        <div class="stat-item">
            <image src="common/stamina_icon.png"></image>
            <text class="stat-value">{{currentStamina}}/{{maxStamina}}</text>
        </div>
        <!-- 更多资源项... -->
    </div>
    <div class="action-button" onclick="quickClaim">
        <text>领取体力</text>
    </div>
</div>
  • CSS（样式） ：定义卡片的视觉样式。注意卡片有圆角限制，背景可以使用渐变色或半透明毛玻璃效果提升质感。
  • JS（逻辑） ：页面的初始数据、生命周期回调（ onInit ， onReady ）和事件处理函数（ quickClaim ）在这里定义。但注意，这里的JS 不直接处理网络请求 ，它只负责调用 FormAbility 提供的方法。

3.2 后台服务（Service Ability）的实现

这是整个卡片的大脑。我们创建一个 GameDataService ，继承自 Ability 。

1. 定义与FormAbility的通信接口 在 GameDataService 中，我们通过 onConnect 返回一个 IRemoteObject ，通常是 RemoteObject 的子类，来实现IPC。这里我定义一个内部类 GameDataRemoteObject 。

public class GameDataService extends Ability {
    private MyRemote remoteObj = new MyRemote();

    @Override
    protected IRemoteObject onConnect(Intent intent) {
        super.onConnect(intent);
        return remoteObj;
    }

    class MyRemote extends RemoteObject implements IRemoteBroker {
        @Override
        public IRemoteObject asObject() {
            return this;
        }

        @Override
        public boolean onRemoteRequest(int code, MessageParcel data, MessageParcel reply, MessageOption option) {
            // 根据code分发不同的请求
            switch (code) {
                case REQUEST_GET_PLAYER_DATA:
                    // 从数据源（网络/缓存）获取玩家数据
                    PlayerData playerData = fetchPlayerData();
                    // 将playerData序列化到reply中，返回给调用方
                    break;
                case REQUEST_CLAIM_STAMINA:
                    boolean result = claimStaminaFromServer();
                    reply.writeBoolean(result);
                    break;
                default:
                    // ...
            }
            return true;
        }
    }
}

2. 实现数据获取与缓存逻辑 在 fetchPlayerData() 方法中，我们需要：

  • 检查网络 ：使用 ConnectionManager 判断网络状态。
  • 缓存策略 ：首先尝试从本地 Preferences 数据库读取缓存。如果缓存存在且未过期（例如，设置缓存5分钟有效），则直接返回缓存数据，保证卡片瞬间显示。
  • 网络请求 ：如果无缓存或缓存过期，则使用 HttpURLConnection 或第三方库（如OkHttp）向游戏服务器发起请求。 这里务必注意，游戏服务器需提供一套专门针对卡片的轻量级API接口 ，返回精简的JSON数据，而不是完整的游戏数据包。
  • 更新缓存 ：获取到网络数据后，解析并更新本地缓存，同时将新数据返回。

3. 实现定时更新机制 除了卡片配置的每日定时更新，我们还需要更细粒度的更新，比如每30分钟同步一次数据。这可以在 Service 的 onStart 中启动一个 Handler 或 TimerTask 来实现。

private Handler mHandler = new Handler(Looper.getMainLooper());
private Runnable mUpdateRunnable = new Runnable() {
    @Override
    public void run() {
        // 执行数据更新逻辑
        updateAllCardsData();
        // 30分钟后再次执行
        mHandler.postDelayed(this, 30 * 60 * 1000);
    }
};

@Override
public void onStart(Intent intent) {
    super.onStart(intent);
    // 延迟5秒启动第一次更新，避免启动时拥堵
    mHandler.postDelayed(mUpdateRunnable, 5000);
}

updateAllCardsData() 方法需要获取所有已创建的该游戏卡片的ID，然后为每个卡片调用 updateForm 方法。卡片ID可以在卡片创建时，由 FormAbility 通知 Service 进行注册管理。

3.3 卡片提供方（FormAbility）的桥梁作用

FormAbility 是连接卡片UI和后台Service的桥梁。它主要做三件事：

1. 卡片生命周期管理 

public class FormAbility extends Ability {
    @Override
    protected void onStart(Intent intent) {
        super.onStart(intent);
    }

    // 当卡片被创建时调用
    @Override
    protected ProviderFormInfo onCreateForm(Intent intent) {
        // 根据intent中的尺寸信息，加载对应的布局
        int dimension = intent.getIntParam(FormConstant.PARAM_FORM_DIMENSION_KEY, 0);
        ProviderFormInfo formInfo = new ProviderFormInfo();
        if (dimension == FormConstant.DIMENSION_2X2) {
            formInfo.setJsComponentName("game_widget_2x2");
        } else if (dimension == FormConstant.DIMENSION_2X4) {
            formInfo.setJsComponentName("game_widget_2x4");
        }
        // 将卡片ID发送给Service，进行注册
        registerCardToService(formId);
        return formInfo;
    }

    // 当卡片被销毁时调用
    @Override
    protected void onDeleteForm(long formId) {
        super.onDeleteForm(formId);
        // 通知Service注销该卡片ID
        unregisterCardFromService(formId);
    }
}

2. 提供JS接口（JS FA卡片） 对于JS卡片， FormAbility 需要将方法暴露给前端JS调用。这通过 FeatureAbility 的 callAbility 或自定义 Native 接口实现。

在 FormAbility 中：

// 声明一个供JS调用的方法，用于获取玩家数据
@JavascriptInterface
public String getPlayerData() {
    // 连接GameDataService，调用REQUEST_GET_PLAYER_DATA，获取数据后转为JSON字符串
    return playerDataJson;
}

在前端JS中：

// 通过FeatureAbility调用原生方法
let playerData = await FeatureAbility.callAbility({
    bundleName: ‘your.bundle.name‘,
    abilityName: ‘FormAbility‘,
    method: ‘getPlayerData‘,
    data: []
});
// 解析playerData，并更新到HML绑定的变量中

3. 处理卡片消息（主动更新） 当后台Service通过 updateForm 请求更新卡片时，会触发 FormAbility 的 onUpdateForm 方法。在这里，我们需要处理从Service传递过来的最新数据，并更新卡片。

@Override
protected void onUpdateForm(long formId) {
    super.onUpdateForm(formId);
    // 从Service获取最新数据
    Object latestData = getLatestDataFromService();
    // 将数据更新到指定的卡片实例
    updateFormData(formId, latestData);
}

3.4 数据流转与状态同步详解

这是整个系统最核心的部分，理解数据如何流动至关重要。

场景一：用户添加卡片到桌面

  1. 用户长按应用图标，选择“服务卡片”，添加一个2x2尺寸的卡片。
  2. 系统调用 FormAbility.onCreateForm() ，卡片被实例化，获得一个唯一的 formId 。
  3. FormAbility 将 formId 通过IPC发送给 GameDataService 的 registerCard 方法。Service将这个ID存入一个列表。
  4. 卡片UI（JS）初始化，调用 FormAbility 暴露的 getPlayerData() 接口。
  5. FormAbility 连接 GameDataService ，请求数据（ REQUEST_GET_PLAYER_DATA ）。
  6. GameDataService 执行 fetchPlayerData() 逻辑：先读缓存，若有则立即返回；若无或过期，则发起网络请求，等待返回后更新缓存再返回。
  7. 数据通过IPC层层返回，最终由JS前端渲染到卡片上。

场景二：后台定时更新

  1. GameDataService 中的定时器触发，执行 updateAllCardsData() 。
  2. 该方法遍历已注册的所有 formId 列表。
  3. 对每个 formId ，Service调用 updateForm(formId, new FormBindingData(latestData)) 。
  4. 系统通知 FormAbility.onUpdateForm(formId) 。
  5. FormAbility 收到通知后，主动从Service拉取最新数据，并更新对应卡片。

场景三：用户点击卡片按钮

  1. 用户点击卡片上的“领取体力”按钮，触发JS中的 onclick 事件。
  2. JS调用 FormAbility 暴露的 claimStamina() 接口。
  3. FormAbility 连接 GameDataService ，调用 REQUEST_CLAIM_STAMINA 。
  4. GameDataService 向游戏服务器发起领取请求。
  5. 服务器处理成功，返回结果。
  6. Service收到成功结果后， 立即 调用 updateForm ，触发卡片数据刷新，让用户立刻看到体力值增加。

实操心得 ：数据同步的可靠性是关键。一定要处理好网络异常、服务重启等情况。我的做法是在Service中维护一个健壮的卡片ID列表，并持久化到 Preferences 中。这样即使Service被系统回收后重建，也能恢复任务，继续为已存在的卡片服务。

4. 进阶功能与性能优化

基础功能实现后，我们可以考虑一些提升体验的进阶功能。

4.1 实现动态卡片与个性化配置

让卡片“活”起来，不止于数据刷新。

  • 动画效果 ：在领取奖励、数值增长时，可以添加简单的Lottie动画或帧动画。例如，点击领取后，金币图标有一个轻微弹跳和数字滚动增加的动画。这需要在JS前端实现，注意动画性能，避免卡顿。
  • 主题切换 ：在卡片上提供一个设置按钮（如一个小齿轮图标），点击后跳转到一个轻量级的配置页面（另一个Ability），让用户选择卡片背景图、显示哪些信息等。这些配置项保存在 Preferences 中，并在卡片渲染时读取。
  • 条件式UI ：根据数据动态改变UI。例如，当体力已满时，“领取体力”按钮变为灰色不可点击状态；当有未读邮件时，在邮箱图标上显示一个红色角标。这通过JS中根据数据绑定不同的样式类来实现。

4.2 性能优化与功耗控制

卡片作为常驻桌面的组件，必须非常注重性能和功耗。

  1. 数据更新频率合理化 ：
    • 实时性要求高的数据 （如限时活动倒计时）：采用 Service 中短间隔定时器（如每分钟）更新，但更新时先检查数据是否有实质变化，无变化则不触发卡片刷新。
    • 变化慢的数据 （如玩家等级、昵称）：依赖卡片配置的每日定时更新，或结合用户主动打开App时由App通知卡片更新。
    • 用户交互触发更新 ：任何卡片上的操作（如领取）成功后，立即触发一次更新。
  2. 内存与缓存优化 ：
    • 图片资源使用 PixelMap 进行高效解码和缓存，避免重复加载。
    • 网络返回的JSON数据，在解析成对象后，及时释放原始字符串所占内存。
    • 本地缓存设置合理的过期时间和最大条目限制，定期清理。
  3. 网络请求优化 ：
    • 所有请求必须设置超时（如10秒），并做好失败处理，显示友好的默认状态（如“网络异常”）。
    • 对请求进行合并。例如，一个请求同时获取玩家基础信息、资源、任务进度，而不是分多个请求。
    • 使用 gzip 压缩减少传输数据量。

4.3 测试与调试技巧

卡片开发调试有其特殊性。

  • 多尺寸测试 ：务必在2x2和2x4两种尺寸下充分测试UI布局，确保在不同屏幕密度的设备上都不会出现错位、遮挡。
  • 生命周期测试 ：反复测试添加卡片、移除卡片、重启设备、清理后台进程后，卡片数据和定时任务是否能恢复正常。
  • 使用HiLog高效调试 ：在 Service 和 FormAbility 的关键节点添加 HiLog.info() 打印日志。通过 hdc shell hilog 命令实时抓取日志，观察数据流转和异常。 
    HiLog.info(LABEL, “GameDataService: fetchPlayerData called, useCache=%{public}b“, useCache);
  • 模拟网络环境 ：在DevEco Studio的设备管理器中，可以模拟2G/3G等弱网环境和高延迟，测试卡片的加载和降级表现。

5. 常见问题与排查实录

在实际开发中，我遇到了不少坑。这里记录下最典型的几个问题和解决方法。

5.1 卡片不更新或更新延迟

  • 现象 ：后台数据变了，但桌面卡片一直显示旧数据。
  • 排查 ：
    1. 首先检查 GameDataService 的定时任务是否正常启动。查看日志，确认 mUpdateRunnable 是否按计划执行。
    2. 检查 updateForm 是否被成功调用。在调用 updateForm 前后打日志，确认参数 formId 是否正确。
    3. 确认 FormAbility.onUpdateForm 方法是否被触发。如果没有，可能是卡片ID管理出了问题， Service 中存储的 formId 列表有误或已失效。
    4. 一个常见陷阱 ： updateForm 的调用必须在主线程。如果在 Service 的子线程中获取数据后直接调用 updateForm ，可能会不生效。需要使用 MainHandler post到主线程执行。 
      getUITaskDispatcher().asyncDispatch(() -> {
    try {
        FormBindingData bindingData = new FormBindingData(createUpdateDataMap());
        FormController.getInstance().updateForm(formId, bindingData);
    } catch (FormException e) {
        HiLog.error(LABEL, “Update form failed: “ + e.getMessage());
    }
});

5.2 卡片布局错乱或显示异常

  • 现象 ：文字溢出、图片拉伸、在不同尺寸手机上显示不一致。
  • 排查 ：
    1. CSS单位 ：优先使用 vp （虚拟像素）和 fp （字体像素）进行布局和字体设置，而不是 px ，以确保不同屏幕的适配。
    2. 多尺寸适配 ：确保为每个 supportDimensions 都提供了独立的HML/CSS文件，并进行充分测试。不要试图用一套布局适配所有尺寸。
    3. 图片资源 ：提供不同分辨率的图片（ base/medium/high 目录），系统会根据设备密度自动选择。确保图片尺寸合理，避免过大导致内存占用高，过小导致模糊。
    4. 使用DevEco Studio的预览器，快速切换不同的设备和尺寸进行视觉检查。

5.3 后台Service被系统终止

  • 现象 ：一段时间后，卡片定时更新停止，需要重新打开一次App才能恢复。
  • 排查与解决 ： 这是Android/HarmonyOS系统常见的后台进程管理策略。为了提升保活能力，可以采取以下措施：
    1. 前台服务通知（谨慎使用） ：如果卡片更新确实需要高实时性，可以考虑将 GameDataService 提升为前台服务，并在通知栏显示一个持续的通知（如“正在同步游戏状态”）。但这会相对耗电，且需要向用户解释，体验不一定好。
    2. 利用系统事件拉活 ：监听网络状态变化、时间变化等广播，在收到事件时尝试重启更新任务。在 config.json 中配置相应的静态订阅。
    3. 依赖系统定时更新 ：将最重要的数据更新，更多地依赖于卡片配置的 scheduledUpdateTime ，这是系统级别的保障，相对可靠。我们的主动定时更新作为补充。
    4. 优雅恢复 ：在 Service 的 onStart 中，检查并恢复之前的状态和定时任务。确保关键数据（如卡片ID列表）已持久化。

5.4 网络请求安全与用户鉴权

  • 问题 ：卡片如何安全地访问需要登录态的游戏服务器API？
  • 方案 ： 这是一个复杂但必须处理的问题。绝对不能在卡片代码中硬编码用户密码或Token。
    1. Token机制 ：当用户在主App内登录成功后，App将服务器返回的 access_token 和 refresh_token 加密后存储到系统的 Key-Value Store 或安全的 Preferences 中。
    2. Service共享Token ： GameDataService 在发起网络请求前，从同一存储区域读取Token。如果Token过期，尝试使用 refresh_token 刷新。如果刷新失败，则卡片显示“请重新登录”的状态，并可能提供一个按钮，点击后跳转回主App进行重新认证。
    3. 接口权限控制 ：卡片调用的服务器API应该是经过严格权限校验的，并且只能进行只读或安全的轻量操作（如领取每日固定奖励），避免通过卡片进行敏感操作（如充值、交易）。

实现一个稳定、好用、美观的游戏万能卡片，远不止是调用几个API那么简单。它涉及前端UI、后台服务、网络通信、数据同步、性能优化和系统交互等多个方面的细致考量。从这次实践来看，HarmonyOS的原子化服务架构为这种轻量化、场景化的体验提供了坚实的技术基础，但真正做出体验优秀的产品，还需要开发者对游戏业务、用户习惯以及系统特性有更深的理解和更精巧的设计。

# 万能卡片 # 原子化服务
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

第41篇｜补光与水印：效果选项如何参与最终照片记录

avatar HarmonyOS开发者社区
cover

HarmonyOS 数据持久化该怎么选型和落地？

avatar HarmonyOS开发者社区
cover

HarmonyOS 6.1 开发者盛宴｜《灵犀厨房》实战（二十三）：【交互动效】转场、列表动画与趣味反馈——让每一次点击都有温度

avatar HarmonyOS开发者社区