Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
未验证 提交 1814c646 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!10301 翻译完成 8281/8969/9020/8645/9014/9073 

Merge pull request !10301 from ester.zhou/C1-1008
上级 9ba9bae4 aac7e98e
显示空白变更内容
内联 并排
Showing with 1124 addition and 825 deletion
en/application-dev/quick-start/package-structure.md
浏览文件 @ 1814c646
......@@ -2,19 +2,19 @@
# Application Package Structure Configuration File
In an application development project, you need to declare the package structure of the application in the **config.json** file.
When developing an application, you must declare the package structure of the application in the **config.json** file.
## Internal Structure of the config.json File
The **config.json** file consists of three mandatory tags, namely, **app**, **deviceConfig**, and **module**. See Table 1 for details.
The **config.json** file consists of three mandatory tags, namely, **app**, **deviceConfig**, and **module**. For details, see Table 1.
Table 1 Internal structure of the config.json file
| Tag | Description | Data Type| Initial Value Allowed|
| ------------ | ------------------------------------------------------------ | -------- | ---------- |
| app | Global configuration of an application. Different HAP files of the same application must use the same **app** configuration. For details, see [Internal Structure of the app Tag](#internal-structure-of-the-app-tag).| Object | No |
| app | Global configuration of the application. Different HAP files of the same application must use the same **app** configuration. For details, see [Internal Structure of the app Tag](#internal-structure-of-the-app-tag).| Object | No |
| deviceConfig | Application configuration applied to a specific type of device. For details, see [Internal Structure of the deviceconfig Tag](#internal-structure-of-the-deviceconfig-tag).| Object | No |
| module | Configuration of a HAP file. The **module** configuration is valid only for the current HAP file. For details, see [Internal Structure of the module Tag](#internal-structure-of-the-module-tag).| Object | No |
| module | Configuration of a HAP file. It is valid only for the current HAP file. For details, see [Internal Structure of the module Tag](#internal-structure-of-the-module-tag).| Object | No |
Example of the **config.json** file:
......@@ -87,11 +87,11 @@ The **app** tag contains the global configuration information of the application
Table 2 Internal structure of the app tag
| Attribute | Description | Data Type| Initial Value Allowed |
| ---------- | ------------------------------------------------------------ | -------- | ------------------ |
| bundleName | Bundle name of the application. It uniquely identifies the application. The bundle name can contain only letters, digits, underscores (_), and periods (.). It must start with a letter. The value is a string with 7 to 127 bytes of a reverse domain name, for example, **com.example.myapplication**. It is recommended that the first level be the domain suffix "com" and the second level be the vendor/individual name. More levels are also accepted.| String | No |
| vendor | Description of the application vendor. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| version | Version information of the application. For details, see Table 3. | Object | No |
| apiVersion | OpenHarmony API version on which the application depends. For details, see Table 4. | Object | Yes (initial value: left empty)|
| ----------------- | ------------------------------------------------------------ | -------- | --------------------------- |
| bundleName | Bundle name, which uniquely identifies an application. The bundle name can contain only letters, digits, underscores (_), and periods (.). It must start with a letter. The value is a string with 7 to 127 bytes of a reverse domain name, for example, **com.example.myapplication**. It is recommended that the first level be the domain suffix "com" and the second level be the vendor/individual name. More levels are also accepted.| String | No |
| vendor | Description of the application vendor. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty) |
| version | Version of the application. For details, see Table 3. | Object | No |
| apiVersion | OpenHarmony API version on which the application depends. For details, see Table 4. | Object | Yes (initial value: left empty) |
Table 3 Internal structure of version
......@@ -99,7 +99,7 @@ Table 3 Internal structure of version
| ------------------------ | ------------------------------------------------------------ | -------- | -------------------------- |
| name | Application version number visible to users. The value can be customized and cannot exceed 127 bytes. The customization rules are as follows:<br>API 5 and earlier versions: A three-segment version number is recommended, for example, A.B.C (also compatible with A.B). In the version number, A, B, and C are integers ranging from 0 to 999. Other formats are not supported.<br> A indicates the major version number. <br> B indicates the minor version number.<br> C indicates the patch version number.<br>API 6 and later versions: A four-segment version number is recommended, for example, A.B.C.D. In the version number, A, B, and C are integers ranging from 0 to 99, and D is an integer ranging from 0 to 999.<br> A indicates the major version number. <br> B indicates the minor version number.<br> C indicates the feature version number.<br> D indicates the patch version number.| Number | No |
| code | Application version number used only for application management by OpenHarmony. This version number is not visible to users of the application. The value rules are as follows:<br>API 5 and earlier versions: It is a non-negative integer less than 32 bits in binary mode, converted from the value of version.name as follows: The conversion rules are as follows:<br> Value of **code** = A * 1,000,000 + B * 1,000 + C. For example, if the value of **version.name** is 2.2.1, the value of **code** is 2002001.<br> API 6 and later versions: The value of **code** is not associated with the value of **version.name** and can be customized. The value is a non-negative integer ranging from 2 to 31. Note that the value must be updated each time the application version is updated. The value for a later version must be greater than that for an earlier version.| Number | No |
| minCompatibleVersionCode | Minimum compatible version of the application. It is used to check whether the application is compatible with the version on other devices in the cross-device scenario.<br> The value rules are the same as those of **version.code**.| Number | No (initial value: **code** attribute value)|
| minCompatibleVersionCode | Earliest version compatible with the application. It is used in the cross-device scenario to check whether the application is compatible with a specific version on other devices.<br> The value rules are the same as those of **version.code**.| Number | No (initial value: **code** attribute value)|
Table 4 Internal structure of apiVersion
......@@ -133,13 +133,13 @@ The **deviceConfig** tag contains the application configuration information on t
Table 5 Internal structure of the deviceConfig tag
| Attribute | Description | Data Type| Initial Value Allowed |
| ------------ | ----------------------------------------------- | -------- | ------------------ |
| default | Application configuration applied to all types of devices. See Table 6. | Object | No |
| tablet | Application configuration specific to tablets. See Table 6. | Object | Yes (initial value: left empty)|
| tv | Application configuration specific to smart TVs. See Table 6. | Object | Yes (initial value: left empty)|
| car | Application configuration specific to head units. See Table 6. | Object | Yes (initial value: left empty)|
| wearable | Application configuration specific to wearables. See Table 6. | Object | Yes (initial value: left empty)|
| Attribute| Description | Data Type| Initial Value Allowed |
| -------- | ----------------------------------------- | -------- | ------------------ |
| default | Application configuration applied to all types of devices. For details, see Table 6.| Object | No |
| tablet | Application configuration specific to tablets. For details, see Table 6. | Object | Yes (initial value: left empty)|
| tv | Application configuration specific to smart TVs. For details, see Table 6. | Object | Yes (initial value: left empty)|
| car | Application configuration specific to head units. For details, see Table 6. | Object | Yes (initial value: left empty)|
| wearable | Application configuration specific to wearables. For details, see Table 6.| Object | Yes (initial value: left empty)|
For details about the internal structures of device attributes, see Table 6.
......@@ -147,12 +147,12 @@ Table 6 Internal structure of device attributes
| Attribute | Description | Data Type| Initial Value Allowed |
| ------------------ | ------------------------------------------------------------ | -------- | ----------------------- |
| process | Name of the process running the application or ability. If the **process** attribute is configured in the **deviceConfig** tag, all abilities of the application run in this process. You can set the **process** attribute for a specific ability in the **abilities** attribute, so that the ability can run in the particular process. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. The value can contain a maximum of 31 characters.| String | Yes |
| process | Process running the application or ability. If the **process** attribute is configured in the **deviceConfig** tag, all abilities of the application run in this process. You can set the **process** attribute for a specific ability in the **abilities** attribute, so that the ability can run in the particular process. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. The value can contain a maximum of 31 characters.| String | Yes |
| supportBackup | Whether the application supports backup and restoration. The value **false** means that the application does not support backup or restoration.<br> This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean | Yes (initial value: **false**)|
| compressNativeLibs | Whether the **libs** libraries are packaged in the HAP file after being compressed. The value **false** means that the **libs** libraries are stored without being compressed and will be directly loaded during the installation of the HAP file.<br> This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean | Yes (initial value: **true**) |
| directLaunch | Whether the application can be started when the device is locked. The value **true** means that the application can be started when the device is locked. Devices running OpenHarmony do not support this attribute.| Boolean | Yes (initial value: **false**)|
| ark | Maple configuration. See Table 7. | Object | Yes (initial value: left empty) |
| network | Network security configuration. You can customize the network security settings of the application in the security statement of the configuration file without modifying the application code. See Table 9.| Object | Yes (initial value: left empty) |
| ark | Maple configuration. For details, see Table 7. | Object | Yes (initial value: left empty) |
| network | Network security configuration. You can customize the network security settings of the application in the security statement of the configuration file without modifying the application code. For details, see Table 9.| Object | Yes (initial value: left empty) |
Table 7 Internal structure of the ark attribute
......@@ -179,9 +179,9 @@ Table 10 Internal structure of the securityConfig attribute
| Attribute | Sub-attribute | Description | Data Type| Initial Value Allowed |
| -------------- | ------------------ | ------------------------------------------------------------ | -------- | ---------------- |
| domainSettings | - | Security settings of the custom network domain. This attribute allows nested domains. To be more specific, the **domainSettings** object of a large domain can be nested with the **domainSettings** objects of small network domains.| Object| Yes (initial value: left empty)|
| domainSettings | - | Security settings of the custom network domain. This attribute allows nested domains. That is, the **domainSettings** object of a network domain can be nested with the **domainSettings** objects of smaller network domains.| Object| Yes (initial value: left empty)|
| | cleartextPermitted | Whether plaintext traffic can be transmitted in the custom network domain. If both **cleartextTraffic** and **security** are declared, whether plaintext traffic can be transmitted in the custom network domain is determined by the **cleartextPermitted** attribute.<br>**true**: Plaintext traffic can be transmitted.<br>**false**: Plaintext traffic cannot be transmitted.| Boolean| No |
| | domains | Domain name configuration. This attribute consists of the **subdomains** and **name** sub-attributes.<br> **subdomains** (boolean): specifies whether the domain name contains subdomains. If this sub-attribute is set to **true**, the domain naming convention applies to all related domains and subdomains (including the lower-level domains of the subdomains). Otherwise, the convention applies only to exact matches.<br> **name** (string): indicates the domain name.| Object array| No |
| | domains | Domain name. This attribute consists of two sub-attributes: **subdomains** and **name**.<br> **subdomains** (boolean): specifies whether the domain name contains subdomains. If this sub-attribute is set to **true**, the domain naming convention applies to all related domains and subdomains (including the lower-level domains of the subdomains). Otherwise, the convention applies only to exact matches.<br> **name** (string): indicates the domain name.| Object array| No |
Example of the deviceConfig tag structure:
......@@ -215,32 +215,32 @@ The **module** tag contains the configuration information of the HAP file. For d
Table 11 Internal structure of the module tag
| Attribute | Description | Data Type | Initial Value Allowed |
| --------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ |
| ----------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ |
| mainAbility | Ability displayed on the Service Center icon. When the resident process is started, the **mainAbility** is started.| String | No if any ability using the Page template exists |
| package | Structure name of the HAP file, which must be unique in the application. The value is a string with a maximum of 127 bytes, in the reverse domain name notation. It is recommended that the value be the same as the project directory of the HAP file. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | No |
| name | Class name of the HAP file. The value is in the reverse domain name notation. The prefix must be the same as the package name specified by the **package** label at the same level. The value can also start with a period (.). The value is a string with a maximum of 255 bytes.<br> This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | No |
| package | Package name of the HAP file, which must be unique in the application. The value is a string with a maximum of 127 bytes, in the reverse domain name notation. It is recommended that the value be the same as the project directory of the HAP file. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. | String | No |
| name | Class name of the HAP file. The value is in the reverse domain name notation, with the prefix same as the package name specified by **package** at the same level. It can also start with a period (.). The value is a string with a maximum of 255 bytes.<br> This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | No |
| description | Description of the HAP file. The value is a string with a maximum of 255 bytes. If the value exceeds the limit or needs to support multiple languages, you can use a resource index to the description. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty) |
| supportedModes | Mode supported by the application. Currently, only the **drive** mode is defined. This attribute applies only to head units.| String array| Yes (initial value: left empty) |
| deviceType | Type of device on which the abilities can run. The device types predefined in the system include **tablet**, **tv**, **car**, and **wearable**.| String array| No |
| distro | Distribution description of the current HAP file. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. For details, see Table 12.| Object | No |
| deviceType | Type of device on which the ability can run. The device types predefined in the system include **tablet**, **tv**, **car**, and **wearable**.| String array| No |
| distro | Distribution description of the HAP file. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. For details, see Table 12.| Object | No |
| metaData | Metadata of the HAP file. For details, see Table 13. | Object | Yes (initial value: left empty) |
| abilities | All abilities in the current module. The value is an array of objects, each of which represents a shortcut object. For details, see Table 17.| Object array | Yes (initial value: left empty) |
| js | A set of JS modules developed using the ArkUI framework. Each element in the set represents the information about a JS module. For details, see Table 22.| Object array | Yes (initial value: left empty) |
| shortcuts | Shortcut information of the application. The value is an array of objects, each of which represents a shortcut object. For details, see Table 25.| Object array | Yes (initial value: left empty) |
| reqPermissions | Permissions that the application applies for from the system before its running. For details, see Table 21. | Object array | Yes (initial value: left empty) |
| colorMode | Color mode of the application.<br>**dark**: Resources applicable for the dark mode are selected.<br>**light**: Resources applicable for the light mode are selected.<br>**auto**: Resources are selected based on the color mode of the system.<br>This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. | String | Yes (initial value: **auto**) |
| distroFilter | Application distribution rules.<br>AppGallery uses these rules to distribute HAP files to the matching devices. Distribution rules cover three factors: API version, screen shape, and screen resolution. AppGallery distributes a HAP file to the device whose on the mapping between **deviceType** and these three factors. For details, see Table 29. | Object | Yes (initial value: left empty)<br/>Set this attribute when an application has multiple entry modules. |
| js | A set of JS modules developed using ArkUI. Each element in the set represents the information about a JS module. For details, see Table 22.| Object array | Yes (initial value: left empty) |
| shortcuts | Shortcuts of the application. The value is an array of objects, each of which represents a shortcut object. For details, see Table 25.| Object array | Yes (initial value: left empty) |
| reqPermissions | Permissions that the application requests from the system when it is running. For details, see Table 21. | Object array | Yes (initial value: left empty) |
| colorMode | Color mode of the application.<br> **dark**: Resources applicable for the dark mode are selected.<br> **light**: Resources applicable for the light mode are selected.<br> **auto**: Resources are selected based on the color mode of the system.<br> This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: **auto**) |
| distroFilter | Distribution rules of the application.<br> AppGallery uses these rules to distribute HAP files to the matching devices. Distribution rules cover three factors: API version, screen shape, and screen resolution. AppGallery distributes a HAP file to the device whose on the mapping between **deviceType** and these three factors. For details, see Table 29.| Object | Yes (initial value: left empty) Set this attribute when an application has multiple entry modules.|
| reqCapabilities | Device capabilities required for running the application. | String array| Yes (initial value: left empty) |
| commonEvents | Static broadcast. For details, see Table 35. | Object array | Yes (initial value: left empty) |
| allowClassMap | Metadata of the HAP file. The value can be **true** or **false**. If the value is **true**, the HAP file uses the Java object proxy mechanism provided by the OpenHarmony framework. | Boolean | No (initial value: **false**) |
| entryTheme | Keyword of an OpenHarmony internal theme. Set it to the resource index of the name.| String | Yes (initial value: left empty) |
| entryTheme | Keyword of an OpenHarmony internal theme. Set it to the resource index of the name. | String | Yes (initial value: left empty) |
Example of the **module** tag structure:
```json
"module": {
"mainAbility": "MainAbility",
"package": "com.example.myapplication.rntry",
"package": "com.example.myapplication.entry",
"name": ".MyOHOSAbilityPackage",
"description": "$string:description_application",
"supportModes": [
......@@ -273,8 +273,8 @@ Table 12 Internal structure of the distro attribute
| Attribute | Description | Data Type| Initial Value Allowed|
| ---------------- | ------------------------------------------------------------ | -------- | ---------- |
| moduleName | Name of the current HAP file. The maximum length is 31 characters. | String | No |
| moduleType | Type of the current HAP file. The value can be **entry** or **feature**. For the HAR type, set this attribute to **har**.| String | No |
| moduleName | Name of the HAP file. The maximum length is 31 characters. | String | No |
| moduleType | Type of the HAP file. The value can be **entry** or **feature**. For the HAR type, set this attribute to **har**.| String | No |
| installationFree | Whether the HAP file supports the installation-free feature.<br> **true**: The HAP file supports the installation-free feature and meets installation-free constraints.<br> **false**: The HAP file does not support the installation-free feature.<br> Pay attention to the following:<br> When **entry.hap** is set to **true**, all **feature.hap** fields related to **entry.hap **must be **true**.<br> When **entry.hap** is set to **false**, **feature.hap** related to **entry.hap** can be set to **true** or **false** based on service requirements.| Boolean | No |
Example of the **distro** attribute structure:
......@@ -299,9 +299,9 @@ Table 14 Internal structure of the parameters attribute
| Attribute | Description | Data Type| Initial Value Allowed |
| ----------- | ------------------------------------------------------------ | -------- | ------------------ |
| description | Description of the parameter. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty)|
| name | Name of the parameter. The value can contain a maximum of 255 characters. | String | Yes (initial value: left empty)|
| type | Type of the parameter, for example, **Integer**. | String | No |
| description | Description of the parameter passed for calling the ability. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty)|
| name | Name of the parameter passed for calling the ability. The value can contain a maximum of 255 characters. | String | Yes (initial value: left empty)|
| type | Type of the parameter passed for calling the ability, for example, **Integer**. | String | No |
Table 15 Internal structure of the results attribute
......@@ -315,9 +315,9 @@ Table 16 Internal structure of the customizeData attribute
| Attribute| Description | Data Type| Initial Value Allowed |
| -------- | ---------------------------------------------------------- | -------- | -------------------- |
| name | Key of a data element. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| value | Value of a data element. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| extra | Custom format of the data element. The value is an index to the resource that identifies the data.| String | Yes (initial value: left empty)|
| name | Key of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| value | Value of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| extra | Custom format of the data item. The value is an index to the resource that identifies the data.| String | Yes (initial value: left empty)|
Example of the **metaData** attribute structure:
......@@ -346,19 +346,19 @@ Table 17 Internal structure of the abilities attribute
| Attribute | Description | Data Type | Initial Value Allowed |
| ---------------- | ------------------------------------------------------------ | ---------- | -------------------------------------------------------- |
| process | Name of the process running the application or ability. If the **process** attribute is configured in the **deviceConfig** tag, all abilities of the application run in this process. You can set the **process** attribute for a specific ability in the **abilities** attribute, so that the ability can run in the particular process. If this attribute is set to the name of the process running other applications, all these applications can run in the same process, provided they have the same unified user ID and the same signature. Devices running OpenHarmony do not support this attribute.| String | Yes (initial value: left empty) |
| name | Name of the ability. The value is a reverse domain name, in the format of "*Bundle name*.*Class name*", for example, **"com.example.myapplication.MainAbility"**. Alternatively, the value can start with a period (.) followed by the class name, for example, **".MainAbility"**.<br> The ability name must be unique in an application. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.<br> Note: When you use DevEco Studio to create a project, the configuration of the first ability is generated by default, including the **MainAbility.java** file and the class name **MainAbility** defaulted in the **name** string for the **abilities** attribute in **config.json**. The value of this attribute can be customized if you use other IDE tools. The value can contain a maximum of 127 characters.| String | No |
| name | Ability name. The value can be a reverse domain name, in the format of "*Bundle name*.*Class name*", for example, **"com.example.myapplication.MainAbility"**. Alternatively, the value can start with a period (.) followed by the class name, for example, **".MainAbility"**.<br> The ability name must be unique in an application. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.<br> Note: If you use DevEco Studio to create the project, an ability named **MainAbility** will be created together with the default configuration in the **config.json** file. The value of this attribute can be customized if you use other IDEs. The value can contain a maximum of 127 characters.| String | No |
| description | Description of the ability. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty) |
| icon | Index to the ability icon file. Example value: **$media:ability_icon**. In the **skills** attribute of the ability, if the **actions** value contains **action.system.home** and the **entities** value contains **entity.system.home**, the icon of the ability is also used as the icon of the application. If multiple abilities address this condition, the icon of the first candidate ability is used as the application icon.<br> Note: The **icon** and **label** values of an application are visible to users. Ensure that at least one of them is different from any existing icons or labels.| String | Yes (initial value: left empty) |
| label | Ability name visible to users. The value can be a name string or a resource index to names in multiple languages. In the **skills** attribute of the ability, if the **actions** value contains **action.system.home** and the **entities** value contains **entity.system.home**, the label of the ability is also used as the label of the application. If multiple abilities address this condition, the label of the first candidate ability is used as the application label.<br> Note: The **icon** and **label** values of an application are visible to users. Ensure that at least one of them is different from any existing icons or labels. The value can be a reference to a string defined in a resource file or a string enclosed in brackets ({}). The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty) |
| uri | Uniform Resource Identifier (URI) of the ability. The value can contain a maximum of 255 characters. | String | Yes (No for abilities using the Data template) |
| launchType | Startup type of the ability. The value can be **standard** or **singleton**.<br>**standard**: Multiple **Ability** instances can be created during startup. Most abilities can use this type.<br>**singleton**: Only a single **Ability** instance can be created across all task stacks during startup. For example, a globally unique incoming call screen uses the singleton startup type. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: **"singleton"**) |
| launchType | Launch type of the ability. Available values are as follows:<br>**"standard"**: Multiple **Ability** instances can be created during startup. Most abilities can use this type.<br>**"singleton"**: Only a single **Ability** instance can be created across all task stacks during startup. For example, a globally unique incoming call screen uses the singleton startup type. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. | String | Yes (initial value: **"singleton"**) |
| visible | Whether the ability can be called by other applications.<br>**true**: The ability can be called by other applications.<br>**false**: The ability cannot be called by other applications.| Boolean | Yes (initial value: **false**) |
| permissions | Permissions required for abilities of another application to call the current ability, generally in the format of a reverse domain name. The value can be either the permissions predefined in the OS or your custom permissions.| String array| Yes (initial value: left empty) |
| permissions | Permissions required for abilities of another application to call the current ability. The value is an array of permission names predefined by the system, generally in the format of a reverse domain name the reverse domain name format (a maximum of 255 bytes).| String array| Yes (initial value: left empty) |
| skills | Types of the **want** that can be accepted by the ability. | Object array | Yes (initial value: left empty) |
| deviceCapability | Device capabilities required to run the ability.| String array| Yes (initial value: left empty) |
| metaData | Metadata. For details, see Table 13. | Object | Yes (initial value: left empty) |
| type | Type of the ability. Available values are as follows:<br>**page**: FA developed using the Page template to provide the capability of interacting with users.<br>**service**: PA developed using the Service template to provide the capability of running tasks in the background.<br>**data**: PA developed using the Data template to provide unified data access for external systems.<br>**CA**: ability that can be started by other applications as a window.| String | No |
| orientation | Display orientation of the ability. This attribute applies only to the ability using the Page template. Available values are as follows:<br>unspecified: indicates that the system automatically determines the display orientation of the ability.<br>**landscape**: indicates the landscape orientation.<br>**portrait**: indicates the portrait orientation.<br>**followRecent**: indicates that the orientation follows the most recent application in the stack.| String | Yes (initial value: **"unspecified"**) |
| type | Ability type. Available values are as follows:<br>**"page"**: FA developed using the Page template to provide the capability of interacting with users.<br>**"service"**: PA developed using the Service template to provide the capability of running tasks in the background.<br>**"data"**: PA developed using the Data template to provide unified data access for external systems.<br>**"CA"**: ability that can be started by other applications as a window. | String | No |
| orientation | Display orientation of the ability. This attribute applies only to the ability using the Page template. Available values are as follows:<br>**"unspecified"**: indicates that the system automatically determines the display orientation of the ability.<br>**"landscape"**: indicates the landscape orientation.<br>**"portrait"**: indicates the portrait orientation.<br>**"followRecent"**: indicates that the orientation follows the most recent application in the stack. | String | Yes (initial value: **"unspecified"**) |
| backgroundModes | Background service type of the ability. You can assign multiple background service types to a specific ability. This attribute applies only to the ability using the Service template. Available values are as follows:<br>**dataTransfer**: service for downloading, backing up, sharing, or transferring data from the network or peer devices<br>**audioPlayback**: audio playback service<br>**audioRecording**: audio recording service<br>**pictureInPicture**: picture in picture (PiP) and small-window video playback services<br>**voip**: voice/video call and VoIP services<br>**location**: location and navigation services<br>**bluetoothInteraction**: Bluetooth scanning, connection, and transmission services<br>**wifiInteraction**: WLAN scanning, connection, and transmission services<br>**screenFetch**: screen recording and screenshot services<br>**multiDeviceConnection**: multi-device interconnection service| String array| Yes (initial value: left empty) |
| grantPermission | Whether permissions can be granted for any data in the ability. | Boolean | Yes (initial value: left empty) |
| readPermission | Permission required for reading data in the ability. This attribute applies only to the ability using the Data template. The value is a string with a maximum of 255 bytes. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty) |
......@@ -366,15 +366,13 @@ Table 17 Internal structure of the abilities attribute
| configChanges | System configurations that the ability concerns. Upon any changes on the concerned configurations, the **onConfigurationUpdated** callback will be invoked to notify the ability. Available values are as follows:<br>**mcc**: indicates that the mobile country code (MCC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MCC is updated.<br>**mnc**: indicates that the mobile network code (MNC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MNC is updated.<br>**locale**: indicates that the locale is changed. Typical scenario: The user has selected a new language for the text display of the device.<br>**layout**: indicates that the screen layout is changed. Typical scenario: Currently, different display forms are all in the active state.<br>**fontSize**: indicates that font size is changed. Typical scenario: A new global font size is set.<br>**orientation**: indicates that the screen orientation is changed. Typical scenario: The user rotates the device.<br>**density**: indicates that the display density is changed. Typical scenario: The user may specify different display ratios, or different display forms are active at the same time.<br>**size**: indicates that the size of the display window is changed.<br>**smallestSize**: indicates that the length of the shorter side of the display window is changed.<br>**colorMode**: indicates that the color mode is changed.| String array| Yes (initial value: left empty) |
| mission | Task stack of the ability. This attribute applies only to the ability using the Page template. By default, all abilities in an application belong to the same task stack. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: bundle name of the application) |
| targetAbility | Target ability that this ability alias points to. This attribute applies only to the ability using the Page template. If the **targetAbility** attribute is set, only **name**, **icon**, **label**, **visible**, **permissions**, and **skills** take effect in the current ability (ability alias). Other attributes use the values of the **targetAbility** attribute. The target ability must belong to the same application as the alias and must be declared in **config.json** ahead of the alias. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty, indicating that the current ability is not an alias)|
| multiUserShared | Whether the ability supports data sharing among multiple users. This attribute applies only to the ability using the Data template. If this attribute is set to **true**, only one copy of data is stored for multiple users. Note that this attribute will invalidate the **visible** attribute. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean | Yes (initial value: **false**) |
| supportPipMode | Whether the ability allows the user to enter the Picture in Picture (PiP) mode. The PiP mode enables the user to watch a video in a small window that hovers on top of a full screen window (main window). This attribute applies only to the ability using the Page template. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean | Yes (initial value: **false**) |
| formsEnabled | Whether the ability can provide forms. This attribute applies only to the ability using the Page template.<br>**true**: This ability can provide forms.<br>**false**: This ability cannot provide forms.| Boolean | Yes (initial value: **false**) |
| forms | Details about the forms used by the ability. This attribute is valid only when **formsEnabled** is set to **true**. For details, see Table 27.| Object array | Yes (initial value: left empty) |
| srcLanguage | Programming language used to develop the ability. | String | The value can be **java**, **js**, or **ets**. |
| srcPath | Path of the JS code and components corresponding to the ability. | String | Yes (initial value: left empty) |
| multiUserShared | Whether the ability supports data sharing among multiple users. This attribute applies only to the ability using the Data template. If this attribute is set to **true**, only one copy of data is stored for multiple users. Note that this attribute will invalidate the **visible** attribute. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean| Yes (initial value: **false**) |
| supportPipMode | Whether the ability allows the user to enter the Picture in Picture (PiP) mode. The PiP mode enables the user to watch a video in a small window that hovers on top of a full screen window (main window). This attribute applies only to the ability using the Page template. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean| Yes (initial value: **false**) |
| formsEnabled | Whether the ability can provide forms. This attribute applies only to the ability using the Page template.<br>**true**: This ability can provide forms.<br>**false**: This ability cannot provide forms.| Boolean| Yes (initial value: **false**) |
| forms | Information about the forms used by the ability. This attribute is valid only when **formsEnabled** is set to **true**. For details, see Table 27.| Object array | Yes (initial value: left empty) |
| srcLanguage | Programming language used to develop the ability. The value can be **"js"** or **"ets"**. | String | Yes |
| srcPath | Path of the JS component code corresponding to the ability. | String | Yes (initial value: left empty) |
| uriPermission | Application data that the ability can access. This attribute consists of the **mode** and **path** sub-attributes. This attribute is valid only for the capability of the type provider. Devices running OpenHarmony do not support this attribute. For details, see Table 18.| Object | Yes (initial value: left empty) |
| startWindowIcon | Index to the icon file of the ability startup page. Example value: **$media:icon**. | String | Yes (initial value: left empty) |
| startWindowBackground | Index to the background color resource file of the ability startup page. Example value: **$color:red**. | String | Yes (initial value: left empty) |
Table 18 Internal structure of the uriPermission attribute
......@@ -413,9 +411,7 @@ Example of the **abilities** attribute structure:
"fontSize",
"orientation"
],
"type": "page",
"startWindowIcon": "$media:icon",
"startWindowBackground": "$color:red"
"type": "page"
},
{
"name": ".PlayService",
......@@ -455,20 +451,20 @@ Table 19 Internal structure of the skills attribute
| Attribute| Description | Data Type | Initial Value Allowed |
| -------- | ------------------------------------------------------------ | ---------- | -------------------- |
| actions | Actions of the **want** that can be accepted by the ability. Generally, the value is an **action** value predefined in the system.| String array| Yes (initial value: left empty)|
| entities | Entities of the **want** that can be accepted by the ability, such as video and Home application.| String array| Yes (initial value: left empty)|
| entities | Entities of the **want** that can be accepted by the ability, such as video and home applications.| String array| Yes (initial value: left empty)|
| uris | URIs of the **want** that can be accepted by the ability. For details, see Table 20.| Object array | Yes (initial value: left empty)|
Table 20 Internal structure of the uris attribute
| Attribute | Description | Data Type| Initial Value Allowed |
| ------------- | -------------------------- | -------- | -------------------- |
| scheme | Scheme in the URI. | String | No |
| host | Host in the URI. | String | Yes (initial value: left empty)|
| port | Port number in the URI. | String | Yes (initial value: left empty)|
| pathStartWith | **pathStartWith** value in the URI.| String | String |
| path | Path in the URI. | String | Yes (initial value: left empty)|
| pathRegx | **pathRegx** value in the URI. | String | Yes (initial value: left empty)|
| type | Type of the URI. | String | Yes (initial value: left empty)|
| scheme | Scheme of the URI. | String | No |
| host | Host value of the URI. | String | Yes (initial value: left empty)|
| port | Port number of the URI. | String | Yes (initial value: left empty)|
| pathStartWith | **pathStartWith** value of the URI.| String | Yes (initial value: left empty)|
| path | **path** value of the URI. | String | Yes (initial value: left empty)|
| pathRegx | **pathRegx** value of the URI. | String | Yes (initial value: left empty)|
| type | **type** value of the URI. | String | Yes (initial value: left empty)|
Example of the **skills** attribute structure:
......@@ -496,35 +492,35 @@ Example of the **skills** attribute structure:
Table 21 reqPermissions
| Attribute | Description | **Type**| **Value Range** | **Default Value** | **Restrictions** |
| --------- | ------------------------------------------------------------ | -------- | ----------------------------------------------------------- | ---------------------- | ------------------------------------------------------------ |
| name | Permission name, which is mandatory. | String | Custom | None | Parsing will fail if this field is not set. |
| reason | Reason for applying for the permission, which is mandatory only when applying for the **user_grant** permission.| String | The displayed text cannot exceed 256 bytes. | Empty | If the requested permission is **user_grant**, this attribute is required for the application to be released to AppGallery. Multi-language adaptation is required.|
| usedScene | Application scenario and timing for using the permission, which is mandatory when the requested permission is **user_grant**. This attribute consists of the **ability** and **when** sub-attributes. Multiple abilities can be configured.| Object | **ability**: ability name; **when**: **inuse** or **always**| **ability**: left empty; **when**: **inuse**| If the requested permission is **user_grant**, the **ability** sub-attribute is mandatory and **when** is optional. |
| Attribute | Description | Data Type| Initial Value Allowed |
| ---------- | ------------------------------------------------------------ | -------- | ------------------ |
| name | Name of the permission to request.| String| No|
| reason | Reason for requesting the permission. The value cannot exceed 256 bytes. Multi-language adaptation is required.| String| No if the requested permission is **user_grant** (if it is left empty, application release will be rejected)|
| usedScene | Application scenario and timing for using the permission. This attribute consists of the **ability** and **when** sub-attributes. **ability**: ability name. Multiple ability names can be configured. **when**: time for using the permission. The options are **inuse** and **always**.| Object| **ability**: mandatory for the **user_grant** permission and can be left empty in other cases<br> **when**: initial value allowed (initial value: **inuse**)|
Table 22 Internal structure of the js attribute
| Attribute| Description | Data Type| Initial Value Allowed |
| -------- | ------------------------------------------------------------ | -------- | ------------------------ |
| name | Name of a JavaScript component. The default value is **default**. | String | No |
| pages | Route information about all pages in the JavaScript component, including the page path and page name. The value is an array, in which each element represents a page. The first element in the array represents the home page of the JavaScript FA.| Array | No |
| name | Name of the JS component. The default value is **default**. | String | No |
| pages | Route information about all pages in the JS component, including the page path and page name. The value is an array, in which each element represents a page. The first element in the array represents the home page of the JavaScript FA.| Array | No |
| window | Window-related configurations. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. For details, see Table 23.| Object | Yes |
| type | Type of the JavaScript component. Available values are as follows:<br>**normal**: indicates that the JavaScript component is an application instance.<br>**form**: indicates that the JavaScript component is a widget instance.| String | Yes (initial value: **normal**)|
| mode | Development mode of the JavaScript component. For details, see Table 24. | Object | Yes (initial value: left empty) |
| type | Type of the JS component. Available values are as follows:<br>**normal**: indicates that the JavaScript component is an application instance.<br>**form**: indicates that the JavaScript component is a widget instance.| String | Yes (initial value: **normal**)|
| mode | Development mode of the JS component. For details, see Table 24. | Object | Yes (initial value: left empty) |
Table 23 Internal structure of the window attribute
| Attribute | Description | Data Type| Initial Value Allowed |
| --------------- | ------------------------------------------------------------ | -------- | ----------------------- |
| designWidth | Baseline width for page design, in pixels. The size of an element is scaled by the actual device width.| Number | Yes (initial value: 720px) |
| autoDesignWidth | Whether to automatically calculate the baseline width for page design. If it is set to **true**, the **designWidth** attribute becomes invalid. The baseline width is calculated based on the device width and screen density.| Boolean| Yes (initial value: **false**)|
| designWidth | Baseline width for page design. The size of an element is scaled by the actual device width.| Number | Yes (initial value: 720px) |
| autoDesignWidth | Whether to automatically calculate the baseline width for page design. If it is set to **true**, the **designWidth** attribute becomes invalid. The baseline width is calculated based on the device width and screen density.| Boolean | Yes (initial value: **false**)|
Table 24 Internal structure of the mode attribute
| Attribute| Description | Data Type | Initial Value Allowed |
| -------- | -------------------- | ----------------------------------- | --------------------------- |
| type | Type of the JavaScript component.| String. The value can be **pageAbility** or **form**.| Yes (initial value: **pageAbility**)|
| syntax | Syntax type of the JavaScript component.| String. The value can be **hml** or **ets**. | Yes (initial value: **hml**) |
| type | Type of the JS component. The value can be **"pageAbility"** or **"form"**. | String | Yes (initial value: **"pageAbility"**) |
| syntax | Syntax type of the JS component. The value can be **"hml"** or **"ets"**. | String | Yes (initial value: **"hml"**) |
Example of the **js** attribute structure:
......@@ -549,8 +545,8 @@ Table 25 Internal structure of the shortcuts attribute
| Attribute | Description | Data Type| Initial Value Allowed |
| ---------- | ------------------------------------------------------------ | -------- | ------------------ |
| shortcutId | Shortcut ID. The value is a string with a maximum of 63 bytes. | String | No |
| label | Label of the shortcut, that is, the text description displayed by the shortcut. The value can be a string or a resource index to the description. The value is a string with a maximum of 63 bytes.| String | Yes (initial value: left empty)|
| shortcutId | ID of the shortcut. The value is a string with a maximum of 63 bytes. | String | No |
| label | Label of the shortcut, that is, the text description displayed for the shortcut. The value can be a string or a resource index to the description. The value is a string with a maximum of 63 bytes.| String | Yes (initial value: left empty)|
| icon | Icon of the shortcut. The value is a resource index to the description. | String | Yes (initial value: left empty)|
| intents | Intents to which the shortcut points. The attribute consists of the **targetClass** and **targetBundle** sub-attributes. For details, see Table 26.| Object array| Yes (initial value: left empty)|
......@@ -558,7 +554,7 @@ Table 26 Internal structure of the intents attribute
| Attribute | Description | Data Type| Initial Value Allowed |
| ------------ | --------------------------------------- | -------- | -------------------- |
| targetClass | Class name for the target ability of the shortcut. | String | Yes (initial value: left empty)|
| targetClass | Target class of the shortcut. | String | Yes (initial value: left empty)|
| targetBundle | Application bundle name for the target ability of the shortcut.| String | Yes (initial value: left empty)|
Example of the **shortcuts** attribute structure:
......@@ -585,28 +581,26 @@ Table 27 Internal structure of the forms attribute
| name | Class name of the widget. The value is a string with a maximum of 127 bytes. | String | No |
| description | Description of the widget. The value can be a string or a resource index to descriptions in multiple languages. The value is a string with a maximum of 255 bytes.| String | Yes (initial value: left empty) |
| isDefault | Whether the widget is a default one. Each ability has only one default widget.<br>**true**: The widget is the default one.<br>**false**: The widget is not the default one.| Boolean | No |
| type | Type of the widget. Available values are as follows:<br>**Java**: indicates a Java-programmed widget.<br>**JS**: indicates a JavaScript-programmed widget.| String | No |
| type | Type of the widget. Available values are as follows:<br>**JS**: indicates a JavaScript-programmed widget. | String | No |
| colorMode | Color mode of the widget. Available values are as follows:<br>**auto**: The widget adopts the auto-adaptive color mode.<br>**dark**: The widget adopts the dark color mode.<br>**light**: The widget adopts the light color mode.| String | Yes (initial value: **auto**)|
| supportDimensions | Grid styles supported by the widget. Available values are as follows:<br>1 * 2: indicates a grid with one row and two columns.<br>2 * 2: indicates a grid with two rows and two columns.<br>2 * 4: indicates a grid with two rows and four columns.<br>4 * 4: indicates a grid with four rows and four columns.| String array| No |
| defaultDimension | Default grid style of the widget. The value must be available in the **supportDimensions** array of the widget.| String | No |
| landscapeLayouts | Landscape layouts for the grid styles. Values in this array must correspond to the values in the **supportDimensions** array. This field is required only by Java-programmed widgets.| String array| No |
| portraitLayouts | Portrait layouts for the grid styles. Values in this array must correspond to the values in the **supportDimensions** array. This field is required only by Java-programmed widgets.| String array| No |
| supportDimensions | Grid styles supported by the widget. Available values are as follows:<br>1 * 2: indicates a grid with one row and two columns.<br>2 * 1: indicates a grid with two rows and one column.<br>2 * 2: indicates a grid with two rows and two columns.<br>2 * 4: indicates a grid with two rows and four columns.<br>4 * 4: indicates a grid with four rows and four columns.| String array| No |
| defaultDimension | Default grid style of the widget. The value must be from the **supportDimensions** array of the widget.| String | No |
| updateEnabled | Whether the widget can be updated periodically. Available values are as follows:<br>**true**: The widget can be updated periodically, depending on the update way you select, either at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** is preferentially recommended.<br>**false**: The widget cannot be updated periodically.| Boolean | No |
| scheduledUpdateTime | Scheduled time to update the widget. The value is in 24-hour format and accurate to minute. | String | Yes (initial value: **0:0**) |
| updateDuration | Interval to update the widget. The value is a natural number, in the unit of 30 minutes.<br>If the value is **0**, this field does not take effect.<br>If the value is a positive integer ***N***, the interval is calculated by multiplying ***N*** and 30 minutes.| Number | Yes (initial value: **0**) |
| formConfigAbility | Link to a specific page of the application. The value is a URI. | String | Yes (initial value: left empty) |
| formConfigAbility | Name of the facility or activity used to adjust the ability. | String | Yes (initial value: left empty) |
| formVisibleNotify | Whether the widget is allowed to use the widget visibility notification. | String | Yes (initial value: left empty) |
| jsComponentName | Component name of the widget. The value is a string with a maximum of 127 bytes. This attribute is required only by JavaScript-programmed widgets.| String | No |
| metaData | Metadata of the widget. This attribute contains the array of the **customizeData** attribute. For details, see Table 13. | Object | Yes (initial value: left empty) |
| customizeData | Custom information about the widget. For details, see Table 28. | Object array | Yes (initial value: left empty) |
| metaData | Metadata of the widget. The value contains value of the **customizeData** attribute. For details, see Table 13. | Object | Yes (initial value: left empty) |
| customizeData | Custom information of the widget. For details, see Table 28. | Object array | Yes (initial value: left empty) |
Table 28 Internal structure of the customizeData attribute
| Attribute| Description | Data Type| Initial Value Allowed |
| -------- | --------------------------------------------------- | -------- | -------------------- |
| name | Name in the custom name-value pair. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| value | Value in the custom name-value pair. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| extra | Format of the current custom data. The value is the resource value of **extra**.| String | Yes (initial value: left empty)|
| name | Key name that identifies a data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| value | Value of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| extra | Current format of the custom data. The value indicates the resource.| String | Yes (initial value: left empty)|
Example of the **forms** attribute structure:
......@@ -630,9 +624,9 @@ Example of the **forms** attribute structure:
]
},
{
"name": "Form_Java",
"description": "It's Java Form",
"type": "Java",
"name": "Form_Js",
"description": "It's JS Form",
"type": "Js",
"colorMode": "auto",
"isDefault": false,
"updateEnabled": true,
......@@ -663,13 +657,13 @@ Example of the **forms** attribute structure:
Table 29 Internal structure of the distroFilter attribute
| Attribute | Description | Data Type| Initial Value Allowed|
| ------------- | ------------------------------------------------------------ | -------- | ---------- |
| apiVersion | Supported API versions. For details, see Table 30. | Object | No |
| screenShape | Supported screen shapes. For details, see Table 31. | Object array| No |
| screenWindow | Supported window resolutions when the application is running. This attribute applies only to the lite wearables. For details, see Table 32.| Object array| No |
| screenDensity | Pixel density of the screen, in dots per inch (DPI). For details, see Table 33. | Object array| No |
| countryCode | Country code used during application distribution. For details, see the ISO-3166-1 standard. Multiple enumerated values of countries and regions are supported. For details, see Table 34.| Object array| No |
| Attribute | Description | Data Type| Initial Value Allowed |
| ------------- | ------------------------------------------------------------ | -------- | -------------------- |
| apiVersion | Supported API versions. For details, see Table 30. | Object | No|
| screenShape | Supported screen shapes. For details, see Table 31. | Object array| No|
| screenWindow | Supported window resolutions for when the application is running. This attribute applies only to the lite wearables. For details, see Table 32.| Object array| No|
| screenDensity | Pixel density of the screen, in dots per inch (dpi). For details, see Table 33. | Object array| No|
| countryCode | Country code used for distributing the application. For details, see the ISO-3166-1 standard. Multiple enumerated values of countries and regions are supported. For details, see Table 34.| Object array| No|
Table 30 Internal structure of the apiVersion attribute
......
en/application-dev/quick-start/stage-structure.md
浏览文件 @ 1814c646
......@@ -2,18 +2,18 @@
# Application Package Structure Configuration File
When developing an application in the Feature Ability (FA) model, you need to declare the package structure of the application in the **config.json** file. Similarly, when developing an application in the stage model, you need to declare the package structure of the application in the **module.json** and **app.json** files.
When developing an application in the Feature Ability (FA) model, you need to declare the package structure of the application in the **config.json** file. Similarly, when developing an application in the stage model, you need to declare the package structure of the application in the **module.json5** and **app.json** files.
## Configuration File Internal Structure
The configuration files consist of two parts: **app** and **module**. See Table 1 for details.
The configuration files each consist of two mandatory tags, namely, **app** and **module**. For details, see Table 1.
Table 1 Configuration file internal structure
| Tag| Description | Data Type| Initial Value Allowed|
| -------- | ------------------------------------------------------------ | -------- | ---------- |
| app | Global configuration of an application. Different HAP files of an application must use the same **app** configuration. For details, see [Internal Structure of the app Tag](#internal-structure-of-the-app-tag).| Object | No |
| module | Configuration of a HAP file. The **module** configuration is valid only for the current HAP file. For details, see [Internal Structure of the module Tag](#internal-structure-of-the-module-tag).| Object | No |
| app | Global configuration of the application. Different HAP files of an application must use the same **app** configuration. For details, see [Internal Structure of the app Tag](#internal-structure-of-the-app-tag).| Object | No |
| module | Configuration of the HAP file. It is valid only for the current HAP file. For details, see [Internal Structure of the module Tag](#internal-structure-of-the-module-tag).| Object | No |
### Internal Structure of the app Tag
......@@ -49,7 +49,7 @@ Table 2 Internal structure of the app tag
| Attribute | Description | Data Type| Initial Value Allowed |
| ------------------------------ | ------------------------------------------------------------ | -------- | ------------------------------------------- |
| bundleName | Bundle name that uniquely identifies the application. The value must comply with the following rules:<br> (1) Consists of letters, digits, underscores (_), and periods (.).<br> (2) Starts with a letter.<br> (3) Contains 7 to 127 bytes.<br>You are advised to use the reverse domain name notion, for example, *com.example.xxx*, where the first part is the domain suffix **com**, the second part is the vendor/individual name, and the third part is the application name, which can be of multiple levels.<br>For an application compiled with the system source code, its bundle name must be in the format of **com.ohos.*xxx***, where **ohos** signifies OpenHarmony. | String | No |
| bundleName | Bundle name that uniquely identifies the application. The value must comply with the following rules:<br> (1) Consists of letters, digits, underscores (_), and periods (.).<br> (2) Starts with a letter.<br> (3) Contains 7 to 127 bytes.<br> You are advised to use the reverse domain name notion, for example, *com.example.xxx*, where the first part is the domain suffix **com**, the second part is the vendor/individual name, and the third part is the application name, which can be of multiple levels.<br> For an application compiled with the system source code, its bundle name must be in the format of **com.ohos.*xxx***, where **ohos** signifies OpenHarmony. | String | No |
| debug | Whether the application can be debugged. | Boolean | Yes (initial value: **false**) |
| icon | Icon of the application. The value is the index to the resource file. | String | No |
| label | Name of the application. The value is a resource index to descriptions in multiple languages.| String | No |
......@@ -57,16 +57,16 @@ Table 2 Internal structure of the app tag
| vendor | Application vendor. The value is a string with a maximum of 255 bytes.| String | Yes (initial value: left empty) |
| versionCode | Version number of the application. The value is a 32-bit non-negative integer and less than 2 to the power of 31. It is used only to determine whether a version is later than another version. A larger value indicates a later version. Ensure that a new version of the application uses a value greater than any of its predecessors. | Number | No |
| versionName | Text description of the version number, which is displayed to users.<br>The value consists of only digits and dots. The four-segment format *A.B.C.D* is recommended, wherein:<br>Segment 1: major version number, which ranges from 0 to 99. A major version consists of major new features or large changes.<br>Segment 2: minor version number, which ranges from 0 to 99. A minor version consists of some new features and large bug fixes.<br>Segment 3: feature version number, which ranges from 0 to 99. A feature version consists of scheduled new features.<br>Segment 4: maintenance release number or patch number, which ranges from 0 to 999. A maintenance release or patch consists of resolution to security flaws or minor bugs.| String | No |
| minCompatibleVersionCode | Minimum API version compatible with the application. | Number | Yes (initial value: value of **versionCode**)|
| minCompatibleVersionCode | Earliest version that the application is compatible with. | Number | Yes (initial value: value of **versionCode**)|
| minAPIVersion | Minimum API version required for running the application. | Number | No |
| targetAPIVersion | Target API version required for running the application. | Integer | No |
| apiReleaseType | Type of the target API version required for running the application. The value can be **CanaryN**, **BetaN**, or **Release**, where **N** represents a positive integer.<br>**Canary**: indicates a restricted release.<br>**Beta**: indicates a publicly released beta version.<br>**Release**: indicates a publicly released official version.| String | Yes (initial value: **"Release"**) |
| distributedNotificationEnabled | Whether the distributed notification feature is enabled for the application. | Boolean | Yes (initial value: **true**) |
| entityType | Category of the application, which can be **game**, **media**, **communication**, **news**, **travel**, **utility**, **shopping**, **education**, **kids**, **business**, and **photography**.| String | Yes (initial value: unspecified) |
| entityType | Category of the application, which can be **game**, **media**, **communication**, **news**, **travel**, **utility**, **shopping**, **education**, **kids**, **business**, and **photography**.| String | Yes (initial value: **"unspecified"**) |
### Internal Structure of the module Tag
Example of the **module.json** file:
Code snippet in the **module.json5** file:
```json
{
......@@ -152,33 +152,33 @@ This tag stores the HAP configuration, which only applies to the current HAP fil
Table 3 Internal structure of the module tag
| Attribute | Description | Data Type | Initial Value Allowed |
| ------------------- | ------------------------------------------------------------ | ---------- | ------------------------------------- |
| -------------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ |
| name | Name of the current module. After the module is packed into a HAP file, this attribute indicates the name of the HAP file. The value is a string with a maximum of 31 bytes and must be unique in the entire application.| String | No |
| type | Type of the current HAP file. There are three types: **entry**, **feature**, and **har**.| String | No |
| type | Type of the HAP file. There are three types: **entry**, **feature**, and **har**.| String | No |
| srcEntrance | Path of the entry JS code corresponding to the HAP file. The value is a string with a maximum of 127 bytes.| String | Yes |
| description | Description of the HAP file. The value can be a string or a resource index to descriptions in multiple languages.| String | Yes (initial value: left empty) |
| process | Process of the HAP file. The value is a string with a maximum of 31 bytes. If a process is configured under **hap**, all abilities of the application run in this process.| String | Yes (initial value: name of the HAP file) |
| process | Process of the HAP file. The value is a string with a maximum of 31 bytes. If a process is configured under **hap**, all abilities of the application run in this process. This attribute applies only to system applications.| String | Yes (initial value: value of **bundleName** under the **app** tag) |
| mainElement | Entrance ability name or extension name of the HAP file. Only the ability or extension whose value is **mainElement** can be displayed in the Service Center. This attribute cannot be left at the initial value for an OpenHarmony atomic service.| String | Yes for an OpenHarmony application |
| deviceTypes | Types of the devices on which the HAP file can run. Table 4 lists the device types predefined by the system.<br>Different from **syscap**, which is based on the device capability (such as Bluetooth and Wi-Fi), **deviceTypes** is based on the device type.| String array| No (can be left empty) |
| deviceTypes | Types of the devices on which the HAP file can run. Table 4 lists the device types predefined by the system.<br>Unlike **syscap**, which is based on the device capability (such as Bluetooth and Wi-Fi), **deviceTypes** is based on the device type.| String array| No (can be left empty) |
| deliveryWithInstall | Whether the current HAP file will be installed when the user installs the application. The value **true** means that the HAP file will be automatically installed when the user installs the application, and **false** means the opposite.| Boolean | No |
| installationFree | Whether the HAP file supports the installation-free feature. <br>**true**: The HAP file supports the installation-free feature and meets installation-free constraints.<br>**false**: The HAP file does not support the installation-free feature.<br><br>When **entry.hap** is set to **true**, all **feature.hap** fields related to **entry.hap** must be **true**.<br>When **entry.hap** is set to **false**, **feature.hap** fields related to **entry.hap** can be set to **true** or **false** based on service requirements. | Boolean | No |
| virtualMachine | Type of the target virtual machine (VM) where the current HAP file is running. It is used for cloud distribution, such as the application market and distribution center.<br>The value **ark** means that the target VM type is Ark, and **default** means otherwise. This attribute is automatically inserted when DevEco Studio builds the HAP file. When the decompression tool parses the HAP file, if the HAP file does not contain this attribute, the value is set to **default**. | String | Yes (initial value: **default**) |
| uiSyntax | Syntax type of the JS component.<br>**hml**: indicates that the JS component is developed using HML, CSS, or JS.<br>**ets**: indicates that the JS component is developed using the eTS declarative syntax.| String | Yes (initial value: **hml**) |
| pages | Profile resource used to list information about each page in the JS component. For details about how to use **pages**, see the **pages** example.| Object | No in the ability scenario|
| metadata | Custom metadata of the HAP file. The configuration is valid only for the current module, ability, or extensionAbility. For details about **metadata**, see [Internal Structure of the metadata Attribute](#internal-structure-of-the-metadata-attribute).| Array | Yes (initial value: left empty) |
| abilities | Metadata capability configuration, which is valid only for the current ability. For details about **abilities**, see [Internal Structure of the abilities Attribute](#internal-structure-of-the-abilities-attribute).| Object | Yes (initial value: left empty) |
| extensionAbilities | Configuration of extensionAbilities, which is valid only for the current extensionAbility. For details about **extensionAbilities**, see [Internal structure of the extensionAbility attribute](#internal-structure-of-the-extensionability-attribute).| Object | Yes (initial value: left empty) |
| requestPermissions | A set of permissions that the application needs to apply for from the system when the application is running. For details about **requestPermissions**, see [Internal structure of the requestPermissions attribute](#internal-structure-of-the-requestpermissions-attribute).| Object | Yes (initial value: left empty) |
| installationFree | Whether the HAP file supports the installation-free feature.<br>**true**: The HAP file supports the installation-free feature and meets installation-free constraints.<br>**false**: The HAP file does not support the installation-free feature.<br><br>When **entry.hap** is set to **true**, all **feature.hap** fields related to **entry.hap** must be **true**.<br>When **entry.hap** is set to **false**, **feature.hap** fields related to **entry.hap** can be set to **true** or **false** based on service requirements. | Boolean | No |
| virtualMachine | Type of the target virtual machine (VM) where the current HAP file is running. It is used for cloud distribution, such as the application market and distribution center.<br>If the target VM type is Ark, the value is **ark**. Otherwise, the value is **default**. This attribute is automatically inserted when the IDE builds the HAP file. When the decompression tool parses the HAP file, if the HAP file does not contain this attribute, the value is set to **default**. | String | Yes (initial value: **default**) |
| uiSyntax | Syntax type of the JS component.<br>**"hml"**: indicates that the JS component is developed using HML, CSS, or JS.<br>**"ets"**: indicates that the JS component is developed using the eTS declarative syntax. | String | Yes (initial value: **"hml"**) |
| pages | Profile resource used to list information about each page in the JS component. For details about how to use **pages**, see the **pages** example.| Object | No in the ability scenario |
| metadata | Custom metadata of the HAP file. The configuration is valid only for the current module, ability, or extensionAbility. For details, see [Internal Structure of the metadata Attribute](#internal-structure-of-the-metadata-attribute). | Array | Yes (initial value: left empty) |
| abilities | Ability configuration, which is valid only for the current ability. For details, see [Internal Structure of the abilities Attribute](#internal-structure-of-the-abilities-attribute).| Object | Yes (initial value: left empty) |
| extensionAbilities | Extension ability configuration, which is valid only for the current Extension ability. For details, see [Internal structure of the extensionAbility attribute](#internal-structure-of-the-extensionability-attribute).| Object | Yes (initial value: left empty) |
| requestPermissions | A set of permissions that the application needs to request from the system when the application is running. For details, see [Internal structure of the requestPermissions attribute](#internal-structure-of-the-requestpermissions-attribute). | Object | Yes (initial value: left empty) |
Table 4 System-defined deviceTypes values
| Device Type | Value | Description |
| ----------- | -------- | -------------------------------------------------------- |
| Tablet | tablet | Tablet, speaker with a screen |
| Smart TV | tv | Smart TV |
| Smart watch | wearable | Smart watch, kids' watch, especially a watch that provides call features|
| Head unit | car | Head unit |
| Router | router | Router |
| Value | Device Type |
| -------- | -------------------------------------------------------- |
| tablet | Tablet, speaker with a screen |
| tv | Smart TV |
| wearable | Smart watch, kids' watch, especially a watch that provides call features|
| car | Head unit |
| router | Router |
Example of the **deviceTypes** attribute structure:
......@@ -232,8 +232,8 @@ Table 5 Internal structure of the metadata attribute
| Attribute| Description | Data Type| Initial Value Allowed |
| -------- | ------------------------------------------------------------ | -------- | -------------------------- |
| name | Name of a data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| value | Value of a data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty) |
| name | Name of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| value | Value of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty) |
| resource | Custom data format. The value is an index to the resource that identifies the data.| String | Yes (initial value: left empty) |
Example of the **metadata** attribute structure:
......@@ -267,14 +267,14 @@ Table 6 Internal structure of the abilities attribute
| --------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ |
| name | Logical name of the ability, which must be unique in the entire application. The value is a string with a maximum of 127 bytes.| String | No |
| srcEntrance | JS code path corresponding to the ability. The value is a string with a maximum of 127 bytes.| String | No |
| launchType | Ability startup mode. The value can be **standard**, **singleton**, or **specified**. The default value is **singleton**. The value **standard** indicates common multi-instance, the value **singleton** indicates a singleton, and the value **specified** indicates one or more specified instances, depending on the internal service of the ability.| String | Yes (initial value: **singleton**) |
| launchType | Ability startup mode. Available values are as follows:<br>**"standard"**: indicates common multi-instance.<br>**"singleton"**: indicates a singleton.<br>**"specified"**: indicates one or more specified instances, depending on the internal service of the ability. | String | Yes (initial value: **singleton**) |
| description | Ability description. The value can be a string or a resource index to descriptions in multiple languages.| String | Yes (initial value: left empty) |
| icon | Icon of the ability. The value is the index to the resource file. | String | Yes (initial value: left empty)<br>If **ability** is set to **MainElement**, this attribute is mandatory.|
| permissions | A set of permissions that need to be applied for when the capability of another application is invoked. The value is a string array. Each array element is a permission name, which is usually represented by a reverse domain name (a maximum of 255 bytes). The permission can be predefined by the system or customized by the application. For the latter, the value must be the same as the **name** value of a permission defined in the **defPermissions** attribute. | String array| Yes (initial value: left empty) |
| metadata | Metadata about the ability. For details about metadata, see [Internal Structure of the metadata Attribute](#internal-structure-of-the-metadata-attribute).| Array | Yes (initial value: left empty) |
| permissions | Permissions required for abilities of another application to call the current ability. The value is an array of permission names predefined by the system, generally in the format of a reverse domain name the reverse domain name format (a maximum of 255 bytes).| String array| Yes (initial value: left empty) |
| metadata | Metadata of the ability. For details, see [Internal Structure of the metadata Attribute](#internal-structure-of-the-metadata-attribute).| Array | Yes (initial value: left empty) |
| visible | Whether the ability can be invoked by other applications. The value **true** means that the ability can be invoked by other applications, and **false** means the opposite. | Boolean | Yes (initial value: **false**) |
| continuable | Whether the ability can be migrated. The value **true** means that the ability can be migrated, and **false** means the opposite.| Boolean | Yes (initial value: **false**) |
| skills | Feature set of wants that can be received by the ability.<br>Configuration rule: In an entry package, you can configure multiple abilities with the **skills** attribute (where **action.system.home** and **entity.system.home** are configured) that has the entry capability. The **label** and **icon** in the first ability that has **skills** configured are used as the **label** and **icon** of the entire service/application.<br>The **skills** attribute with the entry capability can be configured for the feature package of an OpenHarmony application,<br>but not for an OpenHarmony service.<br>For details about the internal structure of **skills**, see [Internal Structure of the skills Attribute](#internal-structure-of-the-skills-attribute).| Array | Yes (initial value: left empty) |
| skills | Feature set of wants that can be received by the ability.<br>Configuration rule: In an entry package, you can configure multiple abilities with the **skills** attribute (where **action.system.home** and **entity.system.home** are configured) that has the entry capability. The **label** and **icon** in the first ability that has **skills** configured are used as the **label** and **icon** of the entire service/application.<br>The **skills** attribute with the entry capability can be configured for the feature package of an OpenHarmony application,<br>but not for an OpenHarmony service.<br>For details, see [Internal Structure of the skills Attribute](#internal-structure-of-the-skills-attribute). | Array | Yes (initial value: left empty) |
| backgroundModes | Continuous task modes of the ability.<br>Continuous tasks are classified into the following types:<br>**dataTransfer**: service for downloading, backing up, sharing, or transferring data from the network or peer devices<br>**audioPlayback**: audio playback service<br>**audioRecording**: audio recording service<br>**location**: location and navigation services<br>**bluetoothInteraction**: Bluetooth scanning, connection, and transmission services (wearables)<br>**multiDeviceConnection**: multi-device interconnection service<br>**wifiInteraction**: Wi-Fi scanning, connection, and transmission services (multi-screen cloning)<br>**voip**: voice/video call and VoIP services<br>**taskKeeping**: computing service<br>| String | Yes (initial value: left empty) |
Example of the **abilities** attribute structure:
......@@ -322,17 +322,17 @@ Table 7 Internal structure of the skills attribute
| -------- | ------------------------------------------------------------ | ---------- | -------------------- |
| actions | A set of want action values that can be received. The value can be a value predefined by the system or a custom value.| String array| Yes (initial value: left empty)|
| entities | Categories of abilities that can receive the want. The value can be a value predefined by the system or a custom value.| String array| Yes (initial value: left empty)|
| uris | Data specification to be added to the want filter. The specification can be of data type only (**mimeType** attribute), URI only, or both. For details about the internal structure of **uris**, see Table 8.| Object array | Yes (initial value: left empty)|
| uris | Data specifications to be added to the want filter. The specification can be of data type only (**mimeType** attribute), URI only, or both. For details, see Table 8. | Object array | Yes (initial value: left empty)|
Table 8 Internal structure of the uris attribute
| Attribute| Description | Data Type| Initial Value Allowed |
| -------- | ------------------- | -------- | -------------------- |
| scheme | Scheme in the URI.| String | No |
| host | Host in the URI. | String | Yes (initial value: left empty)|
| port | Port number in the URI. | String | Yes (initial value: left empty)|
| path | Path in the URI. | String | Yes (initial value: left empty)|
| type | Type of the URI. | String | Yes (initial value: left empty)|
| scheme | Scheme of the URI.| String | No |
| host | Host value of the URI. | String | Yes (initial value: left empty)|
| port | Port number of the URI. | String | Yes (initial value: left empty)|
| path | **path** value of the URI. | String | Yes (initial value: left empty)|
| type | **type** value of the URI. | String | Yes (initial value: left empty)|
Example of the **skills** attribute structure:
......@@ -391,23 +391,23 @@ Example of the **skills** attribute structure:
#### Internal Structure of the extensionAbility Attribute
The **extensionAbility** attribute describes the configuration information of **extensionAbility**. The configuration is valid only for the current extensionAbility.
The **extensionAbility** attribute describes the configuration information of the current Extension ability.
Table 9 Internal structure of the extensionAbility attribute
| Attribute | Description | Data Type | Initial Value Allowed |
| ----------- | ------------------------------------------------------------ | ---------- | ----------------------------- |
| name | Logical name of the current extensionAbility. The value is a string with a maximum of 127 bytes. The name must be unique in the entire application.| String | No |
| srcEntrance | JS code path corresponding to extensionAbility. The value is a string with a maximum of 127 bytes.| String | No |
| description | Description of the extensionAbility. The value can be a string or a resource index to descriptions in multiple languages.| String | Yes (initial value: left empty) |
| icon | Icon of the extensionAbility. The value is the index to the resource file. If **extensionAbility** is set to **MainElement**, this attribute is mandatory.| String | Yes (initial value: left empty) |
| label | Name of the extensionAbility displayed to users. The value is a resource index to names in multiple languages.<br>If **extensionAbility** is set to **MainElement**, this attribute is mandatory and the value must be unique in the application.| String | No |
| type | Type of the extension capability. The value can be **form**, **workScheduler**, **inputMethod**, service, **accessibility**, **dataShare**, **fileShare**, **staticSubscriber**, **wallpaper**, **backup**, or **window**.| String | No |
| name | Logical name of the current Extension ability. The value is a string with a maximum of 127 bytes. The name must be unique in the entire application.| String | No |
| srcEntrance | JS code path corresponding to the Extension ability. The value is a string with a maximum of 127 bytes.| String | No |
| description | Description of the Extension ability. The value can be a string or a resource index to descriptions in multiple languages.| String | Yes (initial value: left empty) |
| icon | Icon of the Extension ability. The value is the index to the resource file. If **extensionAbility** is set to **MainElement**, this attribute is mandatory.| String | Yes (initial value: left empty) |
| label | Name of the Extension ability displayed to users. The value is a resource index to names in multiple languages.<br>If **extensionAbility** is set to **MainElement**, this attribute is mandatory and the value must be unique in the application.| String | No |
| type | Type of the Extension ability. The value can be **"form"**, **"workScheduler"**, **"inputMethod"**, **"service"**, **"accessibility"**, **"dataShare"**, **"fileShare"**, **"staticSubscriber"**, **"wallpaper"**, **"backup"**, **"window"**, **"enterpriseAdmin"**, **"thumbnail"**, or **"preview"**.| String | No |
| permissions | A set of permissions that need to be applied for when the capability of another application is invoked. The value is a string array. Each array element is a permission name, which is usually represented by a reverse domain name (a maximum of 255 bytes). The permission can be predefined by the system or customized by the application. For the latter, the value must be the same as the **name** value of a permission defined in the **defPermissions** attribute.| String array| Yes (initial value: left empty) |
| uri | Data URI provided by the ability. The value is an array containing a maximum of 255 characters and is in the format of a reverse domain name. This attribute is mandatory when **type** is set to **extensionAbility** of the dataShare type.| String | Yes (initial value: left empty) |
| skills | Feature set of wants that can be received by the ability.<br>Configuration rule: In an entry package, you can configure multiple abilities with the **skills** attribute (where **action.system.home** and **entity.system.home** are configured) that has the entry capability. The **label** and **icon** in the first ability that has **skills** configured are used as the **label** and **icon** of the entire service/application.<br>The **skills** attribute with the entry capability can be configured for the feature package of an OpenHarmony application, but not for an OpenHarmony service.<br>For details about the internal structure of **skills**, see [Internal Structure of the skills Attribute](#internal-structure-of-the-skills-attribute). | Array | Yes (initial value: left empty) |
| metadata | Metadata of extensionAbility. For details about metadata, see [Internal Structure of the metadata Attribute](#internal-structure-of-the-metadata-attribute).| Object | Yes (initial value: left empty) |
| visible | Whether extensionAbility can be invoked by other applications. The value is of the Boolean type. The value **true** means that it can be invoked by other applications, and the value **false** means the opposite.| | Yes (initial value: **false**)|
| skills | Feature set of wants that can be received by the ability.<br>Configuration rule: In an entry package, you can configure multiple abilities with the **skills** attribute (where **action.system.home** and **entity.system.home** are configured) that has the entry capability. The **label** and **icon** in the first ability that has **skills** configured are used as the **label** and **icon** of the entire service/application.<br>The **skills** attribute with the entry capability can be configured for the feature package of an OpenHarmony application,<br>but not for an OpenHarmony service.<br>For details, see [Internal Structure of the skills Attribute](#internal-structure-of-the-skills-attribute). | Array | Yes (initial value: left empty) |
| metadata | Metadata of the Extension ability. For details, see [Internal Structure of the metadata Attribute](#internal-structure-of-the-metadata-attribute).| Object | Yes (initial value: left empty) |
| visible | Whether extensionAbility can be invoked by other applications. The value is of the Boolean type. The value **true** means that it can be invoked by other applications, and the value **false** means the opposite.| Boolean | Yes (initial value: **false**)|
Example of the **extensionAbility** attribute structure:
......@@ -445,15 +445,15 @@ Example of the **extensionAbility** attribute structure:
#### Internal Structure of the requestPermissions Attribute
This attribute identifies a set of permissions that the application needs to apply for from the system when the application is running.
The **requestPermissions** attribute indicates the permissions defined for the HAP file.
Table 10 requestPermissions attributes
Table 10 Internal structure of the requestPermissions attribute
| Attribute | Description | **Type** | **Value Range** | **Default Value** | **Restrictions** |
| --------- | ------------------------------------------------------------ | ------------------------------- | ----------------------------------------------------------- | ---------------------- | ------------------------------------------------------------ |
| Attribute | Description | Type | Value Range | Default Value | Restrictions |
| --------- | ------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- | ------------------------------------------------------------ |
| name | Permission name. This attribute is mandatory. | String | Custom | N/A | Parsing will fail if this attribute is not set. |
| reason | Reason for requesting the permission. This attribute is mandatory when the permission to request is **user_grant**. | String | A maximum of 256 bytes | Empty | If the permission to request is **user_grant**, this attribute is required for the application to be released to AppGallery. Multi-language adaptation is required.|
| usedScene | Application scenario and timing for using the permission. This attribute is mandatory when the permission to request is **user_grant**. It consists of the **ability** and **when** sub-attributes. Multiple abilities can be configured.| **ability**: string array; **when**: string| **ability**: ability name; **when**: **inuse** or **always**| **ability**: null; **when**: **inuse**| If the permission to request is **user_grant**, the **ability** sub-attribute is mandatory and **when** is optional. |
| reason | Reason for requesting the permission. This attribute is mandatory when the permission to request is **user_grant**. | String | Resource reference of the string type in `$string: ***` format | Empty | If the permission to request is **user_grant**, this attribute is required for the application to be released to AppGallery. Multi-language adaptation is required. |
| usedScene | Application scenario and timing for using the permission. This attribute is mandatory when the permission to request is **user_grant**. It consists of the **abilities** and **when** sub-attributes. Multiple abilities can be configured. | **abilities**: string array; **when**: string | **abilities**: array of ability names; **when**: **inuse** and **always** | **abilities**: left empty; **when**: left empty | If the permission to request is **user_grant**, the **ability** sub-attribute is mandatory and **when** is optional. |
Example of the **requestPermissions** attribute structure:
......@@ -464,7 +464,7 @@ Example of the **requestPermissions** attribute structure:
"usedScene": {
"abilities": [
"AudioAbility",
"VedioAbility",
"VideoAbility",
],
"when": "inuse"
}
......@@ -478,29 +478,27 @@ The **forms** attribute indicates the service widget configuration. The service
1. Set **type** to **form** in **extensions**.
2. Specify the **form** information in **metadata**, where:
- **name** indicates the name of the service widget, for example, **ohos.extability.form**.
- **resource** indicates where the resources of the service widget are stored.
Table 11 Internal structure of the forms attribute
| Attribute | Description | Data Type | Initial Value Allowed |
| ----------------- | ------------------------------------------------------------ | ---------- | ----------------------------- |
| ------------------- | ------------------------------------------------------------ | ---------- | ----------------------------- |
| name | Class name of the widget. The value is a string with a maximum of 127 bytes. | String | No |
| description | Description of the widget. The value can be a string or a resource index to descriptions in multiple languages. The value is a string with a maximum of 255 bytes.| String | Yes (initial value: left empty) |
| src | UI code of a JS service widget. It is recommended that you use the adaptive layout to display a service widget of different specifications. If the layout of a service widget of different specifications differs greatly, you are advised to use different service widgets.| String | Yes (initial value: left empty) |
| window | Adaptive capability of a JS service widget. For details about the window structure, see Table 12. | Object | Yes (initial value: left empty) |
| isDefault | Whether the service widget is the default one. Each ability has only one default service widget. **true**: The service widget is the default one. **false**: The service widget is not the default one.| Boolean | No |
| colorMode | Theme style of the service widget. The value can be **auto**, **dark**, or **light**.| String | Yes (initial value: **auto**) |
| supportDimensions | Dimensions supported by the service widget. The value can be **1 * 2**, **2 * 2**, **2 * 4**, or **4 * 4**, where the number before the asterisk (*) indicates the number of rows, and the number after the asterisk (*) indicates the number of columns.| String array| No |
| defaultDimension | Default grid style of the widget. The value must be available in the **supportDimensions** array of the widget.| String | No |
| window | Adaptive capability of a JS service widget. For details, see Table 12. | Object | Yes (initial value: left empty) |
| isDefault | Whether the widget is a default one. Each ability has only one default widget. **true**: The service widget is the default one. **false**: The service widget is not the default one.| Boolean | No |
| colorMode | Color mode of the widget. The value can be **auto**, **dark**, or **light**.| String | Yes (initial value: **auto**) |
| supportDimensions | Dimensions supported by the service widget. The value can be **1 * 2**, **2 * 1**, **2 * 2**, **2 * 4**, or **4 * 4**, where the number before the asterisk (\*) indicates the number of rows, and the number after the asterisk (\*) indicates the number of columns. | String array| No |
| defaultDimension | Default grid style of the widget. The value must be from the **supportDimensions** array of the widget.| String | No |
| updateDuration | Update frequency of a widget. The unit is 30 minutes. The value is a multiple of 30. The highest frequency of refreshing a widget is once every 30 minutes. You can also use scheduled refresh to refresh a widget at a fixed time or once every 30 minutes. If both of them are configured, the scheduled refresh takes precedence.| Number | Yes (initial value: left empty) |
| metadata | Custom information about a widget. For details about the internal structure of metadata, see Table 5. | Object | Yes (initial value: left empty) |
| metadata | Metadata of the widget. For details, see Table 5. | Object | Yes (initial value: left empty) |
| formConfigAbility | Ability name for widget adjustment. The value is a string of up to 127 characters. The value must be in the following format:<br>ability:// Name of an ability.<br>The name must be the same as that of the current application.| String | Yes (initial value: left empty) |
| formVisibleNotify | Whether the widget is allowed to use the visibility notification. The value is **true** or **false**.| Boolean | Yes (initial value: **false**)|
Table 12 Internal structure of window
Table 13 Internal structure of the window attribute
| Attribute | Description | Data Type| Initial Value Allowed |
| --------------- | ------------------------------------------------------------ | -------- | -------------------- |
......@@ -545,7 +543,7 @@ Define the **form_config.json** file (this file name is customizable) in **resou
}
```
Define metadata information in the **extension** component of the **module.json** file.
Define metadata information in the **extension** component of the **module.json5** file.
```json
{
......@@ -579,7 +577,7 @@ Table 13 Internal structure of the shortcuts attribute
| Attribute | Description | Data Type| Initial Value Allowed |
| ---------- | ------------------------------------------------------------ | -------- | -------------------------- |
| shortcutId | ID of the shortcut. The value is a string with a maximum of 63 bytes. | String | No |
| label | Label of the shortcut, that is, the text description displayed by the shortcut. The value can be a string or a resource index to the description. The value is a string with a maximum of 63 bytes.| String | Yes (initial value: left empty) |
| label | Label of the shortcut, that is, the text description displayed for the shortcut. The value can be a string or a resource index to the description. The value is a string with a maximum of 63 bytes.| String | Yes (initial value: left empty) |
| icon | Icon of the shortcut. The value is the index to the resource file. | String | Yes (initial value: left empty)|
| wants | Wants to which the shortcut points. The attribute consists of the **bundleName** and **abilityName** sub-attributes.<br>**bundleName**: target bundle name of the shortcut; string type.<br>**abilityName**: target component name of the shortcut; string type.| Object | Yes (initial value: left empty) |
......@@ -603,7 +601,7 @@ Define the **shortcut_config.json** file (this file name is customizable) in **r
}
```
Define the **metadata** information under **module** in the **config.json** file as follows:
Define the **metadata** information under **module** in the **module.json5** file as follows:
```json
{
......@@ -670,7 +668,7 @@ Define the **common_event_config.json** file in **resources/base/profile** in th
}
```
Define the **metadata** information under **extension** in the **module.json** file as follows:
Define the **metadata** information under **extension** in the **module.json5** file as follows:
```json
"extensionAbilities": [
......@@ -690,54 +688,54 @@ Define the **metadata** information under **extension** in the **module.json** f
#### Internal Structure of the distroFilter Attribute
Application distribution rules.
Distribution rules of the application.
This attribute defines the rules for distributing HAP files based on different device specifications, so that precise matching can be performed when AppGallery distributes applications. Applications can be distributed by API version, screen shape, or screen resolution. During distribution, a unique HAP is determined based on the mapping between **deviceType** and these three factors.
This attribute defines the rules for distributing HAP files based on different device specifications, so that precise matching can be performed when AppGallery distributes applications. Distribution rules cover three factors: API version, screen shape, and screen resolution. During distribution, a unique HAP is determined based on the mapping between **deviceType** and these three factors.
Table 15 Internal structure of the distroFilter attribute
Table 16 Internal structure of the distroFilter attribute
| Attribute | Description | Data Type| Initial Value Allowed |
| ------------- | ------------------------------------------------------------ | -------- | -------------------------- |
| apiVersion | Supported API versions. For details, see Table 16. | Object array| Yes (initial value: left empty)|
| screenShape | Supported screen shapes. | Object array| Yes (initial value: left empty)|
| screenWindow | Supported window resolutions when the application is running. This attribute applies only to the lite wearables.| Object array| Yes (initial value: left empty)|
| screenDensity | Dots per inch (DPI) of the screen. This attribute is optional. The value options are as follows:<br>**sdpi**: small-scale dots per inch. This value is applicable for devices with a DPI range of (0, 120].<br>**mdpi**: medium-scale dots per inch. This value is applicable for devices with a DPI range of (120, 160].<br>**ldpi**: large-scale dots per inch. This value is applicable for devices with a DPI in the (160, 240] range.<br> **xldpi**: extra-large-scale dots per inch. This value is applicable for devices with a DPI in the (240, 320] range.<br>**xxldpi**: extra-extra-large-scale dots per inch (XXLDPI). This value is applicable for devices with a DPI in the (320, 480] range.<br>**xxxldpi**: extra-extra-extra-large-scale dots per inch. This value is applicable for devices with a DPI in the (480, 640] range.| Object array| Yes (initial value: left empty)|
| countryCode | Code of the country or region to which an application is to be distributed. For details, see ISO-3166-1. Enumerated definitions of multiple countries and regions are supported. This attribute is optional. The substring of the value consists of two uppercase letters and indicates the supported countries or regions.| Object array| Yes (initial value: left empty)|
| screenWindow | Supported window resolutions for when the application is running. This attribute applies only to the lite wearables.| Object array| Yes (initial value: left empty)|
| screenDensity | Pixel density of the screen, in dots per inch (dpi). This attribute is optional. The value options are as follows:<br>**sdpi**: small-scale dots per inch. This value is applicable for devices with a DPI range of (0, 120].<br>**mdpi**: medium-scale dots per inch. This value is applicable for devices with a DPI range of (120, 160].<br>**ldpi**: large-scale dots per inch. This value is applicable for devices with a DPI in the (160, 240] range.<br> **xldpi**: extra-large-scale dots per inch. This value is applicable for devices with a DPI in the (240, 320] range.<br>**xxldpi**: extra-extra-large-scale dots per inch (XXLDPI). This value is applicable for devices with a DPI in the (320, 480] range.<br>**xxxldpi**: extra-extra-extra-large-scale dots per inch. This value is applicable for devices with a DPI in the (480, 640] range.| Object array| Yes (initial value: left empty)|
| countryCode | Code of the country or region to which the application is to be distributed. For details, see ISO-3166-1. Enumerated definitions of multiple countries and regions are supported. This attribute is optional. The substring of the value consists of two uppercase letters and indicates the supported countries or regions. | Object array| Yes (initial value: left empty)|
Table 16 Internal structure of the apiVersion attribute
Table 17 Internal structure of the apiVersion attribute
| Attribute| Description | Data Type| Initial Value Allowed |
| -------- | ------------------------------------------------------------ | -------- | -------------------- |
| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)|
| value | An integer of the existing API version, for example, 4, 5, or 6. If an application uses two software versions developed using API 5 and API 6 for the same device model, two installation packages of the entry type can be released.| Array | Yes (initial value: left empty)|
Table 17 Internal structure of the screenShape attribute
Table 18 Internal structure of the screenShape attribute
| Attribute| Description | Data Type| Initial Value Allowed |
| -------- | ------------------------------------------------------------ | -------- | -------------------- |
| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)|
| value | The value can be **circle** or **rect**. Example: Different HAP files can be provided for a smart watch with a circular face and a smart watch with a rectangular face.| Array | Yes (initial value: left empty)|
Table 18 Internal structure of the screenWindow attribute
Table 19 Internal structure of the screenWindow attribute
| Attribute| Description | Data Type| Initial Value Allowed |
| -------- | ------------------------------------------------------------ | -------- | -------------------- |
| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)|
| value | Width and height of the screen. The value is in the "width * height" format, in pixels, for example, **454*454**.| Array | Yes (initial value: left empty)|
Table 19 Internal structure of the screenDensity attribute
Table 20 Internal structure of the screenDensity attribute
| Attribute| Description | Data Type| Initial Value Allowed |
| -------- | ------------------------------------------------------------ | -------- | -------------------- |
| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)|
| value | Dots per inch (DPI) of the screen. | Array | Yes (initial value: left empty)|
| value | Pixel density of the screen, in dots per inch (dpi). | Array | Yes (initial value: left empty)|
Table 20 Internal structure of the countryCode attribute
Table 21 Internal structure of the countryCode attribute
| Attribute| Description | Data Type| Initial Value Allowed |
| -------- | ------------------------------------------------------------ | -------- | -------------------- |
| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)|
| value | Code of the country or region to which an application is to be distributed. | Array | Yes (initial value: left empty)|
| value | Code of the country or region to which the application is to be distributed. | Array | Yes (initial value: left empty)|
Example of the **distroFilter** attribute structure:
......@@ -762,7 +760,7 @@ Define the **distroFilter_config.json** file in **resources/base/profile** of th
]
```
Define the **metadata** information under **extensionAbilities** in the **module.json** file as follows:
Define the **metadata** information under **extensionAbilities** in the **module.json5** file as follows:
```json
"extensionAbilities": [
......@@ -780,3 +778,4 @@ Define the **metadata** information under **extensionAbilities** in the **module
]
```
en/application-dev/reference/apis/js-apis-pasteboard.md
浏览文件 @ 1814c646
# Pasteboard
The **pasteboard** module provides the copy and paste support for the system pasteboard. You can use the APIs of this module to operate pasteboard content of the plain text, HTML, URI, Want, pixel map, and other types.
> **NOTE**<br>The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> **NOTE**
>
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
```
```js
import pasteboard from '@ohos.pasteboard';
```
## Attributes
**System capability**: SystemCapability.MiscServices.Pasteboard
| Name | Type | Readable | Writable | Description |
| Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| MAX_RECORD_NUM<sup>7+</sup> | number | Yes | No | Maximum number of records allowed in a **PasteData** object. |
| MIMETYPE_TEXT_HTML<sup>7+</sup> | string | Yes | No | MIME type of the HTML text. |
| MIMETYPE_TEXT_WANT<sup>7+</sup> | string | Yes | No | MIME type of the Want text. |
| MIMETYPE_TEXT_PLAIN<sup>7+</sup> | string | Yes | No | MIME type of the plain text. |
| MIMETYPE_TEXT_URI<sup>7+</sup> | string | Yes | No | MIME type of the URI text. |
| MAX_RECORD_NUM<sup>7+</sup> | number | Yes| No| Maximum number of records in a **PasteData** object.|
| MIMETYPE_TEXT_HTML<sup>7+</sup> | string | Yes| No| MIME type of the HTML content.|
| MIMETYPE_TEXT_WANT<sup>7+</sup> | string | Yes| No| MIME type of the Want content.|
| MIMETYPE_TEXT_PLAIN<sup>7+</sup> | string | Yes| No| MIME type of the plain text content.|
| MIMETYPE_TEXT_URI<sup>7+</sup> | string | Yes| No| MIME type of the URI content.|
## pasteboard.createPlainTextData
createPlainTextData(text:string): PasteData
createPlainTextData(text: string): PasteData
Creates a **PasteData** object for plain text.
Creates a **PasteData** object of the plain text type.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| text | string | Yes | Plain text. |
| text | string | Yes| Plain text.|
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData** object with the specified content. |
| [PasteData](#pastedata) | **PasteData** object.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("content");
```
```js
var pasteData = pasteboard.createPlainTextData("content");
```
## pasteboard.createHtmlData<sup>7+</sup>
createHtmlData(htmlText:string): PasteData
createHtmlData(htmlText: string): PasteData
Creates a **PasteData** object for HTML text.
Creates a **PasteData** object of the HTML type.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| htmlText | string | Yes | HTML text. |
| htmlText | string | Yes| HTML content.|
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData** object with the specified content. |
| [PasteData](#pastedata) | **PasteData** object.|
**Example**
```js
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var pasteData = pasteboard.createHtmlData(html);
```
```js
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var pasteData = pasteboard.createHtmlData(html);
```
## pasteboard.createWantData<sup>7+</sup>
createWantData(want:Want): PasteData
createWantData(want: Want): PasteData
Creates a **PasteData** object for Want text.
Creates a **PasteData** object of the Want type.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes | Want text. |
| want | [Want](js-apis-featureAbility.md#want) | Yes| Want content.|
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData** object with the specified content. |
| [PasteData](#pastedata) | **PasteData** object.|
**Example**
```js
var object = {
```js
var object = {
bundleName: "com.example.aafwk.test",
abilityName: "com.example.aafwk.test.TwoAbility"
};
var pasteData = pasteboard.createWantData(object);
```
};
var pasteData = pasteboard.createWantData(object);
```
## pasteboard.createUriData<sup>7+</sup>
createUriData(uri:string): PasteData
createUriData(uri: string): PasteData
Creates a **PasteData** object for URI text.
Creates a **PasteData** object of the URI type.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| uri | string | Yes | URI text. |
| uri | string | Yes| URI content.|
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData** object with the specified content. |
| [PasteData](#pastedata) | **PasteData** object.|
**Example**
```js
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
```
```js
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt");
```
## pasteboard.createPlainTextRecord<sup>7+</sup>
createPlainTextRecord(text:string): PasteDataRecord
createPlainTextRecord(text: string): PasteDataRecord
Creates a **PasteDataRecord** object of the plain text type.
......@@ -149,26 +147,26 @@ Creates a **PasteDataRecord** object of the plain text type.
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| text | string | Yes | Plain text. |
| text | string | Yes| Plain text.|
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New plain text record. |
| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the plain text type.|
**Example**
```js
var record = pasteboard.createPlainTextRecord("hello");
```
```js
var record = pasteboard.createPlainTextRecord("hello");
```
## pasteboard.createHtmlTextRecord<sup>7+</sup>
createHtmlTextRecord(htmlText:string): PasteDataRecord
createHtmlTextRecord(htmlText: string): PasteDataRecord
Creates a **PasteDataRecord** object of the HTML text type.
......@@ -176,80 +174,100 @@ Creates a **PasteDataRecord** object of the HTML text type.
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| htmlText | string | Yes | HTML text. |
| htmlText | string | Yes| HTML content.|
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New HTML record. |
| [PasteDataRecord](#pastedatarecord7) | **PasteDataRecord** object of the HTML text type.|
**Example**
```js
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var record = pasteboard.createHtmlTextRecord(html);
```
```js
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var record = pasteboard.createHtmlTextRecord(html);
```
## pasteboard.createWantRecord<sup>7+</sup>
createWantRecord(want:Want): PasteDataRecord
createWantRecord(want: Want): PasteDataRecord
Creates a **PasteDataRecord** object of the Want text type.
Creates a **PasteDataRecord** object of the Want type.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes | Want text. |
| want | [Want](js-apis-featureAbility.md#want) | Yes| Want content.|
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New Want record. |
| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the Want type.|
**Example**
```js
var object = {
```js
var object = {
bundleName: "com.example.aafwk.test",
abilityName: "com.example.aafwk.test.TwoAbility"
};
var record = pasteboard.createWantRecord(object);
```
};
var record = pasteboard.createWantRecord(object);
```
## pasteboard.createUriRecord<sup>7+</sup>
createUriRecord(uri:string): PasteDataRecord
createUriRecord(uri: string): PasteDataRecord
Creates a **PasteDataRecord** object of the URI text type.
Creates a **PasteDataRecord** object of the URI type.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| uri | string | Yes | URI text. |
| uri | string | Yes| URI content.|
**Return value**
| Type| Description|
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the URI type.|
**Example**
```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt");
```
## pasteboard.getSystemPasteboard
getSystemPasteboard(): SystemPasteboard
Obtains this **SystemPasteboard** object.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New URI record. |
| [SystemPasteboard](#systempasteboard) | **SystemPasteboard** object.|
**Example**
```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
```
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
```
## PasteDataProperty<sup>7+</sup>
......@@ -258,90 +276,92 @@ Defines the properties of all data records on the pasteboard, including the time
**System capability**: SystemCapability.MiscServices.Pasteboard
| Name | Type | Readable | Writable | Description |
| Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| additions | {[key: string]: object} | Yes | Yes | Additional property data. |
| mimeTypes | Array&lt;string&gt; | Yes | No | Non-repeating data types of the data records on the pasteboard. |
| tag | string | Yes | Yes | User-defined tag. |
| timestamp | number | Yes | No | Timestamp at which the data is written to the pasteboard, in milliseconds. |
| localOnly | boolean | Yes | Yes | Whether local access only is set for the pasteboard.<br/>- The default value is **true**.<br/>- **true**: The **PasteData** is set for local access only.<br/>- **false**: The **PasteData** can be shared between devices. |
| additions | {[key:string]:object} | Yes| Yes| Additional data.|
| mimeTypes | Array&lt;string&gt; | Yes| No| Non-repeating data types of the data records on the pasteboard.|
| tag | string | Yes| Yes| Custom tag.|
| timestamp | number | Yes| No| Timestamp when data is written to the pasteboard (unit: ms).|
| localOnly | boolean | Yes| Yes| Whether the pasteboard content is set for local access only. The default value is **true**.<br>- **true**: The pasteboard content is set for local access only.<br>- **false**: The pasteboard content can be shared between devices.|
## PasteDataRecord<sup>7+</sup>
A data record is an abstract definition of the content on the pasteboard. The pasteboard content consists of one or more plain text, HTML, URI, or Want records.
Provides **PasteDataRecord** APIs. A **PasteDataRecord** is an abstract definition of the content on the pasteboard. The pasteboard content consists of one or more plain text, HTML, URI, or Want records.
### Attributes
**System capability**: SystemCapability.MiscServices.Pasteboard
| Name | Type | Readable | Writable | Description |
| Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| htmlText<sup>7+</sup> | string | Yes | No | HTML text. |
| want<sup>7+</sup> | [Want](js-apis-application-Want.md) | Yes | No | Want text. |
| mimeType<sup>7+</sup> | string | Yes | No | Data type. |
| plainText<sup>7+</sup> | string | Yes | No | Plain text. |
| uri<sup>7+</sup> | string | Yes | No | URI text. |
| htmlText<sup>7+</sup> | string | Yes| No| HTML content.|
| want<sup>7+</sup> | [Want](js-apis-featureAbility.md#want) | Yes| No| Want content.|
| mimeType<sup>7+</sup> | string | Yes| No| Data type.|
| plainText<sup>7+</sup> | string | Yes| No| Plain text.|
| uri<sup>7+</sup> | string | Yes| No| URI content.|
### convertToText<sup>7+</sup>
convertToText(): Promise&lt;string&gt;
Forcibly converts the content in this **PasteData** object to the plain text. This API uses a promise to return the result.
Forcibly converts the content in a **PasteData** object to text. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result. If the operation is successful, the plain text content after conversion is returned. Otherwise, error information is returned. |
| Promise&lt;string&gt; | Promise used to return the text obtained from the conversion.|
**Example**
```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
record.convertToText().then((data) => {
console.info('convertToText success data : ' + JSON.stringify(data));
}).catch((error) => {
console.error('convertToText failed because ' + JSON.stringify(error));
});
```
```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt");
record.convertToText().then((data) => {
console.info('Succeeded in converting to text. Data: ' + JSON.stringify(data));
}).catch((err) => {
console.error('Failed to convert to text. Cause: ' + JSON.stringify(err));
});
```
### convertToText<sup>7+</sup>
convertToText(callback: AsyncCallback&lt;string&gt;): void
Forcibly converts the content in this **PasteData** object to the plain text. This API uses an asynchronous callback to return the result.
Forcibly converts the content in a **PasteData** object to text. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;string&gt; | Yes | Callback used to return the result. If this callback is successful, the plain text content after conversion is returned. Otherwise, error information is returned. |
| callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the text obtained from the conversion. Otherwise, **err** is error information.|
**Example**
```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
record.convertToText((err, data) => {
```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt");
record.convertToText((err, data) => {
if (err) {
console.error('convertToText failed because ' + JSON.stringify(err));
console.error('Failed to convert to text. Cause: ' + JSON.stringify(err));
return;
}
console.info('convertToText success data : ' + JSON.stringify(data));
});
```
console.info('Succeeded in converting to text. Data: ' + JSON.stringify(data));
});
```
## PasteData
Before calling any **PasteData** method, you must obtain a **PasteData** object.
Provides **PasteData** APIs.
Before calling any **PasteData** API, you must obtain a **PasteData** object.
**System capability**: SystemCapability.MiscServices.Pasteboard
......@@ -354,93 +374,92 @@ getPrimaryText(): string
Obtains the plain text of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| string | Plain text. |
| string | Plain text.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var plainText = pasteData.getPrimaryText();
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var plainText = pasteData.getPrimaryText();
```
### getPrimaryHtml<sup>7+</sup>
getPrimaryHtml(): string
Obtains the HTML text of the primary record.
Obtains the HTML content of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| string | HTML text. |
| string | HTML content.|
**Example**
```js
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var pasteData = pasteboard.createHtmlData(html);
var htmlText = pasteData.getPrimaryHtml();
```
```js
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var pasteData = pasteboard.createHtmlData(html);
var htmlText = pasteData.getPrimaryHtml();
```
### getPrimaryWant<sup>7+</sup>
getPrimaryWant(): Want
Obtains the **Want** object of the primary record.
Obtains the Want object of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| [Want](js-apis-application-Want.md) | Want object. |
| [Want](js-apis-featureAbility.md#want) | Want object.|
**Example**
```js
var object = {
```js
var object = {
bundleName: "com.example.aafwk.test",
abilityName: "com.example.aafwk.test.TwoAbility"
};
var pasteData = pasteboard.createWantData(object);
var want = pasteData.getPrimaryWant();
```
};
var pasteData = pasteboard.createWantData(object);
var want = pasteData.getPrimaryWant();
```
### getPrimaryUri<sup>7+</sup>
getPrimaryUri(): string
Obtains the URI text of the primary record.
Obtains the URI of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| string | URI text. |
| string | URI content.|
**Example**
```js
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
var uri = pasteData.getPrimaryUri();
```
```js
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt");
var uri = pasteData.getPrimaryUri();
```
### addTextRecord<sup>7+</sup>
......@@ -455,9 +474,9 @@ The pasteboard supports a maximum number of 128 data records.
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| text | string | Yes | Plain text. |
| text | string | Yes| Plain text.|
**Example**
......@@ -471,7 +490,7 @@ pasteData.addTextRecord("good");
addHtmlRecord(htmlText: string): void
Adds an HTML text record to this pasteboard, and adds **MIMETYPE_TEXT_HTML** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails.
Adds an HTML record to this pasteboard, and adds **MIMETYPE_TEXT_HTML** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails.
The pasteboard supports a maximum number of 128 data records.
......@@ -479,24 +498,24 @@ The pasteboard supports a maximum number of 128 data records.
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| htmlText | string | Yes | HTML text. |
| htmlText | string | Yes| HTML content.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
pasteData.addHtmlRecord(html);
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
pasteData.addHtmlRecord(html);
```
### addWantRecord<sup>7+</sup>
addWantRecord(want: Want): void
Adds a Want text record to this pasteboard, and adds **MIMETYPE_TEXT_WANT** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails.
Adds a Want record to this pasteboard, and adds **MIMETYPE_TEXT_WANT** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails.
The pasteboard supports a maximum number of 128 data records.
......@@ -504,27 +523,27 @@ The pasteboard supports a maximum number of 128 data records.
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes | Want object. |
| want | [Want](js-apis-featureAbility.md#want) | Yes| Want object.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var object = {
```js
var pasteData = pasteboard.createPlainTextData("hello");
var object = {
bundleName: "com.example.aafwk.test",
abilityName: "com.example.aafwk.test.TwoAbility"
};
pasteData.addWantRecord(object);
```
};
pasteData.addWantRecord(object);
```
### addUriRecord<sup>7+</sup>
addUriRecord(uri: string): void
Adds a URI text record to this pasteboard, and adds **MIMETYPE_TEXT_URI** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails.
Adds a URI record to this pasteboard, and adds **MIMETYPE_TEXT_URI** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails.
The pasteboard supports a maximum number of 128 data records.
......@@ -532,16 +551,16 @@ The pasteboard supports a maximum number of 128 data records.
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| uri | string | Yes | URI text. |
| uri | string | Yes| URI content.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addUriRecord("dataability:///com.example.myapplication1?user.txt");
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addUriRecord("dataability:///com.example.myapplication1/user.txt");
```
### addRecord<sup>7+</sup>
......@@ -556,417 +575,396 @@ The pasteboard supports a maximum number of 128 data records.
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| record | [PasteDataRecord](#pastedatarecord7) | Yes | Record to add. |
| record | [PasteDataRecord](#pastedatarecord7) | Yes| Record to add.|
**Example**
```js
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
var textRecord = pasteboard.createPlainTextRecord("hello");
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var htmlRecord = pasteboard.createHtmlTextRecord(html);
pasteData.addRecord(textRecord);
pasteData.addRecord(htmlRecord);
```
```js
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt");
var textRecord = pasteboard.createPlainTextRecord("hello");
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var htmlRecord = pasteboard.createHtmlTextRecord(html);
pasteData.addRecord(textRecord);
pasteData.addRecord(htmlRecord);
```
### getMimeTypes<sup>7+</sup>
getMimeTypes(): Array&lt;string&gt;
Obtains **mimeTypes** in [PasteDataProperty](#pastedataproperty7) from this pasteboard. If the pasteboard is empty, the returned list is also empty.
Obtains a list of **mimeTypes** objects in [PasteDataProperty](#pastedataproperty7) from this pasteboard. If the pasteboard is empty, the returned list is also empty.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| Array&lt;string&gt; | List of non-duplicate MIME types. |
| Array&lt;string&gt; | Non-repeating data types of the data records on the pasteboard.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var types = pasteData.getMimeTypes();
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var types = pasteData.getMimeTypes();
```
### getPrimaryMimeType<sup>7+</sup>
getPrimaryMimeType(): string
Obtains the data type of the primary record.
Obtains the data type of the primary record in this pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| string | Data type of the primary record. |
| string | Data type of the primary record.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var type = pasteData.getPrimaryMimeType();
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var type = pasteData.getPrimaryMimeType();
```
### getProperty<sup>7+</sup>
getProperty(): PasteDataProperty
Obtains the property description object.
Obtains the property of the pasteboard data.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| [PasteDataProperty](#pastedataproperty7) | Property description object. |
| [PasteDataProperty](#pastedataproperty7) | Property of the pasteboard data.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var property = pasteData.getProperty();
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var property = pasteData.getProperty();
```
### getRecordAt<sup>7+</sup>
getRecordAt(index: number): PasteDataRecord
Obtains the record with the specified index.
Obtains the specified record in the pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| index | number | Yes | Index of the specified record. |
| index | number | Yes| Index of the target record.|
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | Record with the specified index. |
| [PasteDataRecord](#pastedatarecord7) | Record with the specified index.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteData.getRecordAt(0);
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteData.getRecordAt(0);
```
### getRecordCount<sup>7+</sup>
getRecordCount(): number
Obtains the number of data records in this pasteboard.
Obtains the number of records in the pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| number | Number of records. |
| number | Number of records.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var count = pasteData.getRecordCount();
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var count = pasteData.getRecordCount();
```
### getTag<sup>7+</sup>
getTag(): string
Obtains the user-defined tag content. If the tag content is not set, null is returned.
Obtains the custom tag from the pasteboard. If no custom tag is set, null is returned.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| string | User-defined tag content if obtained and null if no tag is set. |
| string | Custom tag. If no custom tag is set, null is returned.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var tag = pasteData.getTag();
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var tag = pasteData.getTag();
```
### hasMimeType<sup>7+</sup>
hasMimeType(mimeType: string): boolean
Checks whether the content of this pasteboard contains the specified data type.
Checks whether the pasteboard contains data of the specified type.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| mimeType | string | Yes | Type of the data to query. |
| mimeType | string | Yes| Type of the data to query.|
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| boolean | Returns **true** if the specified data type exists; returns **false** otherwise. |
| boolean | Returns **true** if the specified data type exists; returns **false** otherwise.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN);
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN);
```
### removeRecordAt<sup>7+</sup>
removeRecordAt(index: number): boolean
Removes the data record with a specified index from this pasteboard.
Removes the record with the specified index from the pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| index | number | Yes | Specified index. |
| index | number | Yes| Specified index.|
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| boolean | Returns **true** if the operation is successful; returns **false** otherwise. |
| boolean | Returns **true** if the operation is successful; returns **false** otherwise.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var isRemove = pasteData.removeRecordAt(0);
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var isRemove = pasteData.removeRecordAt(0);
```
### replaceRecordAt<sup>7+</sup>
replaceRecordAt(index: number, record: PasteDataRecord): boolean
Replaces the data record with a specified index in this pasteboard.
Replaces the record with the specified index in the pasteboard with a new record.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| index | number | Yes | Specified index. |
| record | [PasteDataRecord](#pastedatarecord7) | Yes | New record. |
**Return value**
| Type | Description |
| -------- | -------- |
| boolean | Returns **true** if the operation is successful; returns **false** otherwise. |
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
var isReplace = pasteData.replaceRecordAt(0, record);
```
## pasteboard.getSystemPasteboard
getSystemPasteboard(): SystemPasteboard
Obtains the system pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard
| index | number | Yes| Specified index.|
| record | [PasteDataRecord](#pastedatarecord7) | Yes| New record.|
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| [SystemPasteboard](#systempasteboard) | System pasteboard. |
| boolean | Returns **true** if the operation is successful; returns **false** otherwise.|
**Example**
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt");
var isReplace = pasteData.replaceRecordAt(0, record);
```
## SystemPasteboard
Before calling any **SystemPasteboard** method, you must obtain a **SystemPasteboard** object using [getSystemPasteboard](#pasteboardgetsystempasteboard).
Provides **SystemPasteboard** APIs.
```
Before calling any **SystemPasteboard** API, you must obtain a **SystemPasteboard** object using [getSystemPasteboard](#pasteboardgetsystempasteboard).
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
```
### setPasteData
setPasteData(data:PasteData, callback:AsyncCallback&lt;void&gt;): void
setPasteData(data: PasteData, callback: AsyncCallback&lt;void&gt;): void
Writes data to a pasteboard. This API uses an asynchronous callback to return the result.
Writes a **PasteData** object to the pasteboard. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| data | [PasteData](#pastedata) | Yes | **PasteData** object. |
| callback | AsyncCallback&lt;void> | Yes | Callback used to return the data write result. |
| data | [PasteData](#pastedata) | Yes| **PasteData** object.|
| callback | AsyncCallback&lt;void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData, (error, data) => {
if (error) {
console.error('Failed to setPasteData. Cause: ' + error.message);
```js
var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData, (err, data) => {
if (err) {
console.error('Failed to set PasteData. Cause: ' + err.message);
return;
}
console.info('setPasteData successfully.');
});
```
console.info('Succeeded in setting PasteData.');
});
```
### setPasteData
setPasteData(data:PasteData): Promise&lt;void&gt;
setPasteData(data: PasteData): Promise&lt;void&gt;
Writes data to a pasteboard. This API uses a promise to return the result.
Writes a **PasteData** object to the pasteboard. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Description |
| Name| Type| Description|
| -------- | -------- | -------- |
| data | [PasteData](#pastedata) | **PasteData** object. |
| data | [PasteData](#pastedata) | **PasteData** object.|
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the data write result. |
| Promise&lt;void&gt; | Promise that returns no value.|
**Example**
```js
var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData).then((data) => {
console.info('setPasteData success.');
}).catch((error) => {
console.error('Failed to setPasteData. Cause: ' + error.message);
});
```
```js
var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData).then((data) => {
console.info('Succeeded in setting PasteData.');
}).catch((err) => {
console.error('Failed to set PasteData. Cause: ' + err.message);
});
```
### getPasteData
getPasteData( callback:AsyncCallback&lt;PasteData&gt;): void
getPasteData( callback: AsyncCallback&lt;PasteData&gt;): void
Reads the system pasteboard content. This API uses an asynchronous callback to return the result.
Obtains a **PasteData** object from the pasteboard. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[PasteData](#pastedata)&gt; | Yes | Callback used to return the system pasteboard data. |
| callback | AsyncCallback&lt;[PasteData](#pastedata)&gt; | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the system pasteboard data. Otherwise, **err** is an error object.|
**Example**
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData((error, pasteData) => {
if (error) {
console.error('Failed to getPasteData. Cause: ' + error.message);
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData((err, pasteData) => {
if (err) {
console.error('Failed to get PasteData. Cause: ' + err.message);
return;
}
var text = pasteData.getPrimaryText();
});
```
});
```
### getPasteData
getPasteData(): Promise&lt;PasteData&gt;
Reads the system pasteboard content. This API uses a promise to return the result.
Obtains a **PasteData** object from the pasteboard. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| Promise&lt;[PasteData](#pastedata)&gt; | Promise used to return the system pasteboard data. |
| Promise&lt;[PasteData](#pastedata)&gt; | Promise used to return the system pasteboard data.|
**Example**
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData().then((pasteData) => {
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData().then((pasteData) => {
var text = pasteData.getPrimaryText();
}).catch((error) => {
console.error('Failed to getPasteData. Cause: ' + error.message);
})
```
}).catch((err) => {
console.error('Failed to get PasteData. Cause: ' + err.message);
})
```
### on('update')<sup>7+</sup>
on(type: 'update', callback: () =&gt;void ): void
Subscribes to the content change event of the system pasteboard. If the pasteboard content changes, the callback is triggered.
Subscribes to the content change event of the system pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes | Data type. The value **update** indicates the pasteboard content has changed. |
| callback | function | Yes | Callback invoked when the pasteboard content changes. |
| type | string | Yes| Event type. The value **'update'** indicates changes in the pasteboard content.|
| callback | function | Yes| Callback invoked when the pasteboard content changes.|
**Example**
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
var listener = () => {
console.info('The system pasteboard has changed');
};
systemPasteboard.on('update', listener);
```
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
var listener = () => {
console.info('The system pasteboard has changed.');
};
systemPasteboard.on('update', listener);
```
### off('update')<sup>7+</sup>
......@@ -979,69 +977,69 @@ Unsubscribes from the system pasteboard content change event.
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes | Data type. The value **update** indicates the pasteboard content has changed. |
| callback | function | No | Callback invoked when the pasteboard content changes. |
| type | string | Yes| Event type. The value **'update'** indicates changes in the pasteboard content.|
| callback | function | No| Callback invoked when the pasteboard content changes.|
**Example**
```js
let listener = () => {
console.info('The system pasteboard has changed');
};
systemPasteboard.off('update', listener);
```
```js
let listener = () => {
console.info('The system pasteboard has changed.');
};
systemPasteboard.off('update', listener);
```
### hasPasteData<sup>7+</sup>
hasPasteData(callback: AsyncCallback&lt;boolean&gt;): void
Checks whether the system pasteboard contains content. This API uses an asynchronous callback to return the result.
Checks whether the system pasteboard contains data. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Returns **true** if the pasteboard contains content; returns **false** otherwise. |
| callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.|
**Example**
```js
systemPasteboard.hasPasteData((err, data) => {
```js
systemPasteboard.hasPasteData((err, data) => {
if (err) {
console.error('failed to hasPasteData because ' + JSON.stringify(err));
console.error('Failed to check the PasteData. Cause: ' + JSON.stringify(err));
return;
}
console.info('success hasPasteData : ' + JSON.stringify(data));
});
```
console.info('Succeeded in checking the PasteData. Data: ' + JSON.stringify(data));
});
```
### hasPasteData<sup>7+</sup>
hasPasteData(): Promise&lt;boolean&gt;
Checks whether the system pasteboard contains content. This API uses a promise to return the result.
Checks whether the system pasteboard contains data. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| Promise&lt;boolean&gt; | Returns **true** if the pasteboard contains content; returns **false** otherwise. |
| Promise&lt;boolean&gt; | Promise used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.|
**Example**
```js
systemPasteboard.hasPasteData().then((data) => {
console.info('Operation succeeded. ' + JSON.stringify(data));
}).catch((error) => {
console.error('failed to hasPasteData because ' + JSON.stringify(error));
console.info('Succeeded in checking the PasteData. Data: ' + JSON.stringify(data));
}).catch((err) => {
console.error('Failed to check the PasteData. Cause: ' + JSON.stringify(err));
});
```
......@@ -1050,49 +1048,49 @@ systemPasteboard.hasPasteData().then((data) => {
clear(callback: AsyncCallback&lt;void&gt;): void
Clears the system pasteboard content. This API uses an asynchronous callback to return the result.
Clears the system pasteboard. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. |
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```js
systemPasteboard.clear((err, data) => {
```js
systemPasteboard.clear((err, data) => {
if (err) {
console.error('failed to clear because ' + JSON.stringify(err));
console.error('Failed to clear the PasteData. Cause: ' + JSON.stringify(err));
return;
}
console.info('success clear');
});
```
console.info('Succeeded in clearing the PasteData.');
});
```
### clear<sup>7+</sup>
clear(): Promise&lt;void&gt;
Clears the system pasteboard content. This API uses a promise to return the result.
Clears the system pasteboard. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
| Type | Description |
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result. |
| Promise&lt;void&gt; | Promise that returns no value.|
**Example**
```js
systemPasteboard.clear().then((data) => {
console.info('success clear');
}).catch((error) => {
console.error('failed to clear because ' + JSON.stringify(error));
});
```
```js
systemPasteboard.clear().then((data) => {
console.info('Succeeded in clearing the PasteData.');
}).catch((err) => {
console.error('Failed to clear the PasteData. Cause: ' + JSON.stringify(err));
});
```
en/application-dev/reference/arkui-ts/ts-basic-components-textclock.md
浏览文件 @ 1814c646
# TextClock
> ![](public_sys-resources/icon-note.gif) **NOTE** This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
The **<TextClock\>** component displays the current system time in text format for different time zones. The time is accurate to seconds.
## Required Permissions
None
>**NOTE**
>
>This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
None
Not supported
## APIs
TextClock(options?: {timeZoneOffset?: number, contorller?: TextClockController})
TextClock(options?: { timeZoneOffset?: number, controller?: TextClockController })
- Parameters
**Parameters**
| Name | Type| Mandatory| Default Value | Description |
| -------- | -------- | ---- | ------------------ | ------------------------------------------------------------ |
| timeZoneOffset | number | No | Time zone offset| Sets the time zone offset. The value range is [-14, 12], indicating UTC+12 to UTC-12. A negative value indicates Eastern Standard Time, and a positive value indicates Western Standard Time. For example, **-8** indicates UTC+8. For countries or regions crossing the International Date Line, use -13 (UTC+13) and -14 (UTC+14) to ensure consistent time within the entire country or region.|
| contorller | [TextClockContorller](#TextClockController) | No| null | Binds a controller to control the status of the **<TextClock\>** component.|
| Name | Type | Mandatory | Description |
| -------------- | -------- | ------ | --------------------------------------------------------------------------- |
| timeZoneOffset | number | No | Time zone offset.<br>The value range is [-14, 12], indicating UTC+12 to UTC-12. A negative value indicates Eastern Standard Time, and a positive value indicates Western Standard Time. For example, **-8** indicates UTC+8.<br>For countries or regions crossing the International Date Line, use -13 (UTC+13) and -14 (UTC+14) to ensure consistent time within the entire country or region. If the set value is not within the valid range, the time zone offset of the current system will be used.<br/>Default value: time zone offset of the current system |
| controller | [TextClockController](#textclockcontroller) | No | Controller to control the status of the **<TextClock\>** component. |
## Attributes
| Name | Type| Default Value | Description |
| ------ | -------- | -------- | ------------------------------------------------------------ |
| format | string | 'hhmmss' | Time format, for example, **yyyy/mm/dd** or **yyyy-mm-dd**. Supported time format strings: <ul><li>yyyy (year)</li> <li>mm (two-letter abbreviated month name)</li> <li>mmm (three-letter abbreviated month name)</li> <li>mmmm (full month name)</li> <li>dd (two-letter abbreviated day of the week)</li> <li>ddd (three-letter abbreviated day of the week)</li> <li>dddd (full day of the week)</li> <li>HH (24-hour format)</li> <li>hh (12-hour format)</li> <li>MM/mm (minute)</li> <li>SS/ss (second)</li></ul>|
In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
| Name | Type | Description |
| ------ | --------------- | ------------------------------------------------------------ |
| format | string | Time format.<br>The date separator is a slash (/), and the time separator is a colon (:).<br>For example, yyyyMMdd and yyyy-MM-dd are displayed as yyyy/MM/dd,<br>and hhmmss is displayed as hh:mm:ss.<br>Only one digit is required for the time format. This means that hhmmss is equivalent to hms.<br>Supported time format strings:<br>- YYYY/yyyy: four-digit year<br>- YY/yy: last two digits of year<br>- M: one-digit month (MM for two-digit month, for example, 01)<br>- d: one-digit day (dd for two-digit day, for example, 01)<br>- D: number of days that have elapsed in the year<br>- H: 24-hour format<br>- h: 12-hour format<br>- m: minute<br>- s: second<br>- SSS: millisecond<br>Default value: **'hms'**|
## Events
In addition to the universal events (ts-universal-events-click.md), the following events are supported.
| Name | Description |
| -------------------------------------------- | ------------------------------------------------------------ |
| onDateChange(event: (value: number) => void) | Triggered when the time changes in seconds at minimum.<br> **value**: Unix time stamp, which is the number of milliseconds that have elapsed since the Unix epoch.|
| onDateChange(event: (value: number) => void) | Called when the time changes in seconds at minimum.<br> - **value**: Unix time stamp, which is the number of milliseconds that have elapsed since the Unix epoch.|
## TextClockController
Controller of the **<TextClock\>** component, which can be bound to the component for status control.
Defines the controller of the **<TextClock\>** component, which can be bound to the component for status control. A **\<TextClock>** component can be bound to only one controller.
### Objects to Import
```
```ts
controller: TextClockController = new TextClockController()
```
### start
......@@ -61,7 +62,7 @@ Stops the **<TextClock\>** component.
## Example
```
```ts
@Entry
@Component
struct Second {
......@@ -69,11 +70,11 @@ struct Second {
controller: TextClockController = new TextClockController()
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center}) {
Text('current milliseconds is' + this.accumulateTime)
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Text('Current milliseconds is ' + this.accumulateTime)
.fontSize(20)
TextClock({timeZoneOffset: -8, controller: this.controller})
.format('hhmmss')
TextClock({ timeZoneOffset: -8, controller: this.controller })
.format('hms')
.onDateChange((value: number) => {
this.accumulateTime = value
})
......@@ -81,11 +82,11 @@ struct Second {
.fontSize(30)
Button("start TextClock")
.margin({ bottom: 10 })
.onClick(()=>{
.onClick(() => {
this.controller.start()
})
Button("stop TextClock")
.onClick(()=>{
.onClick(() => {
this.controller.stop()
})
}
......
en/application-dev/reference/arkui-ts/ts-matrix-transformation.md
浏览文件 @ 1814c646
# Matrix Transformation
> **NOTE**<br>
> **NOTE**
>
> This animation is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
## Modules to Import
```
```ts
import matrix4 from '@ohos.matrix4'
```
......@@ -23,7 +23,7 @@ None
init(array: Array&lt;number&gt;): Object
Matrix constructor, which is used to create a 4x4 matrix by using the input parameter. Column-major order is used.
Implements a 4x4 matrix by using the input parameter. The column-major order is used.
- Parameters
......@@ -39,29 +39,29 @@ Matrix constructor, which is used to create a 4x4 matrix by using the input para
- Parameter description
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| m00 | number | Yes | Scaling value of the x-axis. Defaults to **1** for the unit matrix. |
| m01 | number | Yes | The second value, which is affected by the rotation of the x, y, and z axes. |
| m02 | number | Yes | The third value, which is affected by the rotation of the x, y, and z axes. |
| m00 | number | Yes | Scaling value along the x-axis. Defaults to **1** for the identity matrix. |
| m01 | number | Yes | The second value, which is affected by the rotation along the x, y, and z axes. |
| m02 | number | Yes | The third value, which is affected by the rotation along the x, y, and z axes. |
| m03 | number | Yes | Meaningless. |
| m10 | number | Yes | The fifth value, which is affected by the rotation of the x, y, and z axes. |
| m11 | number | Yes | Scaling value of the y-axis. Defaults to **1** for the unit matrix. |
| m12 | number | Yes | The seventh value, which is affected by the rotation of the x, y, and z axes. |
| m10 | number | Yes | The fifth value, which is affected by the rotation along the x, y, and z axes. |
| m11 | number | Yes | Scaling value along the y-axis. Defaults to **1** for the identity matrix. |
| m12 | number | Yes | The seventh value, which is affected by the rotation along the x, y, and z axes. |
| m13 | number | Yes | Meaningless. |
| m20 | number | Yes | The ninth value, which is affected by the rotation of the x, y, and z axes. |
| m21 | number | Yes | The tenth value, which is affected by the rotation of the x, y, and z axes. |
| m22 | number | Yes | Scaling value of the z-axis. Defaults to **1** for the unit matrix. |
| m20 | number | Yes | The ninth value, which is affected by the rotation along the x, y, and z axes. |
| m21 | number | Yes | The tenth value, which is affected by the rotation along the x, y, and z axes. |
| m22 | number | Yes | Scaling value along the z-axis. Defaults to **1** for the identity matrix. |
| m23 | number | Yes | Meaningless. |
| m30 | number | Yes | Translation value of the x-axis, in px. Defaults to **0** for the unit matrix. |
| m31 | number | Yes | Translation value of the y-axis, in px. Defaults to **0** for the unit matrix. |
| m32 | number | Yes | Translation value of the z-axis, in px. Defaults to **0** for the unit matrix. |
| m30 | number | Yes | Translation value along the x-axis, in px. Defaults to **0** for the identity matrix. |
| m31 | number | Yes | Translation value along the y-axis, in px. Defaults to **0** for the identity matrix. |
| m32 | number | Yes | Translation value along the z-axis, in px. Defaults to **0** for the identity matrix. |
| m33 | number | Yes | Valid in homogeneous coordinates, presenting the perspective projection effect. |
- Example
```
import Matrix4 from '@ohos.matrix4'
```ts
import matrix4 from '@ohos.matrix4'
// Create a 4x4 matrix.
let matrix = Matrix4.init([1.0, 0.0, 0.0, 0.0,
let matrix = matrix4.init([1.0, 0.0, 0.0, 0.0,
0.0, 1.0, 0.0, 0.0,
0.0, 0.0, 1.0, 0.0,
0.0, 0.0, 0.0, 1.0])
......@@ -73,20 +73,20 @@ Matrix constructor, which is used to create a 4x4 matrix by using the input para
identity(): Object
Matrix initialization function. Can return a unit matrix object.
Performs matrix initialization. This API returns an identity matrix object.
- Return value
| Type | Description |
| -------- | -------- |
| Object | Unit matrix object. |
| Object | Identity matrix object. |
- Example
```
```ts
// The effect of matrix 1 is the same as that of matrix 2.
import Matrix4 from '@ohos.matrix4'
let matrix = Matrix4.init([1.0, 0.0, 0.0, 0.0,
import matrix4 from '@ohos.matrix4'
let matrix = matrix4.init([1.0, 0.0, 0.0, 0.0,
0.0, 1.0, 0.0, 0.0,
0.0, 0.0, 1.0, 0.0,
0.0, 0.0, 0.0, 1.0])
......@@ -99,22 +99,22 @@ Matrix initialization function. Can return a unit matrix object.
copy(): Object
Matrix copy function, which is used to copy the current matrix object.
Copies this matrix object.
- Return value
| Type | Description |
| -------- | -------- |
| Object | Copy object of the current matrix. |
| Object | Copy of the current matrix object. |
- Example
```
import Matrix4 from '@ohos.matrix4'
```ts
import matrix4 from '@ohos.matrix4'
@Entry
@Component
struct Test {
private matrix1 = Matrix4.identity().translate({x:100})
private matrix1 = matrix4.identity().translate({x:100})
private matrix2 = this.matrix1.copy().scale({x:2})
build() {
Column() {
......@@ -143,28 +143,28 @@ Matrix copy function, which is used to copy the current matrix object.
combine(matrix: Matrix4): Object
Matrix overlay function, which is used to overlay the effects of two matrices to generate a new matrix object.
Combines this matrix object with another to generate a new matrix object.
- Parameters
| Name | Type | Mandatory | Default Value | Description |
| -------- | -------- | -------- | -------- | -------- |
| matrix | Matrix4 | Yes | - | Matrix object to be overlaid. |
| matrix | Matrix4 | Yes | - | Matrix object to combine. |
- Return value
| Type | Description |
| -------- | -------- |
| Object | Object after matrix overlay. |
| Object | Object after the combination. |
- Example
```
import Matrix4 from '@ohos.matrix4'
```ts
import matrix4 from '@ohos.matrix4'
@Entry
@Component
struct Test {
private matrix1 = Matrix4.identity().translate({x:200}).copy()
private matrix2 = Matrix4.identity().scale({x:2}).copy()
private matrix1 = matrix4.identity().translate({x:200}).copy()
private matrix2 = matrix4.identity().scale({x:2}).copy()
build() {
Column() {
// Translate the x-axis by 100 pixels and then scale it up or down by 2x.
......@@ -185,7 +185,7 @@ Matrix overlay function, which is used to overlay the effects of two matrices to
invert(): Object
Matrix inverse function. Can return an inverse matrix of the current matrix object, that is, get an opposite effect.
Inverts this matrix object.
- Return value
......@@ -195,11 +195,11 @@ Matrix inverse function. Can return an inverse matrix of the current matrix obje
- Example
```
import Matrix4 from '@ohos.matrix4'
```ts
import matrix4 from '@ohos.matrix4'
// The effect of matrix 1 (width scaled up by 2x) is opposite to that of matrix 2 (width scaled down by 2x).
let matrix1 = Matrix4.identity().scale({x:2})
let matrix2 = matrix1.invert()
let matrix1 = matrix4.identity().scale({x:2})
let matrix2 = matrix1.copy().invert()
```
......@@ -208,15 +208,15 @@ Matrix inverse function. Can return an inverse matrix of the current matrix obje
translate({x?: number, y?: number, z?: number}): Object
Matrix translation function, which is used to add the translation effect to the x, y, and z axes of the current matrix.
Translates this matrix object along the x, y, and z axes.
- Parameters
| Name | Type | Mandatory | Default Value | Description |
| -------- | -------- | -------- | -------- | -------- |
| x | number | No | 0 | Translation distance of the x-axis, in px. |
| y | number | No | 0 | Translation distance of the y-axis, in px. |
| z | number | No | 0 | Translation distance of the z-axis, in px. |
| x | number | No | 0 | Translation distance along the x-axis, in px. |
| y | number | No | 0 | Translation distance along the y-axis, in px. |
| z | number | No | 0 | Translation distance along the z-axis, in px. |
- Return value
......@@ -226,12 +226,12 @@ Matrix translation function, which is used to add the translation effect to the
- Example
```
import Matrix4 from '@ohos.matrix4'
```ts
import matrix4 from '@ohos.matrix4'
@Entry
@Component
struct Test {
private matrix1 = Matrix4.identity().translate({x:100, y:200, z:30})
private matrix1 = matrix4.identity().translate({x:100, y:200, z:30})
build() {
Column() {
Image($r("app.media.bg1")).transform(this.matrix1)
......@@ -250,15 +250,15 @@ Matrix translation function, which is used to add the translation effect to the
scale({x?: number, y?: number, z?: number, centerX?: number, centerY?: number}): Object
Matrix scaling function, which is used to add the scaling effect to the x, y, and z axes of the current matrix.
Scales this matrix object along the x, y, and z axes.
- Parameters
| Name | Type | Mandatory | Default Value | Description |
| -------- | -------- | -------- | -------- | -------- |
| x | number | No | 1 | Scaling multiple of the x-axis. |
| y | number | No | 1 | Scaling multiple of the y-axis. |
| z | number | No | 1 | Scaling multiple of the z-axis. |
| x | number | No | 1 | Scaling multiple along the x-axis. |
| y | number | No | 1 | Scaling multiple along the y-axis. |
| z | number | No | 1 | Scaling multiple along the z-axis. |
| centerX | number | No | 0 | X coordinate of the center point. |
| centerY | number | No | 0 | Y coordinate of the center point. |
......@@ -270,12 +270,12 @@ Matrix scaling function, which is used to add the scaling effect to the x, y, an
- Example
```
import Matrix4 from '@ohos.matrix4'
```ts
import matrix4 from '@ohos.matrix4'
@Entry
@Component
struct Test {
private matrix1 = Matrix4.identity().scale({x:2, y:3, z:4, centerX:50, centerY:50})
private matrix1 = matrix4.identity().scale({x:2, y:3, z:4, centerX:50, centerY:50})
build() {
Column() {
Image($r("app.media.bg1")).transform(this.matrix1)
......@@ -294,7 +294,7 @@ Matrix scaling function, which is used to add the scaling effect to the x, y, an
rotate({x?: number, y?: number, z?: number, angle?: number, centerX?: Length, centerY?: Length}): Object
Matrix rotation function, which is used to add the rotation effect to the x, y, and z axes of the current matrix.
Rotates this matrix object along x, y, and z axes.
- Parameters
......@@ -315,12 +315,12 @@ Matrix rotation function, which is used to add the rotation effect to the x, y,
- Example
```
import Matrix4 from '@ohos.matrix4'
```ts
import matrix4 from '@ohos.matrix4'
@Entry
@Component
struct Test {
private matrix1 = Matrix4.identity().rotate({x:1, y:1, z:2, angle:30})
private matrix1 = matrix4.identity().rotate({x:1, y:1, z:2, angle:30})
build() {
Column() {
Image($r("app.media.bg1")).transform(this.matrix1)
......@@ -339,7 +339,7 @@ Matrix rotation function, which is used to add the rotation effect to the x, y,
transformPoint(point: Point): Point
Matrix point transformation function, which is used to apply the current transformation effect to a coordinate point.
Applies this transformation effect to a coordinate point.
- Parameters
......@@ -355,14 +355,14 @@ Matrix point transformation function, which is used to apply the current transfo
- Example
```
import Matrix4 from '@ohos.matrix4'
```ts
import matrix4 from '@ohos.matrix4'
import prompt from '@system.prompt'
@Entry
@Component
struct Test {
private matrix1 = Matrix4.identity().transformPoint([100, 10])
private matrix1 = matrix4.identity().transformPoint([100, 10])
build() {
Column() {
Button("get Point")
......
en/application-dev/ui/Readme-EN.md
浏览文件 @ 1814c646
......@@ -19,6 +19,7 @@
- Declarative UI Description Specifications
- [Configuration Without Parameters](ts-parameterless-configuration.md)
- [Configuration with Mandatory Parameters](ts-configuration-with-mandatory-parameters.md)
- [Attribute Configuration](ts-attribution-configuration.md)
- [Event Configuration](ts-event-configuration.md)
- [Child Component Configuration](ts-child-component-configuration.md)
......@@ -70,6 +71,8 @@
- [Building a Food Category List Layout](ui-ts-building-category-list-layout.md)
- [Building a Food Category Grid Layout](ui-ts-building-category-grid-layout.md)
- [Implementing Page Redirection and Data Transmission](ui-ts-page-redirection-data-transmission.md)
- [Recommendations for Improving Performance](ts-performance-improvement-recommendation.md)
- JavaScript-based Web-like Development Paradigm
- [Overview](ui-js-overview.md)
- Framework
......
en/application-dev/ui/ts-performance-improvement-recommendation.md 0 → 100644
浏览文件 @ 1814c646
# Recommendations for Improving Performance
Poor-performing code may work, but will take away from your application performance. This topic presents a line-up of recommendations that you can take to improve your implementation, thereby avoiding possible performance drop.
## Lazy Loading
When developing a long list, use of loop rendering, as in the code snippet below, can greatly slow down page loading and increase server load.
```ts
@Entry
@Component
struct MyComponent {
@State arr: number[] = Array.from(Array(100), (v,k) =>k); // Construct an array of 0 to 99.
build() {
List() {
ForEach(this.arr, (item: number) => {
ListItem() {
Text(`item value: ${item}`)
}
}, (item: number) => item.toString())
}
}
}
```
The preceding code snippet loads all of the 100 list elements at a time during page loading. This is generally not desirable. Instead, what we need is to load data from the data source and create corresponding components on demand. This can be achieved through lazy loading. The sample code is as follows:
```ts
class BasicDataSource implements IDataSource {
private listeners: DataChangeListener[] = []
public totalCount(): number {
return 0
}
public getData(index: number): any {
return undefined
}
registerDataChangeListener(listener: DataChangeListener): void {
if (this.listeners.indexOf(listener) < 0) {
console.info('add listener')
this.listeners.push(listener)
}
}
unregisterDataChangeListener(listener: DataChangeListener): void {
const pos = this.listeners.indexOf(listener);
if (pos >= 0) {
console.info('remove listener')
this.listeners.splice(pos, 1)
}
}
notifyDataReload(): void {
this.listeners.forEach(listener => {
listener.onDataReloaded()
})
}
notifyDataAdd(index: number): void {
this.listeners.forEach(listener => {
listener.onDataAdd(index)
})
}
notifyDataChange(index: number): void {
this.listeners.forEach(listener => {
listener.onDataChange(index)
})
}
notifyDataDelete(index: number): void {
this.listeners.forEach(listener => {
listener.onDataDelete(index)
})
}
notifyDataMove(from: number, to: number): void {
this.listeners.forEach(listener => {
listener.onDataMove(from, to)
})
}
}
class MyDataSource extends BasicDataSource {
private dataArray: string[] = ['item value: 0', 'item value: 1', 'item value: 2']
public totalCount(): number {
return this.dataArray.length
}
public getData(index: number): any {
return this.dataArray[index]
}
public addData(index: number, data: string): void {
this.dataArray.splice(index, 0, data)
this.notifyDataAdd(index)
}
public pushData(data: string): void {
this.dataArray.push(data)
this.notifyDataAdd(this.dataArray.length - 1)
}
}
@Entry
@Component
struct MyComponent {
private data: MyDataSource = new MyDataSource()
build() {
List() {
LazyForEach(this.data, (item: string) => {
ListItem() {
Row() {
Text(item).fontSize(20).margin({ left: 10 })
}
}
.onClick(() => {
this.data.pushData('item value: ' + this.data.totalCount())
})
}, item => item)
}
}
}
```
The preceding code initializes only three list elements during page loading and loads a new list item each time a list element is clicked.
## Prioritizing Conditional Rendering over Visibility Control
Use of the visibility attribute to hide or show a component, as in the code snippet below, results in re-creation of the component, leading to performance drop.
```ts
@Entry
@Component
struct MyComponent {
@State isVisible: Visibility = Visibility.Visible;
build() {
Column() {
Button ("Show/Hide")
.onClick(() => {
if (this.isVisible == Visibility.Visible) {
this.isVisible = Visibility.None
} else {
this.isVisible = Visibility.Visible
}
})
Row().visibility(this.isVisible)
.width(300).height(300).backgroundColor(Color.Pink)
}.width('100%')
}
}
```
To avoid the preceding issue, use the **if** conditional statement instead. The sample code is as follows:
```ts
@Entry
@Component
struct MyComponent {
@State isVisible: boolean = true;
build() {
Column() {
Button ("Show/Hide")
.onClick(() => {
this.isVisible = !this.isVisible
})
if (this.isVisible) {
Row()
.width(300).height(300).backgroundColor(Color.Pink)
}
}.width('100%')
}
}
```
## Prioritizing Flex over Column/Row
By default, the flex container needs to re-lay out flex items to comply with the **flexShrink** and **flexGrow** settings. This may result in drop in rendering performance.
```ts
@Entry
@Component
struct MyComponent {
build() {
Flex({ direction: FlexDirection.Column }) {
Flex().width(300).height(200).backgroundColor(Color.Pink)
Flex().width(300).height(200).backgroundColor(Color.Yellow)
Flex().width(300).height(200).backgroundColor(Color.Grey)
}
}
}
```
To avoid the preceding issue, replace **Flex** with **Column** and **Row**, which can create the same page layout as **Flex** does.
```ts
@Entry
@Component
struct MyComponent {
build() {
Column() {
Row().width(300).height(200).backgroundColor(Color.Pink)
Row().width(300).height(200).backgroundColor(Color.Yellow)
Row().width(300).height(200).backgroundColor(Color.Grey)
}
}
}
```
## Setting Width and Height for \<List> Components
When a **\<List>** component is nested within a **\<Scroll>** component, all of its content will be loaded if its width and height is not specified, which may result in performance drop.
```ts
@Entry
@Component
struct MyComponent {
private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
build() {
Scroll() {
List() {
ForEach(this.arr, (item) => {
ListItem() {
Text(`item value: ${item}`).fontSize(30).margin({ left: 10 })
}.height(100)
}, (item) => item.toString())
}
}.backgroundColor(Color.Pink)
}
}
```
Therefore, in the above scenario, you are advised to set the width and height for the **\<List>** component as follows:
```ts
@Entry
@Component
struct MyComponent {
private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
build() {
Scroll() {
List() {
ForEach(this.arr, (item) => {
ListItem() {
Text(`item value: ${item}`).fontSize(30).margin({ left: 10 })
}.height(100)
}, (item) => item.toString())
}.width('100%').height(500)
}.backgroundColor(Color.Pink)
}
}
```
## Minimizing White Blocks During Swiping
To minimize white blocks durign swiping, expand the UI loading range by increasing the value of **cachedCount** for the **\<List>** and **\<Grid>** components. **cachedCount** indicates the number of list or grid items preloaded outside of the screen.
If an item needs to request an online image, set **cachedCount** as appropriate so that the the image is downloaded in advance before the item comes into view on the screen, thereby reducing the number of white blocks.
The following is an example of using **cachedCount**:
```ts
@Entry
@Component
struct MyComponent {
private source: MyDataSource = new MyDataSource();
build() {
List() {
LazyForEach (this.source, item => {
ListItem() {
Text("Hello" + item)
.fontSize(100)
.onAppear(()=>{
console.log("appear:" + item)
})
}
})
}.cachedCount(3) // Increase the value to enlarge the range of logs that appear.
}
}
class MyDataSource implements IDataSource {
data: number[] = [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15];
public totalCount(): number {
return this.data.length
}
public getData(index: number): any {
return this.data[index]
}
registerDataChangeListener(listener: DataChangeListener): void {
}
unregisterDataChangeListener(listener: DataChangeListener): void {
}
}
```
**Instructions**
A greater **cachedCount** value may result in higher CPU and memory overhead of the UI. Adjust the value by taking into account both the comprehensive performance and user experience.
\ No newline at end of file
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或