跳到主要内容

应用接入状态栏

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

从6.0.2(22)版本开始支持更新状态栏图标hover时显示内容。

接口说明​

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

DeskTop Extension Kit（桌面拓展服务）相关API仅在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注销状态栏右键菜单点击事件。

开发步骤​

  1. 导入相关模块。

    import { statusBarManager, StatusBarViewExtensionAbility } from '@kit.DeskTopExtensionKit';
    import { UIExtensionContentSession, Want } from '@kit.AbilityKit';
    import { image } from '@kit.ImageKit';
    import { resourceManager } from '@kit.LocalizationKit';
    import { emitter } from '@kit.BasicServicesKit';

  2. 新建一个MyStatusBarViewAbility.ets文件（例如在entry/src/main/ets/statusbarviewextensionability文件夹下），同时新建一个StatusBarPage的页面（例如在entry/src/main/ets/pages目录下），该页面用于在状态栏图标的左键业务弹窗中显示，然后构建自定义的StatusBarViewExtensionAbility。

    let TAG = 'MyStatusBarViewExtAbility';
    export default class MyStatusBarViewAbility extends StatusBarViewExtensionAbility {
      onCreate() {
        console.info(TAG, `onCreate`);
      }

      onSessionCreate(want: Want, session: UIExtensionContentSession) {
        console.info(TAG, `onSessionCreate, want: ${want.abilityName}`);
        // pages/StatusBarPage为状态栏图标左键业务弹窗显示的页面
        session.loadContent('pages/StatusBarPage');
      }

      onForeground() {
        console.info(TAG, `onForeground`);
      }

      onBackground() {
        console.info(TAG, `onBackground`);
      }

      onSessionDestroy(session: UIExtensionContentSession) {
        console.info(TAG, `onSessionDestroy`);
      }

      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.png和testBlack.png两张图片），在页面组件内(如：index.ets)配置应用接入状态栏显示的图标信息。

    let context: Context | undefined = this.getUIContext().getHostContext();
    if (!context) {
      console.error('getHostContext failed');
      return;
    }
    // 获取resourceManager资源管理器
    const resourceMgr: resourceManager.ResourceManager = context.resourceManager;

    // 创建white pixelMap，需在资源rawfile文件夹中预置testWhite.png图片，图片大小为24vp * 24vp
    const whiteFileData = resourceMgr.getRawFileContentSync('testWhite.png');
    const whiteBuffer = whiteFileData.buffer;
    const whiteImageSource = image.createImageSource(whiteBuffer);
    let whitePixelMap = await whiteImageSource.createPixelMap();

    // 创建black pixelMap，需在资源rawfile文件夹中预置testBlack.png图片，图片大小为24vp * 24vp
    const blackFileData = resourceMgr.getRawFileContentSync('testBlack.png');
    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为上述配置的module.json5中配置的自定义StatusBarViewExtensionAbility名称
      abilityName: "MyStatusBarViewAbility",
      title: "测试Demo",
      height: 300,
      // 可缺省
      moduleName: 'entry'
    };

  6. （可选）配置状态栏右键菜单内容信息，可在状态栏图标的右键菜单中增加自定义菜单选项。

    // 构建右键菜单项内容
    let subMenus: Array<statusBarManager.StatusBarSubMenuItem> = [];
    let subMenuItemAction: statusBarManager.StatusBarMenuAction = {
      abilityName: "EntryAbility"
    }
    let subMenu: statusBarManager.StatusBarSubMenuItem = {
      subTitle: "子菜单项",
      menuAction: subMenuItemAction
    }
    subMenus.push(subMenu);

    let statusBarMenuItems: Array<statusBarManager.StatusBarMenuItem> = [];
    let menuItem: statusBarManager.StatusBarMenuItem = {
      title: "一级菜单项",
      // 一级menuAction和subMenu两项不可都缺省
      subMenu: subMenus
    };
    statusBarMenuItems.push(menuItem);

    let statusBarGroupMenus: Array<statusBarManager.StatusBarGroupMenu> = [];
    statusBarGroupMenus.push(statusBarMenuItems);

  7. 整合配置信息，接入状态栏，显示应用图标。

    // 构建添加到状态栏的图标详细信息
    let item: statusBarManager.StatusBarItem = {
      icons: icon,
      quickOperation: operation,
      // 该参数可选
      statusBarGroupMenu: statusBarGroupMenus
    };

    try {
      statusBarManager.addToStatusBar(context, item);
    } catch (error) {
      console.error(`addToStatusBar failed. error code: ${error.code}, error message: ${error.message}`);
    }

  8. （可选）应用接入状态栏之后，可以通过updateStatusBarMenu接口更新状态栏的右键菜单。

    // 构建右键菜单项内容
    let subMenus: Array<statusBarManager.StatusBarSubMenuItem> = [];
    let subMenuItemAction: statusBarManager.StatusBarMenuAction = {
      abilityName: "EntryAbility"
    }
    let subMenu: statusBarManager.StatusBarSubMenuItem = {
      subTitle: "二级菜单项",
      menuAction: subMenuItemAction
    }
    subMenus.push(subMenu);

    let statusBarMenuItems: Array<statusBarManager.StatusBarMenuItem> = [];
    let menuItem: statusBarManager.StatusBarMenuItem = {
      title: "一级菜单项",
      // 一级menuAction和subMenu两项不可都缺省
      subMenu: subMenus
    };
    statusBarMenuItems.push(menuItem);

    let statusBarGroupMenus: Array<statusBarManager.StatusBarGroupMenu> = [];
    statusBarGroupMenus.push(statusBarMenuItems);

    let context: Context | undefined = this.getUIContext().getHostContext();
    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接口更新状态栏图标左键业务弹窗的高度。

    let context: Context | undefined = this.getUIContext().getHostContext();
    if (!context) {
      console.error('getHostContext failed');
      return;
    }
    let height = 200;
    statusBarManager.updateQuickOperationHeight(context, height);

  10. （可选）应用接入状态栏之后，可以通过updateStatusBarIcon接口将状态栏中对应的应用图标进行更改。

    let context: Context | undefined = this.getUIContext().getHostContext();
    if (!context) {
      console.error('getHostContext failed');
      return;
    }
    // 获取resourceManager资源管理器
    const resourceMgr: resourceManager.ResourceManager = context.resourceManager;

    // 创建white pixelMap，需在资源rawfile文件夹中预置testWhite.png图片，图片大小为24vp * 24vp
    const whiteFileData = resourceMgr.getRawFileContentSync('testWhite.png');
    const whiteBuffer = whiteFileData.buffer;
    const whiteImageSource = image.createImageSource(whiteBuffer);
    let whitePixelMap = await whiteImageSource.createPixelMap();

    // 创建black pixelMap，需在资源rawfile文件夹中预置testBlack.png图片，图片大小为24vp * 24vp
    const blackFileData = resourceMgr.getRawFileContentSync('testBlack.png');
    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接口自定义状态栏图标左键业务。

    private onStatusBarIconClick = (eventData: emitter.EventData) => {
      // 自定义图标点击业务
      let data = eventData.data;
      if (data) {
        switch (data['iconClickType']) {
          case 'leftClickType':
            // 自定义左键点击业务
            break;
          default:
            break;
        }
      }
    }

    // 监听状态栏图标点击事件
    statusBarManager.on('statusBarIconClick', this.onStatusBarIconClick);

    // 注销状态栏图标点击事件
    statusBarManager.off('statusBarIconClick', this.onStatusBarIconClick);

  12. （可选）应用接入状态栏之后，调用updateStatusBarMenu接口，指定菜单StatusBarMenuAction的notifyOnly使能和menuCode菜单项标识，可以通过on/off接口自定义状态栏图标右键菜单点击业务。

    private onRightMenuClick = (eventData: emitter.EventData) => {
      // 自定义图标右键菜单点击业务
      let data = eventData.data;
      if (data) {
        let menuCode = data['menuCode'] as string;
        // 处理点击菜单项业务
      }
    }

    // 监听状态栏图标右键菜单点击事件
    statusBarManager.on('rightMenuClick', this.onRightMenuClick);

    // 注销状态栏图标右键菜单点击事件
    statusBarManager.off('rightMenuClick', this.onRightMenuClick);

  13. （可选）应用接入状态栏之后，调用updateStatusBarHoverTips接口可以自定义图标hover时的显示内容。

    let context: Context | undefined = this.getUIContext().getHostContext();
    if (!context) {
      console.error('getHostContext failed');
      return;
    }
    let hoverTips: string = 'hoverTips';
    try {
      await statusBarManager.updateStatusBarHoverTips(context, hoverTips);
    } catch (err) {
      console.error(`updateStatusBarHoverTips ${err.message} ${err.code}`)
    }

完整示例代码​

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