diff --git a/en/application-dev/reference/apis/js-apis-system-app.md b/en/application-dev/reference/apis/js-apis-system-app.md new file mode 100644 index 0000000000000000000000000000000000000000..a8b05874b03db6ec3f0cd7cc39135a160ba38b6c --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-system-app.md @@ -0,0 +1,208 @@ +# Application Context + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> - The APIs of this module are no longer maintained since API version 7. You are advised to use the new APIs specified in the API descriptions. +> +> - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. + + +## Modules to Import + + +``` +import app from '@system.app'; +``` + + +## app.getInfo + +getInfo(): AppResponse + +Obtains the declared information in the **config.json** file of an application. + +**System capability**: SystemCapability.ArkUI.ArkUI.Lite + +**Return value** + +| Type| Description| +| -------- | -------- | +| [AppResponse](#appresponse) | Application response information.| + +**Example** + + ``` + export default { + getInfo(){ + var info = app.getInfo(); + console.log(JSON.stringify(info)); + } + } + ``` + +## app.terminate + +terminate(): void + +Terminates the current ability. + +**System capability**: SystemCapability.ArkUI.ArkUI.Lite + +**Example** + + ``` + export default { + terminate(){ + app.terminate(); + }} + ``` +## app.requestFullWindow + +requestFullWindow(options?: RequestFullWindowOptions): void + +Requests the application to run in full window. You can call this API when the FA runs in a non-full window, for example, semi-modal FA. This API is invalid for an application already in full-window mode. + +This is a system API and cannot be called by third-party applications. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| options | [RequestFullWindowOptions](#requestfullwindowoptions) | No| Duration for transition from the non-full window to the full window, in milliseconds. By default, the value is in direct proportion to the distance between the non-full window and the full window.| + +**Example** + + ``` + export default { + requestFullWindow(){ + app.requestFullWindow({ + duration: 200}); + } + } + ``` + +## app.setImageCacheCount7+ + +setImageCacheCount(value: number): void + +Sets the maximum number of decoded images that can be cached in the memory to speed up the loading of images from the same sources. If the input parameter is not set, the default value **0** is used, indicating that images are not cached. The built-in Least Recently Used (LRU) policy is used for caching. If the maximum number is exceeded, the images that have not been updated for the longest time will be removed. You are advised to set the parameter based on the application memory requirements. If the number of images is too large, the memory usage may be too high. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| value | number | No| Number of decoded images that are cached in the memory.| + +**Example** + + ``` + // app.ets + import app from '@system.app'; + + export default { + onCreate() { + app.setImageCacheCount(100) // Set the maximum number of decoded images that can be cached in the memory to 100. + console.info('Application onCreate') + }, + onDestroy() { + console.info('Application onDestroy') + }, + } + ``` + +## app.setImageRawDataCacheSize7+ + +setImageRawDataCacheSize(value: number): void + +Sets the maximum size (in bytes) of the image data cached in the memory before decoding to speed up the loading of images from the same sources. If the input parameter is not set, the default value **0** is used, indicating that images are not cached. The LRU policy is used for caching. If the maximum size is exceeded, the images that have not been updated for the longest time will be removed. You are advised to set the parameter based on the application memory requirements. If the image cache is too large, the memory usage may be too high. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| value | number | No| Size of the image data cached before decoding, in bytes.| + +**Example** + + ``` + // app.ets + import app from '@system.app'; + + export default { + onCreate() { + app.setImageRawDataCacheSize(104,857,600) // Set the upper limit of the memory for caching image data before decoding to 100 MB. + console.info('Application onCreate') + }, + onDestroy() { + console.info('Application onDestroy') + }, + } + ``` + +## app.setImageFileCacheSize7+ + +setImageFileCacheSize(value: number): void + +Sets the maximum size of the image file cache (in bytes) to speed up the loading of images from the same sources, especially online image sources and thumbnails. If the input parameter is not set, the default value 100 MB is used. The LRU policy is used for caching. If the maximum size is exceeded, the images that have not been updated for the longest time will be removed. You are advised to set the parameter based on the application memory requirements. If the image cache is too large, the disk usage may be too high. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| value | number | No| Size of the image file cache, in bytes.| + +**Example** + + ``` + // app.ets + import app from '@system.app'; + + export default { + onCreate() { + app.setImageFileCacheSize(209,715,200) // Set the upper limit of the image file cache to 200 MB. + console.info('Application onCreate') + }, + onDestroy() { + console.info('Application onDestroy') + }, + } + ``` + +## AppResponse + +Defines the application response information. + +**System capability**: The items in the table below require different system capabilities. For details, see the table. + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- |-------- | +| appID6+ | string | Yes| Bundle name of an application. It uniquely identifies the application.
**System capability**: SystemCapability.ArkUI.ArkUI.Full| +| appName | string | Yes| Application name.
**System capability**: SystemCapability.ArkUI.ArkUI.Lite| +| versionName | string | Yes| Application version name.
**System capability**: SystemCapability.ArkUI.ArkUI.Lite| +| versionCode | number | Yes| Application version number.
**System capability**: SystemCapability.ArkUI.ArkUI.Lite| + +## ScreenOnVisibleOptions + +Defines the options of the visible interface on the screen. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| visible | boolean | No| Whether to keep the application visible. The default value is **false**.| +| success | () => void | No| Callback upon success.| +| fail | (data: string, code: number) => void | No| Callback upon failure.| +| complete | () => void | No| Called when the API call is complete.| + +## RequestFullWindowOptions + +Defines the options of the **RequestFullWindow** API. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| duration | number | Yes| Number of animation options.| diff --git a/en/application-dev/reference/apis/js-apis-system-mediaquery.md b/en/application-dev/reference/apis/js-apis-system-mediaquery.md new file mode 100644 index 0000000000000000000000000000000000000000..78b8807adbcb9456f5515fe926ccfbdd4ba3ba44 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-system-mediaquery.md @@ -0,0 +1,123 @@ +# Media Query + + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. + + +## Modules to Import + + +``` +import mediaquery from '@system.mediaquery'; +``` + + +## mediaquery.matchMedia + +matchMedia(condition: string): MediaQueryList + +Creates a **MediaQueryList** object based on the query condition. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| condition | string | Yes| Query condition.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| MediaQueryList | Attributes of the **MediaQueryList** object created. For details, see **MediaQueryList** attributes.| + +**Example** + +``` +export default { + matchMedia() { + var mMediaQueryList = mediaquery.matchMedia('(max-width: 466)'); + }, +} +``` + +## MediaQueryEvent + +Defines a media query event. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| matches | boolean | Yes| Matching result.| + +## MediaQueryList + +Defines a media query list. + +### Attributes + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| media | string | No| Serialized media query condition. This parameter is read-only.| +| matches | boolean | Yes| Matching result.| + +### onchange + +onchange?: (matches: boolean) => void + +Called when the **matches** value changes. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| matches | boolean | Yes| New **matches** value.| + + +### MediaQueryList.addListener + +addListener(callback: (event: MediaQueryEvent) => void): void + +Adds a listener for this **MediaQueryList** object. The listener must be added before **onShow** is called, that is, it must be added in the **onInit** or **onReady** API. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | (event: MediaQueryEvent) => void | Yes| Callback invoked when the matching condition changes.| + +**Example** + +``` +mMediaQueryList.addListener(maxWidthMatch); +``` + + +### MediaQueryList.removeListener + +removeListener(callback: (event: MediaQueryEvent) => void): void + +Removes the listener for this **MediaQueryList** object. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | (event: MediaQueryEvent) => void) | Yes| Callback invoked when the matching condition changes.| + +**Example** + +``` +mMediaQueryList.removeListener(maxWidthMatch); +``` diff --git a/en/application-dev/reference/apis/js-apis-system-router.md b/en/application-dev/reference/apis/js-apis-system-router.md new file mode 100644 index 0000000000000000000000000000000000000000..d45acd3f12bdc5520d783101e9c3a9dc2780bf71 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-system-router.md @@ -0,0 +1,395 @@ +# Page Routing + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The APIs of this module are no longer maintained since API version 8. You are advised to use ['@ohos.router'](js-apis-router.md) instead. + + +## Modules to Import + + +``` +import router from '@system.router'; +``` + +## router.push + +push(options: RouterOptions): void + +Navigates to a specified page in the application. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| options | [RouterOptions](#routeroptions) | Yes| Page routing parameters. For details, see **RouterOptions**.| + +**Example** + +``` +// Current page +export default { + pushPage() { + router.push({ + uri: 'pages/routerpage2/routerpage2', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + }, + }, + }); + } +} +``` + + +``` +// routerpage2 page +export default { + data: { + data1: 'default', + data2: { + data3: [1, 2, 3] + } + }, + onInit() { + console.info('showData1:' + this.data1); + console.info('showData3:' + this.data2.data3); + } +} +``` + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> The page routing stack supports a maximum of 32 pages. + + +## router.replace + +replace(options: RouterOptions): void + +Replaces the current page with another one in the application and destroys the current page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Lite + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| options | [RouterOptions](#routeroptions) | Yes| Page routing parameters. For details, see **RouterOptions**.| + +**Example** + +``` +// Current page +export default { + replacePage() { + router.replace({ + uri: 'pages/detail/detail', + params: { + data1: 'message', + }, + }); + } +} +``` + + +``` +// detail page +export default { + data: { + data1: 'default' + }, + onInit() { + console.info('showData1:' + this.data1) + } +} +``` + +## router.back + +back(options?: BackRouterOptions): void + +Returns to the previous page or a specified page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| options | [BackRouterOptions](#backrouteroptions) | Yes| For details, see **BackRouterOptions**.| + +**Example** + +``` +// index page +export default { + indexPushPage() { + router.push({ + uri: 'pages/detail/detail', + }); + } +} +``` + + +``` +// detail page +export default { + detailPushPage() { + router.push({ + uri: 'pages/mall/mall', + }); + } +} +``` + + +``` +// Navigate from the mall page to the detail page through router.back(). +export default { + mallBackPage() { + router.back(); + } +} +``` + + +``` +// Navigate from the detail page to the index page through router.back(). +export default { + defaultBack() { + router.back(); + } +} +``` + + +``` +// Return to the detail page through router.back(). +export default { + backToDetail() { + router.back({uri:'pages/detail/detail'}); + } +} +``` + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> In the example, the **uri** field indicates the page route, which is specified by the **pages** list in the **config.json** file. + +## router.getParams + +getParams(): ParamsInterface + +Obtains parameter information about the current page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Return value** + +| Type| Description| +| -------- | -------- | +| [ParamsInterface](#paramsinterface) | For details, see **ParamsInterface**.| + +## router.clear + +clear(): void + +Clears all historical pages in the stack and retains only the current page at the top of the stack. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Example** + +``` +export default { + clearPage() { + router.clear(); + } +} +``` + +## router.getLength + +getLength(): string + +Obtains the number of pages in the current stack. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Return value** + +| Type| Description| +| -------- | -------- | +| string | Number of pages in the stack. The maximum value is **32**.| + +**Example** + +``` +export default { + getLength() { + var size = router.getLength(); + console.log('pages stack size = ' + size); + } +} +``` + +## router.getState + +getState(): RouterState + +Obtains state information about the current page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Return value** + +| Type| Description| +| -------- | -------- | +| [RouterState](#routerstate) | For details, see **RouterState**.| + +**Example** + +``` +export default { + getState() { + var page = router.getState(); + console.log('current index = ' + page.index); + console.log('current name = ' + page.name); + console.log('current path = ' + page.path); + } +} +``` + +## router.enableAlertBeforeBackPage6+ + +enableAlertBeforeBackPage(options: EnableAlertBeforeBackPageOptions): void + +Enables the display of a confirm dialog box before returning to the previous page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| options | [EnableAlertBeforeBackPageOptions](#enableAlertbeforebackpageoptions6) | Yes| For details, see **EnableAlertBeforeBackPageOptions**.| + +**Example** + +``` +export default { + enableAlertBeforeBackPage() { + router.enableAlertBeforeBackPage({ + message: 'Message Info', + success: function() { + console.log('success'); + }, + fail: function() { + console.log('fail'); + }, + }); + } +} +``` + +## router.disableAlertBeforeBackPage6+ + +disableAlertBeforeBackPage(options?: DisableAlertBeforeBackPageOptions): void + +Disables the display of a confirm dialog box before returning to the previous page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| options | [DisableAlertBeforeBackPageOptions](#disablealertbeforebackpageoptions6) | No| For details, see **DisableAlertBeforeBackPageOptions**.| + +**Example** + +``` +export default { + disableAlertBeforeBackPage() { + router.disableAlertBeforeBackPage({ + success: function() { + console.log('success'); + }, + fail: function() { + console.log('fail'); + }, + }); + } +} +``` + +## RouterOptions + +Defines the page routing parameters. + +**System capability**: SystemCapability.ArkUI.ArkUI.Lite + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| uri | string | Yes| URI of the destination page, in either of the following formats:
1. Absolute path, which is provided by the **pages** list in the **config.json** file. Example:
- pages/index/index
-pages/detail/detail
2. Specific path. If the URI is a slash (/), the home page is displayed.| +| params | Object | No| Data that needs to be passed to the destination page during redirection. After the destination page is displayed, it can use the passed data, for example, **this.data1** (**data1** is a key in **params**). If there is the same key (for example, **data1**) on the destination page, the passed **data1** value will replace the original value on the destination page.| + + +## BackRouterOptions + +Defines the parameters for routing back. + +**System capability**: The items in the table below require different system capabilities. For details, see the table. + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| uri | string | No| URI of the page to return to. If the specified page does not exist in the page stack, the application does not respond. If this parameter is not set, the application returns to the previous page.
**System capability**: SystemCapability.ArkUI.ArkUI.Full| +| params | Object | No| Data that needs to be passed to the destination page during redirection.
**System capability**: SystemCapability.ArkUI.ArkUI.Lite| + +## RouterState + +Defines the page state. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- |-------- | +| index | number | Yes| Index of the current page in the stack. The index starts from 1 from the bottom to the top of the stack.| +| name | string | Yes| Name of the current page, that is, the file name.| +| path | string | Yes| Path of the current page.| + +## EnableAlertBeforeBackPageOptions6+ + +Defines the **EnableAlertBeforeBackPage** parameters. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| message | string | Yes| Content displayed in the confirm dialog box.| +| success | (errMsg: string) => void | No| Called when a dialog box is displayed. **errMsg** indicates the returned information.| +| fail | (errMsg: string) => void | No| Called when the API fails to be called. **errMsg** indicates the returned information.| +| complete | () => void | No| Called when the API call is complete.| + +## DisableAlertBeforeBackPageOptions6+ + +Define the **DisableAlertBeforeBackPage** parameters. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| success | (errMsg: string) => void | No| Called when a dialog box is displayed. **errMsg** indicates the returned information.| +| fail | (errMsg: string) => void | No| Called when the API fails to be called. **errMsg** indicates the returned information.| +| complete | () => void | No| Called when the API call is complete.| + +## ParamsInterface + +| Name| Type| Description| +| -------- | -------- | -------- | +| [key: string] | Object| List of routing parameters.|