diff --git a/zh-cn/application-dev/windowmanager/system-window-stage.md b/zh-cn/application-dev/windowmanager/system-window-stage.md index 1b8b0756e551869d67127b888851237c54a35b7a..c665a537fd281fac2205334f5711cfbbc41003c2 100644 --- a/zh-cn/application-dev/windowmanager/system-window-stage.md +++ b/zh-cn/application-dev/windowmanager/system-window-stage.md @@ -4,6 +4,12 @@ 在`Stage`模型下， 允许系统应用创建和管理系统窗口，包括音量条、壁纸、通知栏、状态栏、导航栏等。具体支持的系统窗口类型见[API参考-WindowType](../reference/apis/js-apis-window.md#windowtype7)。 +在窗口显示、隐藏及窗口间切换时，窗口模块通常会添加动画效果，以使各个交互过程更加连贯流畅。 + +在OpenHarmony中，应用窗口的动效为默认行为，不需要开发者进行设置或者修改。 + +相对于应用窗口，在显示系统窗口过程中，开发者可以自定义窗口的显示动画、隐藏动画。 + > **说明：** > > 本文档涉及系统接口的使用，请使用full-SDK进行开发。具体使用可见[full-SDK替换指南](../quick-start/full-sdk-switch-guide.md)。 @@ -13,23 +19,27 @@ 更多API说明请参见[API参考](../reference/apis/js-apis-window.md)。 -| 实例名 | 接口名 | 描述 | -| -------- | -------- | -------- | -| window静态方法 | createWindow(config: Configuration, callback: AsyncCallback\): void | 创建子窗口或系统窗口。
-`config`：创建窗口时的参数。 | -| Window | resize(width: number, height: number, callback: AsyncCallback<void>): void | 改变当前窗口大小。 | -| Window | moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void | 移动当前窗口位置。 | -| Window | SetUIContent(path: string, callback: AsyncCallback<void>): void | 为当前窗口加载具体页面。 | -| Window | showWindow(callback: AsyncCallback\): void | 显示当前窗口。 | -| Window | on(type: 'touchOutside', callback: Callback<void>): void | 开启本窗口区域外的点击事件的监听。 | -| Window | hide (callback: AsyncCallback\): void | 隐藏当前窗口。此接口为系统接口。 | -| Window | destroyWindow(callback: AsyncCallback<void>): void | 销毁当前窗口。 | - - -## 开发步骤 +| 实例名 | 接口名 | 描述 | +| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| window静态方法 | createWindow(config: Configuration, callback: AsyncCallback\): void | 创建子窗口或系统窗口。
-`config`：创建窗口时的参数。 | +| Window | resize(width: number, height: number, callback: AsyncCallback<void>): void | 改变当前窗口大小。 | +| Window | moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void | 移动当前窗口位置。 | +| Window | SetUIContent(path: string, callback: AsyncCallback<void>): void | 为当前窗口加载具体页面。 | +| Window | showWindow(callback: AsyncCallback\): void | 显示当前窗口。 | +| Window | on(type: 'touchOutside', callback: Callback<void>): void | 开启本窗口区域外的点击事件的监听。 | +| Window | hide (callback: AsyncCallback\): void | 隐藏当前窗口。此接口为系统接口。 | +| Window | destroyWindow(callback: AsyncCallback<void>): void | 销毁当前窗口。 | +| Window | getTransitionController(): TransitionController | 获取窗口属性转换控制器。此接口为系统接口。 | +| TransitionContext | completeTransition(isCompleted: boolean): void | 设置属性转换的最终完成状态。该函数需要在动画函数[animateTo()](../reference/arkui-ts/ts-explicit-animation.md)执行后设置。此接口为系统接口。 | +| Window | showWithAnimation(callback: AsyncCallback\): void | 显示当前窗口，过程中播放动画。此接口为系统接口。 | +| Window | hideWithAnimation(callback: AsyncCallback\): void | 隐藏当前窗口，过程中播放动画。此接口为系统接口。 | +## 系统窗口的开发 本文以音量条窗口为例，介绍系统窗口的基本开发和管理步骤。 +### 开发步骤 + 1. 创建系统窗口。 @@ -112,3 +122,140 @@ export default class ServiceExtensionAbility1 extends ExtensionContext { } }; ``` + +## 自定义系统窗口的显示与隐藏动画 + +在显示系统窗口过程中，开发者可以自定义窗口的显示动画。在隐藏系统窗口过程中，开发者可以自定义窗口的隐藏动画。本文以显示和隐藏动画为例介绍主要开发步骤。 + +### 开发步骤 + +1. 获取窗口属性转换控制器。 + + 通过`getTransitionController`接口获取控制器。后续的动画操作都由属性控制器来完成。 + +2. 配置窗口显示时的动画。 + + 通过动画函数[animateTo()](../reference/arkui-ts/ts-explicit-animation.md)配置具体的属性动画。 + +3. 设置属性转换完成。 + + 通过`completeTransition(true)`来设置属性转换的最终完成状态。如果传入false，则表示撤销本次转换。 + +4. 显示或隐藏当前窗口，过程中播放动画。 + + 调用`showWithAnimation`接口，来显示窗口并播放动画。调用`hideWithAnimation`接口，来隐藏窗口并播放动画。 + +```ts +import ExtensionContext from '@ohos.app.ability.ServiceExtensionAbility'; +import window from '@ohos.window'; + +export default class ServiceExtensionAbility1 extends ExtensionContext { + onCreate(want) { + console.log("[Demo] MainAbility onCreate") + globalThis.abilityWant = want; + // 创建音量条窗口。 + let windowClass = null; + let config = {name: "volume", windowType: window.WindowType.TYPE_VOLUME_OVERLAY, ctx: this.context}; + window.createWindow(config, (err, data) => { + if (err.code) { + console.error('Failed to create the volume window. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in creating the volume window.') + windowClass = data; + // 以下为系统窗口显示动画的开发步骤 + // 1. 获取窗口属性转换控制器 + let controller = windowClass.getTransitionController(); + // 2. 配置窗口显示时的动画 + controller.animationForShown = (context : window.TransitionContext) => { + let toWindow = context.toWindow + // 配置动画参数 + animateTo({ + duration: 1000, // 动画时长 + tempo: 0.5, // 播放速率 + curve: Curve.EaseInOut, // 动画曲线 + delay: 0, // 动画延迟 + iterations: 1, // 播放次数 + playMode: PlayMode.Normal, // 动画模式 + onFinish: ()=> { + // 3. 设置属性转换完成 + context.completeTransition(true) + } + }, () => { + let obj : window.TranslateOptions = { + x : 100.0, + y : 0.0, + z : 0.0 + } + toWindow.translate(obj); + console.info('toWindow translate end'); + }) + console.info('complete transition end'); + } + + windowClass.loadContent("pages/page_volume", (err) => { + if (err.code) { + console.error('Failed to load the content. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in loading the content.'); + // 4.显示当前窗口，过程中播放动画 + windowClass.showWithAnimation((err) => { + if (err.code) { + console.error('Failed to show the window with animation. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in showing the window with animation.'); + }) + }); + }); + } + onDestroy() { + let windowClass = null; + try { + windowClass = window.findWindow('volume'); + } catch (exception) { + console.error('Failed to find the Window. Cause: ' + JSON.stringify(exception)); + } + // 以下为系统窗口隐藏动画的开发步骤 + // 1. 获取窗口属性转换控制器 + let controller = windowClass.getTransitionController(); + // 2. 配置窗口显示时的动画 + controller.animationForHidden = (context : window.TransitionContext) => { + let toWindow = context.toWindow + // 配置动画参数 + animateTo({ + duration: 1000, // 动画时长 + tempo: 0.5, // 播放速率 + curve: Curve.EaseInOut, // 动画曲线 + delay: 0, // 动画延迟 + iterations: 1, // 播放次数 + playMode: PlayMode.Normal, // 动画模式 + onFinish: ()=> { + // 3. 设置属性转换完成 + context.completeTransition(true) + windowClass.destroyWindow((err) => { + if (err.code) { + console.error('Failed to destroy the window. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in destroying the window.'); + }); + } + }, () => { + toWindow.opacity(0.0); + console.info('toWindow opacity end'); + }) + console.info('complete transition end'); + } + // 4.隐藏当前窗口，过程中播放动画 + windowClass.hideWithAnimation((err) => { + if (err.code) { + console.error('Failed to hide the window with animation. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in hiding the window with animation.'); + }); + } +}; +``` \ No newline at end of file