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 MultimodalAwarenessKit 19 */ 20 21import { BusinessError } from './@ohos.base'; 22 23/** 24 * This module provides the capability to use on screen awareness 25 * 26 * @namespace onScreen 27 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 28 * @since 20 29 */ 30 31declare namespace onScreen { 32 /** 33 * Enum for page content scenario 34 * 35 * @enum { number } Scenario 36 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 37 * @since 20 38 */ 39 export enum Scenario { 40 /** 41 * Indicates unknown scenario 42 * 43 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 44 * @systemapi 45 * @since 20 46 */ 47 UNKNOWN = 0, 48 /** 49 * Indicates article scenario 50 * 51 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 52 * @systemapi 53 * @since 20 54 */ 55 ARTICLE = 1, 56 } 57 58 /** 59 * Enum for control event type 60 * 61 * @enum { number } EventType 62 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 63 * @since 20 64 */ 65 export enum EventType { 66 /** 67 * Indicates scroll to hook event type 68 * 69 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 70 * @systemapi 71 * @since 20 72 */ 73 SCROLL_TO_HOOK = 1, 74 } 75 76 /** 77 * Interface for paragraph 78 * @interface Paragraph 79 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 80 * @systemapi 81 * @since 20 82 */ 83 export interface Paragraph { 84 /** 85 * Indicates paragraph hook id 86 * @type { ?number } 87 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 88 * @systemapi 89 * @since 20 90 */ 91 hookId?: number, 92 /** 93 * Indicates paragraph chapter id if paragraph is splited to chapters 94 * @type { ?number } 95 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 96 * @systemapi 97 * @since 20 98 */ 99 chapterId?: number, 100 /** 101 * Indicates paragraph title 102 * @type { ?string } 103 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 104 * @systemapi 105 * @since 20 106 */ 107 title?: string, 108 /** 109 * Indicates paragraph text 110 * @type { ?string } 111 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 112 * @systemapi 113 * @since 20 114 */ 115 text?: string 116 } 117 118 /** 119 * Interface for content options 120 * @interface ContentOptions 121 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 122 * @systemapi 123 * @since 20 124 */ 125 export interface ContentOptions { 126 /** 127 * Indicates the windowId which need to gather, full screen window is specified by default 128 * @type { ?number } 129 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 130 * @systemapi 131 * @since 20 132 */ 133 windowId?: number, 134 /** 135 * Indicates whether content understanding is required, false by default 136 * @type { ?boolean } 137 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 138 * @systemapi 139 * @since 20 140 */ 141 contentUnderstand?: boolean, 142 /** 143 * Indicates whether page link is required, false by default 144 * @type { ?boolean } 145 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 146 * @systemapi 147 * @since 20 148 */ 149 pageLink?: boolean, 150 /** 151 * Indicates whether only text needs to be processed to return paragraphs, false by default 152 * @type { ?boolean } 153 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 154 * @systemapi 155 * @since 20 156 */ 157 textOnly?: boolean, 158 } 159 160 /** 161 * Interface for pageContent 162 * @interface PageContent 163 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 164 * @systemapi 165 * @since 20 166 */ 167 export interface PageContent { 168 /** 169 * Indicates window id corresponding to the content 170 * @type { number } 171 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 172 * @systemapi 173 * @since 20 174 */ 175 windowId: number, 176 /** 177 * Indicates session id corresponding to the content 178 * @type { number } 179 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 180 * @systemapi 181 * @since 20 182 */ 183 sessionId: number, 184 /** 185 * Indicates bundle name corresponding to the content 186 * @type { string } 187 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 188 * @systemapi 189 * @since 20 190 */ 191 bundleName: string, 192 /** 193 * Indicates scenario of the content 194 * @type { ?Scenario } 195 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 196 * @systemapi 197 * @since 20 198 */ 199 scenario?: Scenario, 200 /** 201 * Indicates title if content understand is needed 202 * @type { ?string } 203 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 204 * @systemapi 205 * @since 20 206 */ 207 title?: string, 208 /** 209 * Indicates content if content understand is needed 210 * @type { ?string } 211 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 212 * @systemapi 213 * @since 20 214 */ 215 content?: string, 216 /** 217 * Indicates page link if page link is needed 218 * @type { ?string } 219 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 220 * @systemapi 221 * @since 20 222 */ 223 pageLink?: string, 224 /** 225 * Indicates paragraphs if text only is needed 226 * @type { ?Paragraph[] } 227 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 228 * @systemapi 229 * @since 20 230 */ 231 paragraphs?: Paragraph[], 232 } 233 234 /** 235 * Interface for control event 236 * @interface ControlEvent 237 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 238 * @systemapi 239 * @since 20 240 */ 241 export interface ControlEvent { 242 /** 243 * Indicates controlled window id 244 * @type { number } 245 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 246 * @systemapi 247 * @since 20 248 */ 249 windowId: number, 250 /** 251 * Indicates session id 252 * @type { number } 253 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 254 * @systemapi 255 * @since 20 256 */ 257 sessionId: number, 258 /** 259 * Indicates control event type 260 * @type { EventType } 261 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 262 * @systemapi 263 * @since 20 264 */ 265 eventType: EventType, 266 /** 267 * Indicates controlled hookid for specific event type and specific session id 268 * @type { ?number } 269 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 270 * @systemapi 271 * @since 20 272 */ 273 hookId?: number, 274 } 275 276 /** 277 * Get page content 278 * 279 * @permission ohos.permission.GET_SCREEN_CONTENT 280 * @param { ContentOptions } [options] - Indicates options to get page content 281 * @returns { Promise<PageContent> } Indicates the promise which carrys retrieved page content 282 * @throws { BusinessError } 201 - Permission denied. An attempt was made to get page content forbidden by 283 * <br> permission: ohos.permission.GET_SCREEN_CONTENT. 284 * @throws { BusinessError } 202 - Permission check failed. A non-system application uses the system API. 285 * @throws { BusinessError } 801 - Capability not supported. Function can not work correctly due to limited 286 * <br> device capabilities. 287 * @throws { BusinessError } 34000001 - Service exception. 288 * @throws { BusinessError } 34000002 - The application or page is not supported. 289 * @throws { BusinessError } 34000003 - The window ID is invalid. Possible causes: 1. window id is not passed 290 * <br> when screen is splited. 2. passed window id is not on screen or floating. 291 * @throws { BusinessError } 34000004 - The page is not ready. 292 * @throws { BusinessError } 34000006 - The request timed out. 293 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 294 * @systemapi 295 * @since 20 296 */ 297 function getPageContent(options?: ContentOptions): Promise<PageContent>; 298 299 /** 300 * Send control event 301 * 302 * @permission ohos.permission.SIMULATE_USER_INPUT 303 * @param { ControlEvent } event - Indicates the control event sent to the screen 304 * @returns { Promise<void> } the promise returned by the function. 305 * @throws { BusinessError } 201 - Permission denied. An attempt was made to get page content forbidden by 306 * <br> permission: ohos.permission.SIMULATE_USER_INPUT. 307 * @throws { BusinessError } 202 - Permission check failed. A non-system application uses the system API. 308 * @throws { BusinessError } 801 - Capability not supported. Function can not work correctly due to limited 309 * <br> device capabilities. 310 * @throws { BusinessError } 34000001 - Service exception. 311 * @throws { BusinessError } 34000005 - The target is not found. 312 * @syscap SystemCapability.MultimodalAwareness.OnScreenAwareness 313 * @systemapi 314 * @since 20 315 */ 316 function sendControlEvent(event: ControlEvent): Promise<void>; 317} 318export default onScreen;