1# @ohos.enterprise.deviceSettings （设备设置管理）
2
3本模块提供企业设备设置能力，包括获取设备息屏时间等。
4
5> **说明：**
6>
7> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 本模块接口仅可在Stage模型下使用。
10>
11> 本模块接口仅对[设备管理应用](../../mdm/mdm-kit-guide.md#功能介绍)开放，需将设备管理应用激活后调用，实现相应功能。
12
13## 导入模块
14
15```ts
16import { deviceSettings } from '@kit.MDMKit';
17```
18
19## deviceSettings.setValue
20
21setValue(admin: Want, item: string, value: string): void
22
23修改设备设置策略。
24
25**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SETTINGS
26
27**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
28
29**参数：**
30
31| 参数名 | 类型                                                    | 必填 | 说明                                                         |
32| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
33| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。                                               |
34| item   | string                                                  | 是   | 设备设置策略类型。<br/>- screenOff：设备息屏策略，对于2in1设备，仅支持设置电池供电下的息屏策略。<br/>- dateTime：设置系统时间。<br/>- powerPolicy：设备电源策略，对于2in1设备，仅支持设置电池供电下的电源策略。 |
35| value  | string                                                  | 是   | 策略类型值。<br/>当item为screenOff时，value为设备息屏时间（单位：毫秒）。<br/>当item为dateTime时，value为要设置的系统时间（单位：毫秒）。<br/>当item为powerPolicy时，value为JSON字符串，格式：{"powerScene":xx,"powerPolicy":{"powerPolicyAction":xx,"delayTime":xx}}。powerScene为电源策略场景；delayTime为延迟时间（单位：毫秒），不支持设置为30000毫秒；powerPolicyAction为休眠策略。<br/>电源策略场景：<br/>- 0：超时场景。<br/>休眠策略：<br/>- 0：不执行动作。<br/>- 1：自动进入睡眠。<br/>- 2：强制进入睡眠。<br/>- 3：进入休眠。（当前电源子系统暂不支持）<br/>- 4：关机。 |
36
37**错误码**：
38
39以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
40
41| 错误码ID | 错误信息                                                     |
42| -------- | ------------------------------------------------------------ |
43| 9200001  | The application is not an administrator application of the device. |
44| 9200002  | The administrator application does not have permission to manage the device. |
45| 201      | Permission verification failed. The application does not have the permission required to call the API. |
46| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
47
48**示例：**
49
50```ts
51import { Want } from '@kit.AbilityKit';
52let wantTemp: Want = {
53  bundleName: 'com.example.myapplication',
54  abilityName: 'EntryAbility',
55};
56
57try {
58  deviceSettings.setValue(wantTemp, 'screenOff', '3000');
59  console.info(`Succeeded in setting screen off time.`);
60} catch (err) {
61  console.error(`Failed to set screen off time. Code: ${err.code}, message: ${err.message}`);
62}
63```
64
65## deviceSettings.getValue
66
67getValue(admin: Want, item: string): string
68
69获取设备设置策略。
70
71**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SETTINGS
72
73**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
74
75**参数：**
76
77| 参数名 | 类型                                                    | 必填 | 说明                                                         |
78| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
79| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。                                               |
80| item   | string                                                  | 是   | 设备设置策略类型。<br/>- screenOff：设备息屏策略，对于2in1设备，仅支持查询电池供电下的息屏策略。<br/>- dateTime：设置系统时间。<br/>- powerPolicy：设备电源策略，对于2in1设备，仅支持查询电池供电下的电源策略。 |
81
82**返回值：**
83
84| 类型   | 说明                                                         |
85| ------ | ------------------------------------------------------------ |
86| string | 策略类型值。<br/>当item为screenOff时，返回设备息屏时间（单位：毫秒），对于2in1设备，返回设备电池供电下的息屏时间（单位：毫秒）；<br/>当item为dateTime时，返回设置的系统时间（单位：毫秒）；<br/>当item为powerPolicy时，返回电源策略，对于2in1设备，返回设备电池供电下的电源策略，格式为JSON字符串:{"powerScene":xx,"powerPolicy":{"powerPolicyAction":xx,"delayTime":xx}}。powerScene为电源策略场景；delayTime为延迟时间（单位：毫秒）；powerPolicyAction为休眠策略。<br/>电源策略场景：<br/>- 0：超时场景。<br/>休眠策略：<br/>- 0：不执行动作。<br/>- 1：自动进入睡眠。<br/>- 2：强制进入睡眠。<br/>- 3：进入休眠。（当前电源子系统暂不支持）<br/>- 4：关机。 |
87
88**错误码**：
89
90以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
91
92| 错误码ID | 错误信息                                                     |
93| -------- | ------------------------------------------------------------ |
94| 9200001  | The application is not an administrator application of the device. |
95| 9200002  | The administrator application does not have permission to manage the device. |
96| 201      | Permission verification failed. The application does not have the permission required to call the API. |
97| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
98
99**示例：**
100
101```ts
102import { Want } from '@kit.AbilityKit';
103let wantTemp: Want = {
104  bundleName: 'com.example.myapplication',
105  abilityName: 'EntryAbility',
106};
107
108try {
109  let result: string = deviceSettings.getValue(wantTemp, 'screenOff');
110  console.info(`Succeeded in getting screen off time, result : ${result}`);
111} catch (err) {
112  console.error(`Failed to get screen off time. Code: ${err.code}, message: ${err.message}`);
113}
114```
115