API Reference Template

General Writing Instructions

NOTE

Delete all writing instructions after you finish the writing.

	Item	Writing Instruction
1	Customer-oriented mindset	Stand in the shoes of developers and provide the use cases, parameter selection principles, recommendations/tips, sample code, and anything else that a developer will need to develop the API.
2	Upload path	Upload markdown files to docs/en/application-dev/reference/apis. Upload images to docs/en/application-dev/reference/apis/figures. In addition, reference the image path in the markdown file as follows: ![](figures/exampleImage.jpg), ![](figures/exampleImage.png), or ![](figures/exampleImage.gif).
3	File name	Provide one JS API reference document for each d.ts file. Name the file in the format of js-apis-exampleModule.md, where exampleModule is a variable and must be the same as the actual module name. Examples: For @ohos.multimedia.audio in the Multimedia subsystem, the JS API file name is js-apis-audio.md. For @ohos.telephony.sms in the Telephony subsystem, the JS API file name is js-apis-sms.md.
4	Directory update	After uploading an API reference document, update the Readme-EN.md file in docs/en/application-dev/reference/apis. The directories are automatically arranged in alphabetical order.
5	Document structure	- Module description - Initial version description - Modules to Import/Usage description - API description (properties, constants, methods, enums, and custom types) The order in which APIs are described in the document must be consistent with that in which they appear in the code. If some APIs have a logical sequence, pay attention to their sequence in the API reference document.
6	Asynchronous methods (callback and promise)	Use the following sentences for callback methods. Method introduction: Describe the method. This API uses an asynchronous callback to return the result. Parameter description: callback<boolean>: Callback used to return the result. The value true indicates something, and false indicates the opposite. callback<Object>: Callback used to return something. Example: Callback used to return the AudioCapturer object. AsyncCallback<void>: Callback used to return the result. If the operation (or a specific operation description) is successful, err is undefined; otherwise, err is an error object. AsyncCallback<Object x>: Callback used to return the result. If the operation (or a specific operation description) is successful, err is undefined and data is the x object obtained; otherwise, err is an error object. Use the following sentences for promise methods. Method introduction: Describe the method. This API uses a promise to return the result. Parameter description: Promise<boolean>: Promise used to return the result. The value true indicates something, and false indicates the opposite. Promise<Object>: Promise used to return something. Example: Promise used to return the AudioCapturer object. Promise<void>: Promise that returns no value.
7	Sample code programming language	Use code blocks to provide sample code and mark the programming language. Use `js` as the mark if both JS and eTS can be used, and use `ts` if only eTS can be used.
8	Link	Link format: [Link text](Link content) Cross-folder link format: [markdown file name](../../xxx/xxx.md). One `../` indicates one upper-level folder. Intra-topic link format: [Interface A⁷⁺](#xxxa7). The text in the intra-topic link must be the same as the title to be linked. In the link, all letters must be in lowercase, and no special character (except the hyphen) or tag is included.

Mappings Between d.ts Tags and Document Fields

Except for @since, document fields mapping to the following tags must be provided under each API.

For a property or interface table, if a tag has the same value for all the items in the table, you can place the tag description above the table. Otherwise, place the tag under NOTE for each item.

d.ts Tag	Description	Document Field
@since	Version description	Each module and API must have an initial version description. Since API version 26.0.0: APIs use three-segment version numbers. Do not use superscript tags for the initial version of an API. In the module or API description, use the fixed sentence `Since: 26.0.0`. Place it on the first line below the description. Before API version 26.0.0: 1. Use the greater-than sign (>) to describe the initial version of an API. If an API does not have an initial version marker, it uses the same initial version as the module by default. 2. For APIs added to an existing module, use the `<sup>` tag to mark the corresponding version. The format is `<sup>versionNumber+</sup>`, for example, `<sup>7+</sup>`. Example: If a module exists in API version 6 and a property is added in API version 7, suffix the property with the marker, for example, `newAttribute<sup>7+</sup>`. If a method is added, suffix the method title with the marker, for example, `sim.getSimIccId<sup>7+</sup>`. The same rule applies to interfaces, classes, and enums. Special case to note: Due to the rectification of anonymous objects, the version number of the outer element of some APIs may be later than that of the inner element. To avoid confusion for developers, add the following explanation to the Interface Description section for such APIs: To standardize the definition of anonymous objects, the element definitions have been modified in API version XX. The initial version information of the historical anonymous objects has been retained, which may result in the outer element's @since version number being later than the inner element's version number. However, this does not affect the use of the API.
@deprecated	Deprecated description	Do not delete deprecated content. Instead, mark it with the superscript `(deprecated)`. Since API version 26.0.0: Use fixed sentences in the module or API description. Place the deprecated version on the line after the initial version. Example: Method description. Since: 26.0.0 Deprecated since: x.0.0 Substitutes: [newMethod](#newmethod) Before API version 26.0.0: Use the greater-than sign (>) to describe both the initial version and deprecated version. Example: abandonmentMethod^(deprecated) > NOTE > This API is supported since API version 4 and deprecated since API version 7. You are advised to use [newMethod](#newmethod) instead. If the content within a table is deprecated, you do not need to use reference syntax. Describe it directly in the body text. Example: Note: This API is supported since API version 4 and deprecated since API version 7. You are advised to use [newMethod](#newmethod) instead.
@FAModelOnly / @StageModelOnly	Model restriction description	Model restriction: This API can be used only in the FA model. Model restriction: This API can be used only in the stage model.
@form	Widget capability description	Since API version 26.0.0: Widget capability: This API can be used in ArkTS widgets since version x. Before API version 26.0.0: Widget capability: This API can be used in ArkTS widgets since API version x.
@atomicservice	Atomic service description	Since API version 26.0.0: Atomic service API: This API can be used in atomic services since version x. Before API version 26.0.0: Atomic service API: This API can be used in atomic services since API version x.
@systemapi	System API description	System API: This is a system API.
@syscap	System capability description	System capability: SystemCapability.xxx.xxx
@permission	Permission description	1. If only one permission is required, use the following format: Required permissions: ohos.permission.xxxx 2. If multiple permissions are required, separate them with and or or in the following format: Required permissions: ohos.permission.A and ohos.permission.B Required permissions: ohos.permission.A or ohos.permission.B 3. When permission requirements vary by version, describe them in a list based on the actual requirements of each version, with later versions listed first. Example: Required permissions: - API version y+: ohos.permission.B - API version x-(y-1): ohos.permission.A 4. If permissions are required only in certain fixed scenarios, keep the permission after Required permissions consistent with @permission in the d.ts file, and then add the scenario description. There are two cases: If the scenario is simple, add the description in parentheses. If the scenario is complex, describe it on new lines. Example 1: Required permissions: ohos.permission.A (required only when the created window type is AA) Example 2: Required permissions: ohos.permission.A - When the application is in situation xx, ohos.permission.B must also be requested. - When the application is in situation yy, no permission needs to be requested.
@extends	Inheritance	If the tag is carried or the extends relationship exists but the tag is not carried, clearly state the following information: ExampleA inherits from ExampleB (provide the link of ExampleB).
@DecoratorName	Decorator type	If a class, interface, or property is annotated with a decorator, the relevant description must clearly indicate "Decorator: @DecoratorName", for example, Decorator: @Sendable.

Writing Requirements for System APIs and Public APIs

To support the release of both the Full SDK and Public SDK, API reference documents for System APIs and Public APIs must be written in different Markdown files.

Depending on whether the API definition file of a module contains system APIs, the module can fall into one of the following three cases:

The entire module is a public API
The entire module is a system API
A module contains both system APIs and public APIs

Tip: How do I determine which case applies?

Use the d.ts file of the module as the reference:

If the entire module does not contain the @systemapi tag, the entire module is a public API.

If the entire module is annotated with the @systemapi tag, the entire module is a system API. Sometimes the entire module is not annotated with the @systemapi tag, but every API in the module is annotated with @systemapi. In this case, the entire module is very likely to be a system API, but you still need to confirm with the API designer. If the tag is missing from the module, submit an issue for handling.

Most other cases indicate that the module contains both system APIs and public APIs.

The Entire Module Is a Public API

No special requirements.

The Entire Module Is a System API

File name: End the file name with -sys.md, for example, xxx-sys.md.
Document title: Use # @ohos.xxx (xxx) (System API).

NOTE

Use English parentheses.

For a guide corresponding to system APIs, use # @ohos.xxx (xxx) (for System Applications Only) as the title.

Module description: Add This module provides system APIs. to the module description. Example:

API description xxxxx.

NOTE

The APIs of this module are system APIs.

A Module Contains Both System APIs and Public APIs

File location: Place the system API file and public API file in the same folder.
File name: Add -sys.md to the public API file name to form the system API file name, that is, name it xxx-sys.md.
Document title: Use # @ohos.xxx (xxx) (System API).
Module description: Add This page contains only system APIs of this module. For other public APIs, see [xxx](js-apis-xxx.md). to the module description.

Example:

API description xxxxx.

NOTE

This page contains only system APIs of this module. For other public APIs, see @ohos.app.ability.common (Ability Common Module).

Other Notes

In the Readme file, place the system API files after the public API files, and use the  deletion tags.

Example:

// Readme-EN.md

- [@ohos.app.ability.Ability (Ability)](js-apis-app-ability-ability.md)
- [@ohos.app.ability.AbilityConstant (Ability Constants)](js-apis-app-ability-abilityConstant.md)
<!--Del-->
- [@ohos.app.ability.AbilityConstant (Ability Constants)(System API)](js-apis-app-ability-abilityConstant-sys.md)
- [@ohos.app.ability.application (Application)(System API)](js-apis-app-ability-application-sys.md)
<!--DelEnd-->

System API files can link to public API files, but public API files must not link to system API files. Otherwise, broken links will occur when public documents are released.

The following describes the instructions for writing a specific API reference document.

Document Title

Writing Instructions

Document title: Use phrases that summarize the module functionalities. Examples: Ability and SIM Card Management

Heading levels: Use the document title as the level-1 heading, which is prefixed with # followed by a space. Use the properties, functions, classes, interfaces, enums, and types under the namespace as level-2 headings, which are prefixed with ## followed by a space. Use the properties and functions under classes as level-3 headings, which are prefixed with ### followed by a space.

Initial version description: Place the version description after the module description. A module has only one initial version.
Use the standard sentence "**Since:** x". Change x to the actual version number.

For the sentence patterns used before API version 26.0.0, see the description of @since in Mappings Between d.ts Tags and Document Fields.

Describe the module from its functionalities, use cases, and recommendations in this section.

Example 1: description of the background task management module

This module provides background task management.

If a service needs to be continued when the application or service module is running in the background (not visible to users), the application or service module can request a transient task or continuous task for delayed suspension based on the service type.

Example 2: description of the call module

The call module provides call management functions, including making calls, redirecting to the dial screen, obtaining the call status, and formatting phone numbers.

To subscribe to the call state, use observer.on('callStateChange').

Example 3: description of the distributed data management module

The distributed data management module provides collaboration between databases of different devices for applications.

The APIs provided by distributed data management can be used to save data to the distributed database and perform operations such as adding, deleting, modifying, querying, and synchronizing data in the distributed database.

Example 4: description of the linear container ArrayList module

ArrayList is a linear data structure that is implemented based on arrays. ArrayList can dynamically adjust the capacity based on project requirements. It increases the capacity by 50% each time.

Similar to ArrayList, Vector is also implemented based on arrays and can dynamically adjust the capacity. It increases the capability by 100% each time.

When compared with LinkedList, ArrayList is more efficient in random access but less efficient in the addition or removal operation, because its addition or removal operation affects the position of other elements in the container.

You are advised to use ArrayList when elements in a container need to be frequently read.

Since: 26.0.0

Modules to Import

Writing Instructions

Write the modules to import based on the actual conditions. Provide the import statement in the form of a code block.

If no module needs to be imported, change "Modules to Import" to "Usage" and provide a usage description.
Example of Usage:
Before using the AbilityContext, obtain the Context object through [getContext()](API-reference.md).
   import { featureAbility } from '@kit.AbilityKit';
   let context = featureAbility.getContext();

import { call } from '@kit.TelephonyKit';

Properties

Writing Instructions

This section is optional. Delete it if there is no property.

If a property is of a custom type, create a link to the corresponding interface or enum.

A read-only property is marked with readonly in d.ts files. If it has a limited number of values with special meanings, enumerate the values or provide a link to the corresponding enum.

For an optional property, if only fixed fields are supported, describe them. A property defined with a question mark (?) is optional.

If a property is annotated with a decorator, the relevant description must clearly indicate "Decorator".

System capability: SystemCapability.xxx.xxx (This part is mandatory.)

Name	Type	Read Only	Optional	Description
pluggedType	[BatteryPluggedType](#batterypluggedtype)	Yes	No	Charger type of the current device. Decorator: @Trance
isBatteryPresent	boolean	Yes	No	Whether the battery is supported or present.

Constants

Writing Instructions

This section is optional. Delete it if there is no constant. It corresponds to const in the .d.ts file.

Some constants are used to define read-only variables and have no values. In this case, the table contains four columns: Name, Type, Read Only, and Description.

If a property is of a custom type, create a link to the corresponding interface or enum.

System capability: SystemCapability.xxx.xxx (This part is mandatory.)

Name	Type	Value	Description
uid	number	1	User identifier (UID) of a process.
pid	number	2	Process ID (PID) of a process.

Methods

Writing Instructions
This section is optional. Delete it if there is no method. If there are multiple methods, describe them in separate level-2 headings, prefixed with ## followed by a space.

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.

Example of a common method: sim.getSimIccId Example of a subscription method: sim.on('exampleEvent')
The method call mode is the same as that in .d.ts. The keywords (for example, static, abstract, set, and get), parameter types, parameter names, and return value types must be included.

Examples:

getNetworkState(slotId: number, callback: AsyncCallback<NetworkState>): void
abstract makeNode(uiContext: UIContext): FrameNode | null
Note 1: 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 >.

Note 2: If the methods declared by the set and get keywords appear in pairs and have the same names, place them under the same title and describe the method call modes, tags, parameters, and return values in sequence. It is recommended that the set method be placed before the get method. For details, see backgroundColor.
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.)

Asynchronous methods: If there are asynchronous methods, describe their return type in the method description. For details, see item 14 in "General Writing Instructions."

Line feed in a table: Use <br> for line feed.

Provide the method call mode in the following format: (keyword, if available) methodName (parameterName1: parameterType1, parameterName2: parameterType2, ...): returnValueType

Describe the method. For details, see the fourth and fifth points in "Writing Instructions" above.

Since: 26.0.0

Model restriction: This API can be used only in the FA model. (Delete this part if it is not involved.)

System API: This is a system API. (Delete this part if it is not involved.)

Required permissions: ohos.permission.xxx (Delete this part if no permission is involved.)

System capability: SystemCapability.xxx.xxx (This part is mandatory.)

Parameters (This part is optional. Delete it if there is no parameter.)

Name	Type	Mandatory	Description
parameterOne	number \| string \| CustomType	Yes	The parameter description must include the meaning and purpose of the parameter, the scenarios in which the parameter is used, suggestions for selection, and relationships between parameters. The parameter value description must include the value range, unit, default value, principles for selection, or recommended value. If the boundary value involves restrictions/exceptions, describe the specific scenario. If there is a fixed format, provide a format example, especially for URIs. Provide a link for each custom parameter type.
callback	Callback<Array<CustomType>>	No	Describe the parameter. For an optional parameter, describe the consequences if it is not specified. Example: If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. For details about how to write callback methods, see item 14 in "General Writing Instructions."

Return value (This part is optional. Delete it if there is no return value.)

Type	Description
string	Describe the return value from the following aspects: 1. What can be done after the return value is obtained. 2. If the return values can be enumerated, describe the meaning of the return values. 3. If the return value is a specific value or format, keep the value or format consistent with the actual implementation.
Promise<Array<CustomType>>	Describe the return value. For details about how to write promise methods, see item 14 in "General Writing Instructions."

Error codes (This part is optional. Delete it if no error code is thrown.)

For details about the error codes, see [moduleName Error Codes](link to the error code document of the corresponding module).

ID	Error Message
1300001	Repeated operation.
1300002	This window state is abnormal.

Example

// This part is mandatory.

// All example code must be self-checked to ensure that the execution results meet expectations.
// Minor errors such as missing symbols and variable inconsistency are unacceptable.
// Declare all variables that are used.
// When the interface parameters are abnormal, it is necessary to verify whether the code can catch the error and throw the corresponding error code.

// Write an actual case that can be easily used, rather than the parameter names themselves. Use comments to describe the content that are not user-defined.
// Example: let result = xxx.createExample(parameterOne); // parameterOne is automatically obtained by scanning.

// Provide clear and concise comments in the following typical scenarios:
// 1. The meaning of a variable name or the code logic is not self-explanatory.
// 2. A complex algorithm or special syntax is involved.

On and Off Subscription Methods

Writing Instructions

The basic requirements are the same as those provided in Methods. The following describes only the differences.

Use the actual method name, in the format of ClassName.methodName plus the subscription event, as the level-2 heading. Examples: sim.on(?exampleEvent?) and on('play' | 'pause' | 'stop' | 'reset')

Method calling mode: The description must be the same as that in the .d.ts file and include the parameter type, event name, parameter name, and return value type. Example: on(type: 'ringerModeChange', callback: Callback<AudioRingMode>): void 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 >.

Provide the method name in the following format: (static if it is a static method) methodName (parameterName1: parameterType1, parameterName2: parameterType2, ...): returnValueType

Describe the method. For details, see the fourth and fifth points in "Writing Instructions" under Methods.

Since: 26.0.0

Model restriction: This API can be used only in the FA model. (Delete this part if it is not involved.)

System API: This is a system API. (Delete this part if it is not involved.)

Required permissions: ohos.permission.xxx (Delete this part if no permission is involved.)

System capability: SystemCapability.xxx.xxx (This part is mandatory.)

Parameters (This part is optional. Delete it if there is no parameter.)

Name	Type	Mandatory	Description
type	string	Yes	Describe the event and when or how it will be triggered. If a method involves multiple events, describe them separately. Example 1 (single event): Type of the event. The 'play' event is triggered when the play() API is called and audio playback starts. Example 2 (multiple events): Type of the event. The following events are supported:
callback	Callback<CustomType>	No	Describe the parameter. The instructions are the same as those provided under Methods.

Return value (This part is optional. Delete it if there is no return value.)

Type	Description
string	Describe the return value. The instructions are the same as those provided under Methods.

Example

// This part is mandatory. The instructions are the same as those provided under [Methods](#methods).

// Check all sample code provided in the example.
// Minor errors such as missing symbols and variable inconsistency are unacceptable.
// Declare all variables that are used.

// Write an actual case that can be easily used, rather than the parameter names themselves. Use comments to describe the content that are not user-defined.
// Example: let result = xxx.createExample(parameterOne); // parameterOne is automatically obtained by scanning.

// Provide clear and concise comments in the following typical scenarios:
// 1. The meaning of a variable name or the code logic is not self-explanatory.
// 2. A complex algorithm or special syntax is involved.

Classes/Interfaces

Writing Instructions

This section is optional. Delete it if there is no class or interface. If there are multiple classes or interfaces, describe them in separate level-2 headings, prefixed with ## followed by a space.

Use the actual class or interface name as the level-2 heading.

If the class or interface contains both properties and methods, write the properties above the methods. Write their actual names in separate level-3 headings. If the API contains only properties, you do not need to create a level-3 heading. Instead, use a table to display the properties.

If a class or interface is annotated with a decorator, the relevant description must clearly indicate "Decorator".

Describe 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.

Decorator: @Sendable

Properties

Writing Instructions

Except that level-3 headings are used, other requirements are the same as those in Properties. Write the interface name in the form of level-2 heading.

Methods in Classes/Interfaces

Writing Instructions

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. Example of a common method: getSimIccId Example of a subscription method: on('exampleEvent')

Other instructions are the same as those provided under Methods.

Enums

Writing Instructions

This section is optional. Delete it if there is no enum. If there are multiple enums, describe them in separate level-2 headings, prefixed with ## followed by a space.

Use the actual enum name as the level-2 heading, for example, BatteryHealthState.

Provide a brief description of the enum type. Example: Enumerates the charger types.

Since: 26.0.0

System capability: SystemCapability.xxx.xxx (This part is mandatory.)

Name	Value	Description
NONE	1	Unknown type.

Types

Writing Instructions

This section is optional. Delete it if there is no type. It corresponds to type in the .d.ts file.

Currently, there are two templates, corresponding to two different scenarios.

When the type is union or intersection, the definition format is type Xxx = number | string | 'xxx' or type AB = InterfaceA & InterfaceB. For details, see Template 1.

If the type is the alias of a function or interface, the definition format is type Xxx<Aaa, Bbb> = (param1: number, param2: string) => void or type Xxx = (param1: number, param2: string). Explain the parameters based on the function or interface template and provide its definition before the list. For details, see Template 2.

If the value range is of a specific value, such as a fixed string or enumerated value, describe the data type and specified value. If the value range is of a specified type, describe whether any value of the type or a value range is used.

If a property is of a custom type, create a link to the corresponding interface or enum.

Type-Template-1

type Xxx = number | string | 'xxx'

Provide a brief description of the type. Example: Enumerates the value types.

Provide the logic for obtaining the actual value of this type. Example: The value type is the union set or intersection set in the following table.

Since: 26.0.0

System capability: SystemCapability.xxx.xxx (This part is mandatory.)

Type	Description
number	The value can be any number.
string	The value can be any string.
'xxx'	Meaning of the value. The value is a string fixed at ExampleString.

Type Template 2

(The function alias is used as an example.)

(Provide the definition of the type here.) type Xxx<Aaa, Bbb> = (param1: number, param2: string) => Interface1

Since: 26.0.0

System capability: SystemCapability.xxx.xxx (This part is mandatory.)

Parameters (This part is optional. Delete it if there is no parameter.)

Name	Type	Mandatory	Description
param1	number	Yes	Describe the parameter. The instructions are the same as those provided under Methods.
param2	string	No	Describe the parameter. The instructions are the same as those provided under Methods.

Return value (This part is optional. Delete it if there is no return value.)

Type	Description
Interface1	Describe the return value. The instructions are the same as those provided under Methods.

Type Template 3

(Here, an Interface alias containing multiple property fields is used as an example)

Provide the specific definition form of type here: type Xxx = { aaa: string; bbb?: number; }

Since: 26.0.0

System capability: SystemCapability.xxx.xxx (This part is mandatory.)

Name	Type	Mandatory	Description
aaa	string	Yes	Describes the property.
bbb	number	No	Describes the property.

FAQs for API Reference Writing

Q1: How do I write a parent module with secondary modules?

Requirements for writing a parent module with level-2 modules:

Clearly define the functionality and purpose of the module in the module overview.

Provide the API level and other related information according to the requirements for an API module.

List the level-2 modules contained in the module by section, provide definitions and functionality descriptions for each level-2 module (ensure consistency with the overviews on the sub-module pages), and link to the level-2 modules.

For each section, provide the @syscap field defined in the d.ts file. The toolchain uses this field to add the device-type attribute to the topic.

The following is an example.

@ohos.arkui.node

The Node module provides level-2 module APIs of custom nodes to export and use.

NOTE

The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Custom nodes are not available in DevEco Studio Previewer.

BuilderNode

The BuilderNode module provides APIs for creating a BuilderNode – a custom node that can be used to mount built-in components. Avoid mounting a BuilderNode as a child node to other custom nodes.
System capability: ohos.xxx

FrameNode

The FrameNode module provides APIs for a FrameNode, which represents an entity node in the component tree. It can be used by a NodeController to mount a BuilderNode (that holds the to FrameNode) to a <NodeContainer> or mount a RenderNode to another FrameNode.
System capability: ohos.xxx

Question 2: Where should I place SysCap if a class inherits from another and only one module is imported?

The declaration format is as follows: EmbeddableUIAbilityContext.d.ts. The following is an example:

EmbeddableUIAbilityContext

EmbeddableUIAbilityContext provides the context environment for the EmbeddableUIAbility that needs to save states. It inherits from UIAbilityContext.
EmbeddableUIAbilityContext provides the necessary configurations and methods for managing EmbeddableUIAbilities and ServiceExtensionAbilities, such as starting an EmbeddableUIAbility, terminating an EmbeddableUIAbility to which the current EmbeddableUIAbilityContext belongs, and starting, terminating, connecting to, or disconnecting from a ServiceExtensionAbility.

NOTE

The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The APIs of this module must be used in the main thread, but not in child threads such as Worker and TaskPool.

Modules to Import

import { common } from '@kit.AbilityKit';

Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Atomic service API: This API can be used in atomic services since API version 12.

Problem 3: How do I document an API with a known issue?

Describe the known issue in the release notes.

In the "API Description" section of the API reference, use the following fixed phrase to describe the known issue with the API: "This API has known issues. For details, see Known Issues.""

After the bug of the API is fixed, search for the above fixed phrase in all documents related to the API and remove it.

getStringSync

getStringSync(resId: number, ...args: Array<string | number>): string

Obtains a string based on the specified resource ID and formats the string based on args. This API returns the result synchronously. This API has known issues. For details, see "Known Issues" (linked to the known issues in the Release Notes).

Change History

Change Description	Date
Added the writing method for three-segment version descriptions in API version 26.0.0 and later.	2026/03/20
Revised the description of the @deprecated tag and added the writing method in the table.	2025/12/03
Added the writing method of classes, interfaces, and properties modified with decorators.	2025/09/19
Added the "FAQs for API Reference Writing" section to provide the API reference writing method and common problems in special scenarios.	2025/07/22
Streamlined the standard wording for Promise<void>. New content should use the new wording. There is no need to actively revise existing content if it already conveys the intended meaning.	2025/06/10
Added a standard wording for "Explanation of the @since version number for anonymous object rectification."	2025/06/03
Optimized the writing standards for permissions to cover various types of permission descriptions and meet the requirements of scanning tools.	2025/03/12
Added Type template 3, which includes an interface alias with multiple property fields.	2025/03/04
Added a requirement for example code to capture parameter exceptions.	2025/03/03
Added a template for read-only variables defined by constants.	2024/12/31
1. Updated the method template by adding the description of methods carrying the declaration of keywords such as `static`.	2024/05/16
1. Updated the type template. In addition to the union type, the intersection type and the type used as the alias of a function or interface were added. 2. Updated the property template to specify the rules for determining optional properties in the interfaces and interface definitions.	2024/05/10
1. Changed the template for Properties from Read, Write, and Mandatory to Read Only and Mandatory. 2. Changed the template for Types by using Value Range and Description, and provided the related description. 3. Deleted the custom type, and incorporated the related description under Classes/Interfaces.	2023/02/01
1. Provided the general writing instructions in a table. 2. Added the description about how to reference an image in "Upload path". 3. Added the "Document structure" item to describe the sequence of nodes in the API reference document. 4. Added the description for multiple permissions in "Permission description". 5. Added the description of @FAModelOnly and @StageModelOnly in the API reference document. 6. Added the description of asynchronous methods (callback and promise). 7. Added the standards and specifications for the sample code programming language. 8. Added the standard format for links used in the API reference document. 9. Added examples for "Module description". 10. Added the description of on and off subscription methods. 11. Updated the description of @syscap. 12. Updated the description of @systemapi. Now only the sentence "This is a system API." is used. 13. Deleted the MR version description.	2022/6/24
Added the error code description.	2022/10/11
1. Added the template for constant and type. 2. Modified the table of the custom type interface by deleting the Readable and Writable columns and adding the Mandatory column, for consistency with the content of the .d.ts file. 3. Added the deprecated description for APIs with both the initial version and deprecated version.	2022/11/22