基本概念
窗口沉浸式能力:指对状态栏、导航栏等系统窗口进行控制,减少状态栏导航栏等系统界面的突兀感,从而使用户获得最佳体验的能力。
沉浸式能力只在应用主窗口作为全屏窗口时生效。通常情况下,应用子窗口(弹窗、悬浮窗口等辅助窗口)和处于自由窗口下的应用主窗口无法使用沉浸式能力。
说明 :
当前沉浸式界面开发仅支持window级别的配置,暂不支持Page级别的配置。若有Page级别切换的需要,可以在页面生命周期开始,例如onPageShow中设置沉浸模式,然后在页面退出,例如onPageHide中恢复默认设置来实现。
场景介绍
在FA模型下,管理应用窗口的典型场景有:
- 设置应用子窗口属性及目标页面
- 体验窗口沉浸式能力
以下分别介绍具体开发方式。
接口说明
上述场景涉及的常用接口如下表所示。
实例名 | 接口名 | 描述 |
---|---|---|
window静态方法 | createWindow(config: Configuration, callback: AsyncCallback): void | 创建子窗口。 -config:创建窗口时的参数。 |
window静态方法 | findWindow(name: string): Window | 查找name所对应的窗口。 |
Window | setUIContent(path: string, callback: AsyncCallback): void | 根据当前工程中某个页面的路径为窗口加载具体的页面内容。 其中path为要加载到窗口中的页面内容的路径,在FA模型下该路径需添加到工程的config.json文件中。 |
Window | moveWindowTo(x: number, y: number, callback: AsyncCallback): void | 移动当前窗口。 |
Window | setWindowBrightness(brightness: number, callback: AsyncCallback): void | 设置屏幕亮度值。 |
Window | resize(width: number, height: number, callback: AsyncCallback): void | 改变当前窗口大小。 |
Window | setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback): void | 设置窗口布局是否为全屏布局。 |
Window | setWindowSystemBarEnable(names: Array<‘status’ | ‘navigation’>): Promise |
Window | setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback): void | 设置窗口内导航栏、状态栏属性。 systemBarProperties:导航栏、状态栏的属性集合。 |
Window | showWindow(callback: AsyncCallback): void | 显示当前窗口。 |
Window | on(type: ‘touchOutside’, callback: Callback): void | 开启本窗口区域外的点击事件的监听。 |
Window | destroyWindow(callback: AsyncCallback): void | 销毁当前窗口。 |
设置应用子窗口
开发者可以按需创建应用子窗口,如弹窗等,并对其进行属性设置等操作。
开发步骤
- 创建/获取子窗口对象。
- 可以通过window.createWindow接口创建子窗口。
- 也可以通过window.findWindow接口来查找已经创建的窗口从而得到子窗口。
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
let windowClass: window.Window | null = null;
// 方式一:创建子窗口。
let config: window.Configuration = { name: "subWindow", windowType: window.WindowType.TYPE_APP };
window.createWindow(config, (err: BusinessError, data) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to create the subWindow. Cause: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in creating subWindow. Data: ' + JSON.stringify(data));
windowClass = data;
});
// 方式二:查找得到子窗口。
try {
windowClass = window.findWindow('subWindow');
} catch (exception) {
console.error('Failed to find the Window. Cause: ' + JSON.stringify(exception));
}
- 设置子窗口属性。
子窗口创建成功后,可以改变其大小、位置等,还可以根据应用需要设置窗口背景色、亮度等属性。
// 移动子窗口位置。
let windowClass: window.Window = window.findWindow("test");
windowClass.moveWindowTo(300, 300, (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to move the window. Cause:' + JSON.stringify(err));
return;
}
console.info('Succeeded in moving the window.');
});
// 改变子窗口大小。
windowClass.resize(500, 500, (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to change the window size. Cause:' + JSON.stringify(err));
return;
}
console.info('Succeeded in changing the window size.');
});
- 加载显示子窗口的具体内容。
使用setUIContent和showWindow接口加载显示子窗口的具体内容。
// 为子窗口加载对应的目标页面。
let windowClass: window.Window = window.findWindow("test");
windowClass.setUIContent("pages/page2", (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to load the content. Cause: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in loading the content.');
// 显示子窗口。
windowClass.showWindow((err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to show the window. Cause: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in showing the window.');
});
});
- 销毁子窗口。
当不再需要某些子窗口时,可根据场景的具体实现逻辑,使用destroyWindow接口销毁子窗口。
// 销毁子窗口。当不再需要某些子窗口时,可根据场景的具体实现逻辑,使用destroy接口销毁子窗口。
let windowClass: window.Window = window.findWindow("test");
windowClass.destroyWindow((err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to destroy the subwindow. Cause:' + JSON.stringify(err));
return;
}
console.info('Succeeded in destroying the subwindow.');
});
体验窗口沉浸式能力
在看视频、玩游戏等场景下,用户往往希望隐藏状态栏、导航栏等不必要的系统窗口,从而获得更佳的沉浸式体验。此时可以借助窗口沉浸式能力(窗口沉浸式能力都是针对应用主窗口而言的),达到预期效果。从API version 10开始,沉浸式窗口默认配置为全屏大小并由组件模块控制布局,状态栏、导航栏背景颜色为透明,文字颜色为黑色;应用窗口调用setWindowLayoutFullScreen接口,设置为true表示由组件模块控制忽略状态栏、导航栏的沉浸式全屏布局,设置为false表示由组件模块控制避让状态栏、导航栏的非沉浸式全屏布局。
开发步骤
- 获取主窗口对象。
说明
沉浸式能力需要在成功获取应用主窗口对象的前提下进行。
确保应用内最后显示的窗口为主窗口,然后再使用window.getLastWindow接口来获取得到主窗口。
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
let mainWindowClass: window.Window | null = null;
// 获取主窗口。
class BaseContext {
stageMode: boolean = false;
}
let context: BaseContext = { stageMode: false };
window.getLastWindow(context, (err: BusinessError, data) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to get the subWindow. Cause: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in getting subWindow. Data: ' + JSON.stringify(data));
mainWindowClass = data;
});
- 实现沉浸式效果。有以下两种方式:
- 方式一:应用主窗口为全屏窗口时,调用setWindowSystemBarEnable接口,设置导航栏、状态栏不显示,从而达到沉浸式效果。
- 方式二:调用setWindowLayoutFullScreen接口,设置应用主窗口为全屏布局;然后调用setWindowSystemBarProperties接口,设置导航栏、状态栏的透明度、背景/文字颜色以及高亮图标等属性,使之保持与主窗口显示协调一致,从而达到沉浸式效果。
// 实现沉浸式效果。方式一:设置导航栏、状态栏不显示。
let names: Array<'status' | 'navigation'> = [];
let mainWindowClass: window.Window = window.findWindow("test");
mainWindowClass.setWindowSystemBarEnable(names, (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err));
return;
}
console.info('Succeeded in setting the system bar to be visible.');
});
// 实现沉浸式效果。
// 方式二:设置窗口为全屏布局,配合设置状态栏、导航栏的透明度、背景/文字颜色及高亮图标等属性,与主窗口显示保持协调一致。
let isLayoutFullScreen: boolean = true;
mainWindowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err));
return;
}
console.info('Succeeded in setting the window layout to full-screen mode.');
});
let sysBarProps: window.SystemBarProperties = {
statusBarColor: '#ff00ff',
navigationBarColor: '#00ff00',
// 以下两个属性从API Version8开始支持。
statusBarContentColor: '#ffffff',
navigationBarContentColor: '#ffffff'
};
mainWindowClass.setWindowSystemBarProperties(sysBarProps, (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in setting the system bar properties.');
});
- 加载显示沉浸式窗口的具体内容。
使用setUIContent和showWindow接口加载显示沉浸式窗口的具体内容。
// 为沉浸式窗口加载对应的目标页面。
let mainWindowClass: window.Window = window.findWindow("test");
mainWindowClass.setUIContent("pages/page3", (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to load the content. Cause: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in loading the content.');
// 显示沉浸式窗口。
mainWindowClass.showWindow((err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to show the window. Cause: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in showing the window.');
});
});
鸿蒙全栈开发全新学习指南
有很多小伙伴不知道学习哪些鸿蒙开发技术?不知道需要重点掌握哪些鸿蒙应用开发知识点?而且学习时频繁踩坑,最终浪费大量时间。所以要有一份实用的鸿蒙(HarmonyOS NEXT)学习路线与学习文档用来跟着学习是非常有必要的。
针对一些列因素,整理了一套纯血版鸿蒙(HarmonyOS Next)全栈开发技术的学习路线,包含了鸿蒙开发必掌握的核心知识要点,内容有(ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、WebGL、元服务、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、OpenHarmony驱动开发、系统定制移植等等)鸿蒙(HarmonyOS NEXT)技术知识点。
本路线共分为四个阶段:
第一阶段:鸿蒙初中级开发必备技能
第二阶段:鸿蒙南北双向高工技能基础:gitee.com/MNxiaona/733GH
第三阶段:应用开发中高级就业技术
第四阶段:全网首发-工业级南向设备开发就业技术:gitee.com/MNxiaona/733GH
《鸿蒙 (Harmony OS)开发学习手册》(共计892页)
如何快速入门?
1.基本概念
2.构建第一个ArkTS应用
3.……
开发基础知识:gitee.com/MNxiaona/733GH
1.应用基础知识
2.配置文件
3.应用数据管理
4.应用安全管理
5.应用隐私保护
6.三方应用调用管控机制
7.资源分类与访问
8.学习ArkTS语言
9.……
基于ArkTS 开发
1.Ability开发
2.UI开发
3.公共事件与通知
4.窗口管理
5.媒体
6.安全
7.网络与链接
8.电话服务
9.数据管理
10.后台任务(Background Task)管理
11.设备管理
12.设备使用信息统计
13.DFX
14.国际化开发
15.折叠屏系列
16.……
鸿蒙开发面试真题(含参考答案):gitee.com/MNxiaona/733GH
鸿蒙入门教学视频:
美团APP实战开发教学:gitee.com/MNxiaona/733GH
写在最后
- 如果你觉得这篇内容对你还蛮有帮助,我想邀请你帮我三个小忙:
- 点赞,转发,有你们的 『点赞和评论』,才是我创造的动力。
- 关注小编,同时可以期待后续文章ing🚀,不定期分享原创知识。
- 想要获取更多完整鸿蒙最新学习资源,请移步前往小编:
gitee.com/MNxiaona/733GH