1/* 2 * Copyright (c) 2024 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 Defines the atomicService web component 18 * @kit ArkUI 19 */ 20 21import { Callback } from '@ohos.base'; 22 23/** 24 * Declare Component AtomicServiceWeb. 25 * 26 * @struct { AtomicServiceWeb } 27 * @syscap SystemCapability.ArkUI.ArkUI.Full 28 * @atomicservice 29 * @since 12 30 */ 31@Component 32export declare struct AtomicServiceWeb { 33 /** 34 * The address of the web page to be displayed. 35 * 36 * @type { ResourceStr } 37 * @syscap SystemCapability.ArkUI.ArkUI.Full 38 * @atomicservice 39 * @since 12 40 */ 41 src: ResourceStr; 42 /** 43 * Sets the controller of the AtomicServiceWeb. 44 * 45 * @type { AtomicServiceWebController } 46 * @syscap SystemCapability.ArkUI.ArkUI.Full 47 * @atomicservice 48 * @since 12 49 */ 50 @ObjectLink 51 controller: AtomicServiceWebController; 52 /** 53 * Sets how to load HTTP and HTTPS content. 54 * 55 * @type { ?MixedMode } 56 * @syscap SystemCapability.ArkUI.ArkUI.Full 57 * @atomicservice 58 * @since 12 59 */ 60 @Prop 61 mixedMode?: MixedMode; 62 /** 63 * Sets the dark mode of Web. 64 * 65 * @type { ?WebDarkMode } 66 * @syscap SystemCapability.ArkUI.ArkUI.Full 67 * @atomicservice 68 * @since 12 69 */ 70 @Prop 71 darkMode?: WebDarkMode; 72 /** 73 * Sets whether to enable forced dark algorithm when the web is in dark mode. 74 * 75 * @type { ?boolean } 76 * @syscap SystemCapability.ArkUI.ArkUI.Full 77 * @atomicservice 78 * @since 12 79 */ 80 @Prop 81 forceDarkAccess?: boolean; 82 /** 83 * Sets the nested scroll options. 84 * 85 * @type { ?(NestedScrollOptions | NestedScrollOptionsExt) } 86 * @syscap SystemCapability.ArkUI.ArkUI.Full 87 * @atomicservice 88 * @since 15 89 */ 90 @Prop 91 nestedScroll?: NestedScrollOptions | NestedScrollOptionsExt; 92 /** 93 * The navPathStack to control page route in Navigation and NavDestination. 94 * 95 * @type { ?NavPathStack } 96 * @syscap SystemCapability.ArkUI.ArkUI.Full 97 * @atomicservice 98 * @since 12 99 */ 100 navPathStack?: NavPathStack; 101 /** 102 * The callback method to invoke after page is back or destroyed if postMessage() is called in H5 page. 103 * 104 * @type { ?Callback<OnMessageEvent> } 105 * @syscap SystemCapability.ArkUI.ArkUI.Full 106 * @atomicservice 107 * @since 12 108 */ 109 onMessage?: Callback<OnMessageEvent>; 110 /** 111 * Triggered when the web page receives a web resource loading error. 112 * 113 * @type { ?Callback<OnErrorReceiveEvent> } 114 * @syscap SystemCapability.ArkUI.ArkUI.Full 115 * @atomicservice 116 * @since 12 117 */ 118 onErrorReceive?: Callback<OnErrorReceiveEvent>; 119 /** 120 * Triggered when the web page receives a web resource loading HTTP error. 121 * 122 * @type { ?Callback<OnHttpErrorReceiveEvent> } 123 * @syscap SystemCapability.ArkUI.ArkUI.Full 124 * @atomicservice 125 * @since 12 126 */ 127 onHttpErrorReceive?: Callback<OnHttpErrorReceiveEvent>; 128 /** 129 * Triggered at the begin of web page loading. 130 * 131 * @type { ?Callback<OnPageBeginEvent> } 132 * @syscap SystemCapability.ArkUI.ArkUI.Full 133 * @atomicservice 134 * @since 12 135 */ 136 onPageBegin?: Callback<OnPageBeginEvent>; 137 /** 138 * Triggered at the end of web page loading. 139 * 140 * @type { ?Callback<OnPageEndEvent> } 141 * @syscap SystemCapability.ArkUI.ArkUI.Full 142 * @atomicservice 143 * @since 12 144 */ 145 onPageEnd?: Callback<OnPageEndEvent>; 146 /** 147 * Triggered when The controller is bound to the web component, this controller must be a WebviewController. 148 * This callback can not use the interface about manipulating web pages. 149 * 150 * @type { ?Callback<void> } 151 * @syscap SystemCapability.ArkUI.ArkUI.Full 152 * @atomicservice 153 * @since 12 154 */ 155 onControllerAttached?: Callback<void>; 156 /** 157 * Triggered when the resources loading is intercepted. 158 * 159 * @type { ?OnLoadInterceptCallback } 160 * @syscap SystemCapability.ArkUI.ArkUI.Full 161 * @atomicservice 162 * @since 12 163 */ 164 onLoadIntercept?: OnLoadInterceptCallback; 165 /** 166 * Triggered when the page loading progress changes. 167 * 168 * @type { ?Callback<OnProgressChangeEvent> } 169 * @syscap SystemCapability.ArkUI.ArkUI.Full 170 * @atomicservice 171 * @since 12 172 */ 173 onProgressChange?: Callback<OnProgressChangeEvent>; 174} 175 176/** 177 * Message event after page is back or destroyed if postMessage() is called in H5 page. 178 * 179 * @typedef OnMessageEvent 180 * @syscap SystemCapability.ArkUI.ArkUI.Full 181 * @atomicservice 182 * @since 12 183 */ 184export declare interface OnMessageEvent { 185 /** 186 * The message data list. 187 * 188 * @type { object[] } 189 * @syscap SystemCapability.ArkUI.ArkUI.Full 190 * @atomicservice 191 * @since 12 192 */ 193 data: object[]; 194} 195 196/** 197 * Error receive event when the web page receives a web resource loading error. 198 * 199 * @typedef OnErrorReceiveEvent 200 * @syscap SystemCapability.ArkUI.ArkUI.Full 201 * @atomicservice 202 * @since 12 203 */ 204export declare interface OnErrorReceiveEvent { 205 /** 206 * Web resource request of event. 207 * 208 * @type { WebResourceRequest } 209 * @syscap SystemCapability.ArkUI.ArkUI.Full 210 * @atomicservice 211 * @since 12 212 */ 213 request: WebResourceRequest; 214 215 /** 216 * Web resource error of event. 217 * 218 * @type { WebResourceError } 219 * @syscap SystemCapability.ArkUI.ArkUI.Full 220 * @atomicservice 221 * @since 12 222 */ 223 error: WebResourceError; 224} 225 226/** 227 * Http error receive event when the web page receives a web resource loading HTTP error. 228 * 229 * @typedef OnHttpErrorReceiveEvent 230 * @syscap SystemCapability.ArkUI.ArkUI.Full 231 * @atomicservice 232 * @since 12 233 */ 234export declare interface OnHttpErrorReceiveEvent { 235 /** 236 * Web resource request of event. 237 * 238 * @type { WebResourceRequest } 239 * @syscap SystemCapability.ArkUI.ArkUI.Full 240 * @atomicservice 241 * @since 12 242 */ 243 request: WebResourceRequest; 244 245 /** 246 * Web resource response of event. 247 * 248 * @type { WebResourceResponse } 249 * @syscap SystemCapability.ArkUI.ArkUI.Full 250 * @atomicservice 251 * @since 12 252 */ 253 response: WebResourceResponse; 254} 255 256/** 257 * Page begin event at the begin of web page loading. 258 * 259 * @typedef OnPageBeginEvent 260 * @syscap SystemCapability.ArkUI.ArkUI.Full 261 * @atomicservice 262 * @since 12 263 */ 264export declare interface OnPageBeginEvent { 265 /** 266 * The url of page. 267 * 268 * @type { string } 269 * @syscap SystemCapability.ArkUI.ArkUI.Full 270 * @atomicservice 271 * @since 12 272 */ 273 url: string; 274} 275 276/** 277 * Page end event at the end of web page loading. 278 * 279 * @typedef OnPageEndEvent 280 * @syscap SystemCapability.ArkUI.ArkUI.Full 281 * @atomicservice 282 * @since 12 283 */ 284export declare interface OnPageEndEvent { 285 /** 286 * The url of page. 287 * 288 * @type { string } 289 * @syscap SystemCapability.ArkUI.ArkUI.Full 290 * @atomicservice 291 * @since 12 292 */ 293 url: string; 294} 295 296/** 297 * Load intercept event when the resources loading is intercepted. 298 * 299 * @typedef OnLoadInterceptEvent 300 * @syscap SystemCapability.ArkUI.ArkUI.Full 301 * @atomicservice 302 * @since 12 303 */ 304export declare interface OnLoadInterceptEvent { 305 /** 306 * Web resource request of event. 307 * 308 * @type { WebResourceRequest } 309 * @syscap SystemCapability.ArkUI.ArkUI.Full 310 * @atomicservice 311 * @since 12 312 */ 313 data: WebResourceRequest; 314} 315 316/** 317 * Progress change event when the page loading progress changes. 318 * 319 * @typedef OnProgressChangeEvent 320 * @syscap SystemCapability.ArkUI.ArkUI.Full 321 * @atomicservice 322 * @since 12 323 */ 324export declare interface OnProgressChangeEvent { 325 /** 326 * The new progress of the page. 327 * 328 * @type { number } 329 * @syscap SystemCapability.ArkUI.ArkUI.Full 330 * @atomicservice 331 * @since 12 332 */ 333 newProgress: number; 334} 335 336/** 337 * Provides methods for controlling the AtomicServiceWeb controller. 338 * 339 * @syscap SystemCapability.ArkUI.ArkUI.Full 340 * @atomicservice 341 * @since 12 342 */ 343@Observed 344export declare class AtomicServiceWebController { 345 /** 346 * Gets the default user agent. 347 * 348 * @returns { string } Return user agent information. 349 * @throws { BusinessError } 17100001 - Init error. The AtomicServiceWebController must be associated with a 350 * AtomicServiceWeb component. 351 * @syscap SystemCapability.ArkUI.ArkUI.Full 352 * @atomicservice 353 * @since 12 354 */ 355 getUserAgent(): string; 356 357 /** 358 * Get custom user agent. 359 * 360 * @returns { string } Get custom User agent information. 361 * @throws { BusinessError } 17100001 - Init error. The AtomicServiceWebController must be associated with a 362 * AtomicServiceWeb component. 363 * @syscap SystemCapability.ArkUI.ArkUI.Full 364 * @atomicservice 365 * @since 12 366 */ 367 getCustomUserAgent(): string; 368 369 /** 370 * Set custom user agent. 371 * 372 * @param { string } userAgent - User custom agent information. 373 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 374 * <br>2. Incorrect parameter types. 375 * @throws { BusinessError } 17100001 - Init error. The AtomicServiceWebController must be associated with a 376 * AtomicServiceWeb component. 377 * @syscap SystemCapability.ArkUI.ArkUI.Full 378 * @atomicservice 379 * @since 12 380 */ 381 setCustomUserAgent(userAgent: string): void; 382 383 /** 384 * Refreshes the current URL. 385 * 386 * @throws { BusinessError } 17100001 - Init error. The AtomicServiceWebController must be associated with a 387 * AtomicServiceWeb component. 388 * @syscap SystemCapability.ArkUI.ArkUI.Full 389 * @atomicservice 390 * @since 12 391 */ 392 refresh(): void; 393 394 /** 395 * Goes forward in the history of the web page. 396 * 397 * @throws { BusinessError } 17100001 - Init error. The AtomicServiceWebController must be associated with a 398 * AtomicServiceWeb component. 399 * @syscap SystemCapability.ArkUI.ArkUI.Full 400 * @atomicservice 401 * @since 12 402 */ 403 forward(): void; 404 405 /** 406 * Goes back in the history of the web page. 407 * 408 * @throws { BusinessError } 17100001 - Init error. The AtomicServiceWebController must be associated with a 409 * AtomicServiceWeb component. 410 * @syscap SystemCapability.ArkUI.ArkUI.Full 411 * @atomicservice 412 * @since 12 413 */ 414 backward(): void; 415 416 /** 417 * Checks whether the web page can go forward. 418 * 419 * @returns { boolean } True if the web page can go forward else false. 420 * @throws { BusinessError } 17100001 - Init error. The AtomicServiceWebController must be associated with a 421 * AtomicServiceWeb component. 422 * @syscap SystemCapability.ArkUI.ArkUI.Full 423 * @atomicservice 424 * @since 12 425 */ 426 accessForward(): boolean; 427 428 /** 429 * Checks whether the web page can go back. 430 * 431 * @returns { boolean } True if the web page can go back else false. 432 * @throws { BusinessError } 17100001 - Init error. The AtomicServiceWebController must be associated with a 433 * AtomicServiceWeb component. 434 * @syscap SystemCapability.ArkUI.ArkUI.Full 435 * @atomicservice 436 * @since 12 437 */ 438 accessBackward(): boolean; 439 440 /** 441 * Checks whether the web page can go back or forward the given number of steps. 442 * 443 * @param { number } step - The number of steps. 444 * @returns { boolean } True if the web page can go back else false. 445 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 446 * <br>2. Incorrect parameter types. 3.Parameter verification failed. 447 * @throws { BusinessError } 17100001 - Init error. The AtomicServiceWebController must be associated with a 448 * AtomicServiceWeb component. 449 * @syscap SystemCapability.ArkUI.ArkUI.Full 450 * @atomicservice 451 * @since 12 452 */ 453 accessStep(step: number): boolean; 454 455 /** 456 * Loads the URL. 457 * 458 * @param { string | Resource } url - The URL to load. 459 * @param { Array<WebHeader> } [headers] - Additional HTTP request header for URL. 460 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 461 * <br>2. Incorrect parameter types. 3.Parameter verification failed. 462 * @throws { BusinessError } 17100001 - Init error. The AtomicServiceWebController must be associated with a 463 * AtomicServiceWeb component. 464 * @throws { BusinessError } 17100002 - Invalid url. 465 * @throws { BusinessError } 17100003 - Invalid resource path or file type. 466 * @syscap SystemCapability.ArkUI.ArkUI.Full 467 * @atomicservice 468 * @since 12 469 */ 470 loadUrl(url: string | Resource, headers?: Array<WebHeader>): void; 471} 472 473/** 474 * Defines the Web's request/response header. 475 * 476 * @typedef WebHeader 477 * @syscap SystemCapability.ArkUI.ArkUI.Full 478 * @atomicservice 479 * @since 12 480 */ 481export declare interface WebHeader { 482 /** 483 * Gets the key of the request/response header. 484 * 485 * @type { string } 486 * @syscap SystemCapability.ArkUI.ArkUI.Full 487 * @atomicservice 488 * @since 12 489 */ 490 headerKey: string; 491 492 /** 493 * Gets the value of the request/response header. 494 * 495 * @type { string } 496 * @syscap SystemCapability.ArkUI.ArkUI.Full 497 * @atomicservice 498 * @since 12 499 */ 500 headerValue: string; 501} 502 503/** 504 * Callback for OnLoadIntercept 505 * 506 * @typedef { function } OnLoadIntercept Function. 507 * @param { OnLoadInterceptEvent } event - the load intercept event when the resources loading is intercepted. 508 * @returns { boolean } True if the load is intercepted else false. 509 * @syscap SystemCapability.ArkUI.ArkUI.Full 510 * @atomicservice 511 * @since 12 512 */ 513export type OnLoadInterceptCallback = (event: OnLoadInterceptEvent) => boolean; 514