应用启动
在应用开发中,启动应用(通常指启动UIAbility组件)是开发者的常见任务。例如,从商城应用跳转到支付应用进行付款,从聊天应用启动视频应用播放视频,或者在应用间跳转时需要指定特定的窗口模式等场景。
应用、进程与UIAbility组件的关系
一个应用可以运行在一个或多个进程中,一个进程中也可以运行单个或多个UIAbility组件实例。三方应用开发者开发的应用,必须包含至少一个UIAbility组件,否则没有界面对用户展示。
对于用户而言,只有UIAbility组件是可见的,启动应用内的第一个UIAbility组件就代表启动应用。后面的章节中,启动应用就是指启动UIAbility。
通过StartOptions,开发者可以在启动UIAbility时灵活控制其启动行为,包括窗口模式、窗口位置、启动动效、启动页样式、窗口尺寸限制等多个方面,从而满足不同设备形态和用户场景的需求。
指定窗口模式启动应用
在某些场景下,开发者需要指定UIAbility以特定的窗口模式启动。例如:
- 在平板设备上,商品详情窗口以分屏模式启动,充分利用大屏优势。
- 在2in1设备上,打开文档时以全屏模式启动,提供沉浸式体验。
- 在视频应用中,打开视频播放UIAbility时,希望以悬浮窗形式显示,方便用户同时查看简介和播放界面。
开发步骤如下:
- 在启动UIAbility之前,需要先导入相关的模块。
- 创建Want对象,指定要启动的UIAbility信息。UIAbilityContext的获取方式参见获取UIAbility的上下文信息。
- 配置StartOptions的windowMode,指定窗口模式。windowMode的说明参见StartOptions。
- 调用startAbility接口,启动目标UIAbility。
const TAG: string = '[StartAbility]';
const DOMAIN_NUMBER: number = 0xFF00;
@Entry
@Component
struct StartWithSpecifiedWindowModeAbility {
build() {
Row() {
Column() {
Button("以分屏模式启动")
.onClick(() => {
// context为调用方UIAbility的UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let want: Want = {
deviceId: '', // deviceId为空表示本设备
bundleName: 'com.example.startoptions',
abilityName: 'StartWithSpecifiedWindowModeAbility',
parameters: {
// 自定义信息
info: '从StartWithSpecifiedWindowModeAbility启动'
}
};
let options: StartOptions = {
windowMode: AbilityConstant.WindowMode.WINDOW_MODE_SPLIT_SECONDARY // 以分屏模式拉起
};
context.startAbility(want, options).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting ability.');
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG, `Failed to start ability. Code is ${err.code}, message is ${err.message}`);
});
})
}
.width('100%')
}
.height('100%')
}
}
说明:
如果未指定windowMode,UIAbility将以系统默认的窗口展示形态启动。
指定显示屏幕启动应用
在多屏设备(如平板连接外接显示器、2in1设备等)上,开发者可能需要指定UIAbility在特定的屏幕上启动。例如:
- 在平板设备上,将视频播放功能启动到外接显示器上。
- 在2in1设备上,将辅助功能启动到副屏幕上。
开发步骤如下:
- 在启动UIAbility之前,需要先导入相关的模块。
- 创建Want对象,指定要启动的UIAbility信息。UIAbilityContext的获取方式参见获取UIAbility的上下文信息。
- 配置StartOptions的displayId,指定要显示的屏幕。displayId的说明参见StartOptions。
- 调用startAbility接口,启动目标UIAbility。
const TAG: string = '[StartAbility]';
const DOMAIN_NUMBER: number = 0xFF00;
@Entry
@Component
struct SpecifyDisplayScreen {
build() {
Row() {
Column() {
Button("在当前屏幕上启动")
.onClick(() => {
// context为调用方UIAbility的UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let want: Want = {
deviceId: '', // deviceId为空表示本设备
bundleName: 'com.example.startoptions',
abilityName: 'EntryAbility',
parameters: {
// 自定义信息
info: '从EntryAbility启动'
}
};
let options: StartOptions = {
displayId: -1 // 在当前屏幕上启动
};
context.startAbility(want, options).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting ability.');
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG, `Failed to start ability. Code is ${err.code}, message is ${err.message}`);
});
})
}
.width('100%')
}
.height('100%')
}
}
控制应用启动时是否有动效
需要快速切换界面时,关闭动画以提升响应速度。
开发步骤如下:
- 在启动UIAbility之前,需要先导入相关的模块。
- 创建Want对象,指定要启动的UIAbility信息。UIAbilityContext的获取方式参见获取UIAbility的上下文信息。
- 配置StartOptions的withAnimation,控制是否有启动动效。withAnimation的说明参见StartOptions。
- 调用startAbility接口,启动目标UIAbility。
const TAG: string = '[StartAbility]';
const DOMAIN_NUMBER: number = 0xFF00;
@Entry
@Component
struct ControlStartupAnimation {
build() {
Row() {
Column() {
Button("关闭启动动画")
.onClick(() => {
// context为调用方UIAbility的UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let want: Want = {
deviceId: '', // deviceId为空表示本设备
bundleName: 'com.example.startoptions',
abilityName: 'EntryAbility',
parameters: {
// 自定义信息
info: '从EntryAbility启动'
}
};
let options: StartOptions = {
withAnimation: false // 关闭启动动画
};
context.startAbility(want, options).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting ability.');
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG, `Failed to start ability. Code is ${err.code}, message is ${err.message}`);
});
})
}
.width('100%')
}
.height('100%')
}
}
启动应用时设置窗口位置
在自由窗口状态下,开发者可能需要指定UIAbility窗口的初始位置。例如:
- 在多窗口场景下,让新窗口出现在特定位置,避免遮挡其他重要内容。
- 在大屏设备上,为内容展示类应用设置较大的窗口尺寸。
- 在多窗口场景下,为辅助工具类应用设置较小的窗口尺寸。
- 将辅助窗口放置在屏幕边缘。
开发步骤如下:
- 在启动UIAbility之前,需要先导入相关的模块。
- 创建Want对象,指定要启动的UIAbility信息。UIAbilityContext的获取方式参见获取UIAbility的上下文信息。
- 配置StartOptions的windowLeft、windowTop、windowWidth、windowHeight属性,设置窗口位置和尺寸。相关属性的说明参见StartOptions。
- 调用startAbility接口,启动目标UIAbility。
const TAG: string = '[StartAbility]';
const DOMAIN_NUMBER: number = 0xFF00;
@Entry
@Component
struct SetWindowPosition {
build() {
Row() {
Column() {
Button("设置窗口位置")
.onClick(() => {
// context为调用方UIAbility的UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let want: Want = {
deviceId: '', // deviceId为空表示本设备
bundleName: 'com.example.startoptions',
abilityName: 'EntryAbility',
parameters: {
// 自定义信息
info: '从EntryAbility启动'
}
};
let options: StartOptions = {
displayId: 0,
windowLeft: 100, // 距离屏幕左侧100px
windowTop: 200, // 距离屏幕顶部200px
windowWidth: 800, // 窗口宽度800px
windowHeight: 600 // 窗口高度600px
};
context.startAbility(want, options).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting ability.');
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG, `Failed to start ability. Code is ${err.code}, message is ${err.message}`);
});
})
}
.width('100%')
}
.height('100%')
}
}
说明:
配置windowLeft和windowTop时,建议同时配置这两个属性。
启动应用时设置窗口尺寸限制
在自由窗口状态下,开发者可能需要限制UIAbility窗口的尺寸范围,防止用户将窗口调整得过大或过小。例如:
- 设置最小窗口尺寸,确保UI内容不会因为窗口太小而无法正常显示。
- 设置最大窗口尺寸,避免窗口在大屏设备上过大而影响使用体验。
开发步骤如下:
- 在启动UIAbility之前,需要先导入相关的模块。
- 创建Want对象,指定要启动的UIAbility信息。UIAbilityContext的获取方式参见获取UIAbility的上下文信息。
- 配置StartOptions的minWindowWidth、minWindowHeight、maxWindowWidth、maxWindowHeight属性,设置窗口尺寸限制。相关属性的说明参见StartOptions。
- 调用startAbility接口,启动目标UIAbility。
const TAG: string = '[StartAbility]';
const DOMAIN_NUMBER: number = 0xFF00;
@Entry
@Component
struct SetWindowSizeConstraintsAbility {
build() {
Row() {
Column() {
Button("设置ability的窗口尺寸")
.onClick(() => {
// context为调用方UIAbility的UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let want: Want = {
deviceId: '', // deviceId为空表示本设备
bundleName: 'com.example.startoptions',
abilityName: 'EntryAbility',
parameters: {
// 自定义信息
info: '从EntryAbility启动'
}
};
let options: StartOptions = {
startWindowBackgroundColor: '#E510FFFF', // ARGB格式
minWindowWidth: 320, // 最小宽度320vp
maxWindowWidth: 2560, // 最大宽度2560vp
minWindowHeight: 240, // 最小高度240vp
maxWindowHeight: 2560 // 最大高度2560vp
};
context.startAbility(want, options).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting ability.');
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG, `Failed to start ability. Code is ${err.code}, message is ${err.message}`);
});
})
}
.width('100%')
}
.height('100%')
}
}
说明:
可以通过getWindowLimitsVP获取当前窗口的尺寸限制。
隐藏启动UIAbility
在某些场景下,开发者需要启动UIAbility但不希望其立即显示在前台。例如:启动一个用于后台监控的UIAbility,等待条件触发后再显示。
开发步骤如下:
- 在启动UIAbility之前,需要先导入相关的模块。
- 创建Want对象,指定要启动的UIAbility信息。UIAbilityContext的获取方式参见获取UIAbility的上下文信息。
- 配置StartOptions的processMode和startupVisibility,设置进程模式和可见性。相关属性的说明参见StartOptions。
- 调用startAbility接口,启动目标UIAbility。
const DOMAIN = 0x0000;
const TAG: string = '[StartAbility]';
const DOMAIN_NUMBER: number = 0xFF00;
// ...
onForeground(): void {
// Ability has brought to foreground
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
let want: Want = {
deviceId: '', // deviceId为空表示本设备
bundleName: 'com.example.startoptions',
abilityName: 'EntryAbility',
parameters: {
// 自定义信息
info: '从EntryAbility启动'
}
};
let options: StartOptions = {
processMode: contextConstant.ProcessMode.NEW_PROCESS_ATTACH_TO_PARENT,
startupVisibility: contextConstant.StartupVisibility.STARTUP_HIDE
};
try {
this.context.startAbility(want, options, (err: BusinessError) => {
if (err.code) {
// 处理业务逻辑错误
console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
return;
}
// 执行正常业务
console.info('startAbility succeed');
});
} catch (err) {
// 处理入参错误异常
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startAbility failed, code is ${code}, message is ${message}`);
}
}
// ...
}
说明:
当设置目标UIAbility为不可见时:
- 目标UIAbility的窗口不会显示在前台
- Dock栏也不会有图标
- 目标UIAbility的onForeground生命周期不会被调用
设置启动页图标和背景色
开发者希望自定义UIAbility启动时显示的启动页图标和背景颜色。例如:
- 为特定功能UIAbility设置主题色一致的启动背景和专属图标,提升品牌识别度。
- 根据不同场景展示不同的启动页样式,增强视觉体验。
开发步骤如下:
- 在启动UIAbility之前,需要先导入相关的模块。
- 创建Want对象,指定要启动的UIAbility信息。UIAbilityContext的获取方式参见获取UIAbility的上下文信息。
- 配置StartOptions的startWindowIcon和startWindowBackgroundColor,设置启动页图标和背景色。相关属性的说明参见StartOptions。
- 调用startAbility接口,启动目标UIAbility。
const DOMAIN = 0x0000;
const TAG: string = '[StartAbility]';
const DOMAIN_NUMBER: number = 0xFF00;
// ...
async onForeground(): Promise<void> {
// Ability has brought to foreground
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
let want: Want = {
deviceId: '', // deviceId为空表示本设备
bundleName: 'com.example.startoptions',
abilityName: 'EntryAbility',
parameters: {
// 自定义信息
info: '从EntryAbility启动'
}
};
// 创建PixelMap对象
let color = new ArrayBuffer(512 * 512 * 4);
let bufferArr = new Uint8Array(color);
for (let i = 0; i < bufferArr.length; i += 4) {
bufferArr[i] = 255;
bufferArr[i+1] = 0;
bufferArr[i+2] = 122;
bufferArr[i+3] = 255;
}
let windowParam: window.WindowCreateParams = {};
let options: StartOptions = {
startWindowIcon: await image.createPixelMap(color, {
editable: true,
pixelFormat: image.PixelMapFormat.RGBA_8888,
size: { height: 512, width: 512 }
}),
startWindowBackgroundColor: '#E510FFFF', // ARGB格式
minWindowWidth: 320,
minWindowHeight: 240,
maxWindowWidth: 2560,
maxWindowHeight: 2560,
windowCreateParams: windowParam
};
this.context.startAbility(want, options).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting ability.');
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG, `Failed to start ability. Code is ${err.code}, message is ${err.message}`);
});
}
// ...
}
说明:
- 如果未配置startWindowIcon,则默认采用module.json5文件中startWindowIcon字段的配置。
- 如果未配置startWindowBackgroundColor,则默认采用module.json5文件中startWindowBackground字段的配置。
- 背景颜色格式为ARGB,如:
#E5FFFFFF(透明度为E5,RGB值为FFFFFF)。
获取启动结果
在某些场景下,开发者需要获取UIAbility启动的结果,以便进行后续处理。例如:使用其他应用账号登录,需要知道拉起其他应用是否成功。
开发步骤如下:
- 在启动UIAbility之前,需要先导入相关的模块。
- 创建Want对象,指定要启动的UIAbility信息。UIAbilityContext的获取方式参见获取UIAbility的上下文信息。
- 配置StartOptions的completionHandler,设置启动结果回调。completionHandler的说明参见StartOptions。
- 调用startAbility接口,启动目标UIAbility。
const DOMAIN = 0x0000;
const TAG: string = '[StartAbility]';
const DOMAIN_NUMBER: number = 0xFF00;
// ...
onForeground(): void {
// Ability has brought to foreground
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
let want: Want = {
deviceId: '', // deviceId为空表示本设备
bundleName: 'com.example.startoptions',
abilityName: 'EntryAbility',
parameters: {
// 自定义信息
info: '从EntryAbility启动'
}
};
let completionHandler: CompletionHandler = {
onRequestSuccess: (elementName: bundleManager.ElementName, message: string): void => {
console.info(`${elementName.bundleName}-${elementName.moduleName}-${elementName.abilityName} start succeeded: ${message}`);
},
onRequestFailure: (elementName: bundleManager.ElementName, message: string): void => {
console.error(`${elementName.bundleName}-${elementName.moduleName}-${elementName.abilityName} start failed: ${message}`);
}
};
let options: StartOptions = {
completionHandler: completionHandler
};
this.context.startAbility(want, options).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting ability.');
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG, `Failed to start ability. Code is ${err.code}, message is ${err.message}`);
});
}
// ...
}
隐藏启动页
在某些场景下,开发者希望启动UIAbility时不显示启动页,直接显示应用界面。例如:
- 快速切换功能时,避免启动页闪烁,提升体验流畅度。
- 应用界面加载速度很快时,不需要启动页过渡。
开发步骤如下:
- 在启动UIAbility之前,需要先导入相关的模块。
- 创建Want对象,指定要启动的UIAbility信息。UIAbilityContext的获取方式参见获取UIAbility的上下文信息。
- 配置StartOptions的hideStartWindow,设置隐藏启动页。属性的说明参见StartOptions。
- 调用startAbility接口,启动目标UIAbility。
const DOMAIN = 0x0000;
const TAG: string = '[StartAbility]';
const DOMAIN_NUMBER: number = 0xFF00;
// ...
onForeground(): void {
// Ability has brought to foreground
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
let want: Want = {
deviceId: '', // deviceId为空表示本设备
bundleName: 'com.example.startoptions',
abilityName: 'EntryAbility',
parameters: {
// 自定义信息
info: '从EntryAbility启动'
}
};
let options: StartOptions = {
hideStartWindow: true // 隐藏启动页
};
this.context.startAbility(want, options).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting ability.');
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG, `Failed to start ability. Code is ${err.code}, message is ${err.message}`);
});
}
// ...
}
说明:
启动页介绍和规格详见StartWindow。
设置窗口参数
在某些高级场景下,开发者需要更细粒度地控制UIAbility启动时的窗口参数。例如:窗口动效。
开发步骤如下:
- 在启动UIAbility之前,需要先导入相关的模块。
- 创建Want对象,指定要启动的UIAbility信息。UIAbilityContext的获取方式参见获取UIAbility的上下文信息。
- 配置StartOptions的windowCreateParams,设置窗口参数。窗口参数配置详见WindowCreateParams。
- 调用startAbility接口,启动目标UIAbility。
const DOMAIN = 0x0000;
const TAG: string = '[StartAbility]';
const DOMAIN_NUMBER: number = 0xFF00;
// ...
async onForeground(): Promise<void> {
// Ability has brought to foreground
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
let want: Want = {
deviceId: '', // deviceId为空表示本设备
bundleName: 'com.example.startoptions',
abilityName: 'EntryAbility',
parameters: {
// 自定义信息
info: '从EntryAbility启动'
}
};
// 创建PixelMap对象
let color = new ArrayBuffer(512 * 512 * 4);
let bufferArr = new Uint8Array(color);
for (let i = 0; i < bufferArr.length; i += 4) {
bufferArr[i] = 255;
bufferArr[i+1] = 0;
bufferArr[i+2] = 122;
bufferArr[i+3] = 255;
}
let windowParam: window.WindowCreateParams = {};
let options: StartOptions = {
startWindowIcon: await image.createPixelMap(color, {
editable: true,
pixelFormat: image.PixelMapFormat.RGBA_8888,
size: { height: 512, width: 512 }
}),
startWindowBackgroundColor: '#E510FFFF', // ARGB格式
minWindowWidth: 320,
minWindowHeight: 240,
maxWindowWidth: 2560,
maxWindowHeight: 2560,
windowCreateParams: windowParam
};
this.context.startAbility(want, options).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting ability.');
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG, `Failed to start ability. Code is ${err.code}, message is ${err.message}`);
});
}
// ...
}
本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。
