1# @ohos.screen (屏幕)(系统接口) 2<!--Kit: ArkUI--> 3<!--Subsystem: Window--> 4<!--Owner: @oh_wangxk; @logn--> 5<!--Designer: @hejunfei1991--> 6<!--Tester: @qinliwen0417--> 7<!--Adviser: @ge-yafang--> 8 9本模块提供管理屏幕的一些基础能力，包括获取屏幕对象，监听屏幕变化，创建和销毁虚拟屏幕等。 10 11> **说明：** 12> 13> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 15> - 本模块接口为系统接口。 16 17## 导入模块 18 19```ts 20import { screen } from '@kit.ArkUI'; 21``` 22 23## screen.getAllScreens 24 25getAllScreens(callback: AsyncCallback<Array<Screen>>): void 26 27获取所有的屏幕，使用callback异步回调。 28 29**系统能力：** SystemCapability.WindowManager.WindowManager.Core 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| -------- | --------------------------------------------------- | ---- | -------------------------------------- | 35| callback | AsyncCallback<Array<[Screen](#screen)>> | 是 | 回调函数。返回当前获取的屏幕对象集合。 | 36 37**错误码：** 38 39以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 40 41| 错误码ID | 错误信息 | 42| ------- | ----------------------- | 43| 202 | Permission verification failed. A non-system application calls a system API.| 44| 1400001 | Invalid display or screen. | 45 46**示例：** 47 48```ts 49import { BusinessError } from '@kit.BasicServicesKit'; 50 51let screenClass: screen.Screen | null = null; 52screen.getAllScreens((err: BusinessError, data: Array<screen.Screen>) => { 53 const errCode: number = err.code; 54 if (errCode) { 55 console.error(`Failed to get all screens. Code:${err.code},message is ${err.message}`); 56 return; 57 } 58 console.info('Succeeded in getting all screens. Data:' + JSON.stringify(data)); 59 if(data.length > 0 ）{ 60 screenClass = data[0]; 61 } 62}); 63``` 64 65## screen.getAllScreens 66 67getAllScreens(): Promise<Array<Screen>> 68 69获取所有的屏幕，使用Promise异步回调。 70 71**系统能力：** SystemCapability.WindowManager.WindowManager.Core 72 73**返回值：** 74 75| 类型 | 说明 | 76| --------------------------------------------- | ----------------------------------------- | 77| Promise<Array<[Screen](#screen)>> | Promise对象。返回当前获取的屏幕对象集合。 | 78 79**错误码：** 80 81以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 82 83| 错误码ID | 错误信息 | 84| ------- | ----------------------- | 85| 202 | Permission verification failed. A non-system application calls a system API.| 86| 1400001 | Invalid display or screen. | 87 88**示例：** 89 90```ts 91import { BusinessError } from '@kit.BasicServicesKit'; 92 93let screenClass: screen.Screen | null = null; 94let promise: Promise<Array<screen.Screen>> = screen.getAllScreens(); 95promise.then((data: Array<screen.Screen>) => { 96 if(data.length > 0){ 97 screenClass = data[0]; 98 } 99 console.log('Succeeded in getting all screens. Data:' + JSON.stringify(data)); 100}).catch((err: BusinessError) => { 101 console.log('Failed to get all screens. Cause: ' + JSON.stringify(err)); 102}); 103``` 104 105## screen.on('connect' | 'disconnect' | 'change') 106 107on(eventType: 'connect' | 'disconnect' | 'change', callback: Callback<number>): void 108 109开启屏幕状态变化的监听。 110 111**系统能力：** SystemCapability.WindowManager.WindowManager.Core 112 113**参数：** 114 115| 参数名 | 类型 | 必填 | 说明 | 116| --------- | ---------------------- | ---- | ----------------------------------------------------------- | 117| eventType | string | 是 | 监听事件。<br/>-eventType为"connect"表示屏幕连接事件。<br/>-eventType为"disconnect"表示断开屏幕连接事件。<br/>-eventType为"change"表示屏幕状态改变事件。 | 118| callback | Callback<number> | 是 | 回调函数。返回屏幕的id，该参数为整数。 | 119 120**错误码：** 121 122以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 123 124| 错误码ID | 错误信息 | 125| ------- | ----------------------- | 126| 202 | Permission verification failed. A non-system application calls a system API.| 127| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 128 129**示例：** 130 131```ts 132let callback: Callback<number> = (data: number) => { 133 console.info('Succeeded in registering the callback for screen changes. Data: ' + JSON.stringify(data)) 134}; 135screen.on('connect', callback); 136``` 137 138## screen.off('connect' | 'disconnect' | 'change') 139 140off(eventType: 'connect' | 'disconnect' | 'change', callback?: Callback<number>): void 141 142关闭屏幕状态变化的监听。 143 144**系统能力：** SystemCapability.WindowManager.WindowManager.Core 145 146**参数：** 147 148| 参数名 | 类型 | 必填 | 说明 | 149| --------- | ---------------------- | ---- | ------------------------------------------------------------ | 150| eventType | string | 是 | 监听事件。<br/>-eventType为"connect"表示屏幕连接事件。<br/>-eventType为"disconnect"表示断开屏幕连接事件。<br/>-eventType为"change"表示屏幕状态改变事件。 | 151| callback | Callback<number> | 否 | 回调函数。返回屏幕的id，该参数为整数。 | 152 153**错误码：** 154 155以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 156 157| 错误码ID | 错误信息 | 158| ------- | ----------------------- | 159| 202 | Permission verification failed. A non-system application calls a system API.| 160| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 161 162**示例：** 163 164```ts 165let callback: Callback<number> = (data: number) => { 166 console.info('Succeeded in unregistering the callback for screen changes. Data: ' + JSON.stringify(data)) 167}; 168screen.off('connect', callback); 169screen.off('connect'); 170``` 171 172## screen.makeMirror 173 174makeMirror(mainScreen:number, mirrorScreen:Array<number>, callback: AsyncCallback<number>): void 175 176将屏幕设置为镜像模式，使用callback异步回调。 177 178**系统能力：** SystemCapability.WindowManager.WindowManager.Core 179 180**参数：** 181 182| 参数名 | 类型 | 必填 | 说明 | 183| ------------ | --------------------------- | ---- |--------------------| 184| mainScreen | number | 是 | 主屏幕id，该参数仅支持整数输入。 | 185| mirrorScreen | Array<number> | 是 | 镜像屏幕id集合，其中id应为整数。 | 186| callback | AsyncCallback<number> | 是 | 回调函数。返回镜像屏幕的群组id，其中id为整数。 | 187 188**错误码：** 189 190以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 191 192| 错误码ID | 错误信息 | 193| ------- | ----------------------- | 194| 202 | Permission verification failed. A non-system application calls a system API.| 195| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 196| 1400001 | Invalid display or screen. | 197 198**示例：** 199 200```ts 201import { BusinessError } from '@kit.BasicServicesKit'; 202 203let mainScreenId: number = 0; 204let mirrorScreenIds: Array<number> = [1, 2, 3]; 205screen.makeMirror(mainScreenId, mirrorScreenIds, (err: BusinessError, data: number) => { 206 const errCode: number = err.code; 207 if (errCode) { 208 console.error(`Failed to set screen mirroring. Code:${err.code},message is ${err.message}`); 209 return; 210 } 211 console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data)); 212}); 213``` 214 215## screen.makeMirror 216 217makeMirror(mainScreen:number, mirrorScreen:Array<number>): Promise<number> 218 219将屏幕设置为镜像模式，使用Promise异步回调。 220 221**系统能力：** SystemCapability.WindowManager.WindowManager.Core 222 223**参数：** 224 225| 参数名 | 类型 | 必填 | 说明 | 226| ------------ | ------------------- | ---- |--------------------| 227| mainScreen | number | 是 | 主屏幕id，该参数仅支持整数输入。 | 228| mirrorScreen | Array<number> | 是 | 镜像屏幕id集合。其中id应为整数。 | 229 230**返回值：** 231 232| 类型 | 说明 | 233| --------------------- |---------------------------------| 234| Promise<number> | Promise对象。返回镜像屏幕的群组id，其中id为整数。 | 235 236**错误码：** 237 238以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 239 240| 错误码ID | 错误信息 | 241| ------- | ----------------------- | 242| 202 | Permission verification failed. A non-system application calls a system API.| 243| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 244| 1400001 | Invalid display or screen. | 245 246**示例：** 247 248```ts 249import { BusinessError } from '@kit.BasicServicesKit'; 250 251let mainScreenId: number = 0; 252let mirrorScreenIds: Array<number> = [1, 2, 3]; 253screen.makeMirror(mainScreenId, mirrorScreenIds).then((data: number) => { 254 console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data)); 255}).catch((err: BusinessError) => { 256 console.error(`Failed to set screen mirroring. Code:${err.code},message is ${err.message}`); 257}); 258``` 259 260## screen.stopMirror<sup>10+</sup> 261 262stopMirror(mirrorScreen:Array<number>, callback: AsyncCallback<void>): void 263 264停止屏幕的镜像模式，使用callback异步回调。 265 266**系统能力：** SystemCapability.WindowManager.WindowManager.Core 267 268**参数：** 269 270| 参数名 | 类型 | 必填 | 说明 | 271| ------------ | --------------------------- | --- |-----------------------------------------| 272| mirrorScreen | Array<number> | 是 | 镜像屏幕id集合，其中id应为整数。 mirrorScreen数组大小不应超过1000。 | 273| callback | AsyncCallback<void> | 是 | 回调函数。当停止屏幕镜像模式成功，err为undefined，否则为错误对象。 | 274 275**错误码：** 276 277以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 278 279| 错误码ID | 错误信息 | 280| ------- | ----------------------- | 281| 202 | Permission verification failed. A non-system application calls a system API.| 282| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 283| 1400001 | Invalid display or screen. | 284 285**示例：** 286 287```ts 288import { BusinessError } from '@kit.BasicServicesKit'; 289 290let mirrorScreenIds: Array<number> = [1, 2, 3]; 291screen.stopMirror(mirrorScreenIds, (err: BusinessError) => { 292 const errCode: number = err.code; 293 if (errCode) { 294 console.error(`Failed to stop mirror screens. Code:${err.code},message is ${err.message}`); 295 return; 296 } 297 console.info('Succeeded in stopping mirror screens.'); 298}); 299``` 300 301## screen.stopMirror<sup>10+</sup> 302 303stopMirror(mirrorScreen:Array<number>): Promise<void> 304 305停止屏幕的镜像模式，使用Promise异步回调。 306 307**系统能力：** SystemCapability.WindowManager.WindowManager.Core 308 309**参数：** 310 311| 参数名 | 类型 | 必填 | 说明 | 312| ------------ | ------------------- | --- |--------------------| 313| mirrorScreen | Array<number> | 是 | 镜像屏幕id集合，其中id应为整数。mirrorScreen数组大小不应超过1000。 | 314 315**返回值：** 316 317| 类型 | 说明 | 318| --------------------- | ----------------------- | 319| Promise<void> | 无返回结果的Promise对象。 | 320 321**错误码：** 322 323以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 324 325| 错误码ID | 错误信息 | 326| ------- | ----------------------- | 327| 202 | Permission verification failed. A non-system application calls a system API.| 328| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 329| 1400001 | Invalid display or screen. | 330 331**示例：** 332 333```ts 334import { BusinessError } from '@kit.BasicServicesKit'; 335 336let mirrorScreenIds: Array<number> = [1, 2, 3]; 337screen.stopMirror(mirrorScreenIds).then(() => { 338 console.info('Succeeded in stopping mirror screens.'); 339}).catch((err: BusinessError) => { 340 console.error(`Failed to stop mirror screens.Code:${err.code},message is ${err.message}`); 341}); 342``` 343 344## screen.makeUnique<sup>18+</sup> 345 346makeUnique(uniqueScreen: Array<number>): Promise<Array<number>> 347 348将屏幕设置为异源模式，使用Promise异步回调。 349 350**系统能力：** SystemCapability.Window.SessionManager 351 352**参数：** 353 354| 参数名 | 类型 | 必填 | 说明 | 355| --------- | ------ | ---- | ------------- | 356| uniqueScreen | Array<number> | 是 | 异源屏幕id集合。其中id应为大于0的整数，否则返回401错误码。 | 357 358**返回值：** 359 360| 类型 | 说明 | 361| ------------------- | ------------------------- | 362| Promise<Array<number>> | Promise对象。返回异源屏幕的displayId集合，其中id为大于0的整数。| 363 364**错误码：** 365 366以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 367 368| 错误码ID | 错误信息 | 369| ------- | ----------------------- | 370| 202 | Permission verification failed, non-system application uses system API. | 371| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 372| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 373| 1400001 | Invalid display or screen. | 374| 1400003 | This display manager service works abnormally. | 375 376**示例：** 377 378```ts 379import { BusinessError } from '@kit.BasicServicesKit'; 380 381let uniqueScreenIds: Array<number> = [1001, 1002, 1003]; 382screen.makeUnique(uniqueScreenIds).then((data: Array<number>) => { 383 console.info('Succeeded in making unique screens.'); 384}).catch((err: BusinessError) => { 385 console.error(`Failed to make unique screens. Code:${err.code},message is ${err.message}`); 386}); 387``` 388 389## screen.createVirtualScreen 390 391createVirtualScreen(options:VirtualScreenOption, callback: AsyncCallback<Screen>): void 392 393创建虚拟屏幕，使用callback异步回调。 394 395**系统能力：** SystemCapability.WindowManager.WindowManager.Core 396 397**需要权限**：ohos.permission.CAPTURE_SCREEN 398 399**参数：** 400 401| 参数名 | 类型 | 必填 | 说明 | 402| -------- | ------------------------------------------- | ---- | ---------------------------------- | 403| options | [VirtualScreenOption](#virtualscreenoption) | 是 | 用于创建虚拟屏幕的参数。 | 404| callback | AsyncCallback<[Screen](#screen)> | 是 | 回调函数，返回创建的虚拟屏幕对象。 | 405 406**错误码：** 407 408以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 409 410| 错误码ID | 错误信息 | 411| ------- | ----------------------- | 412| 201 | Permission verification failed. The application does not have the permission required to call the API. | 413| 202 | Permission verification failed. A non-system application calls a system API.| 414| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 415| 1400001 | Invalid display or screen. | 416 417**示例：** 418 419```ts 420import { BusinessError } from '@kit.BasicServicesKit'; 421 422let screenClass: screen.Screen | null = null; 423class VirtualScreenOption { 424 name : string = ''; 425 width : number = 0; 426 height : number = 0; 427 density : number = 0; 428 surfaceId : string = ''; 429} 430 431let option : VirtualScreenOption = { 432 name: 'screen01', 433 width: 1080, 434 height: 2340, 435 density: 2, 436 surfaceId: '' 437}; 438screen.createVirtualScreen(option, (err: BusinessError, data: screen.Screen) => { 439 const errCode: number = err.code; 440 if (errCode) { 441 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 442 return; 443 } 444 screenClass = data; 445 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 446}); 447``` 448 449## screen.createVirtualScreen 450 451createVirtualScreen(options:VirtualScreenOption): Promise<Screen> 452 453创建虚拟屏幕，使用Promise异步回调。 454 455**系统能力：** SystemCapability.WindowManager.WindowManager.Core 456 457**需要权限**：ohos.permission.CAPTURE_SCREEN 458 459**参数：** 460 461| 参数名 | 类型 | 必填 | 说明 | 462| ------- | ------------------------------------------- | ---- | ------------------------ | 463| options | [VirtualScreenOption](#virtualscreenoption) | 是 | 用于创建虚拟屏幕的参数。 | 464 465**返回值：** 466 467| 类型 | 说明 | 468| -------------------------------- | ------------------------------------- | 469| Promise<[Screen](#screen)> | Promise对象。返回创建的虚拟屏幕对象。 | 470 471**错误码：** 472 473以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 474 475| 错误码ID | 错误信息 | 476| ------- | ----------------------- | 477| 201 | Permission verification failed. The application does not have the permission required to call the API. | 478| 202 | Permission verification failed. A non-system application calls a system API.| 479| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 480| 1400001 | Invalid display or screen. | 481 482**示例：** 483 484```ts 485import { BusinessError } from '@kit.BasicServicesKit'; 486 487let screenClass: screen.Screen | null = null; 488class VirtualScreenOption { 489 name : string = ''; 490 width : number = 0; 491 height : number = 0; 492 density : number = 0; 493 surfaceId : string = ''; 494} 495 496let option : VirtualScreenOption = { 497 name: 'screen01', 498 width: 1080, 499 height: 2340, 500 density: 2, 501 surfaceId: '' 502}; 503 504screen.createVirtualScreen(option).then((data: screen.Screen) => { 505 screenClass = data; 506 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 507}).catch((err: BusinessError) => { 508 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 509}); 510``` 511 512## screen.destroyVirtualScreen 513 514destroyVirtualScreen(screenId:number, callback: AsyncCallback<void>): void 515 516销毁虚拟屏幕，使用callback异步回调。 517 518**系统能力：** SystemCapability.WindowManager.WindowManager.Core 519 520**参数：** 521 522| 参数名 | 类型 | 必填 | 说明 | 523| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 524| screenId | number | 是 | 屏幕的id，该参数仅支持整数输入。 | 525| callback | AsyncCallback<void> | 是 | 回调函数。当销毁虚拟屏幕成功，err为undefined，否则为错误对象。 | 526 527**错误码：** 528 529以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 530 531| 错误码ID | 错误信息 | 532| ------- | ----------------------------- | 533| 202 | Permission verification failed. A non-system application calls a system API.| 534| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 535| 1400002 | Unauthorized operation. | 536 537**示例：** 538 539```ts 540import { BusinessError } from '@kit.BasicServicesKit'; 541 542let screenId: number = 1; 543screen.destroyVirtualScreen(screenId, (err: BusinessError) => { 544 const errCode: number = err.code; 545 if (errCode) { 546 console.error(`Failed to destroy the virtual screen. Code:${err.code},message is ${err.message}`); 547 return; 548 } 549 console.info('Succeeded in destroying the virtual screen.'); 550}); 551``` 552 553## screen.destroyVirtualScreen 554 555destroyVirtualScreen(screenId:number): Promise<void> 556 557销毁虚拟屏幕，使用Promise异步回调。 558 559**系统能力：** SystemCapability.WindowManager.WindowManager.Core 560 561**参数：** 562 563| 参数名 | 类型 | 必填 | 说明 | 564| -------- | ------ | ---- | ---------- | 565| screenId | number | 是 | 屏幕的id，该参数仅支持整数输入。 | 566 567**返回值：** 568 569| 类型 | 说明 | 570| ------------------- | ------------------------- | 571| Promise<void> | 无返回结果的Promise对象。 | 572 573**错误码：** 574 575以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 576 577| 错误码ID | 错误信息 | 578| ------- | ----------------------------- | 579| 202 | Permission verification failed. A non-system application calls a system API.| 580| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 581| 1400002 | Unauthorized operation. | 582 583**示例：** 584 585```ts 586import { BusinessError } from '@kit.BasicServicesKit'; 587 588let screenId: number = 1; 589screen.destroyVirtualScreen(screenId).then(() => { 590 console.info('Succeeded in destroying the virtual screen.'); 591}).catch((err: BusinessError) => { 592 console.error(`Failed to destroy the virtual screen.Code:${err.code},message is ${err.message}`); 593}); 594``` 595 596## screen.setVirtualScreenSurface 597 598setVirtualScreenSurface(screenId:number, surfaceId: string, callback: AsyncCallback<void>): void 599 600设置虚拟屏幕的surface，使用callback异步回调。 601 602**系统能力：** SystemCapability.WindowManager.WindowManager.Core 603 604**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。 605 606**参数：** 607 608| 参数名 | 类型 | 必填 | 说明 | 609| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 610| screenId | number | 是 | 屏幕的id，该参数仅支持整数输入。 | 611| surfaceId | string | 是 | 代表虚拟屏幕的surface标识符，surfaceId值可自行定义。 | 612| callback | AsyncCallback<void> | 是 | 回调函数。当设置虚拟屏幕surface成功，err为undefined，否则为错误对象。 | 613 614**错误码：** 615 616以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 617 618| 错误码ID | 错误信息 | 619| ------- | ----------------------- | 620| 201 | Permission verification failed. The application does not have the permission required to call the API. | 621| 202 | Permission verification failed. A non-system application calls a system API.| 622| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 623| 1400001 | Invalid display or screen. | 624 625**示例：** 626 627```ts 628import { BusinessError } from '@kit.BasicServicesKit'; 629 630let screenId: number = 1; 631let surfaceId: string = '2048'; 632screen.setVirtualScreenSurface(screenId, surfaceId, (err: BusinessError) => { 633 const errCode: number = err.code; 634 if (errCode) { 635 console.error(`Failed to set the surface for the virtual screen. Code:${err.code},message is ${err.message}`); 636 return; 637 } 638 console.info('Succeeded in setting the surface for the virtual screen.'); 639}); 640``` 641 642## screen.setVirtualScreenSurface 643 644setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void> 645 646设置虚拟屏幕的surface，使用Promise异步回调。 647 648**系统能力：** SystemCapability.WindowManager.WindowManager.Core 649 650**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。 651 652**参数：** 653 654| 参数名 | 类型 | 必填 | 说明 | 655| --------- | ------ | ---- | ------------- | 656| screenId | number | 是 | 屏幕的id，该参数仅支持整数输入。 | 657| surfaceId | string | 是 | 代表虚拟屏幕的surface标识符，surfaceId值可自行定义。 | 658 659**返回值：** 660 661| 类型 | 说明 | 662| ------------------- | ------------------------- | 663| Promise<void> | 无返回结果的Promise对象。 | 664 665**错误码：** 666 667以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 668 669| 错误码ID | 错误信息 | 670| ------- | ----------------------- | 671| 201 | Permission verification failed. The application does not have the permission required to call the API. | 672| 202 | Permission verification failed. A non-system application calls a system API.| 673| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 674| 1400001 | Invalid display or screen. | 675 676**示例：** 677 678```ts 679import { BusinessError } from '@kit.BasicServicesKit'; 680 681let screenId: number = 1; 682let surfaceId: string = '2048'; 683screen.setVirtualScreenSurface(screenId, surfaceId).then(() => { 684 console.info('Succeeded in setting the surface for the virtual screen.'); 685}).catch((err: BusinessError) => { 686 console.error(`Failed to set the surface for the virtual screen. Code:${err.code},message is ${err.message}`); 687}); 688``` 689 690## screen.setScreenPrivacyMaskImage<sup>19+</sup> 691 692setScreenPrivacyMaskImage(screenId:number, image?: image.PixelMap): Promise<void> 693 694设置屏幕的隐私蒙版图片，使用Promise异步回调。 695 696**系统能力：** SystemCapability.Window.SessionManager 697 698**参数：** 699 700| 参数名 | 类型 | 必填 | 说明 | 701| --------- | ------ | ---- | ------------- | 702| screenId | number | 是 | 屏幕的id，该参数仅支持正整数输入。 | 703| image | [image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md) | 否 | 屏幕的隐私蒙版图片，不传入则使用默认隐私蒙版图片。 | 704 705**返回值：** 706 707| 类型 | 说明 | 708| ------------------- | ------------------------- | 709| Promise<void> | 无返回结果的Promise对象。 | 710 711**错误码：** 712 713以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 714 715| 错误码ID | 错误信息 | 716| ------- | ----------------------- | 717| 202 | Permission verification failed. A non-system application calls a system API.| 718| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 719| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 720| 1400001 | Invalid display or screen. | 721| 1400003 | This display manager service works abnormally. | 722 723**示例：** 724 725```ts 726import { BusinessError } from '@kit.BasicServicesKit'; 727import { image } from '@kit.ImageKit'; 728 729const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4 730let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 731image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 732 console.info('Succeeded in creating pixelmap.'); 733 let screenId: number = 1; 734 screen.setScreenPrivacyMaskImage(screenId, pixelMap).then(() => { 735 console.info('Succeeded in setting the privacy mask image for the screen.'); 736 }).catch((err: BusinessError) => { 737 console.error(`Failed to set the privacy mask image for the screen. Code:${err.code},message is ${err.message}`); 738 }); 739}).catch((error: BusinessError) => { 740 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 741}) 742``` 743 744## screen.isScreenRotationLocked 745 746isScreenRotationLocked(): Promise<boolean> 747 748查询当前自动转屏是否锁定，使用Promise异步回调。 749 750**系统能力：** SystemCapability.WindowManager.WindowManager.Core 751 752**返回值：** 753 754| 类型 | 说明 | 755| ---------------------- | ------------------------------------- | 756| Promise<boolean> | Promise对象。返回true表示当前自动转屏处于锁定状态；返回false表示当前自动转屏不处于锁定状态。 | 757 758**错误码：** 759 760以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 761 762| 错误码ID | 错误信息 | 763| ------- | ----------------------- | 764| 202 | Permission verification failed. A non-system application calls a system API.| 765 766**示例：** 767 768```ts 769import { BusinessError } from '@kit.BasicServicesKit'; 770 771screen.isScreenRotationLocked().then((isLocked: boolean) => { 772 console.info('Succeeded in getting the screen rotation lock status. isLocked:' + JSON.stringify(isLocked)); 773}).catch((err: BusinessError) => { 774 console.error(`Failed to get the screen rotation lock status. Code:${err.code},message is ${err.message}`); 775}); 776``` 777 778## screen.isScreenRotationLocked 779 780isScreenRotationLocked(callback: AsyncCallback<boolean>): void 781 782查询当前自动转屏是否锁定，使用callback异步回调。 783 784**系统能力：** SystemCapability.WindowManager.WindowManager.Core 785 786**参数：** 787 788| 参数名 | 类型 | 必填 | 说明 | 789| --------- | ---------------------------- | ---- | ------------------------------------------------------------ | 790| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前自动转屏处于锁定状态；返回false表示当前自动转屏不处于锁定状态。 | 791 792**错误码：** 793 794以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 795 796| 错误码ID | 错误信息 | 797| ------- | ----------------------- | 798| 202 | Permission verification failed. A non-system application calls a system API.| 799 800**示例：** 801 802```ts 803import { BusinessError } from '@kit.BasicServicesKit'; 804 805screen.isScreenRotationLocked((err: BusinessError, isLocked: boolean) => { 806const errCode: number = err.code; 807if (errCode) { 808 console.error(`Failed to get the screen rotation lock status. Code:${err.code},message is ${err.message}`); 809 return; 810} 811console.info('Succeeded in getting the screen rotation lock status. isLocked:' + JSON.stringify(isLocked)); 812}); 813``` 814 815## screen.setScreenRotationLocked 816 817setScreenRotationLocked(isLocked: boolean): Promise<void> 818 819设置自动转屏开关是否锁定，使用Promise异步回调，不适用于2in1设备。 820 821**系统能力：** SystemCapability.WindowManager.WindowManager.Core 822 823**参数：** 824 825| 参数名 | 类型 | 必填 | 说明 | 826| --------- | ------ | ---- | ------------- | 827| isLocked | boolean | 是 | 自动转屏开关是否锁定。true为锁定，false为未锁定。 | 828 829**返回值：** 830 831| 类型 | 说明 | 832| ------------------- | ------------------------- | 833| Promise<void> | 无返回结果的Promise对象。 | 834 835**错误码：** 836 837以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 838 839| 错误码ID | 错误信息 | 840| ------- | ----------------------- | 841| 202 | Permission verification failed. A non-system application calls a system API.| 842| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 843 844**示例：** 845 846```ts 847import { BusinessError } from '@kit.BasicServicesKit'; 848 849let isLocked: boolean = false; 850screen.setScreenRotationLocked(isLocked).then(() => { 851 console.info('Succeeded in unlocking auto rotate'); 852}).catch((err: BusinessError) => { 853 console.error(`Failed to unlock auto rotate. Code:${err.code},message is ${err.message}`); 854}); 855``` 856 857## screen.setScreenRotationLocked 858 859setScreenRotationLocked(isLocked: boolean, callback: AsyncCallback<void>): void 860 861设置自动转屏开关是否锁定，使用callback异步回调，不适用于2in1设备。 862 863**系统能力：** SystemCapability.WindowManager.WindowManager.Core 864 865**参数：** 866 867| 参数名 | 类型 | 必填 | 说明 | 868| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 869| isLocked | boolean | 是 | 自动转屏开关是否锁定。true为锁定，false为未锁定。 | 870| callback | AsyncCallback<void> | 是 | 回调函数。当设置自动转屏是否锁定成功，err为undefined，否则为错误对象。 | 871 872**错误码：** 873 874以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 875 876| 错误码ID | 错误信息 | 877| ------- | ----------------------- | 878| 202 | Permission verification failed. A non-system application calls a system API.| 879| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 880 881**示例：** 882 883```ts 884import { BusinessError } from '@kit.BasicServicesKit'; 885 886let isLocked: boolean = false; 887screen.setScreenRotationLocked(isLocked, (err: BusinessError) => { 888 const errCode: number = err.code; 889 if (errCode) { 890 console.error(`Failed to unlock auto rotate. Code:${err.code},message is ${err.message}`); 891 return; 892 } 893 console.info('Succeeded in unlocking auto rotate.'); 894}); 895``` 896 897## screen.setMultiScreenMode<sup>13+</sup> 898 899setMultiScreenMode(primaryScreenId: number, secondaryScreenId: number, secondaryScreenMode: MultiScreenMode): Promise<void> 900 901设置扩展屏幕的显示模式（镜像/扩展），使用Promise异步回调。 902 903**系统能力：** SystemCapability.WindowManager.WindowManager.Core 904 905**参数：** 906 907| 参数名 | 类型 | 必填 | 说明 | 908| ------------ | ------------------- | ---- |--------------------| 909| primaryScreenId | number | 是 | 主屏的id，该参数应为正整数。 | 910| secondaryScreenId | number | 是 | 扩展屏幕的id，该参数应为正整数。| 911| secondaryScreenMode | [MultiScreenMode](#multiscreenmode13) | 是 | 扩展屏幕的显示模式。| 912 913**返回值：** 914 915| 类型 | 说明 | 916| ------------------- | ------------------------- | 917| Promise<void> | 无返回结果的Promise对象。 | 918 919**错误码：** 920 921以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 922 923| 错误码ID | 错误信息 | 924| ------- | -------------------------------------------- | 925| 202 | Permission verification failed, non-system application uses system API. | 926| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 927| 1400003 | This display manager service works abnormally. | 928 929**示例：** 930 931```ts 932import { BusinessError } from '@kit.BasicServicesKit'; 933 934let primaryScreenId: number = 0; 935let secondaryScreenId: number = 12; 936let screenMode: screen.MultiScreenMode = screen.MultiScreenMode.SCREEN_MIRROR; 937screen.setMultiScreenMode(primaryScreenId, secondaryScreenId, screenMode).then(() => { 938 console.info('Succeeded in setting multi screen mode. Data: '); 939}).catch((err: BusinessError) => { 940 console.error(`Failed to set multi screen mode. Code:${err.code},message is ${err.message}`); 941}); 942``` 943 944## screen.setMultiScreenRelativePosition<sup>13+</sup> 945 946setMultiScreenRelativePosition(mainScreenOptions: MultiScreenPositionOptions, secondaryScreenOptions: MultiScreenPositionOptions): Promise<void> 947 948仅在扩展模式下，设置主屏和扩展屏幕的位置信息，使用Promise异步回调。 949 950**系统能力：** SystemCapability.WindowManager.WindowManager.Core 951 952**参数：** 953 954| 参数名 | 类型 | 必填 | 说明 | 955| ------------ | ------------------- | ---- |--------------------| 956| mainScreenOptions | [MultiScreenPositionOptions](#multiscreenpositionoptions13) | 是 | 主屏的位置信息。| 957| secondaryScreenOptions | [MultiScreenPositionOptions](#multiscreenpositionoptions13) | 是 | 扩展屏幕的位置信息。| 958 959**返回值：** 960 961| 类型 | 说明 | 962| ------------------- | ------------------------- | 963| Promise<void> | 无返回结果的Promise对象。 | 964 965**错误码：** 966 967以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 968 969| 错误码ID | 错误信息 | 970| ------- | -------------------------------------------- | 971| 202 | Permission verification failed, non-system application uses system API. | 972| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 973| 1400003 | This display manager service works abnormally. | 974 975**示例：** 976 977```ts 978import { BusinessError } from '@kit.BasicServicesKit'; 979 980let mainScreenOptions: screen.MultiScreenPositionOptions = { 981 id : 0, 982 startX : 0, 983 startY : 0 984}; 985 986let secondaryScreenOptions: screen.MultiScreenPositionOptions = { 987 id : 12, 988 startX : 1000, 989 startY : 1000 990}; 991 992screen.setMultiScreenRelativePosition(mainScreenOptions, secondaryScreenOptions).then(() => { 993 console.info('Succeeded in setting multi screen relative position. Data: '); 994}).catch((err: BusinessError) => { 995 console.error(`Failed to set multi screen relative position. Code:${err.code},message is ${err.message}`); 996}); 997``` 998 999## screen.makeMirrorWithRegion<sup>19+</sup> 1000 1001makeMirrorWithRegion(mainScreen:number, mirrorScreen:Array<number>, mainScreenRegion:Rect): Promise<number> 1002 1003将屏幕的某一矩形区域设置为镜像模式，使用Promise异步回调。调用该接口后，不建议再进行屏幕的旋转/折叠，否则可能导致镜像内容异常。 1004 1005**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1006 1007**参数：** 1008 1009| 参数名 | 类型 | 必填 | 说明 | 1010| ------------ | ------------------- | ---- |--------------------| 1011| mainScreen | number | 是 | 主屏幕id，该参数仅支持正整数输入。 | 1012| mirrorScreen | Array<number> | 是 | 镜像屏幕id集合。其中id应为正整数。 | 1013| mainScreenRegion | [Rect](#rect19) | 是 | 主屏创建镜像的矩形区域。 | 1014 1015**返回值：** 1016 1017| 类型 | 说明 | 1018| --------------------- |---------------------------------| 1019| Promise<number> | Promise对象。返回镜像屏幕的群组id，其中id为正整数。 | 1020 1021**错误码：** 1022 1023以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1024 1025| 错误码ID | 错误信息 | 1026| ------- | ----------------------- | 1027| 202 | Permission verification failed. A non-system application calls a system API.| 1028| 1400001 | Invalid display or screen. | 1029 1030**示例：** 1031 1032```ts 1033import { BusinessError } from '@kit.BasicServicesKit'; 1034 1035let mainScreenId: number = 0; 1036let mirrorScreenIds: Array<number> = [1, 2, 3]; 1037let mainScreenRegion: screen.Rect = { 1038 left : 0, 1039 top : 0, 1040 width : 1920, 1041 height : 1080 1042}; 1043screen.makeMirrorWithRegion(mainScreenId, mirrorScreenIds, mainScreenRegion).then((data: number) => { 1044 console.info(`Succeeded in setting screen mirroring. Data: ${JSON.stringify(data)}`); 1045}).catch((err: BusinessError) => { 1046 console.error(`Failed to set screen area mirroring. Code:${err.code},message is ${err.message}`); 1047}); 1048``` 1049 1050## screen.makeExpand<sup>(deprecated)</sup> 1051 1052makeExpand(options:Array<ExpandOption>, callback: AsyncCallback<number>): void 1053 1054将屏幕设置为扩展模式，使用callback异步回调。 1055 1056> **说明：** 1057> 1058> 从API version 9开始支持，从API version 20开始废弃。 1059 1060**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1061 1062**参数：** 1063 1064| 参数名 | 类型 | 必填 | 说明 | 1065| -------- | ------------------------------------------ | ---- |----------------------------| 1066| options | Array<[ExpandOption](#expandoption)> | 是 | 设置扩展屏幕的参数集合。 | 1067| callback | AsyncCallback<number> | 是 | 回调函数。返回扩展屏幕的群组id，其中id为整数。 | 1068 1069**错误码：** 1070 1071以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1072 1073| 错误码ID | 错误信息 | 1074| ------- | ----------------------- | 1075| 202 | Permission verification failed. A non-system application calls a system API.| 1076| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1077| 1400001 | Invalid display or screen. | 1078 1079**示例：** 1080 1081```ts 1082import { BusinessError } from '@kit.BasicServicesKit'; 1083 1084let groupId: number | null = null; 1085class ExpandOption { 1086 screenId: number = 0; 1087 startX: number = 0; 1088 startY: number = 0; 1089} 1090let mainScreenOption: ExpandOption = { screenId: 0, startX: 0, startY: 0 }; 1091let otherScreenOption: ExpandOption = { screenId: 1, startX: 1080, startY: 0 }; 1092let expandOptionArray : ExpandOption[] = [ mainScreenOption, otherScreenOption ]; 1093screen.makeExpand(expandOptionArray, (err: BusinessError, data: number) => { 1094 const errCode: number = err.code; 1095 if (errCode) { 1096 console.error(`Failed to expand the screen. Code:${err.code},message is ${err.message}`); 1097 return; 1098 } 1099 groupId = data; 1100 console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data)); 1101}); 1102``` 1103 1104## screen.makeExpand<sup>(deprecated)</sup> 1105 1106makeExpand(options:Array<ExpandOption>): Promise<number> 1107 1108将屏幕设置为扩展模式，使用Promise异步回调。 1109 1110> **说明：** 1111> 1112> 从API version 9开始支持，从API version 20开始废弃。 1113 1114**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1115 1116**参数：** 1117 1118| 参数名 | 类型 | 必填 | 说明 | 1119| ------- | ------------------------------------------ | ---- | ------------------------ | 1120| options | Array<[ExpandOption](#expandoption)> | 是 | 设置扩展屏幕的参数集合。 | 1121 1122**返回值：** 1123 1124| 类型 | 说明 | 1125| --------------------- |---------------------------------| 1126| Promise<number> | Promise对象。返回扩展屏幕的群组id，其中id为整数。 | 1127 1128**错误码：** 1129 1130以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1131 1132| 错误码ID | 错误信息 | 1133| ------- | ----------------------- | 1134| 202 | Permission verification failed. A non-system application calls a system API.| 1135| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1136| 1400001 | Invalid display or screen. | 1137 1138**示例：** 1139 1140```ts 1141import { BusinessError } from '@kit.BasicServicesKit'; 1142 1143class ExpandOption { 1144 screenId: number = 0; 1145 startX: number = 0; 1146 startY: number = 0; 1147} 1148let mainScreenOption: ExpandOption = { screenId: 0, startX: 0, startY: 0 }; 1149let otherScreenOption: ExpandOption = { screenId: 1, startX: 1080, startY: 0 }; 1150let expandOptionArray : ExpandOption[] = [ mainScreenOption, otherScreenOption ]; 1151screen.makeExpand(expandOptionArray).then(( 1152 data: number) => { 1153 console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data)); 1154}).catch((err: BusinessError) => { 1155 console.error(`Failed to expand the screen. Code:${err.code},message is ${err.message}`); 1156}); 1157``` 1158 1159## screen.stopExpand<sup>(deprecated)</sup> 1160 1161stopExpand(expandScreen:Array<number>, callback: AsyncCallback<void>): void 1162 1163停止屏幕的扩展模式，使用callback异步回调。 1164 1165> **说明：** 1166> 1167> 从API version 10开始支持，从API version 20开始废弃。 1168 1169**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1170 1171**参数：** 1172 1173| 参数名 | 类型 | 必填 | 说明 | 1174| ------------ | --------------------------- | --- |-----------------------------------------| 1175| expandScreen | Array<number> | 是 | 扩展屏幕id集合，其中id为整数。 expandScreen数组大小不应超过1000。 | 1176| callback | AsyncCallback<void> | 是 | 回调函数。当停止屏幕扩展模式成功，err为undefined，否则为错误对象。 | 1177 1178**错误码：** 1179 1180以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1181 1182| 错误码ID | 错误信息 | 1183| ------- | ----------------------- | 1184| 202 | Permission verification failed. A non-system application calls a system API.| 1185| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 1186| 1400001 | Invalid display or screen. | 1187 1188**示例：** 1189 1190```ts 1191import { BusinessError } from '@kit.BasicServicesKit'; 1192 1193let expandScreenIds: Array<number> = [1, 2, 3]; 1194screen.stopExpand(expandScreenIds, (err: BusinessError) => { 1195 const errCode: number = err.code; 1196 if (errCode) { 1197 console.error(`Failed to stop expand screens. Code:${err.code},message is ${err.message}`); 1198 return; 1199 } 1200 console.info('Succeeded in stopping expand screens.'); 1201}); 1202``` 1203 1204## screen.stopExpand<sup>(deprecated)</sup> 1205 1206stopExpand(expandScreen:Array<number>): Promise<void> 1207 1208停止屏幕的扩展模式，使用Promise异步回调。 1209 1210> **说明：** 1211> 1212> 从API version 10开始支持，从API version 20开始废弃。 1213 1214**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1215 1216**参数：** 1217 1218| 参数名 | 类型 | 必填 | 说明 | 1219| ------------ | ------------------- | --- |--------------------| 1220| expandScreen | Array<number> | 是 | 扩展屏幕id集合，其中id为整数。expandScreen数组大小不应超过1000。 | 1221 1222**返回值：** 1223 1224| 类型 | 说明 | 1225| --------------------- | ----------------------- | 1226| Promise<void> | 无返回结果的Promise对象。 | 1227 1228**错误码：** 1229 1230以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1231 1232| 错误码ID | 错误信息 | 1233| ------- | ----------------------- | 1234| 202 | Permission verification failed. A non-system application calls a system API.| 1235| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 1236| 1400001 | Invalid display or screen. | 1237 1238**示例：** 1239 1240```ts 1241import { BusinessError } from '@kit.BasicServicesKit'; 1242 1243let expandScreenIds: Array<number> = [1, 2, 3]; 1244screen.stopExpand(expandScreenIds).then(() => { 1245 console.info('Succeeded in stopping expand screens.'); 1246}).catch((err: BusinessError) => { 1247 console.error(`Failed to stop expand screens. Code:${err.code},message is ${err.message}`); 1248}); 1249``` 1250 1251## ExpandOption 1252 1253扩展屏幕的参数。 1254 1255**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1256 1257| 名称 | 类型 | 只读 | 可选 | 说明 | 1258| -------- | -------- | ---- | ---- | ------------------- | 1259| screenId | number | 否 | 否 | 屏幕的id，该参数应为整数。 | 1260| startX | number | 否 | 否 | 屏幕的起始X轴坐标，该参数应为整数。 | 1261| startY | number | 否 | 否 | 屏幕的起始Y轴坐标，该参数应为整数。 | 1262 1263## MultiScreenMode<sup>13+</sup> 1264 1265屏幕模式枚举。 1266 1267**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1268 1269| 名称 | 值 | 说明 | 1270| ------------------ | ---- | -------------------------------- | 1271| SCREEN_MIRROR | 0 | 表示屏幕为镜像模式。 | 1272| SCREEN_EXTEND | 1 | 表示屏幕为扩展模式。 | 1273 1274## MultiScreenPositionOptions<sup>13+</sup> 1275 1276屏幕位置信息。 1277 1278**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1279 1280| 名称 | 类型 | 只读 | 可选 | 说明 | 1281| -------- | -------- | ---- | ---- | ------------------- | 1282| id | number | 否 | 否 | 屏幕的id，该参数应为正整数，非正整数会作为非法参数报错。| 1283| startX | number | 否 | 否 | 屏幕的起始X轴坐标。以两块屏幕外接矩形的左上顶点为原点，向右为正方向。该参数应为正整数，非正整数会作为非法参数报错。 | 1284| startY | number | 否 | 否 | 屏幕的起始Y轴坐标。以两块屏幕外接矩形的左上顶点为原点，向下为正方向。该参数应为正整数，非正整数会作为非法参数报错。 | 1285 1286## VirtualScreenOption 1287 1288创建虚拟屏幕的参数。 1289 1290**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1291 1292| 名称 | 类型 | 只读 | 可选 | 说明 | 1293| --------- | -------- | ---- | ---- |--------------------------| 1294| name | string | 否 | 否 | 指定虚拟屏幕的名称。 | 1295| width | number | 否 | 否 | 指定虚拟屏幕的宽度，单位为px，该参数应为整数。 | 1296| height | number | 否 | 否 | 指定虚拟屏幕的高度，单位为px，该参数应为整数。 | 1297| density | number | 否 | 否 | 指定虚拟屏幕的密度，单位为px，该参数为浮点数。 | 1298| surfaceId | string | 否 | 否 | 指定虚拟屏幕的surfaceId。 | 1299 1300## Screen 1301 1302屏幕实例。 1303 1304下列API示例中都需先使用[getAllScreens()](#screengetallscreens)、[createVirtualScreen()](#screencreatevirtualscreen)中的任一方法获取到Screen实例，再通过此实例调用对应方法。 1305 1306### 属性 1307 1308**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1309 1310 1311| 名称 | 类型 | 只读 | 可选 | 说明 | 1312| ----------------- | ---------------------------------------------- | ---- | ---- |-------------------------------------------------------------| 1313| id | number | 是 | 否 | 屏幕的id，该参数为整数。 | 1314| parent | number | 是 | 否 | 屏幕所属群组的id，该参数为整数。 | 1315| supportedModeInfo | Array<[ScreenModeInfo](#screenmodeinfo)> | 是 | 否 | 屏幕支持的模式集合。 | 1316| activeModeIndex | number | 是 | 否 | 当前屏幕所处模式索引。模式索引的当前值和值的范围，会根据屏幕当前分辨率、刷新率和设备硬件差异产生变化。该参数为整数。 | 1317| orientation | [Orientation](#orientation) | 是 | 否 | 屏幕方向。 | 1318| sourceMode<sup>10+</sup> | [ScreenSourceMode](#screensourcemode10) | 是 | 否 | 屏幕来源模式。 | 1319| serialNumber<sup>15+</sup> | string | 是 | 是 | 扩展屏幕的序列号，当前仅2in1设备支持此属性。其他设备暂不支持使用此属性。 | 1320 1321### setOrientation 1322 1323setOrientation(orientation: Orientation, callback: AsyncCallback<void>): void 1324 1325设置屏幕方向，使用callback异步回调。 1326 1327**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1328 1329**参数：** 1330 1331| 参数名 | 类型 | 必填 | 说明 | 1332| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 1333| orientation | [Orientation](#orientation) | 是 | 屏幕方向。orientation值必须来自Orientation枚举方向。 | 1334| callback | AsyncCallback<void> | 是 | 回调函数。当设置屏幕方向成功，err为undefined，否则为错误对象。 | 1335 1336**错误码：** 1337 1338以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1339 1340| 错误码ID | 错误信息 | 1341| ------- | -------------------------------------------- | 1342| 202 | Permission verification failed. A non-system application calls a system API.| 1343| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 1344| 1400003 | This display manager service works abnormally. | 1345 1346**示例：** 1347 1348```ts 1349import { BusinessError } from '@kit.BasicServicesKit'; 1350 1351class VirtualScreenOption { 1352 name : string = ''; 1353 width : number = 0; 1354 height : number = 0; 1355 density : number = 0; 1356 surfaceId : string = ''; 1357} 1358 1359let option : VirtualScreenOption = { 1360 name: 'screen01', 1361 width: 1080, 1362 height: 2340, 1363 density: 2, 1364 surfaceId: '' 1365}; 1366 1367screen.createVirtualScreen(option).then((data: screen.Screen) => { 1368 let screenClass: screen.Screen = data; 1369 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1370 screenClass.setOrientation(screen.Orientation.VERTICAL, (err: BusinessError) => { 1371 const errCode: number = err.code; 1372 if (errCode) { 1373 console.error(`Failed to set the vertical orientation. Code:${err.code},message is ${err.message}`); 1374 return; 1375 } 1376 console.info('Succeeded in setting the vertical orientation.'); 1377 }); 1378}).catch((err: BusinessError) => { 1379 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1380}); 1381``` 1382 1383### setOrientation 1384 1385setOrientation(orientation: Orientation): Promise<void> 1386 1387设置屏幕方向，使用Promise异步回调。 1388 1389**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1390 1391**参数：** 1392 1393| 参数名 | 类型 | 必填 | 说明 | 1394| ----------- | --------------------------- | ---- | ---------- | 1395| orientation | [Orientation](#orientation) | 是 | 屏幕方向。orientation值必须来自Orientation枚举方向。 | 1396 1397**返回值：** 1398 1399| 类型 | 说明 | 1400| ------------------- | ------------------------- | 1401| Promise<void> | 无返回结果的Promise对象。 | 1402 1403**错误码：** 1404 1405以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1406 1407| 错误码ID | 错误信息 | 1408| ------- | -------------------------------------------- | 1409| 202 | Permission verification failed. A non-system application calls a system API.| 1410| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 1411| 1400003 | This display manager service works abnormally. | 1412 1413**示例：** 1414 1415```ts 1416import { BusinessError } from '@kit.BasicServicesKit'; 1417 1418class VirtualScreenOption { 1419 name : string = ''; 1420 width : number = 0; 1421 height : number = 0; 1422 density : number = 0; 1423 surfaceId : string = ''; 1424} 1425 1426let option : VirtualScreenOption = { 1427 name: 'screen01', 1428 width: 1080, 1429 height: 2340, 1430 density: 2, 1431 surfaceId: '' 1432}; 1433 1434screen.createVirtualScreen(option).then((data: screen.Screen) => { 1435 let screenClass: screen.Screen = data; 1436 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1437 let promise: Promise<void> = screenClass.setOrientation(screen.Orientation.VERTICAL); 1438 promise.then(() => { 1439 console.info('Succeeded in setting the vertical orientation.'); 1440 }).catch((err: BusinessError) => { 1441 console.error(`Failed to set the vertical orientation. Code:${err.code},message is ${err.message}`); 1442 }); 1443}).catch((err: BusinessError) => { 1444 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1445}); 1446``` 1447 1448### setScreenActiveMode 1449 1450setScreenActiveMode(modeIndex: number, callback: AsyncCallback<void>): void 1451 1452设置屏幕当前显示模式，使用callback异步回调。 1453 1454**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1455 1456**参数：** 1457 1458| 参数名 | 类型 | 必填 | 说明 | 1459| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 1460| modeIndex | number | 是 | 模式索引。模式索引的当前值和值的范围，会根据屏幕当前分辨率、刷新率和设备硬件差异产生变化，该参数仅支持整数输入。索引为screen中[ScreenModeInfo](#screenmodeinfo)属性的模式id。 | 1461| callback | AsyncCallback<void> | 是 | 回调函数。当设置屏幕当前显示模式成功，err为undefined，否则为错误对象。 | 1462 1463**错误码：** 1464 1465以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1466 1467| 错误码ID | 错误信息 | 1468| ------- | -------------------------------------------- | 1469| 202 | Permission verification failed. A non-system application calls a system API.| 1470| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1471| 1400003 | This display manager service works abnormally. | 1472 1473**示例：** 1474 1475```ts 1476import { BusinessError } from '@kit.BasicServicesKit'; 1477 1478class VirtualScreenOption { 1479 name : string = ''; 1480 width : number = 0; 1481 height : number = 0; 1482 density : number = 0; 1483 surfaceId : string = ''; 1484} 1485 1486let option : VirtualScreenOption = { 1487 name: 'screen01', 1488 width: 1080, 1489 height: 2340, 1490 density: 2, 1491 surfaceId: '' 1492}; 1493 1494screen.createVirtualScreen(option).then((data: screen.Screen) => { 1495 let screenClass: screen.Screen = data; 1496 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1497 let modeIndex: number = 0; 1498 screenClass.setScreenActiveMode(modeIndex, (err: BusinessError) => { 1499 const errCode: number = err.code; 1500 if (errCode) { 1501 console.error(`Failed to set screen active mode 0. Code:${err.code},message is ${err.message}`); 1502 return; 1503 } 1504 console.info('Succeeded in setting the vertical orientation.'); 1505 }); 1506}).catch((err: BusinessError) => { 1507 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1508}); 1509``` 1510 1511### setScreenActiveMode 1512 1513setScreenActiveMode(modeIndex: number): Promise<void> 1514 1515设置屏幕当前显示模式，使用Promise异步回调。 1516 1517**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1518 1519**参数：** 1520 1521| 参数名 | 类型 | 必填 | 说明 | 1522| --------- | ------ | ---- | ---------- | 1523| modeIndex | number | 是 | 模式索引。模式索引的当前值和值的范围，会根据屏幕当前分辨率、刷新率和设备硬件差异产生变化，该参数仅支持整数输入。 | 1524 1525**返回值：** 1526 1527| 类型 | 说明 | 1528| ------------------- | ------------------------- | 1529| Promise<void> | 无返回结果的Promise对象。 | 1530 1531**错误码：** 1532 1533以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1534 1535| 错误码ID | 错误信息 | 1536| ------- | -------------------------------------------- | 1537| 202 | Permission verification failed. A non-system application calls a system API.| 1538| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1539| 1400003 | This display manager service works abnormally. | 1540 1541**示例：** 1542 1543```ts 1544import { BusinessError } from '@kit.BasicServicesKit'; 1545 1546class VirtualScreenOption { 1547 name : string = ''; 1548 width : number = 0; 1549 height : number = 0; 1550 density : number = 0; 1551 surfaceId : string = ''; 1552} 1553 1554let option : VirtualScreenOption = { 1555 name: 'screen01', 1556 width: 1080, 1557 height: 2340, 1558 density: 2, 1559 surfaceId: '' 1560}; 1561 1562screen.createVirtualScreen(option).then((data: screen.Screen) => { 1563 let screenClass: screen.Screen = data; 1564 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1565 let modeIndex: number = 0; 1566 let promise: Promise<void> = screenClass.setScreenActiveMode(modeIndex); 1567 promise.then(() => { 1568 console.info('Succeeded in setting screen active mode 0.'); 1569 }).catch((err: BusinessError) => { 1570 console.error(`Failed to set screen active mode 0.Code:${err.code},message is ${err.message}`); 1571 }); 1572}).catch((err: BusinessError) => { 1573 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1574}); 1575``` 1576 1577### setDensityDpi 1578 1579setDensityDpi(densityDpi: number, callback: AsyncCallback<void>): void; 1580 1581设置屏幕的像素密度，使用callback异步回调。 1582 1583**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1584 1585**参数：** 1586 1587| 参数名 | 类型 | 必填 | 说明 | 1588| ---------- | ------------------------- | ---- |------------------------------------------| 1589| densityDpi | number | 是 | 像素密度。支持的输入范围为[80, 640]，该参数仅支持整数输入。 | 1590| callback | AsyncCallback<void> | 是 | 回调函数。当设置屏幕的像素密度成功，err为undefined，否则为错误对象。 | 1591 1592**错误码：** 1593 1594以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1595 1596| 错误码ID | 错误信息 | 1597| ------- | -------------------------------------------- | 1598| 202 | Permission verification failed. A non-system application calls a system API.| 1599| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1600| 1400003 | This display manager service works abnormally. | 1601 1602**示例：** 1603 1604```ts 1605import { BusinessError } from '@kit.BasicServicesKit'; 1606 1607let densityDpi: number = 320; 1608class VirtualScreenOption { 1609 name : string = ''; 1610 width : number = 0; 1611 height : number = 0; 1612 density : number = 0; 1613 surfaceId : string = ''; 1614} 1615 1616let option : VirtualScreenOption = { 1617 name: 'screen01', 1618 width: 1080, 1619 height: 2340, 1620 density: 2, 1621 surfaceId: '' 1622}; 1623 1624screen.createVirtualScreen(option).then((data: screen.Screen) => { 1625 let screenClass: screen.Screen = data; 1626 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1627 screenClass.setDensityDpi(densityDpi, (err: BusinessError) => { 1628 const errCode: number = err.code; 1629 if (errCode) { 1630 console.error(`Failed to set the pixel density of the screen to 320. Code:${err.code},message is ${err.message}`); 1631 return; 1632 } 1633 console.info('Succeeded in setting the vertical orientation.'); 1634 }); 1635}).catch((err: BusinessError) => { 1636 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1637}); 1638``` 1639 1640### setDensityDpi 1641 1642setDensityDpi(densityDpi: number): Promise<void> 1643 1644设置屏幕的像素密度，使用Promise异步回调。 1645 1646**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1647 1648**参数：** 1649 1650| 参数名 | 类型 | 必填 | 说明 | 1651| ---------- | ------ | ---- |------------------------------------| 1652| densityDpi | number | 是 | 像素密度。支持的输入范围为[80, 640]，该参数仅支持整数输入。 | 1653 1654**返回值：** 1655 1656| 类型 | 说明 | 1657| ------------------- | ------------------------- | 1658| Promise<void> | 无返回结果的Promise对象。 | 1659 1660**错误码：** 1661 1662以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1663 1664| 错误码ID | 错误信息 | 1665| ------- | -------------------------------------------- | 1666| 202 | Permission verification failed. A non-system application calls a system API.| 1667| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1668| 1400003 | This display manager service works abnormally. | 1669 1670**示例：** 1671 1672```ts 1673import { BusinessError } from '@kit.BasicServicesKit'; 1674 1675let densityDpi: number = 320; 1676class VirtualScreenOption { 1677 name : string = ''; 1678 width : number = 0; 1679 height : number = 0; 1680 density : number = 0; 1681 surfaceId : string = ''; 1682} 1683 1684let option : VirtualScreenOption = { 1685 name: 'screen01', 1686 width: 1080, 1687 height: 2340, 1688 density: 2, 1689 surfaceId: '' 1690}; 1691 1692screen.createVirtualScreen(option).then((data: screen.Screen) => { 1693 let screenClass: screen.Screen = data; 1694 let promise: Promise<void> = screenClass.setDensityDpi(densityDpi); 1695 promise.then(() => { 1696 console.info('Succeeded in setting the pixel density of the screen to 320.'); 1697 }).catch((err: BusinessError) => { 1698 console.error(`Failed to set the pixel density of the screen to 320. Code:${err.code},message is ${err.message}`); 1699 }); 1700}).catch((err: BusinessError) => { 1701 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1702}); 1703``` 1704 1705## Orientation 1706 1707屏幕方向枚举。 1708 1709**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1710 1711| 名称 | 值 | 说明 | 1712| ------------------ | ---- | -------------------------------- | 1713| UNSPECIFIED | 0 | 表示未指定屏幕方向，由系统指定。 | 1714| VERTICAL | 1 | 表示指定屏幕为垂直方向。 | 1715| HORIZONTAL | 2 | 表示指定屏幕为水平方向。 | 1716| REVERSE_VERTICAL | 3 | 表示指定屏幕为反向垂直方向。 | 1717| REVERSE_HORIZONTAL | 4 | 表示指定屏幕为反向水平方向。 | 1718 1719## ScreenSourceMode<sup>10+</sup> 1720 1721屏幕显示内容来源模式枚举。 1722 1723**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1724 1725| 名称 | 值 | 说明 | 1726| ------------------ | ---- | -------------------------------- | 1727| SCREEN_MAIN | 0 | 表示屏幕为默认主屏。 | 1728| SCREEN_MIRROR | 1 | 表示屏幕内容来自镜像。 | 1729| SCREEN_EXTEND | 2 | 表示屏幕内容来自扩展。 | 1730| SCREEN_ALONE | 3 | 表示屏幕为未指定来源。 | 1731 1732## ScreenModeInfo 1733 1734屏幕显示模式信息。 1735 1736**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1737 1738| 名称 | 类型 | 只读 | 可选 | 说明 | 1739| ----------- | -------- | ---- | ---- | -------------------------------------------------- | 1740| id | number | 否 | 否 | 模式id，所支持的模式由具体设备分辨率和刷新率决定，该参数为整数。 | 1741| width | number | 否 | 否 | 屏幕的宽度，单位为px，该参数为整数。 | 1742| height | number | 否 | 否 | 屏幕的高度，单位为px，该参数为整数。 | 1743| refreshRate | number | 否 | 否 | 屏幕的刷新率，单位为hz，该参数为整数。 | 1744 1745## Rect<sup>19+</sup> 1746 1747矩形信息。 1748 1749**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1750 1751| 名称 | 类型 | 只读 | 可选 | 说明 | 1752| ----------- | -------- | ---- | ---- | -------------------------------------------------- | 1753| left | number | 否 | 否 | 矩形左上角顶点的X轴坐标，单位为px，该参数应为整数。 | 1754| top | number | 否 | 否 | 矩形左上角顶点的Y轴坐标，单位为px，该参数应为整数。 | 1755| width | number | 否 | 否 | 矩形的宽度，单位为px，该参数应为整数。 | 1756| height | number | 否 | 否 | 矩形的高度，单位为px，该参数应为整数。 |