# 应用接入状态栏

应用接入状态栏之后，状态栏会显示应用自定义的图标，图标提供左键显示自定义弹窗、右键显示菜单以及hover状态回调的功能；应用退出时，状态栏图标会随着应用进程的销毁而消失。

*   从API版本26.0.0开始，新增检查设备状态是否支持状态栏图标接入能力，以及图标悬浮（hover）状态回调能力。
*   从6.1.1(24)版本开始，右键菜单获得增强，菜单项支持分别设置默认图标与选中图标，并支持独立更新单个一级菜单项或二级菜单项的内容。
*   从6.0.2(22)版本开始，支持自定义状态栏图标在鼠标悬浮（hover）时显示的内容。

#### 接口说明

以下列出应用接入状态栏的相关API，具体API说明详见接口文档。

Desktop Extension Kit（桌面拓展服务）相关API仅在PC/2in1设备上生效。

**表1** 应用接入状态栏相关功能接口介绍

| 接口名 | 描述 |
| --- | --- |
| addToStatusBar(context: common.Context, statusBarItem: StatusBarItem): void | 添加应用图标到状态栏。 |
| removeFromStatusBar(context: common.Context): void | 移除状态栏的应用图标。 |
| updateQuickOperationHeight(context: common.Context, height: number): void | 更新状态栏图标左键弹窗应用定制区域的高度。 |
| updateStatusBarMenu(context: common.Context, statusBarGroupMenus: StatusBarGroupMenu[]): void | 更新接入状态栏图标的右键菜单内容。 |
| updateStatusBarIcon(context: common.Context, statusBarIcon: StatusBarIcon): void | 更新状态栏图标。 |
| updateStatusBarHoverTips(context: common.Context, hoverTips: string): Promise<void> | 更新状态栏图标hover时显示内容。 |
| on(type: 'statusBarIconClick', callback: Callback<emitter.EventData>): void | 监听状态栏图标点击事件。 |
| off(type: 'statusBarIconClick', callback?: Callback<emitter.EventData>): void | 注销状态栏图标点击事件。 |
| on(type: 'rightMenuClick', callback: Callback<emitter.EventData>): void | 监听状态栏右键菜单点击事件。 |
| off(type: 'rightMenuClick', callback?: Callback<emitter.EventData>): void | 注销状态栏右键菜单点击事件。 |
| updateStatusBarMenuItem(context: common.Context, item: StatusBarMenuItem): Promise<void> | 更新单个一级菜单项内容。 |
| updateStatusBarSubMenuItem(context: common.Context, item: StatusBarSubMenuItem): Promise<void> | 更新菜单项的单个二级菜单项内容。 |
| isStatusBarCapabilitySupported(context: common.Context): Promise<boolean> | 检查是否支持状态栏能力。使用promise异步回调。 |
| onIconHover(callback: Callback<emitter.EventData>): void | 监听状态栏图标悬浮（hover）事件。使用callback异步回调。 |
| offIconHover(callback?: Callback<emitter.EventData>): void | 注销状态栏图标悬浮（hover）事件。使用callback异步回调。 |

#### 开发步骤

1.  导入相关模块。
    
    ```
    import { emitter } from '@kit.BasicServicesKit';
    import { statusBarManager } from '@kit.DeskTopExtensionKit';
    import { image } from '@kit.ImageKit';
    import { resourceManager } from '@kit.LocalizationKit';
    ```
    
2.  新建一个MyStatusBarViewAbility.ets文件（例如在entry/src/main/ets/statusbarviewextensionability文件夹下），同时新建一个StatusBarPage的页面（例如在entry/src/main/ets/pages目录下），该页面用于在状态栏图标的左键业务弹窗中显示，然后构建自定义的StatusBarViewExtensionAbility。
    
    ```
    import { UIExtensionContentSession, Want } from '@kit.AbilityKit';
    import { StatusBarViewExtensionAbility } from '@kit.DeskTopExtensionKit';
    
    let TAG = 'MyStatusBarViewAbility';
    
    export default class MyStatusBarViewAbility extends StatusBarViewExtensionAbility {
      // 当StatusBarViewExtensionAbility组件实例完成创建时，系统会触发该回调。
      onCreate() {
        console.info(TAG, 'onCreate');
      }
    
      // 当UIExtensionContentSession实例创建完成后，系统会触发该回调。
      onSessionCreate(want: Want, session: UIExtensionContentSession) {
        console.info(TAG, `onSessionCreate, want: ${want.abilityName}`);
        // pages/StatusBarPage为状态栏图标左键业务弹窗显示的页面
        session.loadContent('pages/StatusBarPage');
      }
    
      // 当StatusBarViewExtensionAbility组件首次启动到前台或者从后台转入到前台时，系统触发该回调。
      onForeground() {
        console.info(TAG, 'onForeground');
      }
    
      // 当StatusBarViewExtensionAbility组件从前台转入到后台时，系统触发该回调。
      onBackground() {
        console.info(TAG, 'onBackground');
      }
    
      // 当UIExtensionContentSession实例销毁后，系统触发该回调。
      onSessionDestroy(session: UIExtensionContentSession) {
        console.info(TAG, 'onSessionDestroy');
      }
    
      // 当StatusBarViewExtensionAbility组件被销毁时，系统触发该回调。
      onDestroy() {
        console.info(TAG, 'onDestroy');
      }
    }
    ```
    
3.  在MyStatusBarViewAbility所在模块下的module.json5文件中配置状态栏扩展Ability的信息。
    
    ```
    "extensionAbilities": [
        {
            "name": "MyStatusBarViewAbility",
            "icon": "$media:startIcon",
            "description": "statusBar",
            "type": "statusBarView",
            "exported": true,
            // 此处为MyStatusBarViewAbility类所在的文件路径
            "srcEntry": "./ets/statusbarviewextensionability/MyStatusBarViewAbility.ets"
        }
    ],
    ```
    
4.  在对应模块的rawfile文件夹（例如entry/src/main/resources/rawfile）下预置两张24vp \* 24vp尺寸的图片（例如本示例中testWhite.svg和testBlack.svg两张图片），在页面组件内(如：index.ets)配置应用接入状态栏显示的图标信息。
    
    ```
    /**
     * 可以通过自定义组件的内置方法获取Context信息
     * 具体方法：this.getUIContext().getHostContext();
     */
    if (!context) {
      console.error('getHostContext failed');
      return;
    }
    // 获取resourceManager资源管理器
    const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
    
    // 创建white pixelMap，需在资源rawfile文件夹中预置testWhite.svg图片，图片大小为24vp * 24vp
    const whiteFileData = resourceMgr.getRawFileContentSync('testWhite.svg');
    const whiteBuffer = whiteFileData.buffer;
    const whiteImageSource = image.createImageSource(whiteBuffer);
    let whitePixelMap = await whiteImageSource.createPixelMap();
    
    // 创建black pixelMap，需在资源rawfile文件夹中预置testBlack.svg图片，图片大小为24vp * 24vp
    const blackFileData = resourceMgr.getRawFileContentSync('testBlack.svg');
    const blackBuffer = blackFileData.buffer;
    const blackImageSource = image.createImageSource(blackBuffer);
    let blackPixelMap = await blackImageSource.createPixelMap();
    
    // 构建图标信息
    let icon: statusBarManager.StatusBarIcon = {
      white: whitePixelMap,
      black: blackPixelMap
    }
    ```
    
5.  配置状态栏左键点击弹窗相关信息。
    
    ```
    // 构建左键业务弹窗信息
    let operation: statusBarManager.QuickOperation = {
      abilityName: 'MyStatusBarViewAbility',
      title: 'TestDemo',
      height: 300,
      // 可缺省
      moduleName: 'entry'
    };
    ```
    
6.  （可选）配置状态栏右键菜单内容信息，可在状态栏图标的右键菜单中增加自定义菜单选项。无论是否配置右键菜单，系统均会自动生成一个“退出”的菜单选项，该选项不支持应用自定义。若应用具备语言切换功能，该项的语言将遵循系统设置，而非应用内的语言设置。
    
    ```
    // 构建右键菜单项内容
    let subMenus: statusBarManager.StatusBarSubMenuItem[] = [];
    let subMenuItemAction: statusBarManager.StatusBarMenuAction = {
      abilityName: 'EntryAbility'
    }
    let subMenu: statusBarManager.StatusBarSubMenuItem = {
      subTitle: '子菜单项',
      menuAction: subMenuItemAction
    }
    subMenus.push(subMenu);
    
    let statusBarMenuItems: statusBarManager.StatusBarMenuItem[] = [];
    let menuItem: statusBarManager.StatusBarMenuItem = {
      title: '一级菜单项',
      // 一级menuAction和subMenu两项不可都缺省
      subMenu: subMenus
    };
    statusBarMenuItems.push(menuItem);
    
    let statusBarGroupMenus: statusBarManager.StatusBarGroupMenu[] = [];
    statusBarGroupMenus.push(statusBarMenuItems);
    ```
    
7.  整合配置信息，调用isStatusBarCapabilitySupported判断当前设备状态是否支持图标接入状态栏的能力，如果设备状态支持，则调用addToStatusBar将图标接入状态栏，显示应用图标；如果不支持，则调用addToStatusBar后，界面上无效果。
    
    ```
    // 构建添加到状态栏的图标详细信息
    let item: statusBarManager.StatusBarItem = {
      icons: icon,
      quickOperation: operation,
      statusBarGroupMenu: statusBarGroupMenus,
      // 初始化时可以自定义hover时显示内容
      hoverTips: 'appName'
    };
    
    try {
      statusBarManager.addToStatusBar(context, item);
    } catch (error) {
      console.error(`addToStatusBar failed. error code: ${error.code}, error message: ${error.message}`);
    }
    ```
    
8.  （可选）应用接入状态栏之后，可以通过updateStatusBarMenu接口更新状态栏的右键菜单。
    
    ```
    /**
     * 可以通过自定义组件的内置方法获取Context信息
     * 具体方法：this.getUIContext().getHostContext();
     */
    function updateStatusBarMenuExample(context: Context) {
      // 构建右键菜单项内容
      let subMenus: statusBarManager.StatusBarSubMenuItem[] = [];
      let subMenuItemAction: statusBarManager.StatusBarMenuAction = {
        abilityName: 'EntryAbility'
      }
      let subMenu: statusBarManager.StatusBarSubMenuItem = {
        subTitle: '二级菜单项',
        menuAction: subMenuItemAction,
        menuCode: '00'
      }
      subMenus.push(subMenu);
    
      let statusBarMenuItems: statusBarManager.StatusBarMenuItem[] = [];
      let menuItem: statusBarManager.StatusBarMenuItem = {
        title: '一级菜单项',
        menuCode: '0',
        // 一级menuAction和subMenu两项不可都缺省
        subMenu: subMenus
      };
      statusBarMenuItems.push(menuItem);
    
      let statusBarGroupMenus: statusBarManager.StatusBarGroupMenu[] = [];
      statusBarGroupMenus.push(statusBarMenuItems);
    
      if (!context) {
        console.error('getHostContext failed');
        return;
      }
      try {
        statusBarManager.updateStatusBarMenu(context, statusBarGroupMenus);
      } catch (error) {
        console.error(`updateStatusBarMenu failed. error code: ${error.code}, error message: ${error.message}`);
      }
    }
    ```
    
9.  （可选）应用接入状态栏之后，可以通过updateQuickOperationHeight接口更新状态栏图标左键业务弹窗的高度。
    
    ```
    /**
     * 可以通过自定义组件的内置方法获取Context信息
     * 具体方法：this.getUIContext().getHostContext();
     */
    function updateQuickOperationHeightExample(context: Context) {
      if (!context) {
        console.error('getHostContext failed');
        return;
      }
      let height = 200;
      statusBarManager.updateQuickOperationHeight(context, height);
    }
    ```
    
10.  （可选）应用接入状态栏之后，可以通过updateStatusBarIcon接口将状态栏中对应的应用图标进行更改。
     
     ```
     /**
      * 可以通过自定义组件的内置方法获取Context信息
      * 具体方法：this.getUIContext().getHostContext();
      */
     async function updateStatusBarIconExample(context: Context) {
       if (!context) {
         console.error('getHostContext failed');
         return;
       }
       // 获取resourceManager资源管理器
       const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
     
       // 创建white pixelMap，需在资源rawfile文件夹中预置testWhite.svg图片，图片大小为24vp * 24vp
       const whiteFileData = resourceMgr.getRawFileContentSync('testWhite.svg');
       const whiteBuffer = whiteFileData.buffer;
       const whiteImageSource = image.createImageSource(whiteBuffer);
       let whitePixelMap = await whiteImageSource.createPixelMap();
     
       // 创建black pixelMap，需在资源rawfile文件夹中预置testBlack.svg图片，图片大小为24vp * 24vp
       const blackFileData = resourceMgr.getRawFileContentSync('testBlack.svg');
       const blackBuffer = blackFileData.buffer;
       const blackImageSource = image.createImageSource(blackBuffer);
       let blackPixelMap = await blackImageSource.createPixelMap();
     
       // 构建图标信息
       let icons: statusBarManager.StatusBarIcon = {
         white: whitePixelMap,
         black: blackPixelMap
       }
       statusBarManager.updateStatusBarIcon(context, icons);
     }
     ```
     
11.  （可选）应用接入状态栏之后，且未指定图标QuickOperation的abilityName可以通过on/off接口自定义状态栏图标左键业务。
     
     ```
     function listenerLeftClickByOnOff() {
       let onStatusBarIconClick = (eventData: emitter.EventData) => {
         // 自定义图标点击业务
         let data = eventData.data;
         if (data) {
           switch (data['iconClickType']) {
             case 'leftClick':
               // 自定义左键点击业务
               break;
             default:
               break;
           }
         }
       }
     
       // 监听状态栏图标点击事件
       statusBarManager.on('statusBarIconClick', onStatusBarIconClick);
     
       // 注销状态栏图标点击事件,调用on之后最终需要调用off接口
       statusBarManager.off('statusBarIconClick', onStatusBarIconClick);
     }
     ```
     
12.  （可选）应用接入状态栏之后，调用updateStatusBarMenu接口，指定菜单StatusBarMenuAction的notifyOnly使能和menuCode菜单项标识，可以通过on/off接口自定义状态栏图标右键菜单点击业务。
     
     ```
     function listenerRightClickByOnOff() {
       let onRightMenuClick = (eventData: emitter.EventData) => {
         // 自定义图标右键菜单点击业务
         let data = eventData.data;
         if (data) {
           let menuCode = data['menuCode'] as string;
           // 处理点击菜单项业务
         }
       }
     
       // 监听状态栏图标右键菜单点击事件
       statusBarManager.on('rightMenuClick', onRightMenuClick);
     
       // 注销状态栏图标右键菜单点击事件,调用on之后最终需要调用off接口
       statusBarManager.off('rightMenuClick', onRightMenuClick);
     }
     ```
     
13.  （可选）应用接入状态栏之后，调用updateStatusBarHoverTips接口可以自定义图标hover时的显示内容。
     
     ```
     /**
      * 可以通过自定义组件的内置方法获取Context信息
      * 具体方法：this.getUIContext().getHostContext();
      */
     async function updateStatusBarHoverTipsExample(context: Context) {
       if (!context) {
         console.error('getHostContext failed');
         return;
       }
       let hoverTips: string = 'hoverTips';
       try {
         await statusBarManager.updateStatusBarHoverTips(context, hoverTips);
       } catch (error) {
         console.error(`updateStatusBarHoverTips ${error.message} ${error.code}`)
       }
     }
     ```
     
14.  （可选）对于已接入状态栏的应用，如果存在菜单项并且某个一级菜单项已设置menuCode属性，则可调用updateStatusBarMenuItem接口，通过指定的menuCode来更新对应一级菜单项的内容。
     
     ```
     /**
      * 可以通过自定义组件的内置方法获取Context信息
      * 具体方法：this.getUIContext().getHostContext();
      */
     async function updateStatusBarMenuItemExample(context: Context) {
       if (!context) {
         console.error('getHostContext failed');
         return;
       }
       // 获取resourceManager资源管理器
       const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
     
       // 创建white pixelMap，需在资源rawfile文件夹中预置testWhite.svg图片，图片大小为24vp * 24vp
       const whiteFileData = resourceMgr.getRawFileContentSync('testWhite.svg');
       const whiteBuffer = whiteFileData.buffer;
       const whiteImageSource = image.createImageSource(whiteBuffer);
       let whitePixelMap = await whiteImageSource.createPixelMap();
     
       // 创建black pixelMap，需在资源rawfile文件夹中预置testBlack.svg图片，图片大小为24vp * 24vp
       const blackFileData = resourceMgr.getRawFileContentSync('testBlack.svg');
       const blackBuffer = blackFileData.buffer;
       const blackImageSource = image.createImageSource(blackBuffer);
       let blackPixelMap = await blackImageSource.createPixelMap();
     
       // 构建图标信息
       let icon: statusBarManager.StatusBarItemIcon = {
         white: whitePixelMap,
         black: blackPixelMap
       }
     
       let menuItemOptions: statusBarManager.StatusBarMenuItemOptions = {
         icon: icon,
         selected: true
       }
     
       let menuAction: statusBarManager.StatusBarMenuAction = {
         abilityName: 'EntryAbility'
       }
     
       let menuItemTmp: statusBarManager.StatusBarMenuItem = {
         title: 'menuItem after',
         // 当前的menuCode需要已经存在于已有的一级菜单中
         menuCode: '0',
         // 一级菜单项的menuAction和subMenu两项不可同时缺省
         menuAction: menuAction,
         // 支持设置图标及当前菜单项是否选中
         options: menuItemOptions
       }
     
       try {
         updateStatusBarMenuExample(context);
         await statusBarManager.updateStatusBarMenuItem(context, menuItemTmp);
       } catch (error) {
         console.error(`updateStatusBarMenuItem failed. error code: ${error?.code}, error message: ${error?.message}`);
       }
     }
     ```
     
15.  （可选）对于已接入状态栏的应用，若其一级菜单项包含二级菜单，且二级菜单项已设置menuCode属性，则可调用updateStatusBarSubMenuItem接口，通过指定的menuCode来更新对应二级菜单项的内容。
     
     ```
     /**
      * 可以通过自定义组件的内置方法获取Context信息
      * 具体方法：this.getUIContext().getHostContext();
      */
     async function updateStatusBarSubMenuItemExample(context: Context) {
       if (!context) {
         console.error('getHostContext failed');
         return;
       }
       // 获取resourceManager资源管理器
       const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
     
       // 创建white pixelMap，需在资源rawfile文件夹中预置testWhite.svg图片，图片大小为24vp * 24vp
       const whiteFileData = resourceMgr.getRawFileContentSync('testWhite.svg');
       const whiteBuffer = whiteFileData.buffer;
       const whiteImageSource = image.createImageSource(whiteBuffer);
       let whitePixelMap = await whiteImageSource.createPixelMap();
     
       // 创建black pixelMap，需在资源rawfile文件夹中预置testBlack.svg图片，图片大小为24vp * 24vp
       const blackFileData = resourceMgr.getRawFileContentSync('testBlack.svg');
       const blackBuffer = blackFileData.buffer;
       const blackImageSource = image.createImageSource(blackBuffer);
       let blackPixelMap = await blackImageSource.createPixelMap();
     
       // 构建图标信息
       let icon: statusBarManager.StatusBarItemIcon = {
         white: whitePixelMap,
         black: blackPixelMap
       }
       let subMenuItemOptions: statusBarManager.StatusBarMenuItemOptions = {
         icon: icon,
         selected: true
       }
       let menuAction: statusBarManager.StatusBarMenuAction = {
         abilityName: 'EntryAbility'
       }
       let subMenuItemTmp: statusBarManager.StatusBarSubMenuItem = {
         subTitle: 'menuItem',
         // 当前的menuCode需要存在于已有的二级菜单项中
         menuCode: '00',
         menuAction: menuAction,
         // 支持设置图标及当前菜单项是否选中
         options: subMenuItemOptions
       }
       try {
         updateStatusBarMenuExample(context);
         await statusBarManager.updateStatusBarSubMenuItem(context, subMenuItemTmp);
       } catch (error) {
         console.error(`updateStatusBarSubMenuItem failed. error code: ${error?.code}, error message: ${error?.message}`);
       }
     }
     ```
     
16.  （可选）应用接入状态栏之后，可以通过onIconHover/offIconHover接口自定义状态栏图标悬浮（hover）业务。
     
     ```
     let onIconHoverChange = (eventData: emitter.EventData) => {
       let data = eventData.data;
       if (data) {
         let isHovered = data['isHovered'] as boolean;
         // 处理图标悬浮业务
       }
     };
     
     // 监听状态栏图标悬浮事件
     statusBarManager.onIconHover(onIconHoverChange);
     
     // 取消事件回调处理函数
     statusBarManager.offIconHover(onIconHoverChange);
     ```
     

#### 完整示例代码

完整示例代码请参见状态栏开放服务。