【HarmonyOS 6.0】Desktop Extension Kit 正式接棒原状态栏服务，API 引用路径全面更新

文章目录

[1 -> 前言](#1 -> 前言)
[2 -> 变更背景：从状态栏服务到桌面拓展服务](#2 -> 变更背景：从状态栏服务到桌面拓展服务)
- [2.1 -> 命名逻辑的演进](#2.1 -> 命名逻辑的演进)
- [2.2 -> 底层实现的变化](#2.2 -> 底层实现的变化)
[3 -> 核心变更详解：导入方式与API引用](#3 -> 核心变更详解：导入方式与API引用)
- [3.1 -> 模块导入语句变更](#3.1 -> 模块导入语句变更)
- - [3.1.1 -> 旧版写法（已废弃）](#3.1.1 -> 旧版写法（已废弃）)
  - [3.1.2 -> 新版写法（HarmonyOS 6.0+）](#3.1.2 -> 新版写法（HarmonyOS 6.0+）)
- [3.2 -> Package名称变化对照表](#3.2 -> Package名称变化对照表)
- [3.3 -> 版本兼容性说明](#3.3 -> 版本兼容性说明)
[4 -> Desktop Extension Kit核心API详解](#4 -> Desktop Extension Kit核心API详解)
- [4.1 -> 核心接口：statusBarManager](#4.1 -> 核心接口：statusBarManager)
- [4.2 -> StatusBarItem：状态栏图标配置项](#4.2 -> StatusBarItem：状态栏图标配置项)
- [4.3 -> 完整开发流程与代码示例](#4.3 -> 完整开发流程与代码示例)
- [4.4 -> 右键分组菜单配置要点](#4.4 -> 右键分组菜单配置要点)
[5 -> 迁移指南：存量项目如何适配](#5 -> 迁移指南：存量项目如何适配)
- [5.1 -> 全局替换方案](#5.1 -> 全局替换方案)
- [5.2 -> 工程配置变更检查](#5.2 -> 工程配置变更检查)
- [5.3 -> 构建验证步骤](#5.3 -> 构建验证步骤)
[6 -> 常见问题与最佳实践](#6 -> 常见问题与最佳实践)
- [6.1 -> 常见问题排查](#6.1 -> 常见问题排查)
- [6.2 -> 开发最佳实践](#6.2 -> 开发最佳实践)
[7 -> 总结](#7 -> 总结)

1 -> 前言

在HarmonyOS开发体系中，Kit（开发套件）的命名往往直接反映了其核心定位和能力边界。随着HarmonyOS 6.0的演进，系统围绕PC与2in1设备的桌面交互场景进行了能力整合与重构，其中一个值得关注的变更便是 Status Bar Extension Kit（状态栏开放服务）正式更名为Desktop Extension Kit（桌面拓展服务） 。相应的，Kit API引用方式也从 @kit.StatusBarExtensionKit 变更为 @kit.DeskTopExtensionKit。

这一变化不仅仅是名称上的更新，更标志着该Kit的能力定位从单一的"状态栏开放"拓展为更广泛的"桌面快捷交互入口"。本文将从变更背景、导入方式差异、API调用迁移、开发最佳实践等角度，对本次Kit更名进行系统梳理，帮助开发者顺利完成存量应用的适配升级。

2 -> 变更背景：从状态栏服务到桌面拓展服务

2.1 -> 命名逻辑的演进

在HarmonyOS 5.x版本中，Status Bar Extension Kit的核心能力聚焦于状态栏图标管理------应用可通过该Kit在系统的状态栏区域添加自定义图标，并响应点击、右键等交互操作。所有能力边界均围绕"状态栏"这一单一系统UI组件展开。

进入HarmonyOS 6.0后，PC与2in1设备场景下的桌面交互需求显著增长。系统需要为应用提供一个统一的桌面级快捷入口接入框架 ，涵盖状态栏、快捷栏等多个系统UI区域。原有的"Status Bar Extension Kit"命名已不足以概括其能力范围，更名为Desktop Extension Kit（桌面拓展服务）旨在更准确地反映该Kit的核心定位------为应用提供系统级统一的桌面操作入口，支持应用快捷功能接入桌面。

换言之，本次更名的本质是Kit能力边界的语义拓展而非功能裁剪。原有的状态栏管理能力完整保留，同时为未来接入快捷栏、任务栏等功能预留了统一的命名空间。

2.2 -> 底层实现的变化

从技术实现层面来看，底层系统能力标识符 SystemCapability.PCService.StatusBarManager 保持不变，这意味着功能接口的具体实现逻辑没有发生结构性变更，开发者无需修改除导入语句外的业务代码即可完成迁移。这一设计保证了更名过程对存量应用的基本兼容性。

3 -> 核心变更详解：导入方式与API引用

3.1 -> 模块导入语句变更

这是本次Kit更名对开发者影响最直接的变化------涉及所有使用状态栏管理服务的ArkTS文件中，import语句的Kit来源需要同步更新。

3.1.1 -> 旧版写法（已废弃）

typescript 复制代码

// HarmonyOS 5.x及之前版本
import { statusBarManager } from '@kit.StatusBarExtensionKit';

3.1.2 -> 新版写法（HarmonyOS 6.0+）

typescript 复制代码

// HarmonyOS 6.0 +
import { statusBarManager } from '@kit.DeskTopExtensionKit';

从上述代码可以看出，唯一的变化在于Kit命名空间从 StatusBarExtensionKit 变更为 DeskTopExtensionKit，而导入的模块对象 statusBarManager 及其所有API方法均未发生变化。

3.2 -> Package名称变化对照表

项目	旧版（HarmonyOS 5.x）	新版（HarmonyOS 6.0+）
Kit名称	Status Bar Extension Kit	Desktop Extension Kit
中文名称	状态栏开放服务	桌面拓展服务
Kit导入路径	`@kit.StatusBarExtensionKit`	`@kit.DeskTopExtensionKit`
核心模块	`statusBarManager`	`statusBarManager`
系统能力标识	`SystemCapability.PCService.StatusBarManager`	`SystemCapability.PCService.StatusBarManager`
数据接口	`StatusBarItem`、`StatusBarIcon`等	保持不变

3.3 -> 版本兼容性说明

根据HarmonyOS版本管理策略，始于API version 12（HarmonyOS 5.0.0） 的模块接口起始版本标记保持不变。API 20（HarmonyOS 6.0）新增的功能在原有版本号基础上叠加标记，例如 hoverTips 属性起始版本为6.0.2(22)。

这意味着：

已上架的应用如果未主动升级依赖，短期内仍可正常运行
但建议存量应用尽快完成导入语句的更新，避免后续SDK升级时出现兼容性问题
新开发的应用必须使用新命名空间，否则编译将无法通过

4 -> Desktop Extension Kit核心API详解

4.1 -> 核心接口：statusBarManager

statusBarManager 是Desktop Extension Kit中提供状态栏管理能力的核心模块。应用通过该模块的API，可以实现在系统状态栏中添加自定义图标、更新图标显示、移除图标等基础功能，同时支持左键弹窗和右键菜单等交互形式的定制。

4.2 -> StatusBarItem：状态栏图标配置项

添加或更新状态栏图标时，需要通过 StatusBarItem 对象配置图标的完整信息。

typescript 复制代码

import { statusBarManager } from '@kit.DeskTopExtensionKit';
import image from '@ohos.multimedia.image';

// 准备图标资源
const whitePixelMap: image.PixelMap = ...;  // 深色壁纸下展示的图标（建议纯白色）
const blackPixelMap: image.PixelMap = ...;  // 浅色壁纸下展示的图标（建议纯黑色）

const statusBarItem: statusBarManager.StatusBarItem = {
  // 图标图片配置
  icons: {
    white: whitePixelMap,   // 深色壁纸模式下的图标，建议尺寸24vp * 24vp
    black: blackPixelMap    // 浅色壁纸模式下的图标，建议尺寸24vp * 24vp
  },
  
  // 左键弹窗业务配置（必选）
  quickOperation: {
    label: "应用名称",           // 弹窗标题，最长64个字符
    statusBarViewAbility: "MyStatusBarViewAbility"  // 关联的自定义Ability名称
  },
  
  // 右键分组菜单配置（可选）
  statusBarGroupMenu: [
    {
      menuItems: [
        {
          id: "menu1",
          label: "打开主窗口",
          action: () => { /* 响应逻辑 */ }
        },
        {
          id: "menu2", 
          label: "退出应用",
          action: () => { /* 响应逻辑 */ }
        }
      ]
    }
  ],
  
  // 鼠标悬停时的气泡提示（可选，起始版本6.0.2）
  hoverTips: "这是一个快捷工具应用"  // 长度1-128个字符
};

尺寸建议：图标图片建议使用24vp * 24vp的尺寸，类型支持JPEG、PNG、GIF、WebP、BMP、SVG、ICO、DNG等，推荐使用SVG格式以获得最佳的缩放效果。

4.3 -> 完整开发流程与代码示例

以下是一个完整的状态栏图标接入实现示例。

步骤1：添加图标资源

在 entry/src/main/resources/base/media/ 目录下添加两张图标文件，确保尺寸为24vp * 24vp。

步骤2：创建StatusBarViewExtensionAbility

新建 MyStatusBarViewAbility.ets，用于定义左键点击弹窗的UI内容。

typescript 复制代码

// MyStatusBarViewAbility.ets
import { StatusBarViewExtensionAbility } from '@kit.DeskTopExtensionKit';
import { AbilityConstant, Want } from '@kit.AbilityKit';

export default class MyStatusBarViewAbility extends StatusBarViewExtensionAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    console.info('StatusBarViewAbility onCreate');
  }

  onForeground(): void {
    console.info('StatusBarViewAbility onForeground');
  }

  onBackground(): void {
    console.info('StatusBarViewAbility onBackground');
  }

  onDestroy(): void {
    console.info('StatusBarViewAbility onDestroy');
  }
}

步骤3：配置module.json5

在 entry/src/main/module.json5 中注册自定义的StatusBarViewExtensionAbility。

json 复制代码

{
  "module": {
    "extensionAbilities": [
      {
        "name": "MyStatusBarViewAbility",
        "srcEntry": "./ets/statusbarviewextensionability/MyStatusBarViewAbility.ets",
        "type": "statusBarView"
      }
    ]
  }
}

步骤4：接入状态栏（完整示例）

typescript 复制代码

// 在UIAbility或Page中调用
import { statusBarManager } from '@kit.DeskTopExtensionKit';
import image from '@ohos.multimedia.image';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  private statusBarId: string = '';

  // 加载图标资源转换为PixelMap
  async loadIconPixelMap(resId: number): Promise<image.PixelMap> {
    const resourceManager = getContext(this).resourceManager;
    return await resourceManager.getMediaPixelMap(resId);
  }

  // 添加应用到状态栏
  async addToStatusBar(): Promise<void> {
    try {
      const whitePixelMap = await this.loadIconPixelMap($r('app.media.icon_white'));
      const blackPixelMap = await this.loadIconPixelMap($r('app.media.icon_black'));

      const statusBarItem: statusBarManager.StatusBarItem = {
        icons: {
          white: whitePixelMap,
          black: blackPixelMap
        },
        quickOperation: {
          label: "我的应用",
          statusBarViewAbility: "MyStatusBarViewAbility"
        },
        hoverTips: "点击查看快捷操作"
      };

      // 添加图标到状态栏，返回唯一标识ID
      this.statusBarId = await statusBarManager.add(statusBarItem);
      console.info(`状态栏图标添加成功，ID: ${this.statusBarId}`);
    } catch (error) {
      const businessError = error as BusinessError;
      console.error(`添加失败，错误码: ${businessError.code}, 信息: ${businessError.message}`);
    }
  }

  // 更新状态栏图标信息
  async updateStatusBarIcon(): Promise<void> {
    if (!this.statusBarId) return;
    
    try {
      const newWhitePixelMap = await this.loadIconPixelMap($r('app.media.new_icon_white'));
      const newBlackPixelMap = await this.loadIconPixelMap($r('app.media.new_icon_black'));
      
      const updatedItem: statusBarManager.StatusBarItem = {
        icons: {
          white: newWhitePixelMap,
          black: newBlackPixelMap
        },
        quickOperation: {
          label: "应用已更新",
          statusBarViewAbility: "MyStatusBarViewAbility"
        },
        hoverTips: "应用状态已变更"
      };
      
      await statusBarManager.update(this.statusBarId, updatedItem);
      console.info('状态栏图标更新成功');
    } catch (error) {
      const businessError = error as BusinessError;
      console.error(`更新失败，错误码: ${businessError.code}`);
    }
  }

  // 从状态栏移除图标
  async removeFromStatusBar(): Promise<void> {
    if (!this.statusBarId) return;
    
    try {
      await statusBarManager.remove(this.statusBarId);
      this.statusBarId = '';
      console.info('状态栏图标移除成功');
    } catch (error) {
      const businessError = error as BusinessError;
      console.error(`移除失败，错误码: ${businessError.code}`);
    }
  }

  build() {
    Column({ space: 16 }) {
      Button('添加至状态栏').onClick(() => this.addToStatusBar())
      Button('更新图标').onClick(() => this.updateStatusBarIcon())
      Button('从状态栏移除').onClick(() => this.removeFromStatusBar())
    }
    .padding(20)
    .width('100%')
    .height('100%')
  }
}

4.4 -> 右键分组菜单配置要点

statusBarGroupMenu 字段用于配置右键点击图标时弹出的分组菜单。

支持多级分组结构，但所有分组下一级菜单项的总和不可超过20个
每个菜单项需指定唯一ID、显示文本和点击响应动作
菜单项支持配置子菜单（深层嵌套受限）
建议合理规划菜单结构，避免过长列表影响用户体验

5 -> 迁移指南：存量项目如何适配

5.1 -> 全局替换方案

对于中大型项目，建议采用结构化检索替换的策略：

检索范围	检索关键词	替换目标
全部 `.ets` 文件	`@kit.StatusBarExtensionKit`	`@kit.DeskTopExtensionKit`
全部 `.ts` 文件	`@kit.StatusBarExtensionKit`	`@kit.DeskTopExtensionKit`
README/文档	Status Bar Extension	Desktop Extension

5.2 -> 工程配置变更检查

除代码文件外，还需检查以下工程配置文件是否涉及Kit名称引用：

oh-package.json5：依赖声明中的Kit引用
build-profile.json5：签名与构建配置
module.json5：扩展能力注册中的type字段（statusBarView 类型名称未变更）

5.3 -> 构建验证步骤

完成迁移后，建议按以下步骤进行验证：

Clean Project：清除旧的构建缓存，确保不会残留旧Kit的导入引用
重新构建 ：触发完整编译流程，观察是否存在 Cannot find module '@kit.StatusBarExtensionKit' 等错误
真机调试：在PC/2in1设备上运行应用，验证状态栏图标的添加、更新、移除功能均表现正常
边缘场景测试：测试深色/浅色壁纸切换时图标是否正确切换，右键菜单和悬停提示是否符合预期

6 -> 常见问题与最佳实践

6.1 -> 常见问题排查

Q1：更新导入语句后编译报错 "Module not found"

检查DevEco Studio及SDK版本是否已升级至支持HarmonyOS 6.0的最新版本。旧版SDK中可能尚未包含 @kit.DeskTopExtensionKit 的模块映射。

Q2：图标添加成功但在状态栏中不可见

请确认：

设备类型为PC/2in1设备，其他设备类型不支持该Kit
图标图片尺寸符合24vp * 24vp的建议规格
深色/浅色壁纸的图标资源均正确配置（建议同时提供黑白两套图标）

Q3：支持的最低API版本是多少？

本Kit起始版本为API 12（HarmonyOS 5.0.0），建议在 module.json5 中声明对应API等级。悬浮提示（hoverTips）功能起始版本为6.0.2(22)，低于此版本的系统版本调用将不生效。

6.2 -> 开发最佳实践

状态同步管理 ：应用应妥善保存 statusBarManager.add() 返回的图标ID，以便后续进行更新或移除操作。建议在页面销毁或应用退出的生命周期中主动调用移除接口，避免状态栏残留无效图标。
图标资源预加载：白色/黑色两套图片建议提前转换为PixelMap，避免每次更新时都重新加载资源文件。建议将转换后的PixelMap对象缓存，以提升图标更新性能。
错误处理 ：所有状态栏API调用均为异步操作，务必使用 try-catch 进行错误捕获，避免因异常导致应用崩溃。错误码信息可帮助快速定位问题原因。
菜单数量控制：右键分组菜单总项数不得超过20个限制，建议根据功能优先级精简菜单结构，将低频操作收入次级菜单。
地区与设备兼容性检查：上线前务必确认应用的发布地区在中国境内，目标设备为PC/2in1类型，否则状态栏功能将不生效。

7 -> 总结

Desktop Extension Kit（原Status Bar Extension Kit）在HarmonyOS 6.0中的更名，是华为围绕PC与2in1设备场景对系统能力进行整合和语义统一的重要举措。从"状态栏开放服务"到"桌面拓展服务"，名称的变化折射出华为对开发者生态的前瞻性规划------将桌面级快捷入口能力抽象为统一的Kit接口，为未来的功能迭代留出充足空间。

本次更名的核心要点如下：

导入路径必须更新 ：所有使用状态栏相关能力的代码文件，需将 import 语句中的 @kit.StatusBarExtensionKit 替换为 @kit.DeskTopExtensionKit。

API接口保持不变 ：statusBarManager 模块下的所有方法签名、参数类型和返回值均未变更，业务逻辑代码无需额外修改。

设备与地区限制延续：该Kit能力仍仅限PC/2in1设备且在支持地区范围内生效，相关限制条件未发生变化。

对于开发者而言，本次变更的迁移成本相对可控------主要是工程范围内的导入语句替换。但由于Kit名称变更涉及项目中的所有引用文件，建议开发团队采用全局检索替换的方式进行系统性更新，并完成全面的构建与真机验证后再发布新版本。

展望未来，Desktop Extension Kit的命名框架为HarmonyOS在桌面场景的能力扩展打开了更广阔的空间。随着PC融合体验的深度推进，该Kit或将集成更多与桌面快捷栏、任务栏、系统托盘等组件相关的能力接口，为开发者提供更加丰富的桌面级应用交互体验。

感谢各位大佬支持！！！
互三啦！！！