1# JS API Reference Template 2 3> *Writing Instructions* 4> 5> 0.1 - Delete all writing instructions after you finish the writing. 6> 7> 0.2 - Upload JS API reference documents to **docs/en/application-dev/reference/apis**. If these documents contain figures, upload the figures to the **figures** folder. 8> 9> 0.3 - Use a .d.ts file for a JS API reference document. **The file name must be in the following format: js-apis-<moduleName>.md**. Examples: 10> For @ohos.multimedia.audio in the Media subsystem, the file name is **js-apis-audio.md**. 11> For @ohos.telephony.sms in the Telephony subsystem, the file name is **js-apis-sms.md**. 12> 13> 0.4 - After uploading a JS API reference document, update the **Readme-EN.md** file in **docs/en/application-dev/reference/apis**. 14> 15> 0.5 - **Document Title**: Use phrases that summarize the module functionalities. 16> 17> 0.6 - Use the document title as the level-1 heading. Use the attributes, functions, classes, interfaces, enums, and types under the namespace as level-2 headings. Use the attributes and functions under classes as level-3 headings. 18> 19> **Version Description** 20> 21> 0.7 - **When introducing an API to an existing module, use the \<sup> tag to mark its earliest version.** 22> Example: For an existing module of API 6, if an attribute is added in API 7, suffix the \<sup> tag to the name of the new attribute, for example, **newAttribute<sup>7+</sup>**. 23> If a method is added, suffix the \<sup> tag to the method name, for example, **sim.getSimIccId<sup>7+</sup>**. The processing of new interfaces, classes, and enums is similar. 24> 25> 0.8 - **Deprecated content**: Do not delete the deprecated content directly from the document. Instead, suffix **deprecated** as a superscript to the content, and use the greater-than symbol (>) to introduce the substitute method plus the corresponding link. 26> Example: abandonmentMethod<sup>(deprecated) </sup> 27> 28> > This APIs is no longer maintained since API version 7. You are advised to use [newMethod](#newMethod) instead. 29> 30> 0.9 - For **empty APIs that will be implemented only in the MR version**, add the following information to the interface description: 31> This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. 32> 33> **Required Permissions, System Capabilities, and System APIs** 34> 35> 0.10 - **Required permissions**: Maintain consistency with the code implementation. State the required permissions at the level of methods, enumerations, and attributes. Format: 36> (Permissions that can be requested by all applications) **Required permissions**: ohos.permission.xxxx 37> (Permissions that can be requested only by system applications) **Required permissions**: ohos.permission.xxxx (available only to system applications) 38> 39> 0.11 - **System capabilities**: 40> Add the following information for each function: **System capability**: SystemCapability.xxx.xxx 41> There are two cases for the information about system capabilities added to each table (attributes, enums, constants, and variables). 42> Add the following description if all the items in a table require the same system capabilities: 43> SystemCapability.xxx.xxx 44> Add the following description if the items in a table require different system capabilities: 45> The items in the table below require different system capabilities. For details, see the table. 46> 47> 0.12 - **System APIs**: Add the following description for system APIs: This is a system API and cannot be called by third-party applications. 48> The following describes the instructions for writing a specific API. 49 50*** 51> *Writing Instructions* 52> 53> 1.1 - Use the greater-than symbol (>) to describe the initial version of an API. 54> 55> 1.2 - A module has only one initial version. 56> 57> 1.3 - Use the following sentence: "The initial APIs of this module are supported since API version ***x***. Newly added APIs will be marked with a superscript to indicate their earliest API version." Change ***x*** to the actual version. 58 59 60 61> **Note** 62> 63> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 64 65Describe the module from its functionalities, use cases, and use suggestions in this section. 66 67 68 69## Modules to Import 70 71> *Writing Instructions* 72> 73> 2.1 - Write the modules to import based on the actual conditions. Provide the **import** statement in the form of a code segment. 74> 75> 2.2 - If no module needs to be imported, change "Modules to Import" to "How to Use" and provide a usage description. 76> Example of **How to Use**: 77> Before using the **AbilityContext**, obtain the **Context** object through **[getContext()]**(***API-reference***.md). 78> 79> ```js 80> import ability_featureAbility from '@ohos.ability.featureAbility'; 81> var context = ability_featureAbility.getContext(); 82> ``` 83 84```js 85import call from '@ohos.telephony.call'; 86``` 87 88 89## Attributes 90 91> *Writing Instructions* 92> 93> 4.1 - Optional. Delete this heading if there is no attribute. 94> 95> 4.2 - If an attribute is of a custom type, create a link to the corresponding interface or enum. 96> 97> 4.3 - For a readable attribute, if it has a limited number of values with special meanings, enumerate the values. 98> 99> 4.4 - For a writable attribute, if only fixed fields are supported, describe them. 100> 101> 4.5 - If the items in the table require different system capabilities, add the following description: The items in the table below require different system capabilities. For details, see the table. Then, describe the system capabilities for each item. See [Enums](#enums). 102 103**System capability**: SystemCapability.xxx.xxx (Mandatory) 104 105| Name | Type | Readable| Writable| Description | 106| ---------------- | ----------------------------------------- | ---- | ---- | ------------------------------------------ | 107| pluggedType | [BatteryPluggedType](#BatteryPluggedType) | Yes | No | Charger type of the current device. | 108| isBatteryPresent | boolean | Yes | No | Whether the battery is supported or present.| 109 110## Enums 111 112> *Writing Instructions* 113> 114> 5.1 - Optional. Delete this heading if there is no enum. If there are multiple enums, describe them in separate level-2 headings. To create a level-2 heading, use two number signs (#). 115> 116> 5.2 - Use the actual enum name as the level-2 heading, for example, **BatteryHealthState**. 117 118Provide a brief description of the enum type. Example: Enumerates charger types. 119 120**System capability**: The items in the table below require different system capabilities. For details, see the table. (Mandatory) 121 122| Name| Value | Description | 123| ---- | ---- | ------------------------------------------------------------ | 124| NONE | 1 | Unknown type.<br>**System capability**: SystemCapability.xxx.xxx (mandatory)| 125 126## Methods 127 128> *Writing Instructions* 129> 130> 6.1 - Optional. Delete this heading if there is no method. If there are multiple methods, describe them in separate level-2 headings. To create a level-2 heading, use two number signs (#). 131> 132> 6.2 - Use the actual method name, in the format of ClassName.methodName, as the level-2 heading. For a subscription method, add the subscription event to the method name. 133> Example of a common method: sim.getSimIccId 134> Example of a subscription method: sim.on('exampleEvent') 135> 136> 6.3 - **Method calling mode**: The description must be the same as that in the .d.ts file. The description must include the parameter type, parameter name, and return value type. 137> Example: getNetworkState(slotId: number, callback: AsyncCallback\<NetworkState>): void 138> Note: The angle bracket (<>) may be identified as a label and not displayed. To ensure normal display, you can either add a backslash (\\) (in the format of "\\<>") or use escape characters \< and \>. 139> 140> 6.4.1 - **Method description**: Describe the features implemented by the method and include the prerequisites for using the method, the impact of the method, and the permissions and system capabilities required to use the method. (*Example of prerequisites: This method can be called only after the xx method is called; you must ensure that the connection to the Internet is normal. Example of impact: xx does not take effect after this method is called.*) 141> 142> 6.4.2 - **Asynchronous method**: If there are asynchronous methods, describe their return type in the method description. The return type can be a callback function or a **Promise** instance. 143> 144> 6.4.3 - **Line feed in a table**: Use \<br> for line feed. 145 146Provide the method name in the following format: (**static** if it is a static method) methodName (parameterName1: parameterType1, parameterName2: parameterType2, ...): returnValueType 147 148Describe the method. For details, see 6.4.1 and 6.4.2. 149 150**Required permissions**: ohos.permission.xxx (Delete this part if no permission is involved. If a system permission is required, specify it.) 151 152**System capability**: SystemCapability.xxx.xxx (mandatory) 153 154**Parameters** (Optional. Delete this heading if there is no parameter.) 155 156| Name | Type | Mandatory| Description | 157| ------------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 158| parameterOne | number \| string \| [CustomType](#CustomType) | Yes | Describe the parameter. Provide the value range and recommended value. If there is a fixed format, provide a format example, especially for the URI.<br>Provide a link for each custom parameter type.| 159| callback | Callback\<Array<[CustomType](#CustomType)>> | No | Describe the parameter. For an optional parameter, describe the consequences if it is not specified.<br>Example: If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| 160 161**Return value** (Optional. Delete this heading if there is no return value.) 162 163| Type | Description | 164| ------------------------------------------ | -------------------------------------------- | 165| string | Describe the return value, for example, what can be done after the return value is obtained.| 166| Promise\<Array<[CustomType](#CustomType)>> | Describe the return value, for example, what is obtained through the **Promise** instance. | 167 168**Example** 169 170```js 171// This part is mandatory. 172// Check all sample code provided in the example. 173// Minor errors such as missing symbols and variable inconsistency are unacceptable. 174// Declare all variables that are used. 175// Write an actual case that can be easily used, rather than the parameter names themselves. 176// Use comments to describe the content that are not user-defined. 177// Example: var result = xxx.createExample(parameterOne); // parameterOne is automatically obtained by scanning. 178``` 179 180## Classes/Interfaces 181 182> *Writing Instructions* 183> 184> 7.1 - Optional. Delete this heading if there is no class or interface. If there are multiple classes or interfaces, describe them in multiple level-2 headings. To create a level-2 heading, use two number signs (#). 185> 186> 7.2 - Use the actual class or interface name as the level-2 heading. 187> 188> 7.3 - If the class or interface contains both attributes and methods, write the attributes above the methods. Write their actual names in separate level-3 headings. 189> If the class of interface contains only attributes, you do not need to create a level-3 heading. Instead, use a table to display the attributes. For details, see [CustomType](#CustomType). 190 191Describe the class or interface. If there are usage restrictions, describe them as well, for example, whether there is a prerequisite and whether an instance needs to be created by using any method. 192 193### Attributes 194 195> *Writing Instructions* 196> 197> Except that a level-3 heading is used, other instructions are the same as those listed under [Attributes](#Attributes). 198 199### Methods in Classes/Interfaces 200 201> *Writing Instructions* 202> 203> 7.4 - Use the actual method name as the level-3 heading. **Do not add a prefix**. For a subscription method, add the corresponding subscription event to the method name. 204> Example of a common method: getSimIccId 205> Example of a subscription method: on('exampleEvent') 206> The other instructions are the same as those stipulated in [Methods](#Methods). 207 208Describe the method calling mode. For details, see 6.3. 209 210Describe the method. For details, see 6.4.1 and 6.4.2. 211 212**Required permissions**: ohos.permission.xxx (Delete this part if no permission is involved. If a system permission is required, specify it.) 213 214**System capability**: SystemCapability.xxx.xxx (mandatory) 215 216**Parameters** (Optional. Delete this heading if there is no parameter.) 217 218| Name | Type | Mandatory| Description | 219| ------------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 220| parameterOne | number \| string \| [CustomType](#CustomType) | Yes | Describe the parameter. Provide the value range and recommended value. If there is a fixed format, provide a format example, especially for the URI.<br>Provide a link for each custom parameter type.| 221| callback | Callback\<Array<[CustomType](#CustomType)>> | No | Describe the parameter. For an optional parameter, describe the consequences if it is not specified.<br>Example: If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| 222 223**Return value** (Optional. Delete this heading if there is no return value.) 224 225| Type | Description | 226| ------------------------------------------ | -------------------------------------------- | 227| string | Describe the return value, for example, what can be done after the return value is obtained.| 228| Promise\<Array<[CustomType](#CustomType)>> | Describe the return value, for example, what is obtained through the **Promise** instance. | 229 230**Example** 231 232```js 233// This part is mandatory. 234// Check all sample code provided in the example. 235// Minor errors such as missing symbols and variable inconsistency are unacceptable. 236// Declare all variables that are used. 237// Write an actual case that can be easily used, rather than the parameter names themselves. 238// Use comments to describe the content that are not user-defined. 239// Example: var result = xxx.createExample(parameterOne); // parameterOne is automatically obtained by scanning. 240``` 241 242## CustomType 243 244The following is an example of the custom type of a key-value pair. 245**System capability**: SystemCapability.xxx.xxx (Mandatory) 246 247| Name | Type | Readable| Writable| Description | 248| ------------ | ------------------- | ---- | ---- | ------------------------------------------------------------ | 249| parameterUrl | string | Yes | Yes | Media output URI. The following types of URIs are supported:<br>1. Relative path whose protocol type is internal. Examples:<br>Temporary directory: internal://cache/test.mp4<br><br>2. Absolute path. Examples:<br>file:///data/data/ohos.xxx.xxx/files/test.mp4<br> | 250| parameterOne | [CustomEnum](#enums) | Yes | Yes | Describe the attributes. The requirements are similar to those for the parameter description. | 251 252