【鸿蒙心迹】ExtensionAbility 实战——从 Form 到分享与备份的组件选型（HarmonyOS 7.x）

摘要: 鸿蒙开发中最常见的困惑之一：明明功能就几行代码，为什么要新建一个 ExtensionAbility？做了无数次 UIAbility 之后，一碰到分享、备份、卡片这些场景才发现，ExtensionAbility 覆盖的场景比想象中多得多------它不是"另一种 Ability"，而是面向特定系统场景的能力载体，有独立的声明方式、生命周期和调度模型。本文以 HarmonyOS NEXT 7.x（API 14+，2026 年稳定版）为目标版本，用一张类型对比表加一棵选型决策树，把 7 种常用 ExtensionAbility 的适用边界讲清楚，再用 3 个真实接入案例（信息流分享、应用数据备份、桌面卡片）把 module.json5 声明、配置 JSON、回调实现三个关键环节落到代码层，最后沉淀 3 个选型踩坑和一份完整类型速查表。适合已经熟悉 UIAbility 生命周期、正在做功能扩展的开发者对照参考。

适用版本: HarmonyOS NEXT 7.x / API 14+（2026 年稳定版，基于 OpenHarmony 5.1.0 验证）

开篇：卡片、分享、备份，该选哪个 Extension

"加个分享功能，为什么要新建一个 Ability？"

2026 年 8 月，涟漪睡眠 App 加"分享到朋友圈"。我最初的理解是：在 EntryAbility 里写个 share() 方法，调一下系统分享面板就完事了。结果 DevEco 里一查文档，发现分享入口必须走 ShareExtensionAbility，而且要在 module.json5 里声明 type: "share"、配置 share_config.json 支持的分享类型。

顺着这个线索往下挖，才意识到鸿蒙的 ExtensionAbility 是一个"场景化扩展能力"的体系------分享、备份、卡片、输入法、文件预览、无障碍，十几种类型各自对应一个特定系统场景，每种都有独立的声明方式、生命周期回调和调度模型。做了无数次 UIAbility 之后，这些扩展场景全要新建对应类型的 ExtensionAbility，不是"换个名字"那么简单。

这篇把选型讲清楚：先给一张类型对比表加一棵决策树，再用 3 个真实接入（分享 / 备份 / 卡片）把声明和回调落到代码层，最后沉淀 3 个踩坑。

一、UIAbility vs ExtensionAbility

维度	UIAbility	ExtensionAbility
界面	有独立 UI	无独立 UI（部分有卡片 UI）
生命周期	用户驱动	系统按场景调度
启动方式	startAbility	系统绑定/特定入口
多实例	支持	通常单实例
适用	主页面、用户交互	后台能力、系统扩展

二、选型决策树

#mermaid-svg-Qc1o2in8ijvdkJwS{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Qc1o2in8ijvdkJwS .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Qc1o2in8ijvdkJwS .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Qc1o2in8ijvdkJwS .error-icon{fill:#552222;}#mermaid-svg-Qc1o2in8ijvdkJwS .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Qc1o2in8ijvdkJwS .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Qc1o2in8ijvdkJwS .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Qc1o2in8ijvdkJwS .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Qc1o2in8ijvdkJwS .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Qc1o2in8ijvdkJwS .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Qc1o2in8ijvdkJwS .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Qc1o2in8ijvdkJwS .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Qc1o2in8ijvdkJwS .marker.cross{stroke:#333333;}#mermaid-svg-Qc1o2in8ijvdkJwS svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Qc1o2in8ijvdkJwS p{margin:0;}#mermaid-svg-Qc1o2in8ijvdkJwS .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-Qc1o2in8ijvdkJwS .cluster-label text{fill:#333;}#mermaid-svg-Qc1o2in8ijvdkJwS .cluster-label span{color:#333;}#mermaid-svg-Qc1o2in8ijvdkJwS .cluster-label span p{background-color:transparent;}#mermaid-svg-Qc1o2in8ijvdkJwS .label text,#mermaid-svg-Qc1o2in8ijvdkJwS span{fill:#333;color:#333;}#mermaid-svg-Qc1o2in8ijvdkJwS .node rect,#mermaid-svg-Qc1o2in8ijvdkJwS .node circle,#mermaid-svg-Qc1o2in8ijvdkJwS .node ellipse,#mermaid-svg-Qc1o2in8ijvdkJwS .node polygon,#mermaid-svg-Qc1o2in8ijvdkJwS .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Qc1o2in8ijvdkJwS .rough-node .label text,#mermaid-svg-Qc1o2in8ijvdkJwS .node .label text,#mermaid-svg-Qc1o2in8ijvdkJwS .image-shape .label,#mermaid-svg-Qc1o2in8ijvdkJwS .icon-shape .label{text-anchor:middle;}#mermaid-svg-Qc1o2in8ijvdkJwS .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Qc1o2in8ijvdkJwS .rough-node .label,#mermaid-svg-Qc1o2in8ijvdkJwS .node .label,#mermaid-svg-Qc1o2in8ijvdkJwS .image-shape .label,#mermaid-svg-Qc1o2in8ijvdkJwS .icon-shape .label{text-align:center;}#mermaid-svg-Qc1o2in8ijvdkJwS .node.clickable{cursor:pointer;}#mermaid-svg-Qc1o2in8ijvdkJwS .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Qc1o2in8ijvdkJwS .arrowheadPath{fill:#333333;}#mermaid-svg-Qc1o2in8ijvdkJwS .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Qc1o2in8ijvdkJwS .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Qc1o2in8ijvdkJwS .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Qc1o2in8ijvdkJwS .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Qc1o2in8ijvdkJwS .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Qc1o2in8ijvdkJwS .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Qc1o2in8ijvdkJwS .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Qc1o2in8ijvdkJwS .cluster text{fill:#333;}#mermaid-svg-Qc1o2in8ijvdkJwS .cluster span{color:#333;}#mermaid-svg-Qc1o2in8ijvdkJwS div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Qc1o2in8ijvdkJwS .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Qc1o2in8ijvdkJwS rect.text{fill:none;stroke-width:0;}#mermaid-svg-Qc1o2in8ijvdkJwS .icon-shape,#mermaid-svg-Qc1o2in8ijvdkJwS .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Qc1o2in8ijvdkJwS .icon-shape p,#mermaid-svg-Qc1o2in8ijvdkJwS .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Qc1o2in8ijvdkJwS .icon-shape .label rect,#mermaid-svg-Qc1o2in8ijvdkJwS .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Qc1o2in8ijvdkJwS .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Qc1o2in8ijvdkJwS .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Qc1o2in8ijvdkJwS :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 是 主页面
否 后台/扩展
桌面卡片
分享/被分享
数据备份
后台长任务
输入法
文件预览
需要新增能力
需要用户界面交互?
UIAbility
什么场景?
FormExtensionAbility
ShareExtensionAbility
BackupExtensionAbility
ServiceExtensionAbility
InputMethodExtensionAbility
FilePreviewExtensionAbility

三、实战 1：ShareExtensionAbility（分享）

场景：涟漪睡眠 App 被其他应用分享内容

系统分享面板只识别 type: "share" 的 ExtensionAbility，用 UIAbility 不会出现在分享目标列表里。所以第一步必须在 module.json5 里声明扩展能力，并在 share_config.json 里声明支持的分享类型（text / image / url）。

module.json5 声明：

// module.json5
{
  "module": {
    "extensionAbilities": [
      {
        "name": "ShareArticleAbility",
        "srcEntry": "./ets/share/ShareArticleAbility.ets",
        "type": "share",
        "metadata": [
          { "name": "ohos.extension.share", "resource": "$profile:share_config" }
        ]
      }
    ]
  }
}

share_config.json（放在 resources/base/profile/ 目录）声明支持的分享类型：

{
  "supportedTypes": ["text", "url", "image"],
  "shareTargets": [
    {
      "label": "分享到涟漪睡眠",
      "icon": "$media:share_icon",
      "abilityName": "ShareArticleAbility"
    }
  ]
}

onShare 是系统调用你时的唯一回调，want.parameters 里携带的是发起方 App 传入的分享内容。处理完必须 terminateSelf()，否则系统会判定你"占用分享通道"，后续分享请求会排队等待。

import { ShareExtensionAbility } from '@kit.AbilityKit';
import { Want } from '@kit.AbilityKit';

export default class ShareArticleAbility extends ShareExtensionAbility {
  onShare(want: Want): void {
    const sharedData = want.parameters?.['content'];
    // 处理分享进来的内容（如保存到草稿箱）
    this.saveToDrafts(sharedData);
    // 必须终止自身，释放分享通道
    this.terminateSelf();
  }
}

避坑 1 ：ShareExtensionAbility 的 type 必须是 "share"，且要在 share_config.json 里声明支持的分享类型（text/image/url）。如果 share_config.json 里没写 "supportedTypes"，分享面板会显示"不支持该类型"。

四、实战 2：BackupExtensionAbility（备份）

场景：应用数据备份到云或本地

系统级备份（如云备份、换机迁移）只调度 type: "backup" 的 ExtensionAbility，普通 UIAbility 不会被纳入备份链路。onBackup 是系统备份时的唯一回调，onRestore 是恢复时的唯一回调------两者都不在用户进程里运行，而是在独立的备份沙箱里执行，所以不能依赖应用主进程的任何状态。

module.json5 声明：

{
  "extensionAbilities": [
    {
      "name": "AppBackupAbility",
      "srcEntry": "./ets/backup/AppBackupAbility.ets",
      "type": "backup",
      "metadata": [
        { "name": "ohos.extension.backup", "resource": "$profile:backup_config" }
      ]
    }
  ]
}

onBackup 被系统调度时没有 UI 上下文，也不能阻塞------系统给每次备份操作一个时间窗口，超时未返回会被强制终止。大文件（如本地缓存、用户数据）必须分片处理，每片控制在 100MB 以内，避免单片写入超时。

import { BackupExtensionAbility } from '@kit.AbilityKit';
import { fileIo } from '@kit.CoreFileKit';

export default class AppBackupAbility extends BackupExtensionAbility {
  // 系统备份时调用
  async onBackup(): Promise<void> {
    // 分片收集数据，每片 < 100MB
    const chunks = await this.collectAllDataInChunks(100 * 1024 * 1024);
    for (const chunk of chunks) {
      await this.writeToBackupFile(chunk);
    }
  }

  // 系统恢复时调用
  async onRestore(): Promise<void> {
    const chunks = await this.readFromBackupFileInChunks();
    for (const chunk of chunks) {
      await this.restoreChunk(chunk);
    }
  }
}

避坑 2 ：备份 ExtensionAbility 在系统备份时被调度，不要做耗时操作（>10s 会被系统杀掉），大文件分片处理。onBackup 里不要调用应用主进程的数据库连接------备份沙箱和应用沙箱是隔离的，跨沙箱访问会报权限错误。

五、实战 3：FormExtensionAbility（卡片）

场景：涟漪睡眠 App 桌面卡片展示"今日精选"

FormExtension 是 ExtensionAbility 里最特殊的一个------它有卡片 UI，且生命周期由用户桌面驱动（添加/刷新/移除），不是系统按场景调度。

桌面卡片是"常驻入口"，用户不需要打开 App 就能看到内容。但卡片运行在独立的进程里，不能直接访问应用主进程的数据，所以必须通过 onUpdateForm 定时拉取数据、通过 postCardAction 实现卡片与 App 的双向通信。

module.json5 声明：

{
  "extensionAbilities": [
    {
      "name": "DailyCardForm",
      "srcEntry": "./ets/form/DailyCardForm.ets",
      "type": "form",
      "metadata": [
        { "name": "ohos.extension.form", "resource": "$profile:form_config" }
      ]
    }
  ]
}

form_config.json 声明卡片尺寸和刷新策略：

{
  "forms": [
    {
      "name": "daily_card",
      "description": "今日精选",
      "srcEntry": "./ets/form/DailyCardForm.ets",
      "windowSize": [
        { "support": ["1*2"] },
        { "support": ["2*4"] }
      ],
      "updateEnabled": true,
      "scheduledUpdateTime": "08:00",
      "updateDuration": 1
    }
  ]
}

onAddForm 是用户把卡片添加到桌面时调用的，onUpdateForm 是系统定时刷新（或用户手动下拉刷新）时调用的，onFormEvent 是用户点击卡片内元素时调用的。三者职责不同，不能混用------onAddForm 只负责初始化，onUpdateForm 只负责拉取新数据，onFormEvent 只负责响应用户交互。

import { FormExtensionAbility, formBindingData } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';

export default class DailyCardForm extends FormExtensionAbility {
  // 用户把卡片添加到桌面
  onAddForm(want: Want): formBindingData.FormBindingData {
    const init = this.fetchDailyTop(3);
    return formBindingData.createFormBindingData({ topList: init, updatedAt: Date.now() });
  }

  // 系统定时刷新 / 用户手动刷新
  onUpdateForm(formId: string): formBindingData.FormBindingData {
    const fresh = this.fetchDailyTop(3);
    return formBindingData.createFormBindingData({ topList: fresh, updatedAt: Date.now() });
  }

  // 用户点击卡片内元素（如"查看更多"）
  onFormEvent(formId: string, message: string): void {
    if (message === 'openDetail') {
      // 通过 startAbility 拉起 App 对应页面
      this.context.startAbility({
        bundleName: 'com.example.feeds',
        abilityName: 'EntryAbility',
        parameters: { from: 'form', formId: formId }
      });
    }
  }

  // 用户移除卡片
  onRemoveForm(formId: string): void {
    // 清理卡片关联的本地缓存
    this.clearFormCache(formId);
  }
}

完整的 FormExtension 全链路（卡片 UI 定义、数据更新、事件通信）详见 第 12 篇：互动卡片全链路 FormKit 实战。

补充：ExtensionAbility 系统调度时序

理解 ExtensionAbility 和 UIAbility 最本质的区别，看一张系统调度时序图：
应用上下文 UIAbility（可选） ExtensionAbility 实例 系统（分享/备份/桌面） 应用上下文 UIAbility（可选） ExtensionAbility 实例 系统（分享/备份/桌面） #mermaid-svg-uWxO4VT4GbxjVLaN{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-uWxO4VT4GbxjVLaN .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-uWxO4VT4GbxjVLaN .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-uWxO4VT4GbxjVLaN .error-icon{fill:#552222;}#mermaid-svg-uWxO4VT4GbxjVLaN .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-uWxO4VT4GbxjVLaN .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-uWxO4VT4GbxjVLaN .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-uWxO4VT4GbxjVLaN .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-uWxO4VT4GbxjVLaN .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-uWxO4VT4GbxjVLaN .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-uWxO4VT4GbxjVLaN .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-uWxO4VT4GbxjVLaN .marker{fill:#333333;stroke:#333333;}#mermaid-svg-uWxO4VT4GbxjVLaN .marker.cross{stroke:#333333;}#mermaid-svg-uWxO4VT4GbxjVLaN svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-uWxO4VT4GbxjVLaN p{margin:0;}#mermaid-svg-uWxO4VT4GbxjVLaN .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-uWxO4VT4GbxjVLaN text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-uWxO4VT4GbxjVLaN .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-uWxO4VT4GbxjVLaN .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-uWxO4VT4GbxjVLaN .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-uWxO4VT4GbxjVLaN .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-uWxO4VT4GbxjVLaN #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-uWxO4VT4GbxjVLaN .sequenceNumber{fill:white;}#mermaid-svg-uWxO4VT4GbxjVLaN #sequencenumber{fill:#333;}#mermaid-svg-uWxO4VT4GbxjVLaN #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-uWxO4VT4GbxjVLaN .messageText{fill:#333;stroke:none;}#mermaid-svg-uWxO4VT4GbxjVLaN .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-uWxO4VT4GbxjVLaN .labelText,#mermaid-svg-uWxO4VT4GbxjVLaN .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-uWxO4VT4GbxjVLaN .loopText,#mermaid-svg-uWxO4VT4GbxjVLaN .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-uWxO4VT4GbxjVLaN .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-uWxO4VT4GbxjVLaN .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-uWxO4VT4GbxjVLaN .noteText,#mermaid-svg-uWxO4VT4GbxjVLaN .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-uWxO4VT4GbxjVLaN .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-uWxO4VT4GbxjVLaN .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-uWxO4VT4GbxjVLaN .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-uWxO4VT4GbxjVLaN .actorPopupMenu{position:absolute;}#mermaid-svg-uWxO4VT4GbxjVLaN .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-uWxO4VT4GbxjVLaN .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-uWxO4VT4GbxjVLaN .actor-man circle,#mermaid-svg-uWxO4VT4GbxjVLaN line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-uWxO4VT4GbxjVLaN :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} onCreate（轻量初始化） alt 需要 UI 交互 系统回收实例，生命周期结束 按场景调度（如触发分享） onShare / onBackup / onAddForm 读取参数（want.parameters） startAbility 拉起 UIAbility 用户操作完成 释放资源（不能依赖 onDestroy） terminateSelf 终止

关键点：

• onCreate 里只做轻量初始化（如读取配置），不要在这里加载数据库连接、网络客户端等重量级资源
• 资源释放放在具体回调（onShare / onBackup / onAddForm）结束时 ，不要只依赖 onDestroy------系统可能直接回收实例而不调用 onDestroy
• 需要 UI 交互时，必须通过 startAbility 启动 UIAbility，ExtensionAbility 自身没有窗口

六、3 个选型踩坑

1. 用 UIAbility 代替 ExtensionAbility

现象（2026-08 涟漪睡眠 App v3.2 提测）：分享功能用 UIAbility 实现，系统分享面板里不显示"分享到涟漪睡眠"入口，用户只能看到微信/QQ 等系统预置目标。

根因 ：系统分享面板只识别 type: "share" 的 ExtensionAbility，UIAbility 不会出现在分享目标列表里。这是系统级约束，不是配置问题。

解决：分享/备份/卡片必须用对应类型的 ExtensionAbility，不能用 UIAbility 代替。

效果 ：改为 ShareExtensionAbility 后，分享面板正常显示自定义目标，测试通过。

预防：在需求评审阶段确认功能类型------凡涉及系统分享面板、系统备份链路、桌面卡片的，直接定为 ExtensionAbility 需求，不写"用 UIAbility 实现"。

2. ExtensionAbility 里尝试显示全屏 UI

现象 （2026-08 涟漪睡眠 App v3.2 开发期）：在 ShareExtensionAbility 里调 loadContent 加载分享成功页，运行崩溃，日志报 Error: 100010 Unknown error。

根因 ：ExtensionAbility 没有窗口，不能加载 UI（FormExtension 的卡片 UI 是例外，它走的是卡片渲染通道而非普通页面通道）。loadContent 是 UIAbility 的能力，ExtensionAbility 里没有对应的窗口句柄。

解决 ：需要 UI 交互的，从 ExtensionAbility startAbility 启动 UIAbility：

onShare(want: Want): void {
  const data = want.parameters?.['content'];
  // 先做轻量处理（如保存到草稿箱）
  this.saveToDrafts(data);
  // 再拉起 UIAbility 展示分享成功页
  this.context.startAbility({
    bundleName: 'com.example.feeds',
    abilityName: 'EntryAbility',
    parameters: { action: 'handleShare', data: data, from: 'shareExt' }
  });
  this.terminateSelf();
}

效果：分享成功后正常跳转到 App 内"分享成功"页面，无崩溃。

预防 ：团队内约定------ExtensionAbility 里禁止出现 loadContent / WindowStage 相关调用，Code Review 时作为必查项。

3. ExtensionAbility 生命周期不完整

现象 （2026-09 备份功能灰度期）：在 onCreate 里初始化了一个内存缓存池，onDestroy 里释放。灰度用户反馈：频繁触发备份后，App 内存占用持续增长，最终 OOM 崩溃。

根因 ：ExtensionAbility 的生命周期由系统调度，不一定走完整流程。系统在某些场景下（如备份超时被强制终止、进程被系统回收）会直接销毁实例而不调用 onDestroy，导致 onCreate 里初始化的资源永远无法释放。

解决 ：在 onCreate 做轻量初始化（如读取配置），资源释放放在具体回调（onShare / onBackup / onAddForm）结束时 ，不依赖 onDestroy：

// 错误写法：依赖 onDestroy 释放
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  this.cachePool = new CachePool(64 * 1024 * 1024); // 64MB 缓存
}
onDestroy(): void {
  this.cachePool?.release(); // 系统不一定调用这里
}

// 正确写法：在回调结束时释放
onBackup(): Promise<void> {
  const cachePool = new CachePool(64 * 1024 * 1024);
  try {
    // 执行备份逻辑...
  } finally {
    cachePool.release(); // 确保释放，不依赖 onDestroy
  }
}

效果：改为回调内释放后，灰度用户内存占用稳定，OOM 崩溃归零。

预防 ：团队内约定------ExtensionAbility 的 onCreate 里禁止初始化重量级资源（>10MB 内存、长连接、数据库连接），重量级资源在回调内按需创建、回调结束释放。

性能对比：UIAbility 方案 vs ExtensionAbility 方案

维度	UIAbility 方案	ExtensionAbility 方案	差异说明
分享面板可见性	不显示	正常显示	系统级约束，无法绕过
冷启动耗时（ms）	~450（启动整个 App）	~80（仅启动扩展进程）	扩展进程更轻量，无需加载 UI 资源
内存占用（MB）	~120（完整 App 进程）	~35（扩展进程）	扩展进程不加载 UI 框架和页面资源
备份调度兼容性	不被系统备份链路识别	正常纳入备份链路	系统只调度 type: "backup"
桌面卡片支持	不支持	正常支持（卡片 UI）	只有 FormExtension 有卡片渲染通道

七、ExtensionAbility 类型速查

类型	type 值	场景	有 UI?	调度模型	典型回调
Form	form	桌面卡片	卡片 UI	用户桌面驱动（添加/刷新/移除）	onAddForm / onUpdateForm / onFormEvent / onRemoveForm
Share	share	分享/被分享	无	系统按分享面板调度	onShare
Backup	backup	数据备份恢复	无	系统备份链路调度	onBackup / onRestore
Service	service	后台长任务	无	系统按任务调度	onStartCommand
InputMethod	inputMethod	输入法	输入法 UI	用户切换输入法时调度	onCreate / onDestroy
FilePreview	filePreview	文件预览	预览 UI	系统文件管理器调度	onCreate / onDestroy
Accessibility	accessibility	无障碍服务	无	系统无障碍框架调度	onCreate / onDestroy

选型口诀：

• 有界面 → UIAbility
• 没界面 + 系统调度 → ExtensionAbility（按场景选 type）
• 有卡片 UI → 只有 FormExtension 能做到

避坑要点

1. 分享/备份必须用对应 Extension：UIAbility 不会被系统识别
2. ExtensionAbility 无窗口：需要 UI 就 startAbility 启动 UIAbility
3. 生命周期不完整：资源释放别只靠 onDestroy

边界与已知限制

限制项	具体表现	规避方式
类型固定	ExtensionAbility 类型是系统预定义的，不能自定义	按场景选官方类型，不强行改造
进程独立	与主 Ability 不共享内存状态	数据落盘后再共享，不依赖内存变量
运行时长	后台 Extension 有执行时长约束	长任务拆分，或回到应用内处理
权限声明	部分类型需额外权限	按类型补齐声明并说明用途
版本差异	各类型支持的 API 版本不同	按类型核对最低支持版本
调试成本	独立进程，断点链路与主流程不同	以日志打点为主
数量约束	单应用可声明的数量有限	合并相似能力，避免类型膨胀

小结

ExtensionAbility 的选型关键是先认清它是"系统托管的扩展点"而不是"应用的子模块"：生命周期由系统驱动，进程可能与主应用分离，运行时长也受约束。

按这个认知去选型，卡片用 Form、分享用 Share、备份用 Backup，各自补声明、走存储共享数据，就不会出现"数据不同步"和"莫名其妙被回收"这两类高频问题。

评论区交流: 你踩过 ExtensionAbility 选型的哪些坑？分享场景 / 备份链路 / 桌面卡片，欢迎在评论区交流接入经验和踩坑记录。