一、FA（元服务）基础概念

1. FA（Feature Ability）是什么
   FA是鸿蒙应用的基本组成单元，代表一个可以独立运行的界面或功能模块。在卡片化服务场景中，FA作为后台逻辑支持，而Widget则作为前端展示。

2. 卡片化服务的优势
   ​​即时访问​​：用户无需打开完整应用即可获取关键信息
   ​​低资源消耗​​：轻量级运行，减少系统资源占用
   ​​动态更新​​：支持定时或事件驱动的数据刷新
   ​​交互功能​​：可直接在卡片上执行简单操作
   二、开发环境配置

3. DevEco Studio配置
   在build.gradle中添加卡片相关依赖：

dependencies {
implementation ‘io.harmony:widget:1.0.0’
implementation ‘io.harmony:form:1.0.0’
}
2. 权限配置
在config.json中添加权限声明：

{
“reqPermissions”: [
{
“name”: “ohos.permission.SET_FORM”,
“reason”: “卡片创建权限”
},
{
“name”: “ohos.permission.GET_BUNDLE_INFO”,
“reason”: “查询卡片信息”
}
],
“abilities”: [
{
“name”: “.NewsWidget”,
“label”: “新闻卡片”,
“type”: “form”,
“visible”: true
}
],
“forms”: [
{
“name”: “NewsWidget”,
“description”: “新闻卡片”,
“window”: {
“designWidth”: 720,
“autoDesignWidth”: false
},
“colorMode”: “auto”,
“type”: “JS”,
“supportDimensions”: [“2 * 2”, “2 * 4”, “4 * 4”]
}
]
}
三、FA元服务开发实战

1. 创建FA基础服务
   // NewsService.java
   public class NewsService extends Ability {
   private static final String TAG = “NewsService”;

   @Override
   protected void onStart(Intent intent) {
   super.onStart(intent);
   HiLog.info(TAG, “新闻服务已启动”);
   }

   @Override
   protected void onCommand(Intent intent, boolean restart, int startId) {
   // 处理卡片请求
   if (intent.hasParameter(“action”)) {
   String action = intent.getStringParam(“action”);
   handleCardAction(action, intent);
   }
   }

   private void handleCardAction(String action, Intent intent) {
   switch (action) {
   case “refresh”:
   refreshNewsData();
   break;
   case “openDetail”:
   openNewsDetail(intent.getStringParam(“newsId”));
   break;
   }
   }

   private void refreshNewsData() {
   // 获取最新新闻数据
   List<NewsItem> news = NewsFetcher.fetchLatest();
   updateAllCards(news);
   }

   private void updateAllCards(List<NewsItem> news) {
   FormController controller = FormController.getInstance(this);
   List<FormState> forms = controller.getForms(“NewsWidget”);

    for (FormState form : forms) {
        ZSONObject data = createCardData(news, form.getDimension());
        controller.updateForm(form.getFormId(), data.toString());
    }
   

   }

   private ZSONObject createCardData(List<NewsItem> news, int dimension) {
   // 根据卡片尺寸返回不同数据结构
   ZSONObject data = new ZSONObject();

    if (dimension == 2) { // 2 * 2卡片
        data.put("title", news.get(0).getTitle());
        data.put("image", news.get(0).getCoverUrl());
    } else { // 大尺寸卡片
        List<ZSONObject> items = new ArrayList<>();
        for (int i = 0; i < Math.min(3, news.size()); i++) {
            ZSONObject item = new ZSONObject();
            item.put("id", news.get(i).getId());
            item.put("title", news.get(i).getTitle());
            item.put("image", news.get(i).getCoverUrl());
            items.add(item);
        }
        data.put("items", items);
    }
    
    data.put("updateTime", System.currentTimeMillis());
    return data;
   

   }
   }

2. 新闻数据模型
   public class NewsItem {
   private String id;
   private String title;
   private String content;
   private String coverUrl;
   private long publishTime;

   // 构造函数、getter和setter
   }
   四、卡片Widget开发实现

3. 卡片布局设计
   在resources/base/layout/news_widget.xml中创建布局：

<!-- 2 * 2 卡片布局 -->
<DirectionalLayout
xmlns:ohos=“http://schemas.huawei.com/res/ohos”
ohos:id=“$+id:root_view”
ohos:width=“match_parent”
ohos:height=“match_parent”
ohos:background_element=“$graphic:widget_bg”
ohos:padding=“12vp”
ohos:orientation=“vertical”>

<Image
    ohos:id="$+id:news_image"
    ohos:width="match_parent"
    ohos:height="0vp"
    ohos:weight="1"
    ohos:scale_mode="center_crop"
    ohos:margin_bottom="8vp"/>
    
<Text
    ohos:id="$+id:news_title"
    ohos:width="match_parent"
    ohos:height="match_content"
    ohos:text_size="16fp"
    ohos:text_color="#FFFFFF"
    ohos:max_text_lines="2"
    ohos:auto_font_size="true"/>
    
<Button
    ohos:id="$+id:refresh_btn"
    ohos:width="40vp"
    ohos:height="40vp"
    ohos:right_margin="8vp"
    ohos:alignment="bottom|right"
    ohos:background_element="$graphic:ic_refresh"
    ohos:visibility="invisible"/>

</DirectionalLayout>
2. 卡片服务实现
// NewsWidget.java
public class NewsWidget extends FormAbility {
private static final HiLogLabel TAG = new HiLogLabel(HiLog.DEBUG, 0, “NewsWidget”);
private static final int FORM_ID = 1001;

@Override
public ProviderFormInfo onCreateForm(Intent intent) {
    // 创建卡片实例
    int dimension = intent.getIntParam(FormAbility.PARAM_FORM_DIMENSION, 0);
    ProviderFormInfo formInfo = new ProviderFormInfo();
    formInfo.setName("NewsWidget");
    formInfo.setFormId(FORM_ID);
    
    // 根据尺寸选择布局
    int layoutRes;
    if (dimension == 2) { // 2 * 2
        layoutRes = ResourceTable.Layout_news_widget_2x2;
    } else if (dimension == 3) { // 2 * 4
        layoutRes = ResourceTable.Layout_news_widget_2x4;
    } else { // 4 * 4
        layoutRes = ResourceTable.Layout_news_widget_4x4;
    }
    
    formInfo.setLayout(layoutRes);
    return formInfo;
}

@Override
protected String onAcquireFormData(int formId) {
    // 获取卡片数据
    return createDummyData(formId).toString();
}

@Override
protected void onUpdateForm(int formId) {
    // 请求更新数据
    requestNewsData(formId);
}

@Override
protected void onTriggerFormEvent(int formId, String message) {
    // 处理卡片事件
    ZSONObject event = ZSONObject.stringToZSON(message);
    String action = event.getString("action");
    
    if ("refresh".equals(action)) {
        requestNewsData(formId);
    } else if ("open_detail".equals(action)) {
        openNewsDetail(event.getString("newsId"));
    }
}

private void requestNewsData(int formId) {
    // 连接到FA服务获取数据
    Intent intent = new Intent();
    Operation operation = new Intent.OperationBuilder()
        .withDeviceId("")
        .withBundleName(getBundleName())
        .withAbilityName(NewsService.class.getName())
        .build();
    intent.setOperation(operation);
    intent.setParam("formId", formId);
    intent.setParam("action", "refresh");
    startAbility(intent);
}

private void openNewsDetail(String newsId) {
    // 打开详情页面
    Intent intent = new Intent();
    Operation operation = new Intent.OperationBuilder()
        .withDeviceId("")
        .withBundleName(getBundleName())
        .withAbilityName(NewsDetailAbility.class.getName())
        .build();
    intent.setOperation(operation);
    intent.setParam("newsId", newsId);
    startAbility(intent);
}

private ZSONObject createDummyData(int formId) {
    // 默认数据
    ZSONObject data = new ZSONObject();
    data.put("title", "加载中...");
    data.put("image", ResourceTable.Media_placeholder);
    return data;
}

}
3. 卡片数据更新机制
public class NewsWidgetController {
private static NewsWidgetController instance;
private final Context context;
private final Map<Integer, List<NewsItem>> cache = new HashMap<>();

private NewsWidgetController(Context context) {
    this.context = context;
}

public static synchronized NewsWidgetController getInstance(Context context) {
    if (instance == null) {
        instance = new NewsWidgetController(context);
    }
    return instance;
}

public void updateWidgetData(int formId, List<NewsItem> news) {
    // 更新缓存
    cache.put(formId, news);
    
    // 更新卡片UI
    FormController controller = FormController.getInstance(context);
    ZSONObject data = createCardData(news, controller.getFormDimension(formId));
    controller.updateForm(formId, data.toString());
}

public void broadcastUpdate() {
    // 广播更新所有卡片
    FormController controller = FormController.getInstance(context);
    for (FormState form : controller.getForms("NewsWidget")) {
        if (cache.containsKey(form.getFormId())) {
            updateWidgetData(form.getFormId(), cache.get(form.getFormId()));
        }
    }
}

}
五、桌面Widget功能扩展

1. 多尺寸卡片适配
   在resources/base/layout/中创建不同尺寸的布局：

<!-- 4 * 4 卡片布局 -->
<DirectionalLayout
ohos:width=“match_parent”
ohos:height=“match_parent”>

<ListContainer
    ohos:id="$+id:news_list"
    ohos:width="match_parent"
    ohos:height="match_parent"
    ohos:divider="1vp"
    ohos:divider_color="#30000000"/>
    
<Button
    ohos:id="$+id:refresh_all_btn"
    ohos:width="match_parent"
    ohos:height="40vp"
    ohos:text="刷新全部"/>

</DirectionalLayout>
2. 动态交互效果
// 在卡片中处理交互
@Override
protected void onTriggerFormEvent(int formId, String message) {
ZSONObject event = ZSONObject.stringToZSON(message);
String action = event.getString(“action”);

if ("refresh".equals(action)) {
    // 显示加载动画
    showLoadingAnimation(formId);
    requestNewsData(formId);
}

}

private void showLoadingAnimation(int formId) {
Component form = FormController.getInstance(this).getFormView(formId);
if (form != null) {
Button refreshBtn = (Button) form.findComponentById(ResourceTable.Id_refresh_btn);

    // 创建旋转动画
    AnimatorProperty animator = new AnimatorProperty();
    animator.setDuration(1000).rotate(360).setLoopedCount(Animator.INFINITE);
    refreshBtn.setComponentAnimator(animator);
}

}

public void hideLoadingAnimation(int formId) {
Component form = FormController.getInstance(this).getFormView(formId);
if (form != null) {
Button refreshBtn = (Button) form.findComponentById(ResourceTable.Id_refresh_btn);
refreshBtn.getComponentAnimator().stop();
}
}
3. 定时数据刷新
在config.json中配置定时刷新：

{
“forms”: [
{
“name”: “NewsWidget”,
“scheduledUpdateTime”: “10:30”,
“updateDuration”: 1,
“updateEnabled”: true
}
]
}
实现自动刷新逻辑：

public class AutoRefreshService extends Ability {
private static final long REFRESH_INTERVAL = 30 * 60 * 1000; // 30分钟
private Handler handler;

@Override
protected void onStart(Intent intent) {
    super.onStart(intent);
    handler = new Handler(EventRunner.getMainEventRunner());
    startAutoRefresh();
}

private void startAutoRefresh() {
    handler.postTask(() -> {
        NewsFetcher.refreshAll();
        handler.postTask(this::startAutoRefresh, REFRESH_INTERVAL);
    }, REFRESH_INTERVAL);
}

}
六、完整卡片生命周期管理

1. 卡片状态监听
   public class NewsWidget extends FormAbility {
   // …

   @Override
   public void onVisibilityChange(int formId, boolean visible) {
   if (visible) {
   // 卡片可见时请求数据更新
   requestNewsData(formId);
   } else {
   // 卡片不可见时暂停资源占用
   pauseBackgroundTasks(formId);
   }
   }

   @Override
   public void onDeleteForm(int formId) {
   // 清理卡片特定资源
   cleanFormResources(formId);
   }
   }

2. 多卡片协同管理
   public class WidgetManager {
   private static WidgetManager instance;
   private final Context context;
   private final Set<Integer> activeCards = new HashSet<>();

   public void registerCard(int formId) {
   activeCards.add(formId);
   if (activeCards.size() == 1) {
   startBackgroundService();
   }
   }

   public void unregisterCard(int formId) {
   activeCards.remove(formId);
   if (activeCards.isEmpty()) {
   stopBackgroundService();
   }
   }

   public void updateActiveCards() {
   for (int formId : activeCards) {
   FormController.getInstance(context).updateForm(formId);
   }
   }
   }
   七、调试与部署

3. 测试卡片布局
   在模拟器上预览不同尺寸卡片：

public class WidgetPreviewActivity extends Ability {
@Override
protected void onStart(Intent intent) {
super.onStart(intent);
setUIContent(ResourceTable.Layout_widget_preview);

    // 添加预览卡片
    FormController controller = FormController.getInstance(this);
    ProviderFormInfo formInfo = new ProviderFormInfo();
    formInfo.setLayout(ResourceTable.Layout_news_widget_4x4);
    Component card = controller.createFormView(formInfo);
    
    // 添加卡片到界面
    DirectionalLayout container = 
        (DirectionalLayout) findComponentById(ResourceTable.Id_preview_container);
    container.addComponent(card);
}

}
2. 自动化测试脚本

test_widget.py

import unittest
from ohos.device import Device
from ohos.widget import WidgetTestCase

class NewsWidgetTest(WidgetTestCase):
def setUp(self):
self.device = Device()
self.widget_id = self.device.createWidget(“com.example.NewsWidget”)

def test_widget_update(self):
    # 模拟更新数据
    self.device.setWidgetData(self.widget_id, 
                              '{"title": "测试新闻", "image": "res://placeholder"}')
    
    # 验证UI更新
    title_view = self.findComponentById(self.widget_id, "news_title")
    self.assertEqual(title_view.getText(), "测试新闻")

def test_refresh_action(self):
    # 触发刷新动作
    refresh_btn = self.findComponentById(self.widget_id, "refresh_btn")
    self.tapComponent(refresh_btn)
    
    # 验证刷新请求
    actions = self.device.getServiceRequests("NewsService")
    self.assertTrue(any("action=refresh" in req for req in actions))

def tearDown(self):
    self.device.removeWidget(self.widget_id)

八、最佳实践与优化建议

1. 性能优化技巧
   ​​数据压缩​​：减少卡片数据传输量
   private byte[] compressData(String json) {
   ByteArrayOutputStream bos = new ByteArrayOutputStream();
   GZIPOutputStream gzip = new GZIPOutputStream(bos);
   gzip.write(json.getBytes(StandardCharsets.UTF_8));
   gzip.close();
   return bos.toByteArray();
   }
   ​​内存管理​​：及时释放不使用的资源
   @Override
   public void onBackground(int formId) {
   // 释放图片资源
   Component formView = getFormView(formId);
   if (formView != null) {
   Image image = formView.findComponentById(ResourceTable.Id_news_image);
   image.setPixelMap(null);
   }
   }

2. 用户体验优化
   ​​加载状态提示​​：添加骨架屏效果
   ​​过渡动画​​：数据更新时使用渐变效果
   ​​错误处理​​：网络异常时显示优雅降级UI

3. 差异化布局实现
   private ZSONObject createCardData(int dimension, String theme) {
   ZSONObject data = new ZSONObject();

   // 根据主题选择颜色
   if (“dark”.equals(theme)) {
   data.put(“bgColor”, “#1E1E1E”);
   data.put(“textColor”, “#FFFFFF”);
   } else {
   data.put(“bgColor”, “#FFFFFF”);
   data.put(“textColor”, “#000000”);
   }

   // 根据尺寸选择布局模式
   if (dimension < 3) { // 小卡片
   data.put(“layoutMode”, “compact”);
   } else { // 大卡片
   data.put(“layoutMode”, “detail”);
   }

   return data;
   }
   总结
   本文详细介绍了鸿蒙5卡片化服务的开发流程，包括：

​​FA元服务开发​​：创建后台逻辑支持服务
​​卡片Widget实现​​：设计多尺寸卡片布局和交互
​​数据管理​​：实现高效的数据获取与更新机制
​​生命周期管理​​：完整处理卡片创建、更新和销毁
​​性能优化​​：提升卡片运行效率和用户体验
关键实现点：

使用FormAbility作为卡片基类
通过FormController管理卡片生命周期
采用ZSONObject进行数据传输
实现多尺寸卡片适配
添加定时刷新和动态交互功能
实际开发中建议：

优先设计小尺寸卡片，确保核心信息展示
针对不同场景提供多种尺寸选择
严格控制卡片资源占用
添加详细的状态提示和错误处理
进行充分的跨设备适配测试
通过合理利用鸿蒙的卡片化服务，开发者可以显著提升应用的用户体验和便捷性，让用户在桌面上即可快速获取关键信息。