目录

@ohos.window.floatView (Float View)

A float view is a small window that floats on a desktop or an application screen, providing flexible window management capabilities.

This module provides capabilities about the float view, including determining whether a device supports a float view, and creating a float view controller to start, update, or stop a float view.

Application scenarios:

A float view is applicable to scenarios where application content needs to be continuously displayed in an independent small window or shortcut operations need to be provided. Examples:

Comparison between the float view and floating ball:

Linkage with the floating ball:

This module can be used together with @ohos.window.floatingBall. After the float view controller is bound to the floating ball controller using the floatView.bind API, users can click the floating ball to expand it as a float view, and click the minimize button in the upper left corner of the float view to collapse it back as a floating ball. This allows for seamless switching between the two window forms.

Comparison between a global floating window and a float view:

Since: 26.0.0

  • Use canIUse() to check whether the device supports the system capability SystemCapability.Window.SessionManager and the corresponding APIs.

  • The APIs of this module can be used only in the stage model.

Modules to Import

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

floatView.isFloatViewEnabled

isFloatViewEnabled(): boolean

Checks whether the current device supports the float view feature.

Since: 26.0.0

System capability: SystemCapability.Window.SessionManager

Model restriction: This API can be used only in the stage model.

Return value

Type Description
boolean Whether the current device supports the float view. true to support; false otherwise.

Example

// Check whether the current device supports the float view feature.
let enable: boolean = floatView.isFloatViewEnabled();
console.info('Float view enabled is: ' + enable);

floatView.create

create(config: FloatViewConfiguration): Promise<FloatViewController>

Creates a float view controller. This API uses a promise to return the result.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
config FloatViewConfiguration Yes Parameter for creating a float view controller. This parameter and its context field cannot be null or undefined. Otherwise, error code 401 is thrown. Error code 1300016 is thrown for other parameter exceptions.

Return value

Type Description
Promise<FloatViewController> Promise used to return the float view controller.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID Error Message
801 Capability not supported. Possible cause: Call the API on unsupported device.
1300002 This window state is abnormal. Possible cause: 1. This window context is abnormal. 2. System error, such as a null pointer, insufficient memory or a JS engine exception.
1300016 Parameter error. Possible cause: Invalid template type.

Example

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

@Entry
@Component
struct Index {
  private floatViewController: floatView.FloatViewController | undefined = undefined;
  aboutToAppear(): void {
    // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
    let ctx = this.getUIContext().getHostContext() as common.UIAbilityContext;
    // Create a float view configuration object.
    let config: floatView.FloatViewConfiguration = {
      context: ctx,
      templateType: floatView.FloatViewTemplateType.ROUNDED_RECTANGLE
    };
    try {
      // Create a float view controller.
      floatView.create(config).then((data: floatView.FloatViewController) => {
        this.floatViewController = data;
        console.info(`Succeeded in creating float view controller. Data: ${data}`);
      }).catch((err: BusinessError): void => {
        console.error(`Failed to create float view controller. Cause:${err.code}, message:${err.message}`);
      });
    } catch (e) {
      console.error(`Failed to create float view controller. Cause:${e.code}, message:${e.message}`);
    }
  }
}

floatView.bind

bind(floatViewController: FloatViewController, floatingBallController: floatingBall.FloatingBallController, floatingBallParams: floatingBall.FloatingBallParams): Promise<void>

Binds the float view and the floating ball. You need to create the float view controller and floating ball controller first, and neither of them has been started. This API uses a promise to return the result.

  • After the binding is successful, calling start() or startFloatingBall() will create both a float view and the floating ball, and trigger the status callback registered for the corresponding window. However, only one window is displayed at a time, and the display sequence depends on which controller's start API is called first.
  • After the binding is successful, users can switch between the float view and the floating ball by clicking.
  • After the binding is successful, calling the stop API (stop() or stopFloatingBall()) of either controller will destroy both the float view and the floating ball, and trigger the status callback registered for the corresponding window.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.USE_FLOAT_BALL and ohos.permission.FLOAT_VIEW

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
floatViewController FloatViewController Yes Float view controller, which is used to manage operations such as starting and stopping the float view and listening the status of the float view.
floatingBallController floatingBall.FloatingBallController Yes Floating ball controller, which is used to manage operations such as starting and stopping the floating ball and listening the status of the floating ball.
floatingBallParams floatingBall.FloatingBallParams Yes Floating ball parameters. The parameters set during binding will overwrite the parameters saved when the floating ball controller is started.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID Error Message
201 Permission verification failed. Possible cause: The application does not have the permission required to call the API.
801 Capability not supported on this device. Possible cause: Call api on unsupported device.
1300019 Wrong parameters for operating the floating ball. Possible cause: Invalid floating ball params.
1300025 The floating ball state does not support this operation. Possible cause: 1. The floating ball has started but not stopped yet. 2. The floating ball controller has been bound.
1300031 The floatView state does not support this operation. Possible cause: 1. The float view has started but not stopped yet. 2. The float view controller has been bound.

Example

// Entry.ets
import { BusinessError } from '@kit.BasicServicesKit';
import { floatingBall, floatView } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  private floatingBallController: floatingBall.FloatingBallController | undefined = undefined;
  private floatViewController: floatView.FloatViewController | undefined = undefined;
  // Create a controller.
  // ...
  public bindController(): void {
    let floatingBallParams: floatingBall.FloatingBallParams = {
      template: floatingBall.FloatingBallTemplate.EMPHATIC,
      title: 'title',
      content: 'content'
    };

    try {
      if (this.floatViewController && this.floatingBallController) {
        // Bind the float view and the floating ball.
        floatView.bind(this.floatViewController!, this.floatingBallController!, floatingBallParams).then(() => {
          console.info('Succeeded in binding float view and floating ball.');
        }).catch((err: BusinessError): void => {
          console.error(`Failed to bind float view and floating ball. Cause:${err.code}, message:${err.message}`);
        });
      }
    } catch (e) {
      console.error(`Failed to bind float view and floating ball. Cause:${e.code}, message:${e.message}`);
    }
  }
}

floatView.unbind

unbind(floatViewController: FloatViewController, floatingBallController: floatingBall.FloatingBallController): Promise<void>

Unbinds the float view and the floating ball. The unbinding can be performed only after both the float view controller and floating ball controller are stopped. This API uses a promise to return the result.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
floatViewController FloatViewController Yes Float view controller, which is used to manage operations such as starting and stopping the float view and listening the status of the float view.
floatingBallController floatingBall.FloatingBallController Yes Floating ball controller, which is used to manage operations such as starting and stopping the floating ball and listening the status of the floating ball.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID Error Message
801 Capability not supported on this device. Possible cause: Call api on unsupported device.
1300025 The floating ball state does not support this operation. Possible cause: 1. The floating ball has started but not stopped yet. 2. The floatingBallController has not been bound.
1300031 The floatView state does not support this operation. Possible cause: 1. The float view has started but not stopped yet. 2. The floatViewController has not been bound. 3. The floatViewController and the floatingBallController are not bound together.

Example

// Entry.ets
import { BusinessError } from '@kit.BasicServicesKit';
import { floatingBall, floatView } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  private floatingBallController: floatingBall.FloatingBallController | undefined = undefined;
  private floatViewController: floatView.FloatViewController | undefined = undefined;
  // Create a controller.
  // ...
  public unbindController(): void {
    try {
      // Use the float view controller and floating ball controller passed during the binding.
      if (this.floatViewController && this.floatingBallController) {
        // Unbind the float view and the floating ball.
        floatView.unbind(this.floatViewController!, this.floatingBallController!).then(() => {
          console.info('Succeeded in unbinding float view and floating ball.');
        }).catch((err: BusinessError): void => {
          console.error(`Failed to unbind float view and floating ball. Cause:${err.code}, message:${err.message}`);
        });
      }
    } catch (e) {
      console.error(`Failed to unbind float view and floating ball. Cause:${e.code}, message:${e.message}`);
    }
  }
}

floatView.getFloatViewLimits

getFloatViewLimits(templateType: FloatViewTemplateType): FloatViewLimits

Obtains the limits of the float view based on the passed template type. The unit is px.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
templateType FloatViewTemplateType Yes Template type of the float view.

Return value

Type Description
FloatViewLimits Limits of the float view, including the maximum size, minimum size, and aspect ratio.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID Error Message
801 Capability not supported. Possible cause: Call the API on unsupported device.
1300002 This window state is abnormal. Possible cause: System error, such as a null pointer, insufficient memory or a JS engine exception.
1300003 This window manager service works abnormally. Possible cause: Internal IPC error.
1300016 Parameter error. Possible cause: Invalid template type.

Example

// Obtain the float view limit of the rounded rectangle template.
let limits: floatView.FloatViewLimits = floatView.getFloatViewLimits(floatView.FloatViewTemplateType.ROUNDED_RECTANGLE);
console.info('Float view limits: ' + JSON.stringify(limits));

FloatViewConfiguration

Provides parameter configuration required for creating a float view controller.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Name Type Read-Only Optional Description
context BaseContext No No Context, which is used to associate the main window of the application when creating a float view controller. A valid UIAbilityContext instance must be passed.
templateType FloatViewTemplateType No No Template type of the float view.
isConfirmOnClose boolean No Yes Whether to require user confirmation when the close button is clicked. The value true indicates that user confirmation is required when the close button is clicked. Otherwise, user confirmation is not required. The default value is false.

TemplateProperty

Provides parameter configuration required for switching the float view template and modifying the size of the window.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Name Type Read-Only Optional Description
templateType FloatViewTemplateType No No Template type of the float view.
size window.Size No No Window size required for updating the template type.

FloatViewController

Defines a float view controller instance, which is used to start and stop the float view and register callbacks.

Before calling the following APIs, you must use floatView.create() to create a float view controller instance (that is, floatViewController).

Model restriction: This API can be used only in the stage model.

[h2]setUIContext

setUIContext(path: string, storage?: LocalStorage): Promise<void>

Loads the content of a page, with its path specified in the current project, for the float view, and transfers the state attribute to the page through LocalStorage. This API uses a promise to return the result.

You are advised to call this API before the float view is started. If called repeatedly, this API will destroy the existing page content (UIContent) before loading new content. Exercise caution when using it.

This API does not support loading cross-package pages. If needed, use the setUIContextByName() API instead.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
path string Yes Path of the page content which needs to be loaded to the window. The path needs to be configured in the main_pages.json file of the project. The path cannot be a relative path and must be the same as the value of src in the main_pages.json file. If the path is invalid or does not meet the preceding requirements, error code 1300016 will be thrown.
storage LocalStorage No Page-level UI state storage unit, which is used to transfer the state attribute for the page. By default, the value is empty.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.
1300016 Parameter error. Possible causes: Invalid path.

Example

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

try {
  // Obtain floatViewController using floatView.create(). For details, see the floatView.create() sample.
  // Set the page content path of the float view.
  this.floatViewController?.setUIContext('pages/Index').then(() => {
    console.info('Succeeded in setting UI context.');
  }).catch((err: BusinessError): void => {
    console.error(`Failed to set UI context. Cause:${err.code}, message:${err.message}`);
  });
} catch (e) {
  console.error(`Failed to set UI context. Cause:${e.code}, message:${e.message}`);
}

[h2]setUIContextByName

setUIContextByName(name: string, storage?: LocalStorage): Promise<void>

Loads the content of a named route page to this window, and transfers the state attribute to the page through a local storage. This API uses a promise to return the result.

You are advised to call this API before the float view is started. If called repeatedly, this API will destroy the existing page content (UIContent) before loading new content. Exercise caution when using it.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
name string Yes Name of the named route page, which is used to load the content of the specified named route page. The value must be the same as the name specified by the routeName parameter in the @Entry decorator.
storage LocalStorage No Page-level UI state storage unit, which is used to transfer the state attribute for the page. By default, the value is empty.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.
1300016 Parameter error. Possible causes: Invalid name.

Example

// Index.ets
import { BusinessError } from '@kit.BasicServicesKit';
import { entryName } from './Hello'; // Import the named route page.
import { floatView } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  private floatViewController: floatView.FloatViewController | undefined = undefined;
  // Create a controller.
  // ...
  public setUIContextByName(): void {
    try {
      // Set the page content of the float view based on the named route page.
      this.floatViewController?.setUIContextByName(entryName).then(() => {
        console.info('Succeeded in loading the content.');
      }).catch((err: BusinessError): void => {
        console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
      });
    } catch (e) {
      console.error(`Failed to load the content. Cause code: ${e.code}, message: ${e.message}`);
    }
  }
}
// Hello.ets
export const entryName : string = 'Hello';
@Entry({routeName: entryName, useSharedStorage: true})
@Component
export struct Hello {
  @State message: string = 'Hello World'
  build() {
    Row() {
      Column() {
        Text(this.message)
      }
      .width('100%')
    }
    .height('100%')
  }
}

[h2]setWindowSize

setWindowSize(size: window.Size): Promise<void>

Sets the size of the float view. You are advised to call the getFloatViewLimits API to obtain the recommended width and height ranges and aspect ratio range, and then call this API based on the recommended values. The actual window size change can be listened to through the onRectChange API. This API uses a promise to return the result.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
size window.Size Yes Window size, in px. The width and height must be greater than 0. If the value is not within the valid range, error code 1300016 will be thrown. It is recommended that the size meet the limits returned by the getFloatViewLimits API.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.
1300003 This window manager service works abnormally. Possible cause: Internal IPC error.
1300016 Parameter error. Possible cause: The value of the size is less than or equal to 0.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { floatView, window } from '@kit.ArkUI';

// Set the window size.
let size: window.Size = {
  width: 400,
  height: 600
};
try {
  // Set the size of the float view.
  this.floatViewController?.setWindowSize(size).then(() => {
    console.info('Succeeded in setting window size.');
  }).catch((err: BusinessError): void => {
    console.error(`Failed to set window size. Cause:${err.code}, message:${err.message}`);
  });
} catch (e) {
  console.error(`Failed to set window size. Cause:${e.code}, message:${e.message}`);
}

[h2]switchTemplate

switchTemplate(templateProperty: TemplateProperty): Promise<void>

Switches the template of the flow view and changes the window size. You are advised to call the getFloatViewLimits API to obtain the recommended width and height ranges and aspect ratio range of the target template type, and then call this API based on the recommended values. The actual window size change can be listened to through the onRectChange API. This API uses a promise to return the result.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
templateProperty TemplateProperty Yes Target flow view template and window size. The width and height in size must be greater than 0. If the value is not within the valid range, error code 1300016 will be thrown. It is recommended that the size meet the limits returned by the getFloatViewLimits API.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.
1300003 This window manager service works abnormally. Possible cause: Internal IPC error.
1300016 Parameter error. Possible cause: 1. Invalid template type. 2. The value of the size is less than or equal to 0.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { floatView, window } from '@kit.ArkUI';

// Set the size of the new window.
let newSize: window.Size = {
  width: 800,
  height: 100
};
// Set the template property.
let templateProperty: floatView.TemplateProperty = {
  templateType: floatView.FloatViewTemplateType.HORIZONTAL_BAR,
  size: newSize
}
try {
  // Switch the template of the float view and change the window size.
  this.floatViewController?.switchTemplate(templateProperty).then(() => {
    console.info('Succeeded in switching window type and size.');
  }).catch((err: BusinessError): void => {
    console.error(`Failed to switch window type and size. Cause:${err.code}, message:${err.message}`);
  });
} catch (e) {
  console.error(`Failed to switch window type and size. Cause:${e.code}, message:${e.message}`);
}

[h2]start

start(): Promise<void>

Starts the float view. The return value of this API does not indicate that the start process is complete. You need to use the onStateChange API to listen for the STARTED callback to determine whether the start is successful. You are advised to call this API after calling setUIContext() or setUIContextByName(). This API uses a promise to return the result.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

Required permission: ohos.permission.FLOAT_VIEW

System capability: SystemCapability.Window.SessionManager

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID Error Message
201 Permission verification failed. Possible cause: The application does not have the permission required to call the API.
1300002 This window state is abnormal. Possible cause: The float view controller object is null.
1300003 This window manager service works abnormally. Possible cause: Internal IPC error.
1300030 Repeated operations on the float view. Possible cause: The float view is starting or has already started.
1300031 The float view state does not support this operation. Possible cause: The float view is stopping.
1300033 Failed to start float view. Possible causes: 1. Start multiple float views. 2. The main window of context is not foreground.
1300034 This operation conflicts with other floating windows. Possible cause: App has already started floating ball or pip window.

Example

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

try {
  // Start the float view.
  this.floatViewController?.start().then(() => {
    console.info('Succeeded in starting float view.');
  }).catch((err: BusinessError): void => {
    console.error(`Failed to start float view. Cause:${err.code}, message:${err.message}`);
  });
} catch (e) {
  console.error(`Failed to start float view. Cause:${e.code}, message:${e.message}`);
}

[h2]stop

stop(): Promise<void>

Stops the float view. The return value of this API does not indicate that the stop process is complete. You need to use the onStateChange API to listen for the STOPPED callback to determine whether the stop is successful. This API uses a promise to return the result.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.
1300003 This window manager service works abnormally. Possible cause: Internal IPC error.
1300030 Repeated operations on the float view. Possible cause: The float view is stopping or has already stopped.
1300031 This operation is not supported on the float view in the current state. Possible cause: The float view window is not started.

Example

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

try {
  // Stop the float view.
  this.floatViewController?.stop().then(() => {
    console.info('Succeeded in stopping float view.');
  }).catch((err: BusinessError): void => {
    console.error(`Failed to stop float view. Cause:${err.code}, message:${err.message}`);
  });
} catch (e) {
  console.error(`Failed to stop float view. Cause:${e.code}, message:${e.message}`);
}

[h2]setFloatViewVisibilityInApp

setFloatViewVisibilityInApp(isVisible: boolean): Promise<void>

Sets whether the float view is visible when the application is running in the foreground. This API uses a promise to return the result.

After the float view is created and before this API is called, the float view is visible by default when the application is running in the foreground.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
isVisible boolean Yes Whether the float view is visible when the application is running in the foreground. The value true indicates that the window is visible, and false indicates the opposite.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.
1300003 This window manager service works abnormally. Possible cause: Internal IPC error.

Example

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

try {
  // Set whether the float view is visible when the application is running in the foreground.
  this.floatViewController?.setFloatViewVisibilityInApp(true).then(() => {
    console.info('Succeeded in setting float view visibility in app.');
  }).catch((err: BusinessError): void => {
    console.error(`Failed to set float view visibility in app. Cause:${err.code}, message:${err.message}`);
  });
} catch (e) {
  console.error(`Failed to set float view visibility in app. Cause:${e.code}, message:${e.message}`);
}

[h2]restoreMainWindow

restoreMainWindow(wantParameters?: Record<string, Object>): Promise<void>

Restores the main window of the float view to display in the foreground. If this API is called when the main window is already in the foreground, the main window level will be raised. This API can be called only when the float view is in the STARTED state and after the user taps the float view. If the main window is in the PAUSED state or in the multitasking state, error code 1300032 will be returned if this API is called. This API uses a promise to return the result.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
wantParameters Record<string, Object> No Custom parameters passed to the main window when the main window of the float view is restored. The main window will receive the parameters when the onNewWant callback is triggered. The default value is empty, indicating that no custom parameters are passed to the main window.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.
1300003 This window manager service works abnormally. Possible cause: Internal IPC error.
1300031 This operation is not supported on the float view in the current state. Possible cause: The float view window is not started when restoring.
1300032 Failed to restore the main window. Possible cause: 1. User has never clicked the float view window before restore. 2. The float view window is not in the foreground. 3. The main window is in PAUSED lifecycle state. 4. The main window is in background during recent.

Example

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

// Define the parameter for restoring the main window.
let param: Record<string, Object> = {
  'info': 'helloworld',
};
// The float view must be in the STARTED state.
try {
  // Restore the main window of the float view to display in the foreground.
  this.floatViewController?.restoreMainWindow(param).then(() => {
    console.info('Succeeded in restoring main window.');
  }).catch((err: BusinessError): void => {
    console.error(`Failed to restore main window. Cause:${err.code}, message:${err.message}`);
  });
} catch (e) {
  console.error(`Failed to restore main window. Cause:${e.code}, message:${e.message}`);
}

[h2]getWindowProperties

getWindowProperties(): FloatViewProperties

Obtains the properties of the float view.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Return value

Type Description
FloatViewProperties Properties of the float view.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.
1300031 This operation is not supported on the float view in the current state. Possible cause: The float view window has not started, has stopped, or is in an error state.

Example

try {
  // Obtain the properties of the float view.
  let properties: floatView.FloatViewProperties | undefined = this.floatViewController?.getWindowProperties();
  console.info('Float view properties: ' + JSON.stringify(properties));
} catch (e) {
  console.error(`Failed to get window properties. Cause:${e.code}, message:${e.message}`);
}

[h2]onStateChange

onStateChange(callback: Callback<FloatViewStateChangeInfo>): void

Registers a callback for listening to float view state changes. To prevent memory leaks, remember to unregister the callback when it is no longer needed.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
callback Callback<FloatViewStateChangeInfo> Yes Callback used to return the state change information of the current float view.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.
1300030 Repeated operations on the float view. Possible cause: The callback has already registered.

Example

// Define the callback function for status changes.
let onStateChange = (info: floatView.FloatViewStateChangeInfo) => {
  console.info('Float view stateChange: ' + JSON.stringify(info));
};
try {
  // Register the callback for listening to float view state changes.
  this.floatViewController?.onStateChange(onStateChange);
} catch (e) {
  console.error(`Failed to on stateChange float view. Cause:${e.code}, message:${e.message}`);
}

[h2]offStateChange

offStateChange(callback?: Callback<FloatViewStateChangeInfo>): void

Unregisters the callback for listening to float view state changes.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
callback Callback<FloatViewStateChangeInfo> No Callback used to return the state change information of the current float view. If a value is passed in, the corresponding callback is unregistered. If no value is passed in, all callbacks associated with the state change event of the float view are unregistered.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.

Example

// Define the callback function for status changes.
let onStateChange = (info: floatView.FloatViewStateChangeInfo) => {
  console.info('Float view stateChange: ' + JSON.stringify(info));
};
try {
  // Unregister the callback for listening to float view state changes.
  this.floatViewController?.offStateChange(onStateChange);
} catch (e) {
  console.error(`Failed to off stateChange float view. Cause:${e.code}, message:${e.message}`);
}

[h2]onRectChange

onRectChange(callback: Callback<FloatViewRectChangeInfo>): void

Registers a callback for listening to changes in the rectangle area (position and size) of the float view. To prevent memory leaks, remember to unregister the callback when it is no longer needed.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
callback Callback<FloatViewRectChangeInfo> Yes Callback used to return the rectangle area change information of the current float view.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.
1300030 Repeated operations on the float view. Possible cause: The callback has already registered.

Example

// Define the callback function for rectangular area changes.
let onRectChange = (info: floatView.FloatViewRectChangeInfo) => {
  console.info('Float view rectChange: ' + JSON.stringify(info));
};
try {
  // Register the callback for listening to changes in the rectangle area of the float view.
  this.floatViewController?.onRectChange(onRectChange);
} catch (e) {
  console.error(`Failed to on rectChange float view. Cause:${e.code}, message:${e.message}`);
}

[h2]offRectChange

offRectChange(callback?: Callback<FloatViewRectChangeInfo>): void

Unregisters the callback for listening to changes in the rectangle area of the float view.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
callback Callback<FloatViewRectChangeInfo> No Callback used to return the rectangle area change information of the current float view. If a value is passed in, the corresponding callback is unregistered. If no value is passed in, all callbacks associated with the rectangle area change event of the float view are unregistered.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.

Example

// Define the callback function for rectangular area changes.
let onRectChange = (info: floatView.FloatViewRectChangeInfo) => {
  console.info('Float view rectChange: ' + JSON.stringify(info));
};
try {
  // Unregister the callback for listening to changes in the rectangle area of the float view.
  this.floatViewController?.offRectChange(onRectChange);
} catch (e) {
  console.error(`Failed to off rectChange float view. Cause:${e.code}, message:${e.message}`);
}

[h2]onLimitsChange

onLimitsChange(callback: Callback<FloatViewLimits>): void

Registers a callback for listening to limit changes of the float view. When the limit changes (for example, the screen width changes or the template is switched due to folding or unfolding), the callback is triggered and the limit information of the current window template type is returned. To prevent memory leaks, remember to unregister the callback when it is no longer needed.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
callback Callback<FloatViewLimits> Yes Callback used to return the limit change information of the current float view.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.
1300030 Repeated operations on the float view. Possible cause: The callback has already registered.

Example

// Define the callback function for limit changes.
let onLimitsChange = (limits: floatView.FloatViewLimits) => {
  console.info('Float view limitsChange: ' + JSON.stringify(limits));
};
try {
  // Register the callback for listening to limit changes of the float view.
  this.floatViewController?.onLimitsChange(onLimitsChange);
} catch (e) {
  console.error(`Failed to on limitsChange float view. Cause:${e.code}, message:${e.message}`);
}

[h2]offLimitsChange

offLimitsChange(callback?: Callback<FloatViewLimits>): void

Unregisters the callback for listening to limit changes of the float view.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name Type Mandatory Description
callback Callback<FloatViewLimits> No Callback used to return the limit change information of the current float view. If a value is passed in, the corresponding callback is unregistered. If no value is passed in, all callbacks associated with the limit change event of the float view are unregistered.

Error codes

For details about the error codes, see Window Error Codes.

ID Error Message
1300002 This window state is abnormal. Possible cause: The float view controller object is null.

Example

// Define the callback function for limit changes.
let onLimitsChange = (limits: floatView.FloatViewLimits) => {
  console.info('Float view limitsChange: ' + JSON.stringify(limits));
};
try {
  // Unregister the callback for listening to limit changes of the float view.
  this.floatViewController?.offLimitsChange(onLimitsChange);
} catch (e) {
  console.error(`Failed to off limitsChange float view. Cause:${e.code}, message:${e.message}`);
}

FloatViewTemplateType

Enumerates the template types of the float view.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Name Value Description
ROUNDED_RECTANGLE 0 Rectangle with rounded corners.
HORIZONTAL_BAR 1 Horizontal bar rectangle.

FloatViewProperties

Provides the properties of the float view.

Since: 26.0.0

System capability: SystemCapability.Window.SessionManager

Model restriction: This API can be used only in the stage model.

Name Type Read-Only Optional Description
templateType FloatViewTemplateType No No Template type of the float view.
windowId number No No Float view ID.
displayId number No No ID of the display where the float view is located.
windowRect window.Rect No No Rectangle area of the float view.
windowScale number No No Scale factor of the float view.
avoidArea window.AvoidArea No No

Avoid area for the content of the float view.

Note:

On the page loaded by setUIContext() or setUIContextByName(), components in the avoid area do not respond to gesture events. When adding components that require gesture response events, avoid the area.
inSidebar boolean No No Whether the float view is in the sidebar. true: in the sidebar; false: not in the sidebar.

RatioLimit

Provides the aspect ratio range of the float view. The aspect ratio is obtained by dividing the width of the rectangular area of the window by its height.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Name Type Read-Only Optional Description
minRatio number No No Minimum aspect ratio of the float view.
maxRatio number No No Maximum aspect ratio of the float view.

FloatViewLimits

Provides the limits of the float view.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Name Type Read-Only Optional Description
minSize window.Size No No Minimum size of the float view.
maxSize window.Size No No Maximum size of the float view.
ratioLimits Array<RatioLimit> No No Aspect ratio range of the float view. Each element in the array contains minRatio (minimum aspect ratio) and maxRatio (maximum aspect ratio).

FloatViewStateChangeInfo

Provides the state change information of the float view.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Name Type Read-Only Optional Description
state FloatViewState No No Status of the float view.
stopReason string No No

Reason why the float view stops. This parameter is valid only when state is set to FloatViewState.STOPPED. In other states, this parameter is an empty string by default. The stop reasons and their meanings are as follows:

"APP_STOP": The application proactively stops the float view.

"STOP_IN_SIDEBAR": The float view is closed in the sidebar.

"TITLE_BAR_STOP_CLICK": The float view is closed by clicking the close button on the title bar.

"DUMPSTER_STOP": The float view is dragged to the trash can.

"REPLACE_STOP": The float view is replaced by another float view.

"FLOATING_BALL_STOP": The float view stops when the bound floating ball stops.

"MAIN_WINDOW_DESTROY_STOP": The float view stops after the main window associated with the context is destroyed.

FloatViewState

Enumerates the states of the float view.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Name Value Description
STARTED 1 The float view has been started and displayed.
HIDDEN 2 The float view has been hidden. This state is triggered when the user swipes up to enter the multitasking screen or when the setFloatViewVisibilityInApp API is called to hide the float view when the application is in the foreground and the application now is in the foreground.
STOPPED 3 The float view has been stopped.
IN_SIDEBAR 4 The float view is in the sidebar.
IN_FLOATING_BALL 5 The float view is switched to the floating ball.
ERROR 6 An exception occurs in the float view.

FloatViewRectChangeInfo

Provides the rectangle area change information of the float view.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Name Type Read-Only Optional Description
windowRect window.Rect No No Rectangle area of the float view.
windowScale number No No Scale factor of the float view.
reason string No No

Reason for the change of the rectangle area of the float view. The reasons and their meanings are as follows:

"POSITION_CHANGE": The position changes.

"SIZE_CHANGE": The size changes.

"RECT_CHANGE": Both the position and size change.