1/* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"), 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit AbilityKit 19 */ 20 21import type common from './@ohos.app.ability.common'; 22import { AbilityResult } from './ability/abilityResult'; 23 24/** 25 * Defines a OnError function. 26 * 27 * @typedef { function } OnErrorFn 28 * @param { number } code - The code returned if the UIAbility or UIExtensionAbility failed to start. 29 * @param { string } name - The name returned if the UIAbility or UIExtensionAbility failed to start. 30 * @param { string } message - The message returned if the UIAbility or UIExtensionAbility failed to start. 31 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 32 * @systemapi 33 * @stagemodelonly 34 * @since 20 35 */ 36type OnErrorFn = (code: number, name: string, message: string) => void; 37 38/** 39 * Defines a onResult function. 40 * 41 * @typedef { function } OnResultFn 42 * @param { AbilityResult } parameter - The Parameter returned if the UIExtensionAbility call terminateSelfWithResult. 43 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 44 * @systemapi 45 * @stagemodelonly 46 * @since 20 47 */ 48type OnResultFn = (parameter: AbilityResult) => void; 49 50/** 51 * Defines a vertical domain panel manager. 52 * 53 * @namespace verticalPanelManager 54 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 55 * @systemapi 56 * @stagemodelonly 57 * @since 20 58 */ 59declare namespace verticalPanelManager { 60 61 /** 62 * Starts the vertical domain picker with panel config. 63 * If the target ability is visible, you can start the target ability; If the target ability is invisible, 64 * you need to apply for permission:ohos.permission.START_INVISIBLE_ABILITY to start target invisible ability. 65 * If the caller application is in the background, it is not allowed to call this interface. 66 * 67 * @param { common.UIAbilityContext } context - Indicates the ui ability context of the application. 68 * @param { Record<string, Object> } wantParam - Indicates the want parameter. 69 * @param { PanelConfig } panelConfig - Indicates the panel config. 70 * @param { PanelStartCallback } panelStartCallback - indicates the panelStartCallback. 71 * @returns { Promise<void> } The promise returned by the function. 72 * @throws { BusinessError } 202 - The application is not a system application. 73 * @throws { BusinessError } 16000050 - Failed to connect to the system service or system server handle failed. 74 * @throws { BusinessError } 16000135 - The main window of this ability of this context does not exits. 75 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 76 * @systemapi 77 * @stagemodelonly 78 * @since 20 79 */ 80 function startVerticalPanel( 81 context: common.UIAbilityContext, 82 wantParam: Record<string, Object>, 83 panelConfig: PanelConfig, 84 panelStartCallback: PanelStartCallback 85 ): Promise<void>; 86 87 /** 88 * Indicates the panel config 89 * 90 * @interface PanelConfig 91 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 92 * @systemapi 93 * @stagemodelonly 94 * @since 20 95 */ 96 interface PanelConfig { 97 /** 98 * The type of vertical domain 99 * 100 * @type { VerticalType } 101 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 102 * @systemapi 103 * @stagemodelonly 104 * @since 20 105 */ 106 type: VerticalType; 107 108 /** 109 * Indicates the info about source app 110 * 111 * <p>**NOTE** 112 * <br>1. The values of the following keys are assigned by the system. Manual settings do not take effect, 113 * since the system automatically changes the values to the actual values during data transfer. 114 * -SOURCE_APP_BUNDLE_NAME: bundle name of the caller. The value is a string. 115 * -SOURCE_APP_MODULE_NAME: module name of the caller. The value is a string. 116 * -SOURCE_APP_ABILITY_NAME: ability name of the caller. The value is a string. 117 * -SOURCE_APP_WINDOW_ID: the window ID of the caller. The value is a string. 118 * -SOURCE_APP_SCREEN_MODE: the screen mode of the split screen. The value is a string. The value is "1". 119 * @type { Record<string, string> } 120 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 121 * @systemapi 122 * @stagemodelonly 123 * @since 20 124 */ 125 sourceAppInfo: Record<string, string>; 126 } 127 128 /** 129 * Provides vertical type definition. 130 * 131 * @enum { string } VerticalType 132 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 133 * @systemapi 134 * @stagemodelonly 135 * @since 20 136 */ 137 export enum VerticalType { 138 /** 139 * Indicates the type for Navigation. 140 * 141 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 142 * @systemapi 143 * @stagemodelonly 144 * @since 20 145 */ 146 NAVIGATION = 'navigation', 147 } 148 149 /** 150 * The callback of start vertical panel. 151 * 152 * @typedef PanelStartCallback 153 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 154 * @systemapi 155 * @stagemodelonly 156 * @since 20 157 */ 158 interface PanelStartCallback { 159 /** 160 * Called when some error occurred except disconnected from UIAbility or UIExtensionAbility. 161 * 162 * @type { OnErrorFn } 163 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 164 * @systemapi 165 * @stagemodelonly 166 * @since 20 167 */ 168 onError: OnErrorFn; 169 170 /** 171 * Called when UIExtensionAbility terminate with result. 172 * 173 * @type { ?OnResultFn } 174 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 175 * @systemapi 176 * @stagemodelonly 177 * @since 20 178 */ 179 onResult?: OnResultFn; 180 } 181 182 /** 183 * export the const string of bundleName and provide it for sourceAppInfo. 184 * @constant 185 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 186 * @systemapi 187 * @stagemodelonly 188 * @since 20 189 */ 190 export const SOURCE_APP_BUNDLE_NAME = 'bundleName'; 191 192 /** 193 * export the const string of moduleName and provide it for sourceAppInfo. 194 * @constant 195 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 196 * @systemapi 197 * @stagemodelonly 198 * @since 20 199 */ 200 export const SOURCE_APP_MODULE_NAME = 'moduleName'; 201 202 /** 203 * export the const string of abilityName and provide it for sourceAppInfo. 204 * @constant 205 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 206 * @systemapi 207 * @stagemodelonly 208 * @since 20 209 */ 210 export const SOURCE_APP_ABILITY_NAME = 'abilityName'; 211 212 /** 213 * export the const string of windowId and provide it for sourceAppInfo. 214 * @constant 215 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 216 * @systemapi 217 * @stagemodelonly 218 * @since 20 219 */ 220 export const SOURCE_APP_WINDOW_ID = 'windowId'; 221 222 /** 223 * export the const string of screenMode and provide it for sourceAppInfo. 224 * @constant 225 * @syscap SystemCapability.Ability.AppExtension.VerticalPanel 226 * @systemapi 227 * @stagemodelonly 228 * @since 20 229 */ 230 export const SOURCE_APP_SCREEN_MODE = 'screenMode'; 231} 232 233export default verticalPanelManager;