1# @system.app (应用上下文)
2
3> **说明：**
4>
5> 本模块首批接口从API version 3开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
6
7
8## 导入模块
9
10
11```ts
12import app, { AppResponse } from '@system.app'
13```
14
15## App
16
17### getInfo
18
19static getInfo(): AppResponse
20
21获取当前应用配置文件中声明的信息。在Stage模型下接口返回值为null。
22
23从API Version9开始，推荐使用[bundleManager.getBundleInfoForSelf](../apis-ability-kit/js-apis-bundleManager.md#bundlemanagergetbundleinfoforself)。
24
25**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
26
27**系统能力：** SystemCapability.ArkUI.ArkUI.Lite
28
29**返回值：**
30
31| 参数类型 | 说明 |
32| -------- | -------- |
33| [AppResponse](#appresponse) | 定义AppResponse信息。 |
34
35**示例：**
36
37```ts
38import app, { AppResponse } from '@system.app'
39export default class Info {
40  getInfo() {
41    let info:AppResponse = app.getInfo()
42    console.log(JSON.stringify(info))
43  }
44}
45```
46
47### terminate
48
49static terminate(): void
50
51退出当前Ability。在Stage模型下接口功能不生效。
52
53从API Version 7开始，推荐使用[`@ohos.ability.featureAbility`](../apis-ability-kit/js-apis-ability-featureAbility.md)。
54
55**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
56
57**系统能力：** SystemCapability.ArkUI.ArkUI.Lite
58
59**示例：**
60
61```ts
62import app, { AppResponse } from '@system.app'
63export default class TerM {
64  terminate() {
65    app.terminate()
66  }
67}
68```
69### setImageCacheCount<sup>7+</sup>
70
71static setImageCacheCount(value: number): void
72
73设置内存中缓存解码后图片的数量上限，提升再次加载同源图片的加载速度。如果不设置则默认为0，不进行缓存。缓存采用内置的LRU策略，新图片加载后，如果超过缓存上限，会删除最久未再次加载的缓存。建议根据应用内存需求，设置合理缓存数量，数字过大可能导致内存使用过高。
74
75setImageCacheCount方法需要在@Entry标记的页面，[onPageShow](../apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#onpageshow)或[aboutToAppear](../apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#abouttoappear)里面设置才生效。
76
77setImageCacheCount、setImageRawDataCacheSize、和setImageFileCacheSize并不灵活，后续不继续演进，对于复杂情况，更推荐使用[ImageKnife](https://gitee.com/openharmony-tpc/ImageKnife)。
78
79**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
80
81**系统能力：** SystemCapability.ArkUI.ArkUI.Full
82
83**参数：**
84
85| 参数名 | 类型 | 必填 | 说明 |
86| -------- | -------- | -------- | -------- |
87| value | number | 是 | 内存中解码后图片的缓存数量。 |
88
89**示例：**
90
91```ts
92// xxx.ets
93import app, { AppResponse } from '@system.app'
94
95@Entry
96@Component
97struct Index {
98  onPageShow() {
99    // 设置解码后图片内存缓存上限为100张
100    app.setImageCacheCount(100)
101    console.info('Application onPageShow')
102  }
103  onDestroy() {
104    console.info('Application onDestroy')
105  }
106
107  build() {
108    Row(){
109      // xxxxxxxxxxxxx为图片地址
110      Image('xxxxxxxxxxxxx')
111        .width(200)
112        .height(50)
113    }.width('100%')
114  }
115}
116```
117
118### setImageRawDataCacheSize<sup>7+</sup>
119
120static setImageRawDataCacheSize(value: number): void
121
122设置内存中缓存解码前图片数据的大小上限，单位为字节，提升再次加载同源图片的加载速度。如果不设置则默认为0，不进行缓存。缓存采用内置的LRU策略，新图片加载后，如果解码前数据超过缓存上限，会删除最久未再次加载的图片数据缓存。建议根据应用内存需求，设置合理缓存上限，过大可能导致应用内存使用过高。
123
124setImageRawDataCacheSize方法需要在@Entry标记的页面，[onPageShow](../apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#onpageshow)或[aboutToAppear](../apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#abouttoappear)里面设置才生效。
125
126**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
127
128**系统能力：** SystemCapability.ArkUI.ArkUI.Full
129
130**参数：**
131
132| 参数名 | 类型 | 必填 | 说明 |
133| -------- | -------- | -------- | -------- |
134| value | number | 是 | 内存中解码前图片数据的缓存大小，单位为字节。 |
135
136**示例：**
137
138```ts
139// xxx.ets
140import app, { AppResponse } from '@system.app'
141
142@Entry
143@Component
144struct Index {
145  onPageShow() {
146    // 设置解码前图片数据内存缓存上限为100MB (100MB=100*1024*1024B=104857600B)
147    app.setImageRawDataCacheSize(104857600)
148    console.info('Application onPageShow')
149  }
150  onDestroy() {
151    console.info('Application onDestroy')
152  }
153
154  build() {
155    Row(){
156      // xxxxxxxxxxxxx为图片地址
157      Image('xxxxxxxxxxxxx')
158        .width(200)
159        .height(50)
160    }.width('100%')
161  }
162}
163```
164
165### setImageFileCacheSize<sup>7+</sup>
166
167static setImageFileCacheSize(value: number): void
168
169设置图片文件缓存的大小上限，单位为字节，提升再次加载同源图片的加载速度，特别是对网络图源会有较明显提升。如果不设置则默认为100MB。缓存采用内置的LRU策略，新图片加载后，如果超过文件缓存上限，会按照时间由远到近删除缓存图片文件直到缓存图片大小满足缓存上限。建议根据应用实际需求，设置合理文件缓存上限，数字过大可能导致磁盘空间占用过高。
170
171**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
172
173**系统能力：** SystemCapability.ArkUI.ArkUI.Full
174
175**参数：**
176
177| 参数名 | 类型 | 必填 | 说明 |
178| -------- | -------- | -------- | -------- |
179| value | number | 是 | 图片文件的缓存大小，单位为字节。 |
180
181**示例：**
182
183```ts
184// app.ets
185import app, { AppResponse } from '@system.app'
186
187export default class OnC {
188  onCreate() {
189    app.setImageFileCacheSize(209715200)
190    // 设置图片文件数据缓存上限为200MB (200MB=200*1024*1024B=209715200B)
191    console.info('Application onCreate')
192  }
193  onDestroy() {
194    console.info('Application onDestroy')
195  }
196}
197```
198
199### ScreenOnVisible<sup>(deprecated)</sup>
200
201static screenOnVisible(options?: ScreenOnVisibleOptions):&nbsp;void
202
203定义屏幕唤醒时是否保持应用可见。
204
205该接口从API Version 8 开始废弃。
206
207**系统能力：**  以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full
208
209| 名称    | 类型                                              | 必填 | 说明                                                         |
210| ------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ |
211| options | [ScreenOnVisibleOptions](#screenonvisibleoptions) | 否   | 当启动保活时，锁屏时将阻止系统返回桌面显示，以保持屏幕唤醒时应用可见。 |
212
213### requestFullWindow<sup>(deprecated)</sup>
214
215static requestFullWindow(options?: RequestFullWindowOptions): void
216
217请求应用以全窗口运行，FA在某些场景下（如半模态FA）会以非全窗口运行，调用该接口会从非全窗口切换为全窗口运行，如果已经以全窗口运行则该接口调用无效。
218
219从API Version 7开始，推荐使用[`@ohos.window`](js-apis-window.md)。
220
221**系统能力：** SystemCapability.ArkUI.ArkUI.Full
222
223**参数：**
224
225| 参数名  | 类型                                                  | 必填 | 说明                                                         |
226| ------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ |
227| options | [RequestFullWindowOptions](#requestfullwindowoptions) | 否   | 请求全屏时，设定非全屏到全屏的过渡时间，单位为毫秒，默认时间与非全屏到全屏的距离成正比。 |
228
229**示例：**
230
231```ts
232import app, { AppResponse } from '@system.app'
233export default class Req {
234  requestFullWindow() {
235    app.requestFullWindow({
236      duration: 200
237    })
238  }
239}
240```
241
242## AppResponse
243
244定义AppResponse信息。
245
246**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
247
248**系统能力：**  以下各项对应的系统能力有所不同，详见下表。
249
250| 名称 | 类型 | 必填 | 说明 |
251| -------- | -------- | -------- |-------- |
252| appID<sup>6+</sup> | string | 是 | 表示应用的包名，用于标识应用的唯一性。 <br> **系统能力：** SystemCapability.ArkUI.ArkUI.Full|
253| appName | string | 是 | 表示应用的名称。 <br> **系统能力：** SystemCapability.ArkUI.ArkUI.Lite|
254| versionName | string | 是 | 表示应用的版本名称。 <br> **系统能力：** SystemCapability.ArkUI.ArkUI.Lite|
255| versionCode | number | 是 | 表示应用的版本号。 <br> **系统能力：** SystemCapability.ArkUI.ArkUI.Lite|
256
257## ScreenOnVisibleOptions
258
259定义屏幕上可见接口的选项。
260
261**系统能力：**  以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full
262
263| 名称 | 类型 | 必填 | 说明 |
264| -------- | -------- | -------- | -------- |
265| visible | boolean | 否 | 是否启动保活，默认值false。 |
266| success | () => void | 否 | 接口调用成功的回调函数。 |
267| fail | (data: string, code: number) => void | 否 | 接口调用失败的回调函数。 |
268| complete | () => void | 否 | 接口调用结束的回调函数。 |
269
270## RequestFullWindowOptions
271
272定义RequestFullWindow接口的选项。
273
274**系统能力：**  以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full
275
276| 名称 | 类型 | 必填 | 说明 |
277| -------- | -------- | -------- | -------- |
278| duration | number | 是 | 定义动画选项的持续时间，单位为毫秒。 |
279
280