1# @ohos.window.floatingBall (闪控球窗口) 2<!--Kit: ArkUI--> 3<!--Subsystem: Window--> 4<!--Owner: @betafringe007--> 5<!--Designer: @zhoulin_--> 6<!--Tester: @qinliwen0417--> 7<!--Adviser: @ge-yafang--> 8 9该模块提供闪控球的基础功能，包括判断设备是否支持闪控球功能，以及创建闪控球控制器来启动、更新或停止闪控球。适用于比价、搜题或抢单等场景，以小窗模式呈现内容。闪控球以悬浮小组件形式显示在其他应用之上，即时呈现应用的关键信息。 10 11> **说明：** 12> 13> 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```ts 18import { floatingBall } from '@kit.ArkUI'; 19``` 20 21## floatingBall.isFloatingBallEnabled 22 23isFloatingBallEnabled(): boolean 24 25判断当前设备是否支持闪控球功能。 26 27**系统能力：** SystemCapability.Window.SessionManager 28 29**返回值：** 30 31| 类型 | 说明 | 32|------------|------------| 33| boolean | 当前设备是否支持闪控球功能。true表示支持，false则表示不支持。 | 34 35**示例：** 36 37```ts 38let enable: boolean = floatingBall.isFloatingBallEnabled(); 39console.info('Floating ball enabled is: ' + enable); 40``` 41 42## floatingBall.create 43 44create(config: FloatingBallConfiguration): Promise<FloatingBallController> 45 46创建闪控球控制器，使用Promise异步回调。 47 48**系统能力：** SystemCapability.Window.SessionManager 49 50**设备行为差异：** 该接口在Phone和Tablet设备中可正常调用，在其他设备中返回801错误码。 51 52**参数：** 53 54| 参数名 | 类型 | 必填 | 说明 | 55|------------|------------|------------|------------| 56| config | [FloatingBallConfiguration](#floatingballconfiguration) | 是 | 创建闪控球控制器的参数。该参数不能为空，并且构造该参数的context不能为空。 | 57 58**返回值：** 59 60| 类型 | 说明 | 61|------------|------------| 62| Promise<[FloatingBallController](#floatingballcontroller)> | Promise对象。返回当前创建的闪控球控制器。 | 63 64**错误码：** 65 66以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 67 68| 错误码ID | 错误信息 | 69|------------|------------| 70| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 71| 1300019 | Wrong parameters for operating the floating ball. | 72| 1300023 | Floating ball internal error. | 73 74**示例：** 75 76```ts 77import { BusinessError } from '@kit.BasicServicesKit'; 78import { common } from '@kit.AbilityKit'; 79 80let floatingBallController: floatingBall.FloatingBallController | undefined = undefined; 81//请在组件内获取context，确保this.getUIContext().getHostContext()返回的结果为UIAbilityContext 82let ctx = this.getUIContext().getHostContext() as common.UIAbilityContext; 83let config: floatingBall.FloatingBallConfiguration = { 84 context: ctx, 85}; 86try { 87 floatingBall.create(config).then((data: floatingBall.FloatingBallController) => { 88 floatingBallController = data; 89 console.info(`Succeeded in creating floating ball controller. Data: ${data}`); 90 }).catch((err: BusinessError) => { 91 console.error(`Failed to create floating ball controller. Cause:${err.code}, message:${err.message}`); 92 }); 93} catch(e) { 94 console.error(`Failed to create floating ball controller. Cause:${e.code}, message:${e.message}`); 95} 96``` 97 98## FloatingBallConfiguration 99 100创建闪控球控制器时需要提供的参数配置。 101 102**系统能力：** SystemCapability.Window.SessionManager 103 104| 名称 | 类型 | 只读 | 可选 | 说明 | 105|------------|------------|------------|------------|------------| 106| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 否 | 否 | 表示上下文环境。| 107 108## FloatingBallController 109 110闪控球控制器实例，用于启动、更新、停止闪控球以及注册回调等操作。 111 112下列API示例中都需先使用[floatingBall.create()](#floatingballcreate)方法获取到闪控球控制器实例（即floatingBallController），再通过此实例调用对应方法。 113 114**系统能力：** SystemCapability.Window.SessionManager 115 116### startFloatingBall 117 118startFloatingBall(params: FloatingBallParams): Promise<void> 119 120启动闪控球，使用Promise异步回调。 121 122**需要权限：** ohos.permission.USE_FLOAT_BALL 123 124**系统能力：** SystemCapability.Window.SessionManager 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129|------------|------------|------------|------------| 130| params | [FloatingBallParams](#floatingballparams) | 是 | 启动闪控球的参数。 | 131 132**返回值：** 133 134| 类型 | 说明 | 135|------------|------------| 136| Promise<void> | 无返回结果的Promise对象。 | 137 138**错误码：** 139 140以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 141 142| 错误码ID | 错误信息 | 143|------------|------------| 144| 201 | Permission verification failed, usually returned by VerifyAccessToken. | 145| 1300019 | Wrong parameters for operating the floating ball. | 146| 1300020 | Failed to create the floating ball window. | 147| 1300021 | Failed to start multiple floating ball windows. | 148| 1300022 | Repeated floating ball operation. | 149| 1300023 | Floating ball internal error. | 150| 1300024 | The floating ball window state is abnormal. | 151| 1300025 | The floating ball state does not support this operation. | 152 153**示例：** 154 155```ts 156import { BusinessError } from '@kit.BasicServicesKit'; 157 158let startParams: floatingBall.FloatingBallParams = { 159 template: floatingBall.FloatingBallTemplate.EMPHATIC, 160 title: 'title', 161 content: 'content' 162}; 163try { 164 floatingBallController.startFloatingBall(startParams).then(() => { 165 console.info('Succeeded in starting floating ball.'); 166 }).catch((err: BusinessError) => { 167 console.error(`Failed to start floating ball. Cause:${err.code}, message:${err.message}`); 168 }); 169} catch(e) { 170 console.error(`Failed to start floating ball. Cause:${e.code}, message:${e.message}`); 171} 172``` 173 174### updateFloatingBall 175 176updateFloatingBall(params: FloatingBallParams): Promise<void> 177 178更新闪控球，使用Promise异步回调。 179 180**系统能力：** SystemCapability.Window.SessionManager 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185|------------|------------|------------|------------| 186| params | [FloatingBallParams](#floatingballparams) | 是 | 更新闪控球的参数。 | 187 188**返回值：** 189 190| 类型 | 说明 | 191|------------|------------| 192| Promise<void> | 无返回结果的Promise对象。 | 193 194**错误码：** 195 196以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 197 198| 错误码ID | 错误信息 | 199|------------|------------| 200| 1300002 | This window state is abnormal. | 201| 1300003 | This window manager service works abnormally. | 202| 1300004 | Unauthorized operation. | 203| 1300019 | Wrong parameters for operating the floating ball. | 204| 1300023 | Floating ball internal error. | 205| 1300024 | The floating ball window state is abnormal. | 206| 1300025 | The floating ball state does not support this operation. | 207| 1300027 | When updating the floating ball, the template type cannot be changed. | 208| 1300028 | Updating static template-based floating balls is not supported. | 209 210**示例：** 211 212```ts 213import { BusinessError } from '@kit.BasicServicesKit'; 214 215let updateParams: floatingBall.FloatingBallParams = { 216 template: floatingBall.FloatingBallTemplate.EMPHATIC, 217 title: 'title2', 218 content: 'content2' 219}; 220try { 221 floatingBallController.updateFloatingBall(updateParams).then(() => { 222 console.info('Succeeded in updating floating ball.'); 223 }).catch((err: BusinessError) => { 224 console.error(`Failed to update floating ball. Cause:${err.code}, message:${err.message}`); 225 }); 226} catch(e) { 227 console.error(`Failed to update floating ball. Cause:${e.code}, message:${e.message}`); 228} 229``` 230 231### stopFloatingBall 232 233stopFloatingBall(): Promise<void> 234 235停止闪控球，使用Promise异步回调。 236 237**系统能力：** SystemCapability.Window.SessionManager 238 239**返回值：** 240 241| 类型 | 说明 | 242|------------|------------| 243| Promise<void> | 无返回结果的Promise对象。 | 244 245**错误码：** 246 247以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 248 249| 错误码ID | 错误信息 | 250|------------|------------| 251| 1300022 | Repeated floating ball operation. | 252| 1300023 | Floating ball internal error. | 253| 1300024 | The floating ball window state is abnormal. | 254 255**示例：** 256 257```ts 258import { BusinessError } from '@kit.BasicServicesKit'; 259 260floatingBallController.stopFloatingBall().then(() => { 261 console.info('Succeeded in stopping floating ball.'); 262}).catch((err: BusinessError) => { 263 console.error(`Failed to stop floating ball. Cause:${err.code}, message:${err.message}`); 264}); 265``` 266 267### on('stateChange') 268 269on(type: 'stateChange', callback: Callback<FloatingBallState>): void 270 271注册闪控球生命周期状态变化的监听事件。不再使用时，取消监听以避免内存泄漏。 272 273**系统能力：** SystemCapability.Window.SessionManager 274 275**参数：** 276 277| 参数名 | 类型 | 必填 | 说明 | 278|------------|------------|------------|------------| 279| type | string | 是 | 监听事件，固定为'stateChange'，即闪控球生命周期状态变化事件。 | 280| callback | Callback<[FloatingBallState](#floatingballstate)> | 是 | 回调函数。返回当前的闪控球生命周期状态。 | 281 282**错误码：** 283 284以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 285 286| 错误码ID | 错误信息 | 287|------------|------------| 288| 1300019 | Wrong parameters for operating the floating ball. | 289| 1300022 | Repeated floating ball operation. | 290| 1300023 | Floating ball internal error. | 291| 1300024 | The floating ball window state is abnormal. | 292 293**示例：** 294 295```ts 296let onStateChange = (state: floatingBall.FloatingBallState) => { 297 console.info('Floating ball stateChange: ' + state); 298}; 299try { 300 floatingBallController.on('stateChange', onStateChange); 301} catch(e) { 302 console.error(`Failed to on stateChange floating ball. Cause:${e.code}, message:${e.message}`); 303} 304``` 305 306### off('stateChange') 307 308off(type: 'stateChange', callback?: Callback<FloatingBallState>): void 309 310取消闪控球生命周期状态变化的监听事件。 311 312**系统能力：** SystemCapability.Window.SessionManager 313 314**参数：** 315 316| 参数名 | 类型 | 必填 | 说明 | 317|------------|------------|------------|------------| 318| type | string | 是 | 监听事件，固定为'stateChange'，即闪控球生命周期状态变化事件。 | 319| callback | Callback<[FloatingBallState](#floatingballstate)> | 否 | 回调函数。返回当前的闪控球生命周期状态。若传入参数，则停止该监听。若未传入参数，则停止所有闪控球生命周期状态变化的监听。 | 320 321**错误码：** 322 323以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 324 325| 错误码ID | 错误信息 | 326|------------|------------| 327| 1300019 | Wrong parameters for operating the floating ball. | 328| 1300023 | Floating ball internal error. | 329| 1300024 | The floating ball window state is abnormal. | 330 331**示例：** 332 333```ts 334let onStateChange = (state: floatingBall.FloatingBallState) => { 335 console.info('Floating ball stateChange: ' + state); 336}; 337try { 338 floatingBallController.off('stateChange', onStateChange); 339} catch(e) { 340 console.error(`Failed to off stateChange floating ball. Cause:${e.code}, message:${e.message}`); 341} 342``` 343 344### on('click') 345 346on(type: 'click', callback: Callback<void>): void 347 348注册闪控球的点击监听事件，不使用时，取消监听以避免内存泄漏。 349 350**系统能力：** SystemCapability.Window.SessionManager 351 352**参数：** 353 354| 参数名 | 类型 | 必填 | 说明 | 355|------------|------------|------------|------------| 356| type | string | 是 | 监听事件，固定为'click'，即闪控球点击事件。 | 357| callback | Callback<void> | 是 | 回调函数。当点击闪控球事件发生时的回调。该回调函数不返回任何参数。 | 358 359**错误码：** 360 361以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 362 363| 错误码ID | 错误信息 | 364|------------|------------| 365| 1300019 | Wrong parameters for operating the floating ball. | 366| 1300022 | Repeated floating ball operation. | 367| 1300023 | Floating ball internal error. | 368| 1300024 | The floating ball window state is abnormal. | 369 370**示例：** 371 372```ts 373let onClick = () => { 374 console.info('Floating ball onClick'); 375}; 376try { 377 floatingBallController.on('click', onClick); 378} catch(e) { 379 console.error(`Failed to on click floating ball. Cause:${e.code}, message:${e.message}`); 380} 381``` 382 383### off('click') 384 385off(type: 'click', callback?: Callback<void>): void 386 387取消闪控球点击的监听事件。 388 389**系统能力：** SystemCapability.Window.SessionManager 390 391**参数：** 392 393| 参数名 | 类型 | 必填 | 说明 | 394|------------|------------|------------|------------| 395| type | string | 是 | 监听事件，固定为'click'，即闪控球点击事件。 | 396| callback | Callback<void> | 否 | 回调函数。当点击闪控球事件发生时的回调。该回调函数不返回任何参数。若传入参数，则关闭特定的监听。若未传入参数，则关闭所有闪控球点击的监听。 | 397 398**错误码：** 399 400以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 401 402| 错误码ID | 错误信息 | 403|------------|------------| 404| 1300019 | Wrong parameters for operating the floating ball. | 405| 1300023 | Floating ball internal error. | 406| 1300024 | The floating ball window state is abnormal. | 407 408**示例：** 409 410```ts 411let onClick = () => { 412 console.info('Floating ball onClick'); 413}; 414try { 415 floatingBallController.off('click', onClick); 416} catch(e) { 417 console.error(`Failed to off click floating ball. Cause:${e.code}, message:${e.message}`); 418} 419``` 420 421### getFloatingBallWindowInfo 422 423getFloatingBallWindowInfo(): Promise<FloatingBallWindowInfo> 424 425获得闪控球窗口信息，使用Promise异步回调。 426 427**系统能力：** SystemCapability.Window.SessionManager 428 429**返回值：** 430 431| 类型 | 说明 | 432|------------|------------| 433| Promise<[FloatingBallWindowInfo](#floatingballwindowinfo)> | Promise对象，返回闪控球窗口信息。 | 434 435**错误码：** 436 437以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 438 439| 错误码ID | 错误信息 | 440|------------|------------| 441| 1300002 | This window state is abnormal. | 442| 1300003 | This window manager service works abnormally. | 443| 1300004 | Unauthorized operation. | 444| 1300023 | Floating ball internal error. | 445| 1300024 | The floating ball window state is abnormal. | 446| 1300025 | The floating ball state does not support this operation. | 447 448**示例：** 449 450```ts 451import { BusinessError } from '@kit.BasicServicesKit'; 452 453floatingBallController.getFloatingBallWindowInfo().then((data: floatingBall.FloatingBallWindowInfo) => { 454 console.info('Succeeded in getting floating ball window info. Info: ' + JSON.stringify(data)); 455}).catch((err: BusinessError) => { 456 console.error(`Failed to get floating ball window info. Cause code: ${err.code}, message: ${err.message}`); 457}); 458``` 459 460### restoreMainWindow 461 462restoreMainWindow(want: Want): Promise<void> 463 464恢复应用主窗口并加载指定页面。仅支持在点击闪控球后调用，使用Promise异步回调。 465 466**需要权限：** ohos.permission.USE_FLOAT_BALL 467 468**系统能力：** SystemCapability.Window.SessionManager 469 470**参数：** 471 472| 参数名 | 类型 | 必填 | 说明 | 473|------------|------------|------------|------------| 474| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 加载指定页面的Want。 | 475 476**返回值：** 477 478| 类型 | 说明 | 479|------------|------------| 480| Promise<void> | 无返回结果的Promise对象。 | 481 482**错误码：** 483 484以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 485 486| 错误码ID | 错误信息 | 487|------------|------------| 488| 201 | Permission verification failed, usually returned by VerifyAccessToken. | 489| 1300002 | This window state is abnormal. | 490| 1300003 | This window manager service works abnormally. | 491| 1300004 | Unauthorized operation. | 492| 1300019 | Wrong parameters for operating the floating ball. | 493| 1300023 | Floating ball internal error. | 494| 1300024 | The floating ball window state is abnormal. | 495| 1300025 | The floating ball state does not support this operation. | 496| 1300026 | Failed to restore the main window. | 497 498**示例：** 499 500```ts 501import { BusinessError } from '@kit.BasicServicesKit'; 502import { Want } from '@kit.AbilityKit'; 503 504let want: Want = { 505 bundleName: 'xxx.xxx.xxx', 506 abilityName: 'EntryAbility' 507}; 508try { 509 floatingBallController.restoreMainWindow(want).then(() => { 510 console.info('Succeeded in restoring floating ball main window.'); 511 }).catch((err: BusinessError) => { 512 console.error(`Failed to restore floating ball main window. Cause code: ${err.code}, message: ${err.message}`); 513 }); 514} catch(e) { 515 console.error(`Failed to create floating ball controller. Cause:${e.code}, message:${e.message}`); 516} 517``` 518 519## FloatingBallParams 520 521启动和更新闪控球的配置参数。 522 523**系统能力：** SystemCapability.Window.SessionManager 524 525| 名称 | 类型 | 只读 | 可选 | 说明 | 526|------------|------------|------------|------------|------------| 527| template | [FloatingBallTemplate](#floatingballtemplate) | 否 | 否 | 闪控球模板。 | 528| title | string | 否 | 否 | 闪控球标题，不可为空字符串，大小不超过64字节。 | 529| content | string | 否 | 是 | 闪控球内容，大小不超过64字节。不传入时默认为空字符串，不显示闪控球内容。 | 530| backgroundColor | string | 否 | 是 | 闪控球背景颜色，为不带透明度的十六进制颜色格式（例如'#008EF5'或'#FF008EF5'），不传入时闪控球跟随系统深浅色模式的默认背景色。 | 531| icon | [image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md) | 否 | 是 | 闪控球图标，图标像素的总字节数不超过192KB（图标像素的总字节数通过[getPixelBytesNumber](../apis-image-kit/arkts-apis-image-PixelMap.md#getpixelbytesnumber7)获取）。建议图标像素宽高为128px*128px。实际显示效果依赖于设备能力和闪控球UI样式。 | 532 533## FloatingBallState 534 535闪控球生命周期状态的枚举。 536 537**系统能力：** SystemCapability.Window.SessionManager 538 539| 名称 | 值 | 说明 | 540|------------|------------|------------| 541| STARTED | 1 | 表示闪控球启动。 | 542| STOPPED | 2 | 表示闪控球停止。 | 543 544## FloatingBallTemplate 545 546闪控球模板类型的枚举。 547 548**系统能力：** SystemCapability.Window.SessionManager 549 550| 名称 | 值 | 说明 | 551|------------|------------|------------| 552| STATIC | 1 | 静态布局，支持标题和图标。使用此模板时，FloatingBallParams中的title参数和icon参数必传。 | 553| NORMAL | 2 | 普通文本布局，支持标题和内容。使用此模板时，FloatingBallParams中的title参数必传。 | 554| EMPHATIC | 3 | 强调文本布局，支持图标、标题和内容。使用此模板时，FloatingBallParams中的title参数必传。 | 555| SIMPLE | 4 | 纯文本布局，只支持标题。使用此模板时，FloatingBallParams中的title参数必传。 | 556 557## FloatingBallWindowInfo 558 559闪控球窗口信息。 560 561**系统能力：** SystemCapability.Window.SessionManager 562 563| 名称 | 类型 | 只读 | 可选 | 说明 | 564|------------|------------|------------|------------|------------| 565| windowId | number | 是 | 否 | 闪控球窗口ID。 |