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