1# @ohos.screen (屏幕) 2 3本模块提供管理屏幕的一些基础能力，包括获取屏幕对象，监听屏幕变化，创建和销毁虚拟屏幕等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 本模块接口为系统接口。 10 11## 导入模块 12 13```js 14import screen from '@ohos.screen'; 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以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 34 35| 错误码ID | 错误信息 | 36| ------- | ----------------------- | 37| 1400001 | Invalid display or screen. | 38 39**示例：** 40 41```js 42let screenClass = null; 43screen.getAllScreens((err, data) => { 44 if (err.code) { 45 console.error('Failed to get all screens. Cause: ' + JSON.stringify(err)); 46 return; 47 } 48 console.info('Succeeded in getting all screens. Data:' + JSON.stringify(data)); 49 screenClass = data[0]; 50}); 51``` 52 53## screen.getAllScreens 54 55getAllScreens(): Promise<Array<Screen>> 56 57获取所有的屏幕，使用Promise异步回调。 58 59**系统能力：** SystemCapability.WindowManager.WindowManager.Core 60 61**返回值：** 62 63| 类型 | 说明 | 64| --------------------------------------------- | ----------------------------------------- | 65| Promise<Array<[Screen](#screen)>> | Promise对象。返回当前获取的屏幕对象集合。 | 66 67**错误码：** 68 69以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 70 71| 错误码ID | 错误信息 | 72| ------- | ----------------------- | 73| 1400001 | Invalid display or screen. | 74 75**示例：** 76 77```js 78let screenClass = null; 79let promise = screen.getAllScreens(); 80promise.then((data) => { 81 screenClass = data[0]; 82 console.log('Succeeded in getting all screens. Data:'+ JSON.stringify(data)); 83}).catch((err) => { 84 console.log('Failed to get all screens. Cause: ' + JSON.stringify(err)); 85}); 86``` 87 88## screen.on('connect' | 'disconnect' | 'change') 89 90on(eventType: 'connect' | 'disconnect' | 'change', callback: Callback<number>): void 91 92开启屏幕状态变化的监听。 93 94**系统能力：** SystemCapability.WindowManager.WindowManager.Core 95 96**参数：** 97 98| 参数名 | 类型 | 必填 | 说明 | 99| --------- | ---------------------- | ---- | ------------------------------------------------------------ | 100| eventType | string | 是 | 监听事件。<br/>-eventType为"connect"表示屏幕连接事件。<br/>-eventType为"disconnect"表示断开屏幕连接事件。<br/>-eventType为"change"表示屏幕状态改变事件。 | 101| callback | Callback<number> | 是 | 回调函数。返回屏幕的id。 | 102 103**示例：** 104 105```js 106try { 107 let callback = (data) => { 108 console.info('Succeeded in registering the callback for screen changes. Data: ' + JSON.stringify(data)) 109 }; 110 screen.on('connect', callback); 111} catch (exception) { 112 console.error('Failed to register the callback for screen changes. Code: ' + JSON.stringify(exception)); 113}; 114``` 115 116## screen.off('connect' | 'disconnect' | 'change') 117 118off(eventType: 'connect' | 'disconnect' | 'change', callback?: Callback<number>): void 119 120关闭屏幕状态变化的监听。 121 122**系统能力：** SystemCapability.WindowManager.WindowManager.Core 123 124**参数：** 125 126| 参数名 | 类型 | 必填 | 说明 | 127| --------- | ---------------------- | ---- | ------------------------------------------------------------ | 128| eventType | string | 是 | 监听事件。<br/>-eventType为"connect"表示屏幕连接事件。<br/>-eventType为"disconnect"表示断开屏幕连接事件。<br/>-eventType为"change"表示屏幕状态改变事件。 | 129| callback | Callback<number> | 否 | 回调函数。返回屏幕的id。 | 130 131**示例：** 132 133```js 134try { 135 let callback = (data) => { 136 console.info('Succeeded in unregistering the callback for screen changes. Data: ' + JSON.stringify(data)) 137 }; 138 screen.off('connect', callback); 139} catch (exception) { 140 console.error('Failed to register the callback for screen changes. Code: ' + JSON.stringify(exception)); 141}; 142``` 143 144## screen.makeExpand 145 146makeExpand(options:Array<ExpandOption>, callback: AsyncCallback<number>): void 147 148将屏幕设置为扩展模式，使用callback异步回调。 149 150**系统能力：** SystemCapability.WindowManager.WindowManager.Core 151 152**参数：** 153 154| 参数名 | 类型 | 必填 | 说明 | 155| -------- | ------------------------------------------ | ---- | -------------------------------- | 156| options | Array<[ExpandOption](#expandoption)> | 是 | 设置扩展屏幕的参数集合。 | 157| callback | AsyncCallback<number> | 是 | 回调函数。返回扩展屏幕的群组id。 | 158 159**错误码：** 160 161以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 162 163| 错误码ID | 错误信息 | 164| ------- | ----------------------- | 165| 1400001 | Invalid display or screen. | 166 167**示例：** 168 169```js 170try { 171 let groupId = null; 172 screen.makeExpand([{screenId: 0, startX: 0, startY: 0}, {screenId: 1, startX: 1080, startY: 0}], (err, data) => { 173 if (err.code) { 174 console.error('Failed to expand the screen. Code:' + JSON.stringify(err)); 175 return; 176 } 177 groupId = data; 178 console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data)); 179 }); 180} catch (exception) { 181 console.error('Failed to expand the screen. Code: ' + JSON.stringify(exception)); 182}; 183``` 184 185## screen.makeExpand 186 187makeExpand(options:Array<ExpandOption>): Promise<number> 188 189将屏幕设置为扩展模式，使用Promise异步回调。 190 191**系统能力：** SystemCapability.WindowManager.WindowManager.Core 192 193**参数：** 194 195| 参数名 | 类型 | 必填 | 说明 | 196| ------- | ------------------------------------------ | ---- | ------------------------ | 197| options | Array<[ExpandOption](#expandoption)> | 是 | 设置扩展屏幕的参数集合。 | 198 199**返回值：** 200 201| 类型 | 说明 | 202| --------------------- | ----------------------------------- | 203| Promise<number> | Promise对象。返回扩展屏幕的群组id。 | 204 205**错误码：** 206 207以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 208 209| 错误码ID | 错误信息 | 210| ------- | ----------------------- | 211| 1400001 | Invalid display or screen. | 212 213**示例：** 214 215```js 216try { 217 screen.makeExpand([{screenId: 0, startX: 0, startY: 0}, {screenId: 1, startX: 1080, startY: 0}]).then((data) => { 218 console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data)); 219 }).catch((err) => { 220 console.error('Failed to expand the screen. Code:' + JSON.stringify(err)); 221 }); 222} catch (exception) { 223 console.error('Failed to expand the screen. Code: ' + JSON.stringify(exception)); 224}; 225``` 226 227## screen.makeMirror 228 229makeMirror(mainScreen:number, mirrorScreen:Array<number>, callback: AsyncCallback<number>): void 230 231将屏幕设置为镜像模式，使用callback异步回调。 232 233**系统能力：** SystemCapability.WindowManager.WindowManager.Core 234 235**参数：** 236 237| 参数名 | 类型 | 必填 | 说明 | 238| ------------ | --------------------------- | ---- |-----------------| 239| mainScreen | number | 是 | 主屏幕id。 | 240| mirrorScreen | Array<number> | 是 | 镜像屏幕id集合。 | 241| callback | AsyncCallback<number> | 是 | 回调函数。返回镜像屏幕的群组id。 | 242 243**错误码：** 244 245以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 246 247| 错误码ID | 错误信息 | 248| ------- | ----------------------- | 249| 1400001 | Invalid display or screen. | 250 251**示例：** 252 253```js 254let mainScreenId = 0; 255let mirrorScreenIds = [1, 2, 3]; 256try { 257 screen.makeMirror(mainScreenId, mirrorScreenIds, (err, data) => { 258 if (err.code) { 259 console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(err)); 260 return; 261 } 262 console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data)); 263 }); 264} catch (exception) { 265 console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(exception)); 266}; 267``` 268 269## screen.makeMirror 270 271makeMirror(mainScreen:number, mirrorScreen:Array<number>): Promise<number> 272 273将屏幕设置为镜像模式，使用Promise异步回调。 274 275**系统能力：** SystemCapability.WindowManager.WindowManager.Core 276 277**参数：** 278 279| 参数名 | 类型 | 必填 | 说明 | 280| ------------ | ------------------- | ---- |-----------| 281| mainScreen | number | 是 | 主屏幕id。 | 282| mirrorScreen | Array<number> | 是 | 镜像屏幕id集合。 | 283 284**返回值：** 285 286| 类型 | 说明 | 287| --------------------- | ----------------------------------- | 288| Promise<number> | Promise对象。返回镜像屏幕的群组id。 | 289 290**错误码：** 291 292以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 293 294| 错误码ID | 错误信息 | 295| ------- | ----------------------- | 296| 1400001 | Invalid display or screen. | 297 298**示例：** 299 300```js 301let mainScreenId = 0; 302let mirrorScreenIds = [1, 2, 3]; 303try { 304 screen.makeMirror(mainScreenId, mirrorScreenIds).then((data) => { 305 console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data)); 306 }).catch((err) => { 307 console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(err)); 308 }); 309} catch (exception) { 310 console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(exception)); 311}; 312``` 313 314## screen.createVirtualScreen 315 316createVirtualScreen(options:VirtualScreenOption, callback: AsyncCallback<Screen>): void 317 318创建虚拟屏幕，使用callback异步回调。 319 320**系统能力：** SystemCapability.WindowManager.WindowManager.Core 321 322**需要权限**：ohos.permission.CAPTURE_SCREEN，如果VirtualScreenOption.surfaceId有效，此权限是必需的。仅系统应用可用。 323 324**参数：** 325 326| 参数名 | 类型 | 必填 | 说明 | 327| -------- | ------------------------------------------- | ---- | ---------------------------------- | 328| options | [VirtualScreenOption](#virtualscreenoption) | 是 | 用于创建虚拟屏幕的参数。 | 329| callback | AsyncCallback<[Screen](#screen)> | 是 | 回调函数，返回创建的虚拟屏幕对象。 | 330 331**错误码：** 332 333以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 334 335| 错误码ID | 错误信息 | 336| ------- | ----------------------- | 337| 1400001 | Invalid display or screen. | 338 339**示例：** 340 341```js 342let screenClass = null; 343try { 344 screen.createVirtualScreen({ 345 name: 'screen01', 346 width: 1080, 347 height: 2340, 348 density: 2, 349 surfaceId: '' 350 }, (err, data) => { 351 if (err.code) { 352 console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err)); 353 return; 354 } 355 screenClass = data; 356 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 357 }); 358} catch (exception) { 359 console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(exception)); 360}; 361``` 362 363## screen.createVirtualScreen 364 365createVirtualScreen(options:VirtualScreenOption): Promise<Screen> 366 367创建虚拟屏幕，使用Promise异步回调。 368 369**系统能力：** SystemCapability.WindowManager.WindowManager.Core 370 371**需要权限**：ohos.permission.CAPTURE_SCREEN，如果VirtualScreenOption.surfaceId有效，此权限是必需的。仅系统应用可用。 372 373**参数：** 374 375| 参数名 | 类型 | 必填 | 说明 | 376| ------- | ------------------------------------------- | ---- | ------------------------ | 377| options | [VirtualScreenOption](#virtualscreenoption) | 是 | 用于创建虚拟屏幕的参数。 | 378 379**返回值：** 380 381| 类型 | 说明 | 382| -------------------------------- | ------------------------------------- | 383| Promise<[Screen](#screen)> | Promise对象。返回创建的虚拟屏幕对象。 | 384 385**错误码：** 386 387以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 388 389| 错误码ID | 错误信息 | 390| ------- | ----------------------- | 391| 1400001 | Invalid display or screen. | 392 393**示例：** 394 395```js 396let screenClass = null; 397try { 398 screen.createVirtualScreen({ 399 name: 'screen01', 400 width: 1080, 401 height: 2340, 402 density: 2, 403 surfaceId: '' 404 }).then((data) => { 405 screenClass = data; 406 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 407 }).catch((err) => { 408 console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err)); 409 }); 410} catch (exception) { 411 console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(exception)); 412}; 413``` 414 415## screen.destroyVirtualScreen 416 417destroyVirtualScreen(screenId:number, callback: AsyncCallback<void>): void 418 419销毁虚拟屏幕，使用callback异步回调。 420 421**系统能力：** SystemCapability.WindowManager.WindowManager.Core 422 423**参数：** 424 425| 参数名 | 类型 | 必填 | 说明 | 426| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 427| screenId | number | 是 | 屏幕的id。 | 428| callback | AsyncCallback<void> | 是 | 回调函数。当销毁虚拟屏幕成功，err为undefined，否则为错误对象。 | 429 430**错误码：** 431 432以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 433 434| 错误码ID | 错误信息 | 435| ------- | ----------------------------- | 436| 1400002 | Unauthorized operation. | 437 438**示例：** 439 440```js 441let screenId = 1; 442try { 443 screen.destroyVirtualScreen(screenId, (err,data) => { 444 if (err.code) { 445 console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(err)); 446 return; 447 } 448 console.info('Succeeded in destroying the virtual screen.'); 449 }); 450} catch (exception) { 451 console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(exception)); 452}; 453``` 454 455## screen.destroyVirtualScreen 456 457destroyVirtualScreen(screenId:number): Promise<void> 458 459销毁虚拟屏幕，使用Promise异步回调。 460 461**系统能力：** SystemCapability.WindowManager.WindowManager.Core 462 463**参数：** 464 465| 参数名 | 类型 | 必填 | 说明 | 466| -------- | ------ | ---- | ---------- | 467| screenId | number | 是 | 屏幕的id。 | 468 469**返回值：** 470 471| 类型 | 说明 | 472| ------------------- | ------------------------- | 473| Promise<void> | 无返回结果的Promise对象。 | 474 475**错误码：** 476 477以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 478 479| 错误码ID | 错误信息 | 480| ------- | ----------------------------- | 481| 1400002 | Unauthorized operation. | 482 483**示例：** 484 485```js 486let screenId = 1; 487try { 488 screen.destroyVirtualScreen(screenId).then((data) => { 489 console.info('Succeeded in destroying the virtual screen.'); 490 }).catch((err) => { 491 console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(err)); 492 }); 493} catch (exception) { 494 console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(exception)); 495}; 496``` 497 498## screen.setVirtualScreenSurface 499 500setVirtualScreenSurface(screenId:number, surfaceId: string, callback: AsyncCallback<void>): void 501 502设置虚拟屏幕的surface，使用callback异步回调。 503 504**系统能力：** SystemCapability.WindowManager.WindowManager.Core 505 506**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。 507 508**参数：** 509 510| 参数名 | 类型 | 必填 | 说明 | 511| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 512| screenId | number | 是 | 屏幕的id。 | 513| surfaceId | string | 是 | surface的id。 | 514| callback | AsyncCallback<void> | 是 | 回调函数。当设置虚拟屏幕surface成功，err为undefined，否则为错误对象。 | 515 516**错误码：** 517 518以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 519 520| 错误码ID | 错误信息 | 521| ------- | ----------------------- | 522| 1400001 | Invalid display or screen. | 523 524**示例：** 525 526```js 527let screenId = 1; 528let surfaceId = '2048'; 529try { 530 screen.setVirtualScreenSurface(screenId, surfaceId, (err,data) => { 531 if (err.code) { 532 console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(err)); 533 return; 534 } 535 console.info('Succeeded in setting the surface for the virtual screen.'); 536 }); 537} catch (exception) { 538 console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(exception)); 539}; 540``` 541 542## screen.setVirtualScreenSurface 543 544setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void> 545 546设置虚拟屏幕的surface，使用Promise异步回调。 547 548**系统能力：** SystemCapability.WindowManager.WindowManager.Core 549 550**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。 551 552**参数：** 553 554| 参数名 | 类型 | 必填 | 说明 | 555| --------- | ------ | ---- | ------------- | 556| screenId | number | 是 | 屏幕的id。 | 557| surfaceId | string | 是 | surface的id。 | 558 559**返回值：** 560 561| 类型 | 说明 | 562| ------------------- | ------------------------- | 563| Promise<void> | 无返回结果的Promise对象。 | 564 565**错误码：** 566 567以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 568 569| 错误码ID | 错误信息 | 570| ------- | ----------------------- | 571| 1400001 | Invalid display or screen. | 572 573**示例：** 574 575```js 576let screenId = 1; 577let surfaceId = '2048'; 578try { 579 screen.setVirtualScreenSurface(screenId, surfaceId).then((data) => { 580 console.info('Succeeded in setting the surface for the virtual screen.'); 581 }).catch((err) => { 582 console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(err)); 583 }); 584} catch (exception) { 585 console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(exception)); 586}; 587``` 588 589## screen.isScreenRotationLocked 590 591isScreenRotationLocked(): Promise<boolean> 592 593查询当前自动转屏是否锁定，使用Promise异步回调。 594 595**系统能力：** SystemCapability.WindowManager.WindowManager.Core 596 597**返回值：** 598 599| 类型 | 说明 | 600| ---------------------- | ------------------------------------- | 601| Promise<boolean> | Promise对象。返回true表示当前自动转屏处于锁定状态；返回false表示当前自动转屏不处于锁定状态。 | 602 603**示例：** 604 605```js 606screen.isScreenRotationLocked().then((isLocked) => { 607 console.info('Succeeded in getting the screen rotation lock status. isLocked:'+ JSON.stringify(isLocked)); 608}).catch((err) => { 609 console.error('Failed to get the screen rotation lock status. Cause:' + JSON.stringify(err)); 610}); 611``` 612 613## screen.isScreenRotationLocked 614 615isScreenRotationLocked(callback: AsyncCallback<boolean>): void 616 617查询当前自动转屏是否锁定，使用callback异步回调。 618 619**系统能力：** SystemCapability.WindowManager.WindowManager.Core 620 621**参数：** 622 623| 参数名 | 类型 | 必填 | 说明 | 624| --------- | ---------------------------- | ---- | ------------------------------------------------------------ | 625| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前自动转屏处于锁定状态；返回false表示当前自动转屏不处于锁定状态。 | 626 627**示例：** 628 629```js 630screen.isScreenRotationLocked((err, isLocked) => { 631 if (err.code) { 632 console.error('Failed to get the screen rotation lock status. Cause:' + JSON.stringify(err)); 633 return; 634 } 635 console.info('Succeeded in getting the screen rotation lock status. isLocked:' + JSON.stringify(isLocked)); 636}); 637``` 638 639## screen.setScreenRotationLocked 640 641setScreenRotationLocked(isLocked: boolean): Promise<void> 642 643设置自动转屏开关是否锁定，使用Promise异步回调。 644 645**系统能力：** SystemCapability.WindowManager.WindowManager.Core 646 647**参数：** 648 649| 参数名 | 类型 | 必填 | 说明 | 650| --------- | ------ | ---- | ------------- | 651| isLocked | boolean | 是 | 自动转屏开关是否锁定。true为锁定，false为未锁定. | 652 653**返回值：** 654 655| 类型 | 说明 | 656| ------------------- | ------------------------- | 657| Promise<void> | 无返回结果的Promise对象。 | 658 659**示例：** 660 661```js 662let isLocked = false; 663try { 664 screen.setScreenRotationLocked(isLocked).then((data) => { 665 console.info('Succeeded in unlocking auto rotate'); 666 }).catch((err) => { 667 console.error('Failed to unlock auto rotate. Code: ' + JSON.stringify(err)); 668 }); 669} catch (exception) { 670 console.error('Failed to unlock auto rotate. Code: ' + JSON.stringify(exception)); 671}; 672``` 673 674## screen.setScreenRotationLocked 675 676setScreenRotationLocked(isLocked: boolean, callback: AsyncCallback<void>): void 677 678设置自动转屏开关是否锁定，使用callback异步回调。 679 680**系统能力：** SystemCapability.WindowManager.WindowManager.Core 681 682**参数：** 683 684| 参数名 | 类型 | 必填 | 说明 | 685| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 686| isLocked | boolean | 是 | 自动转屏开关是否锁定。true为锁定，false为未锁定. | 687| callback | AsyncCallback<void> | 是 | 回调函数。当设置自动转屏是否锁定成功，err为undefined，否则为错误对象。 | 688 689**示例：** 690 691```js 692let isLocked = false; 693try { 694 screen.setScreenRotationLocked(isLocked, (err, data) => { 695 if (err.code) { 696 console.error('Failed to unlock auto rotate. Cause:' + JSON.stringify(err)); 697 return; 698 } 699 console.info('Succeeded in unlocking auto rotate.'); 700 }); 701} catch (exception) { 702 console.error('Failed to unlock auto rotate. Code: ' + JSON.stringify(exception)); 703}; 704``` 705 706## ExpandOption 707 708扩展屏幕的参数。 709 710**系统能力：** SystemCapability.WindowManager.WindowManager.Core 711 712| 名称 | 类型 | 可读 | 可写 | 说明 | 713| -------- | -------- | ---- | ---- | ------------------- | 714| screenId | number | 是 | 是 | 屏幕的id。 | 715| startX | number | 是 | 是 | 屏幕的起始X轴坐标。 | 716| startY | number | 是 | 是 | 屏幕的起始Y轴坐标。 | 717 718## VirtualScreenOption 719 720创建虚拟屏幕的参数。 721 722**系统能力：** SystemCapability.WindowManager.WindowManager.Core 723 724| 名称 | 类型 | 可读 | 可写 | 说明 | 725| --------- | -------- | ---- | ---- | ------------------------- | 726| name | string | 是 | 是 | 指定虚拟屏幕的名称。 | 727| width | number | 是 | 是 | 指定虚拟屏幕的宽度，单位为像素。 | 728| height | number | 是 | 是 | 指定虚拟屏幕的高度，单位为像素。 | 729| density | number | 是 | 是 | 指定虚拟屏幕的密度。 | 730| surfaceId | string | 是 | 是 | 指定虚拟屏幕的surfaceId。 | 731 732## Screen 733 734屏幕实例。 735 736下列API示例中都需先使用[getAllScreens()](#screengetallscreens)、[createVirtualScreen()](#screencreatevirtualscreen)中的任一方法获取到Screen实例，再通过此实例调用对应方法。 737 738**系统能力：** SystemCapability.WindowManager.WindowManager.Core 739 740| 名称 | 类型 | 可读 | 可写 | 说明 | 741| ----------------- | ---------------------------------------------- | ---- | ---- | ---------------------- | 742| id | number | 是 | 否 | 屏幕的id。 | 743| parent | number | 是 | 否 | 屏幕所属群组的id。 | 744| supportedModeInfo | Array<[ScreenModeInfo](#screenmodeinfo)> | 是 | 否 | 屏幕支持的模式集合。 | 745| activeModeIndex | number | 是 | 否 | 当前屏幕所处模式索引。模式索引的当前值和值的范围，会根据屏幕当前分辨率、刷新率和设备硬件差异产生变化。 | 746| orientation | [Orientation](#orientation) | 是 | 否 | 屏幕方向。 | 747 748### setOrientation 749 750setOrientation(orientation: Orientation, callback: AsyncCallback<void>): void 751 752设置屏幕方向，使用callback异步回调。 753 754**系统能力：** SystemCapability.WindowManager.WindowManager.Core 755 756| 参数名 | 类型 | 必填 | 说明 | 757| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 758| orientation | [Orientation](#orientation) | 是 | 屏幕方向。 | 759| callback | AsyncCallback<void> | 是 | 回调函数。当设置屏幕方向成功，err为undefined，否则为错误对象。 | 760 761**错误码：** 762 763以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 764 765| 错误码ID | 错误信息 | 766| ------- | -------------------------------------------- | 767| 1400003 | This display manager service works abnormally. | 768 769**示例：** 770 771```js 772try { 773 screenClass.setOrientation(screen.Orientation.VERTICAL, (err, data) => { 774 if (err.code) { 775 console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(err)); 776 return; 777 } 778 console.info('Succeeded in setting the vertical orientation. data: ' + JSON.stringify(data)); 779 }); 780} catch (exception) { 781 console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(exception)); 782}; 783``` 784 785### setOrientation 786 787setOrientation(orientation: Orientation): Promise<void> 788 789设置屏幕方向，使用Promise异步回调。 790 791**系统能力：** SystemCapability.WindowManager.WindowManager.Core 792 793| 参数名 | 类型 | 必填 | 说明 | 794| ----------- | --------------------------- | ---- | ---------- | 795| orientation | [Orientation](#orientation) | 是 | 屏幕方向。 | 796 797**返回值：** 798 799| 类型 | 说明 | 800| ------------------- | ------------------------- | 801| Promise<void> | 无返回结果的Promise对象。 | 802 803**错误码：** 804 805以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 806 807| 错误码ID | 错误信息 | 808| ------- | -------------------------------------------- | 809| 1400003 | This display manager service works abnormally. | 810 811**示例：** 812 813```js 814try { 815 let promise = screenClass.setOrientation(screen.Orientation.VERTICAL); 816 promise.then((data) => { 817 console.info('Succeeded in setting the vertical orientation. Data: ' + JSON.stringify(data)); 818 }).catch((err) => { 819 console.error('Failed to set the vertical orientation. Cause: ' + JSON.stringify(err)); 820 }); 821} catch (exception) { 822 console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(exception)); 823}; 824``` 825 826### setScreenActiveMode 827 828setScreenActiveMode(modeIndex: number, callback: AsyncCallback<void>): void 829 830设置屏幕当前显示模式，使用callback异步回调。 831 832**系统能力：** SystemCapability.WindowManager.WindowManager.Core 833 834| 参数名 | 类型 | 必填 | 说明 | 835| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 836| modeIndex | number | 是 | 模式索引。模式索引的当前值和值的范围，会根据屏幕当前分辨率、刷新率和设备硬件差异产生变化。 | 837| callback | AsyncCallback<void> | 是 | 回调函数。当设置屏幕当前显示模式成功，err为undefined，否则为错误对象。 | 838 839**错误码：** 840 841以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 842 843| 错误码ID | 错误信息 | 844| ------- | -------------------------------------------- | 845| 1400003 | This display manager service works abnormally. | 846 847**示例：** 848 849```js 850let modeIndex = 0; 851try { 852 screenClass.setScreenActiveMode(modeIndex, (err, data) => { 853 if (err.code) { 854 console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(err)); 855 return; 856 } 857 console.info('Succeeded in setting screen active mode 0. data: ' + JSON.stringify(data)); 858 }); 859} catch (exception) { 860 console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(exception)); 861}; 862``` 863 864### setScreenActiveMode 865 866setScreenActiveMode(modeIndex: number): Promise<void> 867 868设置屏幕当前显示模式，使用Promise异步回调。 869 870**系统能力：** SystemCapability.WindowManager.WindowManager.Core 871 872| 参数名 | 类型 | 必填 | 说明 | 873| --------- | ------ | ---- | ---------- | 874| modeIndex | number | 是 | 模式索引。模式索引的当前值和值的范围，会根据屏幕当前分辨率、刷新率和设备硬件差异产生变化。 | 875 876**返回值：** 877 878| 类型 | 说明 | 879| ------------------- | ------------------------- | 880| Promise<void> | 无返回结果的Promise对象。 | 881 882**错误码：** 883 884以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 885 886| 错误码ID | 错误信息 | 887| ------- | -------------------------------------------- | 888| 1400003 | This display manager service works abnormally. | 889 890**示例：** 891 892```js 893let modeIndex = 0; 894try { 895 let promise = screenClass.setScreenActiveMode(modeIndex); 896 promise.then((data) => { 897 console.info('Succeeded in setting screen active mode 0. Data: ' + JSON.stringify(data)); 898 }).catch((err) => { 899 console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(err)); 900 }); 901} catch (exception) { 902 console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(exception)); 903}; 904``` 905 906### setDensityDpi 907 908setDensityDpi(densityDpi: number, callback: AsyncCallback<void>): void; 909 910设置屏幕的像素密度，使用callback异步回调。 911 912**系统能力：** SystemCapability.WindowManager.WindowManager.Core 913 914| 参数名 | 类型 | 必填 | 说明 | 915| ---------- | ------------------------- | ---- | ------------------------------------------------------------ | 916| densityDpi | number | 是 | 像素密度。支持的输入范围为80-640。 | 917| callback | AsyncCallback<void> | 是 | 回调函数。当设置屏幕的像素密度成功，err为undefined，否则为错误对象。 | 918 919**错误码：** 920 921以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 922 923| 错误码ID | 错误信息 | 924| ------- | -------------------------------------------- | 925| 1400003 | This display manager service works abnormally. | 926 927**示例：** 928 929```js 930let densityDpi = 320; 931try { 932 screenClass.setDensityDpi(densityDpi, (err, data) => { 933 if (err.code) { 934 console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(err)); 935 return; 936 } 937 console.info('Succeed in setting the pixel density of the screen to 320. data: ' + JSON.stringify(data)); 938 }); 939} catch (exception) { 940 console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(exception)); 941}; 942``` 943 944### setDensityDpi 945 946setDensityDpi(densityDpi: number): Promise<void> 947 948设置屏幕的像素密度，使用Promise异步回调。 949 950**系统能力：** SystemCapability.WindowManager.WindowManager.Core 951 952| 参数名 | 类型 | 必填 | 说明 | 953| ---------- | ------ | ---- | ---------------------------------- | 954| densityDpi | number | 是 | 像素密度。支持的输入范围为80-640。 | 955 956**返回值：** 957 958| 类型 | 说明 | 959| ------------------- | ------------------------- | 960| Promise<void> | 无返回结果的Promise对象。 | 961 962**错误码：** 963 964以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 965 966| 错误码ID | 错误信息 | 967| ------- | -------------------------------------------- | 968| 1400003 | This display manager service works abnormally. | 969 970**示例：** 971 972```js 973let densityDpi = 320; 974try { 975 let promise = screenClass.setDensityDpi(densityDpi); 976 promise.then((data) => { 977 console.info('Succeeded in setting the pixel density of the screen to 320. Data: ' + JSON.stringify(data)); 978 }).catch((err) => { 979 console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(err)); 980 }); 981} catch (exception) { 982 console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(exception)); 983}; 984``` 985 986## Orientation 987 988屏幕方向枚举。 989 990**系统能力：** SystemCapability.WindowManager.WindowManager.Core 991 992| 名称 | 值 | 说明 | 993| ------------------ | ---- | -------------------------------- | 994| UNSPECIFIED | 0 | 表示未指定屏幕方向，由系统指定。 | 995| VERTICAL | 1 | 表示指定屏幕为垂直方向。 | 996| HORIZONTAL | 2 | 表示指定屏幕为水平方向。 | 997| REVERSE_VERTICAL | 3 | 表示指定屏幕为反向垂直方向。 | 998| REVERSE_HORIZONTAL | 4 | 表示指定屏幕为反向水平方向。 | 999 1000## ScreenModeInfo 1001 1002屏幕显示模式信息。 1003 1004**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1005 1006| 名称 | 类型 | 可读 | 可写 | 说明 | 1007| ----------- | -------- | ---- | ---- | -------------------------------------------------- | 1008| id | number | 是 | 是 | 模式id，所支持的模式由具体设备分辨率和刷新率决定。 | 1009| width | number | 是 | 是 | 屏幕的宽度，单位为像素。 | 1010| height | number | 是 | 是 | 屏幕的高度，单位为像素。 | 1011| refreshRate | number | 是 | 是 | 屏幕的刷新率。 |