diff --git a/en/application-dev/reference/arkui-js/js-components-custom-basic-usage.md b/en/application-dev/reference/arkui-js/js-components-custom-basic-usage.md index 8ae629cba3025d8d6b6d9f3ea4597678a6c1d138..b6f659f069b4e7c5f6dc6347664552a8c6a82e4d 100644 --- a/en/application-dev/reference/arkui-js/js-components-custom-basic-usage.md +++ b/en/application-dev/reference/arkui-js/js-components-custom-basic-usage.md @@ -1,6 +1,7 @@ -# Basic Usage +# Basic Usage of Custom Components + +Custom components are existing components encapsulated based on service requirements. A custom component can be invoked multiple times in a project to improve the code readability. You can import a custom component to the host page through **element** as shown in the following code snippet: -Custom components are existing components encapsulated based on service requirements. A custom component can be invoked multiple times in a project to improve the code readability. You can introduce a custom component to the host page through **element** as shown in the following code snippet: ```html
@@ -8,8 +9,8 @@ Custom components are existing components encapsulated based on service requirem
``` +The following is an example of using a custom component with **if-else**, which displays **comp1** when **showComp1** is set to **true** and displays **comp2** otherwise. -The following is an example of using a custom component with **if-else**: ```html @@ -19,18 +20,142 @@ The following is an example of using a custom component with **if-else**: ``` +The **name** attribute indicates the custom component name (optional), which is case-insensitive and is in lowercase by default. The **src** attribute indicates the **.hml** file path (mandatory) of the custom component. If **name** is not set, the **.hml** file name is used as the component name by default. + + +## Custom Events + +To bind an event to a custom child component, use the **(on|@)event-name="bindParentVmMethod"** syntax. **this.$emit('eventName', { params: 'passedParameters' })** is used in the child component to trigger the event and pass parameters to the parent component. The parent component then calls the **bindParentVmMethod** API and receives parameters passed by the child component. + +> **NOTE** +> +> For child component events that are named in camel case, convert the names to kebab case when binding the events to the parent component. For example, use **\@children-event** in the parent component instead of **childrenEvent** used in the child component. + +**Example 1 with parameters passed** + +The following example describes how to define a child component **comp**: + +```html + +
+ Click here to view the hidden text. + hello world +
+``` + +```css +/* comp.css */ +.item { + width: 700px; + flex-direction: column; + height: 300px; + align-items: center; + margin-top: 100px; +} +.text-style { + font-weight: 500; + font-family: Courier; + font-size: 40px; +} +``` + +```js +// comp.js +export default { + data: { + showObj: false, + }, + childClicked () { + this.$emit('eventType1'); + this.showObj = !this.showObj; + }, +} +``` + +The following example describes how to import **comp** to the parent component: + +```html + + +
+ +
+``` + +```css +/* xxx.css */ +.container { + background-color: #f8f8ff; + flex: 1; + flex-direction: column; + align-content: center; +} +``` + +```js +// xxx.js +export default { + textClicked () {} +} +``` + +**Example 2 with no parameters passed** + +The following example describes how to define a child component **comp**: + +```html + +
+ Click here to view the hidden text. + hello world +
+``` + +```js +// comp.js +export default { + childClicked () { + this.$emit('eventType1', { text: 'Receive the parameters from the child component.' }); + this.showObj = !this.showObj; + }, +} +``` + +In the following example, the child component passes the **text** parameter to the parent component, and the parent component obtains the parameter through **e.detail**: + +```html + + +
+ Parent component: {{text}} + +
+``` + +```js +// xxx.js +export default { + data: { + text: 'Start' + }, + textClicked (e) { + this.text = e.detail.text; + }, +} +``` + +![EventParameters](figures/EventParameters.gif) + + +## Custom Component Data -- The **name** attribute indicates the custom component name (optional), which is case-insensitive and is in lowercase by default. The **src** attribute indicates the **.hml** file path (mandatory) of the custom component. If **name** is not set, the **.hml** file name is used as the component name by default. -- Event binding: Use **(on|@)***child1* syntax to bind a child component event to a custom component. In the child component, use **this.$emit('***child1***', {params:'***parameter to pass***'})** for event triggering and value transferring. In the parent component, call **bindParentVmMethod** method and receive the parameters passed from the child component. - > **NOTE** - > - > For child component events that are named in camel case, convert the names to kebab case when binding the events to the parent component. For example, use **\@children-event** instead of **childrenEvent**: **\@children-event="bindParentVmMethod"**. +In the JS file of a custom component, you can define, pass, and process data by declaring fields such as **data**, **props**, and **computed**. For details about how to use **props** and **computed**, see [Data Transfer and Processing](js-components-custom-props.md). -**Table 1** Objects +**Table 1** Custom component data -| Name | Type | Description | +| Name | Type | Description | | -------- | --------------- | ---------------------------------------- | -| data | Object/Function | Data model of the page. If the attribute is of the function type, the return value must be of the object type. The attribute name cannot start with a dollar sign ($) or underscore (_). Do not use reserved words (**for**, **if**, **show**, and **tid**).
Do not use this attribute and **private** or **public** at the same time.(Rich) | -| props | Array/Object | Used for communication between components. This attribute can be transferred to components via **\**. A **props** name must be in lowercase and cannot start with a dollar sign ($) or underscore (\_). Do not use reserved words (**for**, **if**, **show**, and **tid**). Currently, **props** does not support functions.| -| computed | Object | Used for pre-processing an object for reading and setting. The result is cached. The name cannot start with a dollar sign ($) or underscore (\_). Do not use reserved words.| +| data | Object \| Function | Data model of the page. If the attribute is of the function type, the return value must be of the object type. The name cannot start with a dollar sign ($) or underscore (\_). Do not use reserved words (**for**, **if**, **show**, and **tid**).
Do not use this attribute and **private** or **public** at the same time.| +| props | Array \| Object | Used for communication between components. This attribute can be passed to components through **\**. A **props** name must be in lowercase and cannot start with a dollar sign ($) or underscore (_). Do not use reserved words (**for**, **if**, **show**, and **tid**) in the name. Currently, **props** does not support functions.| +| computed | Object | Used for pre-processing for reading and setting parameters. The result is cached. The name cannot start with a dollar sign ($) or underscore (\_). Do not use reserved words.| diff --git a/en/application-dev/reference/arkui-js/js-components-custom-props.md b/en/application-dev/reference/arkui-js/js-components-custom-props.md index f2a3a4c4faf87d3230de6d128c9c55ad20548f9d..c9c496b57842c628eabb96377c8096c6a9cc1f9c 100644 --- a/en/application-dev/reference/arkui-js/js-components-custom-props.md +++ b/en/application-dev/reference/arkui-js/js-components-custom-props.md @@ -1,22 +1,25 @@ -# props +# Data Transfer and Processing -You can use **props** to declare attributes of a custom component and pass the attributes to the child component. The supported types of **props** include String, Number, Boolean, Array, Object, and Function. Note that a camel case attribute name \(**compProp**\) should be converted to the kebab case format \(**comp-prop**\) when you reference the attribute in an external parent component. You can add **props** to a custom component, and pass the attribute to the child component. -``` +## props + +You can use **props** to declare attributes of a custom component and pass the attributes to the child component. The supported types of **props** include String, Number, Boolean, Array, Object, and Function. Note that a camel case attribute name (**compProp**) should be converted to the kebab case format (**comp-prop**) when you reference the attribute in an external parent component. The following is sample for adding **props** to a custom component and passing the attribute to the child component. + +```html
{{compProp}}
``` -``` +```js // comp.js export default { props: ['compProp'], } ``` -``` +```html
@@ -24,21 +27,22 @@ export default {
``` ->![](../../public_sys-resources/icon-note.gif) **NOTE:** ->The name of a custom attribute cannot start with reserved keywords such as **on**, **@**, **on:**, and **grab:**. +> **NOTE** +> +> The name of a custom attribute cannot start with reserved keywords such as **on**, **@**, **on:**, and **grab:**. -## Default Value +### Default Value -You can set the default value for a child component attribute via **default**. The default value is used if the parent component does not have **default** set. In this case, the **props** attribute must be in object format instead of an array. +You can set the default value for a child component attribute via **default**. The default value is used if the parent component does not have **default** set. In this case, the **props** attribute must be in object format instead of an array. -``` +```html
{{title}}
``` -``` +```js // comp.js export default { props: { @@ -49,21 +53,21 @@ export default { } ``` -In this example, a **** component is added to display the title. The title content is a custom attribute, which displays the text specified by a user. If the user has not set a title, the default text will be displayed. Add the attribute when referencing the custom component. +In this example, a **\** component is added to display the title. The title content is a custom attribute, which displays the text specified by a user. If the user has not set a title, the default text will be displayed. Add the attribute when referencing the custom component. -``` +```html
- +
``` -## Unidirectional Value Transfer +### Unidirectional Value Transfer -Data can be transferred only from the parent component to child components. You are not allowed to change the value passed to the child component. However, you can receive the value passed by **props** as a default value in **data**, and then change the **data** value. +Data can be transferred only from the parent component to child components. You are not allowed to change the value passed to the child component. However, you can receive the value passed by **props** as a default value in **data**, and then change the **data** value. -``` +```js // comp.js export default { props: ['defaultCount'], @@ -78,11 +82,11 @@ export default { } ``` -## Monitoring Data Changes by **$watch** +### Monitoring Data Changes by **$watch** -To listen for attribute changes in a component, you can use the **$watch** method to add a callback. The following code snippet shows how to use **$watch**: +To listen for attribute changes in a component, you can use the **$watch** method to add a callback. The following code snippet shows how to use **$watch**: -``` +```js // comp.js export default { props: ['title'], @@ -90,16 +94,17 @@ export default { this.$watch('title', 'onPropertyChange'); }, onPropertyChange(newV, oldV) { - console.info('title attribute changed'+ newV + ' ' + oldV) + console.info('title attribute changed'+ newV + ' ' + oldV) }, } ``` -## Computed Property -To improve the development efficiency, you can use a computed property to pre-process an attribute in a custom component before reading or setting the attribute. In the **computed** field, you can set a getter or setter to be triggered when the attribute is read or written, respectively. The following is an example: +## computed -``` +To improve the development efficiency, you can use a computed property to pre-process an attribute in a custom component before reading or setting the attribute. In the **computed** field, you can set a getter or setter to be triggered when the attribute is read or written, respectively. The following is an example: + +```js // comp.js export default { props: ['title'], @@ -129,5 +134,4 @@ export default { } ``` -The first computed property **message** has only a getter. The value of **message** changes depending on the **objTitle** value. The getter can only read but cannot set the value. You need a setter \(such as **notice** in the sample code\) to set the value of the computed property. - +The first computed property **message** has only a getter. The value of **message** changes depending on the **objTitle** value. The getter can only read but cannot set the value (such as **time** defined during initialization in **data**). You need a setter (such as **notice** in the sample code) to set the value of the computed property. diff --git a/en/application-dev/reference/arkui-js/js-components-custom-slot.md b/en/application-dev/reference/arkui-js/js-components-custom-slot.md index b65cfd01d2603195100ed8c0709289dd7b59b692..50c5b9ed0d1ad181567945134be95e0f9c229fed 100644 --- a/en/application-dev/reference/arkui-js/js-components-custom-slot.md +++ b/en/application-dev/reference/arkui-js/js-components-custom-slot.md @@ -1,13 +1,15 @@ -# slot +# slot ->![](../../public_sys-resources/icon-note.gif) **NOTE:** ->The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. +> **NOTE** +> +> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. -## Default Slot -You can use the **** tag to create a slot inside a custom component to fill the content defined in the parent component. The sample code is as follows: +## Default Slot -``` +You can use the **\** tag to create a slot inside a custom component to fill the content defined in the parent component. The sample code is as follows: + +```html
The following uses the content defined in the parent component. @@ -16,22 +18,22 @@ You can use the **** tag to create a slot inside a custom component to ``` The following references the custom component: - -``` +```html
- Content defined in the parent component + Content defined in the parent component
``` -## Named Slot -When multiple slots are need inside a custom component, you can name them, so that you can specify the slot in which you want to fill content by setting the **** attribute. +## Named Slot -``` +When multiple slots are need inside a custom component, you can name them, so that you can specify the slot in which you want to fill content by setting the **** attribute. + +```html
The following uses the content defined in the parent component. @@ -41,8 +43,7 @@ When multiple slots are need inside a custom component, you can name them, so th ``` The following references the custom component: - -``` +```html
@@ -53,6 +54,6 @@ The following references the custom component:
``` ->![](../../public_sys-resources/icon-note.gif) **NOTE:** ->**** and **** do not support dynamic data binding. - +> **NOTE** +> +> **\** and **\** do not support dynamic data binding. diff --git a/en/application-dev/reference/arkui-js/js-components-custom-style.md b/en/application-dev/reference/arkui-js/js-components-custom-style.md index 37e0770cdeec8de1e3bd3c89360c56973353cea4..ba8644e3e347e700b523ea0c7f2ab02159faeca7 100644 --- a/en/application-dev/reference/arkui-js/js-components-custom-style.md +++ b/en/application-dev/reference/arkui-js/js-components-custom-style.md @@ -1,16 +1,19 @@ # Style Inheritance + > **NOTE**
-> The APIs of this module are supported since API 9. Updates will be marked with a superscript to indicate their earliest API version. +> +> The APIs of this module are supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version. A custom component has the **inherit-class** attribute, which is defined in the following table. -| Name | Type | Default Value| Mandatory| Description | -| ------------ | ------ | ------ | ---- | ------------------------------------------------------ | -| inherit-class | string | - | No | Class styles inherited from the parent component, seperated by spaces.| +| Name | Type | Default Value | Mandatory | Description | +| ------------- | ------ | ---- | ---- | -------------------------------- | +| inherit-class | string | - | No | Class styles inherited from the parent component, separated by spaces.| To enable a custom component to inherit the styles of its parent component, set the **inherit-calss** attribute for the custom component. -The example below is a code snippet in the HML file of the parent page that references a custom component named **comp**. This component uses the **inherit-class** attribute to inherit the styles of its parent component: **parent-class1** and **parent-class2**. +The example below is a code snippet in the HML file of the parent component that references a custom component named **comp**. This component uses the **inherit-class** attribute to inherit the styles of its parent component: **parent-class1** and **parent-class2**. + ```html @@ -20,9 +23,10 @@ The example below is a code snippet in the HML file of the parent page that refe
``` -Code snippet in the CSS file of the parent page: -```html -// xxx.css +Code snippet in the CSS file of the parent component: + +```css +/* xxx.css */ .parent-class1 { background-color:red; border:2px; @@ -34,6 +38,7 @@ Code snippet in the CSS file of the parent page: ``` Code snippet in the HML file of the custom component, where **parent-class1** and **parent-class2** are styles inherited from the parent component: + ```html