@ohos.window.floatingBall (闪控球窗口)

导入模块

import { floatingBall } from '@kit.ArkUI';

floatingBall.isFloatingBallEnabled

isFloatingBallEnabled(): boolean

判断当前设备是否支持闪控球功能。

系统能力： SystemCapability.Window.SessionManager

返回值：

示例：

// 判断当前设备是否支持闪控球功能
let enable: boolean = floatingBall.isFloatingBallEnabled();
console.info('Floating ball enabled is: ' + enable);

floatingBall.create

create(config: FloatingBallConfiguration): Promise<FloatingBallController>

创建闪控球控制器，使用Promise异步回调。

系统能力： SystemCapability.Window.SessionManager

设备行为差异： 在HarmonyOS 7.0.0之前，该接口在Tablet设备的非电脑模式、Phone设备下可正常调用，在其他设备、Tablet设备的电脑模式下调用返回801错误码。从HarmonyOS 7.0.0开始，支持在Phone、PC/2in1、Tablet设备使用，其他设备调用返回801错误码。

参数：

返回值：

错误码：

以下错误码的详细介绍请参见通用错误码和窗口错误码。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// 声明闪控球控制器实例
let floatingBallController: floatingBall.FloatingBallController | undefined = undefined;
// 请在组件内获取context，确保this.getUIContext().getHostContext()返回的结果为UIAbilityContext
let ctx = this.getUIContext().getHostContext() as common.UIAbilityContext;
// 配置闪控球控制器参数
let config: floatingBall.FloatingBallConfiguration = {
  context: ctx,
};
try {
  // 创建闪控球控制器
  floatingBall.create(config).then((data: floatingBall.FloatingBallController) => {
    // 保存控制器实例
    floatingBallController = data;
    console.info(`Succeeded in creating floating ball controller. Data: ${data}`);
  }).catch((err: BusinessError) => {
    console.error(`Failed to create floating ball controller. Cause:${err.code}, message:${err.message}`);
  });
} catch (e) {
  console.error(`Failed to create floating ball controller. Cause:${e.code}, message:${e.message}`);
}

FloatingBallConfiguration

创建闪控球控制器时需要提供的参数配置。

系统能力： SystemCapability.Window.SessionManager

FloatingBallController

闪控球控制器实例，用于启动、更新、停止闪控球以及注册回调等操作。

下列API示例中都需先使用floatingBall.create()方法获取到闪控球控制器实例（即floatingBallController），再通过此实例调用对应方法。

系统能力： SystemCapability.Window.SessionManager

startFloatingBall

startFloatingBall(params: FloatingBallParams): Promise<void>

启动闪控球，使用Promise异步回调。

需要权限： ohos.permission.USE_FLOAT_BALL

系统能力： SystemCapability.Window.SessionManager

参数：

返回值：

错误码：

以下错误码的详细介绍请参见通用错误码和窗口错误码。

示例：

import { BusinessError } from '@kit.BasicServicesKit';

// 配置闪控球启动参数
let startParams: floatingBall.FloatingBallParams = {
  template: floatingBall.FloatingBallTemplate.EMPHATIC,
  title: 'title',
  content: 'content'
};
try {
  // 启动闪控球
  floatingBallController.startFloatingBall(startParams).then(() => {
    console.info('Succeeded in starting floating ball.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to start floating ball. Cause:${err.code}, message:${err.message}`);
  });
} catch (e) {
  console.error(`Failed to start floating ball. Cause:${e.code}, message:${e.message}`);
}

updateFloatingBall

updateFloatingBall(params: FloatingBallParams): Promise<void>

更新闪控球，使用Promise异步回调。必须先调用startFloatingBall()启动闪控球后，才能调用此方法更新闪控球参数。

系统能力： SystemCapability.Window.SessionManager

参数：

返回值：

错误码：

以下错误码的详细介绍请参见窗口错误码。

示例：

import { BusinessError } from '@kit.BasicServicesKit';

// 配置闪控球更新参数
let updateParams: floatingBall.FloatingBallParams = {
  template: floatingBall.FloatingBallTemplate.EMPHATIC,
  title: 'title2',
  content: 'content2'
};
try {
  // 更新闪控球
  floatingBallController.updateFloatingBall(updateParams).then(() => {
    console.info('Succeeded in updating floating ball.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to update floating ball. Cause:${err.code}, message:${err.message}`);
  });
} catch (e) {
  console.error(`Failed to update floating ball. Cause:${e.code}, message:${e.message}`);
}

stopFloatingBall

stopFloatingBall(): Promise<void>

停止闪控球，使用Promise异步回调。

系统能力： SystemCapability.Window.SessionManager

返回值：

错误码：

以下错误码的详细介绍请参见窗口错误码。

示例：

import { BusinessError } from '@kit.BasicServicesKit';

// 停止闪控球
floatingBallController.stopFloatingBall().then(() => {
  console.info('Succeeded in stopping floating ball.');
}).catch((err: BusinessError) => {
  console.error(`Failed to stop floating ball. Cause:${err.code}, message:${err.message}`);
});

on('stateChange')

on(type: 'stateChange', callback: Callback<FloatingBallState>): void

注册闪控球生命周期状态变化的监听事件。不再使用时，取消监听以避免内存泄漏。

系统能力： SystemCapability.Window.SessionManager

参数：

错误码：

以下错误码的详细介绍请参见窗口错误码。

示例：

// 定义状态变化回调函数
let onStateChange = (state: floatingBall.FloatingBallState) => {
  console.info('Floating ball stateChange: ' + state);
};
try {
  // 注册闪控球状态变化监听
  floatingBallController.on('stateChange', onStateChange);
} catch (e) {
  console.error(`Failed to on stateChange floating ball. Cause:${e.code}, message:${e.message}`);
}

off('stateChange')

off(type: 'stateChange', callback?: Callback<FloatingBallState>): void

取消闪控球生命周期状态变化的监听事件。

系统能力： SystemCapability.Window.SessionManager

参数：

错误码：

以下错误码的详细介绍请参见窗口错误码。

示例：

// 定义状态变化回调函数（需与注册时的回调一致）
let onStateChange = (state: floatingBall.FloatingBallState) => {
  console.info('Floating ball stateChange: ' + state);
};
try {
  // 取消闪控球状态变化监听
  floatingBallController.off('stateChange', onStateChange);
} catch (e) {
  console.error(`Failed to off stateChange floating ball. Cause:${e.code}, message:${e.message}`);
}

on('click')

on(type: 'click', callback: Callback<void>): void

注册闪控球的点击监听事件，不使用时，取消监听以避免内存泄漏。

系统能力： SystemCapability.Window.SessionManager

参数：

错误码：

以下错误码的详细介绍请参见窗口错误码。

示例：

// 定义点击事件回调函数
let onClick = () => {
  console.info('Floating ball onClick');
};
try {
  // 注册闪控球点击监听
  floatingBallController.on('click', onClick);
} catch (e) {
  console.error(`Failed to on click floating ball. Cause:${e.code}, message:${e.message}`);
}

off('click')

off(type: 'click', callback?: Callback<void>): void

取消闪控球点击的监听事件。

系统能力： SystemCapability.Window.SessionManager

参数：

错误码：

以下错误码的详细介绍请参见窗口错误码。

示例：

// 定义点击事件回调函数（需与注册时的回调一致）
let onClick = () => {
  console.info('Floating ball onClick');
};
try {
  // 取消闪控球点击监听
  floatingBallController.off('click', onClick);
} catch (e) {
  console.error(`Failed to off click floating ball. Cause:${e.code}, message:${e.message}`);
}

getFloatingBallWindowInfo

getFloatingBallWindowInfo(): Promise<FloatingBallWindowInfo>

获取闪控球窗口信息，使用Promise异步回调。

系统能力： SystemCapability.Window.SessionManager

返回值：

错误码：

以下错误码的详细介绍请参见窗口错误码。

示例：

import { BusinessError } from '@kit.BasicServicesKit';

// 获取闪控球窗口信息
floatingBallController.getFloatingBallWindowInfo().then((data: floatingBall.FloatingBallWindowInfo) => {
  console.info('Succeeded in getting floating ball window info. Info: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error(`Failed to get floating ball window info. Cause code: ${err.code}, message: ${err.message}`);
});

restoreMainWindow

restoreMainWindow(want: Want): Promise<void>

恢复应用主窗口并加载指定页面。使用Promise异步回调。仅支持在点击闪控球后调用；若应用拥有ohos.permission.AUTO_RESTORE_MAIN_WINDOW权限，可以无需点击直接调用该接口。

需要权限： ohos.permission.USE_FLOAT_BALL

系统能力： SystemCapability.Window.SessionManager

参数：

返回值：

错误码：

以下错误码的详细介绍请参见通用错误码和窗口错误码。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { Want } from '@kit.AbilityKit';

// 配置要恢复的主窗口Want参数
let want: Want = {
  bundleName: 'xxx.xxx.xxx',
  abilityName: 'EntryAbility'
};
try {
  // 恢复应用主窗口并加载指定页面
  floatingBallController.restoreMainWindow(want).then(() => {
    console.info('Succeeded in restoring floating ball main window.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to restore floating ball main window. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (e) {
  console.error(`Failed to restore floating ball main window. Cause:${e.code}, message:${e.message}`);
}

setFloatingBallVisibilityInApp²⁴⁺

setFloatingBallVisibilityInApp(isVisible: boolean): Promise<void>

设置闪控球在应用内是否可见。使用Promise异步回调。

• 当应用处于多任务界面时（生命周期状态为PAUSED），闪控球不可见。
• 默认情况（即未调用此接口设置时）和调用此接口传入true时：除多任务界面外，闪控球均可见。
• 调用此接口传入false时：当应用处于前台（生命周期状态为SHOWN或者RESUMED）时，闪控球不可见；当应用处于后台（生命周期状态为HIDDEN）时，闪控球可见。

系统能力： SystemCapability.Window.SessionManager

模型约束： 此接口仅可在Stage模型下使用。

参数：

返回值：

错误码：

以下错误码的详细介绍请参见窗口错误码。

示例：

import { BusinessError } from '@kit.BasicServicesKit';

// 设置闪控球在应用内不可见
floatingBallController?.setFloatingBallVisibilityInApp(false).then(() => {
  console.info('Succeeded in setting floating ball visibility.');
}).catch((err: BusinessError) => {
  console.error(`Failed to set floating ball visibility. Cause code: ${err.code}, message: ${err.message}`);
});

onDestroyBeta

onDestroy(callback: Callback<string>): void

注册闪控球销毁事件的监听。当闪控球销毁时，回调函数会接收到销毁原因的字符串。不再使用时，调用offDestroy接口取消监听以避免内存泄漏。

系统能力： SystemCapability.Window.SessionManager

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 26.0.0

参数：

错误码：

以下错误码的详细介绍请参见窗口错误码。

示例：

// 定义销毁事件回调函数
let onDestroy = (reason: string) => {
  console.info('Floating ball has destroyed, reason: ' + reason);
};
try {
  // 注册闪控球销毁事件监听
  floatingBallController?.onDestroy(onDestroy);
} catch (e) {
  console.error(`Failed to onDestroy floating ball. Cause:${e.code}, message:${e.message}`);
}

offDestroyBeta

offDestroy(callback?: Callback<string>): void

取消闪控球销毁事件的监听。

系统能力： SystemCapability.Window.SessionManager

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 26.0.0

参数：

错误码：

以下错误码的详细介绍请参见窗口错误码。

示例：

// 定义销毁事件回调函数（需与注册时的回调一致）
let onDestroy = (reason: string) => {
  console.info('Floating ball has destroyed, reason: ' + reason);
};
try {
  // 取消闪控球销毁事件监听
  floatingBallController?.offDestroy(onDestroy);
} catch (e) {
  console.error(`Failed to offDestroy floating ball. Cause:${e.code}, message:${e.message}`);
}
// 取消所有监听
try {
  floatingBallController?.offDestroy();
} catch (e) {
  console.error(`Failed to offDestroy all listeners. Cause:${e.code}, message:${e.message}`);
}

FloatingBallParams

启动和更新闪控球的配置参数。

系统能力： SystemCapability.Window.SessionManager

FloatingBallState

闪控球生命周期状态的枚举。

系统能力： SystemCapability.Window.SessionManager

FloatingBallTemplate

闪控球模板类型的枚举。

系统能力： SystemCapability.Window.SessionManager

FloatingBallWindowInfo

闪控球窗口信息。

系统能力： SystemCapability.Window.SessionManager

FloatingBallTextUpdateAnimationTypeBeta

闪控球文本更新动画类型的枚举。

系统能力： SystemCapability.Window.SessionManager

模型约束： 此接口仅可在Stage模型下使用。

起始版本：26.0.0