1# Advanced TS Component Reference Template
2
3## General Writing Instructions
4
5|      | Item            | Writing Instruction                                                        |
6| ---- | ------------------ | ------------------------------------------------------------ |
7| 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 component.**|
8| 2    | Upload path          | Upload markdown files to **docs/en/application-dev/reference/apis-*ExampleKit*-kit/**.<br>Upload images to **docs/en/application-dev/reference/apis-*ExampleKit*-kit/figures**. In addition, reference the image path in the markdown file as follows: **\![]\(figures/exampleImage.jpg)**, **\![]\(figures/exampleImage.png)**, or **\![]\(figures/exampleImage.gif)**.|
9| 3    | File name          | Provide one advanced TS component reference document for each .d.ets file. Name the reference document the same as the .d.ets file name, except by changing the dots (.) to hyphens (-).<br>Example:<br>ohos-arkui-advanced-Chip.md |
10| 4    | Directory update          | After uploading an advanced TS component reference document, update the **Readme-EN.md** file in **docs/en/application-dev/reference/apis-*exampleKit*-kit**.|
11| 5    | Document structure          | - Component description<br>- Initial version description<br>- Modules to import/Usage description<br>- Child components<br>- API description (attributes, constants, methods, enums, and custom types)<br>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 document.|
12| 6   | Sample code programming language      | Use code blocks to provide sample code, and mark the programming language ts by adding `// xxx.ets` at the beginning of every sample code block.|
13| 7   | Link          | Link format: [Link text]\(Link content)<br>Cross-folder link format: [markdown file name]\(\.\./../xxx/xxx.md). One `../` indicates one upper-level folder.<br>Intra-topic link format: [Interface A<sup>7+</sup>]\(#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.|
14
15## Mappings Between .d.ets Tags and Document Fields
16
17Except for @since, document fields mapping to the following tags must be provided under each API.
18
19For an attribute 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.
20
21| .d.ets Tag                    | Description    | Document Field                                                    |
22| ------------------------------ | -------- | ------------------------------------------------------------ |
23| @since                         | Version description| 1. Use the greater-than sign (>) followed by a space to indent the description about the initial version of the component. Unless otherwise marked, all APIs in the component have the same initial version.<br>2. When introducing an API to an existing component, use the `<sup>` tag to mark its initial version. The format is `<sup>versionNumber+</sup>`, for example, `<sup>7+</sup>`.  <br>When introducing an attribute to an existing component, suffix the `<sup>` tag to the new attribute name, for example, `newAttribute<sup>7+</sup>`.<br>When introducing a method to an existing component, suffix the `<sup>` tag to the method name, for example, `getSimIccId<sup>7+</sup>`. The same rule applies to new interfaces, classes, and enums.|
24| @deprecated                    | Deprecated description| Do not delete the deprecated content from the document. Instead, suffix `deprecated` as a superscript to the content, and use the greater-than sign (>) to introduce the initial version and deprecated version. If there is no substitute API, provide the substitute solution.<br>Example: abandonmentMethod<sup>(deprecated)</sup><br>> This API is supported since API version 4 and deprecated since API version 7. You are advised to use [newMethod]\(#newmethod) instead.|
25| @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.|
26| @form                          | Widget capability description| **Widget capability**: Since API version *x*, this feature is supported in ArkTS widgets.|
27| @systemapi                     | System API description| **System API**: This is a system API.                           |
28| @syscap                        | System capability description| **System capability**: SystemCapability.*A.B*                      |
29| @permission                    | Permission    | 1. If only one permission is required for using the component, use the following format:<br>**Required permissions**: ohos.permission.examplePermission<br>2. If multiple permissions are required for using the component, provide the permissions with **and** or **or** in the following format:<br>**Required permissions**: ohos.permission.examplePermissionA and ohos.permission.examplePermissionB<br>**Required permissions**: ohos.permission.examplePermissionA or ohos.permission.examplePermissionB|
30| @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*).|
31
32The following describes the instructions for writing a specific component reference document.
33
34***
35
36# Document Title
37
38> *Writing Instructions*
39>
40> 1. **Document title**: Use phrases that summarize the component functionalities. Examples: `Button` and `Slider`.
41> 2. **Heading levels**: Use the document title as the level-1 heading, which is prefixed with `#` followed by a space. Use the functions, classes, interfaces, enums, and types as level-2 headings, which are prefixed with `##` followed by a space. Use the attributes and functions under classes as level-3 headings, which are prefixed with `###` followed by a space.
42> 3. **Initial version description**: Use the greater-than symbol (>) to indent the description about the initial version of the component. Use a line break after **NOTE**.<br>Place the version description after the component description. A component has only one initial version.<br>Use the following sentence: "This component is 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 number.
43
44Describe the component from its functionalities, use cases, and recommendations in this section. 
45
46
47
48
49
50**Example**: @ohos.arkui.advanced.EditableTitleBar (Editable Title Bar)
51
52The editable title bar is a title bar that comes with button icons, typically **Cancel** on the left and **Confirm** on the right, on a multi-select or editing page.
53
54## Modules to Import
55
56> *Writing Instructions*
57>
58> This section is mandatory. Write the modules to import based on the actual conditions. Provide the `import` statement in the form of a code block.<br>**Example:**
59>
60
61```js
62import { EditableTitleBar } from "@ohos.arkui.advanced.EditableTitleBar"
63```
64
65## Child Components
66
67> *Writing Instructions*
68>
69> If there are restrictions on the use of child components, describe them here.
70
71Example: The *ExampleA* component can contain the child component *ExampleB*.
72
73
74## Attributes
75
76> *Writing Instructions*
77>
78> This section is mandatory. Specify whether universal attributes are supported (with links provided).
79
80Example:
81
82Universal attributes are not supported.
83
84## Events
85
86> *Writing Instructions*
87>
88> 1. This section is mandatory. Specify whether universal events are supported (with links provided).
89
90Example:
91
92Universal events are not supported.
93
94## Structs
95
96> *Writing Instructions*
97>
98>  1. This section is optional. Delete it if there is no attribute. If there are multiple classes or interfaces, describe them in separate level-2 headings, prefixed with `##` followed by a space.
99>  2. The writing requirements are the same as those provided in [Methods](js-template.md#methods).
100>  3. Use the actual struct name as the level-2 heading.
101>  4. If the struct or its parameters are modified by a decorator, specify the decorator type.
102
103Example:
104
105ComposeListItem({contentItem?: ContentItem, operateItem?: OperateItem})
106
107**Decorator**: \@Component
108
109
110**Parameters**
111
112
113| Name       | Type                       | Mandatory| Decorator| Description                  |
114| ----------- | --------------------------- | ---- | ---------- | ---------------------- |
115| contentItem | [ContentItem](#contentitem) | No  | \@Prop     | Defines the left and middle elements.|
116| operateItem | [OperateItem](#operateitem) | No  | \@Prop     | Defines the right element.        |
117
118## Methods
119
120> *Writing Instructions*
121>
122> 1. This section is optional. Delete it if there is no method. The writing requirements are the same as those provided in [Methods](js-template.md#methods).
123> 2. No sample code is required.
124
125
126## Classes
127
128> *Writing Instructions*
129>
130> 1. This section is optional. Delete it if there is no class. If there are multiple classes, describe them in separate level-2 headings, prefixed with `##` followed by a space.
131> 2. Use the actual class or interface name as the level-2 heading.
132> 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. If the API contains only attributes, you do not need to create a level-3 heading. Instead, use a table to display the attributes.
133
134### Attributes
135
136> *Writing Instructions*
137>
138> This section is optional. Delete it if there is no attribute. The writing requirements are the same as those provided in [Attributes](js-template.md#attributes).
139
140### Methods in Classes
141
142> *Writing Instructions*
143>
144> 1. This section is optional. Delete it if there is no method in the class. The writing requirements are the same as those provided in [Methods](js-template.md#methods).
145
146## Enums
147
148> *Writing Instructions*
149>
150> 1. This section is optional. Delete it if there is no enum. The writing requirements are the same as those provided in [Enums](js-template.md#enums).
151
152## Types
153
154> *Writing Instructions*
155>
156> 1. This section is optional. Delete it if there is no type. The writing requirements are the same as those provided in [Types](js-template.md#types).
157
158## Example
159
160Provide the display effect of the example.
161
162> *Writing Instructions*
163>
164> 1. This section is mandatory. Use a level-2 or level-3 heading, and provide sample codes and figures under the heading.
165> 2. Use multiple level-3 headings to present the function of a component or module one by one, if the functions are complex.
166>
167> ```tsx
168> // This section is mandatory.
169> 
170> // Check all sample code provided in the example.
171> // Minor errors such as missing symbols and variable inconsistency are unacceptable.
172> // Declare all variables that are used.
173> // Mark the programming language of the sample code.
174> 
175> // 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.
176> // Example: var result = xxx.createExample(parameterOne); // parameterOne is automatically obtained by scanning.
177> 
178> // The layout of the image must be clear, the color must be simple and elegant, and the image must be copyrighted.
179> 
180> // Provide clear and concise comments in the following typical scenarios:
181> // 1. The meaning of a variable name or the code logic is not self-explanatory.
182> // 2. A complex algorithm or special syntax is involved.
183> ```
184
185Example:
186
187```ts
188// xxx.ets
189@Entry
190@Component
191struct CheckboxExample {
192  build() {
193    Row() {
194      // Generate a check box that is selected by default and can be clicked to display its status.
195      Checkbox({name: 'checkbox1',  group: 'checkboxGroup'})
196        .select(true)
197        .selectedColor(0xed6f21)
198        .onChange((value: boolean) => {
199          console.info('Checkbox1 change is'+ value)
200        })
201      // Generate a check box that is not selected by default and can be clicked to display its status.
202      Checkbox({name: 'checkbox2',  group: 'checkboxGroup'})
203        .select(false)
204        .selectedColor(0x39a2db)
205        .onChange((value: boolean) => {
206          console.info('Checkbox2 change is'+ value)
207        })
208    }
209  }
210}
211```
212<!--no_check-->
213