The **fileManager** module provides APIs for accessing and managing user files. It interworks with the underlying file management services to implement media library and external card management, and provides capabilities for applications to query and create user files.
>**NOTE**<br/>
>
>- The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>- The APIs of this module are system APIs and cannot be called by third-party applications. Currently, these APIs can be called only by **filepicker**.
| options | Object | No| The options are as follows:<br>- **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.|
**Return value**
| Type| Description|
| --- | -- |
| Promise<[FileInfo](#fileinfo)[]> | Promise used to return the root album or directory information obtained.|
| options | Object | No| The options are as follows:<br>- **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.|
| callback | AsyncCallback<[FileInfo](#fileinfo)[]> | Yes | Callback invoked to return the root album or directory information obtained. |
| path | string | Yes| URI of the directory to query.|
| type | string | Yes| Type of the files to query. The file type can be **file**, **image**, **audio**, or **video**.|
| options | Object | No| The options are as follows:<br>- **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.<br>- **offset**: position to start the query. The value is a number.<br>- **count**: number of files to query.|
**Return value**
| Type| Description|
| --- | -- |
| Promise<FileInfo[]> | Promise used to return the album or file information obtained.|
**Error**
| Error Info| Error Code|Description|
| -- | --- | -- |
| No such file or directory | 2 | The directory or album of the specified URI does not exist.|
| No such process | 3 | Failed to obtain the FMS service.|
| Not a directory | 20 | The object specified by the URI is not a directory or album.|
**Example**
```js
// Obtain all files in the directory. You can use getRoot to obtain the directory URI.
| path | string | Yes | URI of the directory to query. |
| type | string | Yes | Type of the files to query. The file type can be **file**, **image**, **audio**, or **video**.|
| options | Object | No| The options are as follows:<br>- **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.<br>- **offset**: position to start the query. The value is a number.<br>- **count**: number of files to query.|
| callback | AsyncCallback<[FileInfo](#fileinfo)[]> | Yes | Callback invoked to return the root album or directory information obtained. |
| filename | string | Yes| Name of the file to create.|
| path | string | Yes| URI of the file to create.|
| options | Object | No| The options are as follows:<br>- **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.|
**Return value**
| Type| Description|
| --- | -- |
| Promise<string> | Promise used to return the URI of the file created.|
**Error**
| Error Info| Error Code|Description|
| -- | --- | -- |
| Operation not permitted | 1 | A file with the same name already exists.|
| No such file or directory | 2 | The directory or album of the specified URI does not exist.|
| No such process | 3 | Failed to obtain the FMS service.|
| Not a directory | 20 | The object specified by the URI is not a directory or album.|
**Example**
```js
// Create a file.
letmedia_path=""// Obtain the file URI using listFile() and getRoot().
| filename | string | Yes | Name of the file to create. |
| path | string | Yes | URI of the file to create. |
| options | Object | No| The options are as follows:<br>- **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.|
| callback | AsyncCallback<[FileInfo](#fileinfo)[]> | Yes | Callback invoked to return the root album or directory information obtained. |
Environment is a singleton object created by the framework when the application is started. It provides the AppStorage with a series of environment state attributes required by the application. These attributes describe the device environment where the application runs. Environment and its attributes are immutable, and all attribute values are of the simple type. The following example shows how to obtain the semantic environment from Environment:
accessibilityEnabled is the default system variable identifier provided by Environment. You need to bind the corresponding system attribute to the AppStorage. Then, you can use the methods or decorators in the AppStorage to access the corresponding system attribute data.
## Environment APIs
| key | Parameter | Return Value | Description |
| -------- | -------- | -------- | -------- |
| EnvProp | key: string,<br/>defaultValue: any | boolean | Binds this system attribute to the AppStorage. You are advised to use this API during application startup. If the attribute already exists in the AppStorage, false is returned. Do not use the variables in the AppStorage. Instead, call this method to bind environment variables. |
| EnvProps | keys: {<br/>key: string,<br/>defaultValue: any<br/>}[] | void | Associates this system item array with the AppStorage. |
| Keys | Array<string> | number | Returns the associated system item array. |
## Built-in Environment Variables
| key | Type | Description |
| -------- | -------- | -------- |
| accessibilityEnabled | boolean | Whether to enable accessibility. |
| colorMode | ColorMode | Color mode. The options are as follows:<br/>- **ColorMode.LIGHT**: light mode.<br/>- **ColorMode.DARK**: dark mode. |
| fontScale | number | Font scale. The value range is [0.85, 1.45]. |
| fontWeightScale | number | Font weight scale. The value range is [0.6, 1.6]. |
| layoutDirection | LayoutDirection | Layout direction. The options are as follows:<br/>- **LayoutDirection.LTR**: The direction is from left to right.<br/>- **LayoutDirection.RTL**: The direction is from right to left. |
| languageCode | string | Current system language. The value is in lowercase, for example, zh. |
ArkUI provides some static methods in the PersistentStorage class for managing persistent data of applications. Persistent data with specific tags can be linked to the AppStorage, and then the persistent data can be accessed through the AppStorage APIs. Alternatively, the @StorageLink decorator can be used to access the variable of the specific key.
| Name | Type | Return Value | Definition |
| -------- | -------- | -------- | -------- |
| PersistProp | key : string<br/>defaultValue: T | void | Changes the associated named attribute to persistent data in the AppStorage. The value overwriting sequence is as follows:<br/>- If the attribute exists in the AppStorage, use it to overwrite the value in Persistent.<br/>- If Persistent contains the specified attribute, use the attribute value in Persistent.<br/>- If the preceding conditions are not met, use defaultValue. The values null and undefined are not supported. |
| DeleteProp | key: string | void | Cancels two-way binding. The value of this attribute will be deleted from the persistent storage. |
AppStorage is a singleton object in an application, which is created by the UI framework when the application is started and destroyed when the application exits. It is used to provide central storage for changing state attributes of an application. AppStorage contains all the state attributes that need to be accessed throughout the application. The AppStorage retains all attributes and their values as long as the application remains running, and the attribute values can be accessed through unique key values.
The UI component can synchronize the application state data with the AppStorage through the decorators. The application service logic can also be implemented by accessing the AppStorage through APIs.
The selection state attribute of the AppStorage can be synchronized with different data sources or data sinks. These data sources and data sinks can be local or remote devices and provide different functions, such as data persistence. Such data sources and data sinks can be implemented independently of the UI in the service logic.
By default, the attributes in the AppStorage are changeable. If needed, AppStorage can also use immutable (read-only) attributes.
## AppStorage APIs
| Name | Type | Return Value | Definition |
| -------- | -------- | -------- | -------- |
| SetAndLink | key: string,<br/>defaultValue: T | @Link | Works in a way similar to the Link API. If the current key is stored in the AppStorage, the value corresponding to the key is returned. If the key has not been created, a Link instance corresponding to the default value is created and returned. |
| Set | key: string,<br/>newValue: T | void | Replaces the value of a saved key. |
| Link | key: string | @Link | Returns two-way binding to this attribute if there is data with a given key. This means that attribute changes made by a variable or component will be synchronized to the AppStorage, and attribute changes made through the AppStorage will be synchronized to the variable or component. If the attribute with this key does not exist or is read-only, undefined is returned. |
| SetAndProp | propName: string,<br/>defaultValue: S | @Prop | Works in a way similar to the Prop API. If the current key is stored in the AppStorage, the value corresponding to the key is returned. If the key has not been created, a Prop instance corresponding to the default value is created and returned. |
| Prop | key: string | @Prop | Returns one-way binding to an attribute with a given key if the attribute exists. This means that attribute changes made through the AppStorage will be synchronized to the variable or component, but attribute changes made by the variable or component will be synchronized to the AppStorage. The variable returned by this method is an immutable one, which is applicable both to the variable and immutable state attributes. If the attribute with the specified key does not exist, undefined is returned.<br/>**NOTE**<br/>The attribute value used in the prop method must be of a simple type. |
| SetOrCreate | key: string,<br/>newValue: T | boolean | If an attribute that has the same name as the specified key exists: replaces the value of the attribute and returns true when the attribute can be modified; retains the original value of the attribute and returns false otherwise.<br/>If an attribute that has the same name as the specified key does not exist: creates an attribute whose key is key and value is newValue. The values null and undefined are not supported. |
| Get | key: string | T or undefined | Obtains the value of the specified key. |
| Has | propName: string | boolean | Checks whether the attribute corresponding to the specified key value exists. |
| Keys | void | array<string> | Returns an array of strings containing all keys. |
| Delete | key: string | boolean | Deletes the key-value pair for the specified key. Returns true if the key-value pair exists and is successfully deleted; returns false otherwise. |
| Clear | void | boolean | Deletes all attributes. If any of the attributes is being referenced by a state variable, false is returned. |
| IsMutable | key: string | boolean | Specifies whether the attribute exists and can be changed. |
## Synchronization Between AppStorage and Components
In [Managing Component States](ts-component-states-state.md), we have defined how to synchronize the state variables of child components with the @State decorated variables in the parent component or ancestor component, including @Prop, @Link, and @Consume.
In this section, we'll describe how to synchronize component variables with the AppStorage through the @StorageLink and @StorageProp decorators.
### @StorageLink Decorator
Two-way data binding can be established between components and the AppStorage through state variables decorated by @StorageLink(_key_). Wherein, key is the attribute key value in the AppStorage. When a component containing the @StorageLink decorated variable is created, the variable is initialized using the value in the AppStorage. Changes made to this variable in the component will be first synchronized to the AppStorage, and then to other bound instances, such as PersistentStorage or other bound UI components.
### @StorageProp Decorator
One-way data binding can be established between components and the AppStorage through state variables decorated by @StorageProp(_key_). Wherein, key is the attribute key value in the AppStorage. When a component containing the @StorageProp decorated variable is created, the variable is initialized using the value in the AppStorage. Changes made to the value in the AppStorage will cause the bound UI component to update the state.
Each time the user clicks the **Count** button, the value of **this.varA** will increase by 1. This variable is synchronized with varA in the AppStorage. Each time the user clicks the language icon, the value of **languageCode** in the AppStorage will be changed, and the change will be synchronized to the **this.lang** variable.
Use attribute methods to configure component attributes. An attribute method follows the corresponding component and is bound to the component using the "." operator.
- The following is an example of configuring the font size attribute of the Text component:
```ts
Text('123')
.fontSize(12)
```
- Use the "." operator to implement chain call to configure multiple attributes at the same time, as shown below:
```ts
Image('a.jpg')
.alt('error.jpg')
.width(100)
.height(100)
```
- In addition to constants, you can also pass variables or expressions, as shown below:
```ts
// Size, count, and offset are private variables defined in the component.
Text('hello')
.fontSize(this.size)
Image('a.jpg')
.width(this.count%2===0?100:200)
.height(this.offset+100)
```
- For attributes of preset components, the framework also provides some predefined enumeration types, which you can pass as parameters to methods. Enumeration types must meet the parameter type requirements on the enumeration type definitions for specific attributes. You can configure the font color and weight attributes of the Text component as follows:
For a component that supports child components, for example, a container component, add the UI descriptions of the child components inside "{ ... }". The **\<Column>**, **\<Row>**, **\<Stack>**, **\<Button>**, **\<Grid>**, and **\<List>** components are container components.
- The following is a simple example of the **\<Column>** component:
```ts
Column(){
Text('Hello')
.fontSize(100)
Divider()
Text(this.myText)
.fontSize(100)
.fontColor(Color.Red)
}
```
- Multiple child components can be nested in the **\<Column>** component, as shown below:
```ts
Column(){
Column(){
Button(){
Text('+ 1')
}.type(ButtonType.Capsule)
.onClick(()=>console.log('+1 clicked!'))
Image('1.jpg')
}
Divider()
Column(){
Button(){
Text('+ 2')
}.type(ButtonType.Capsule)
.onClick(()=>console.log('+2 clicked!'))
Image('2.jpg')
}
Divider()
Column(){
Button(){
Text('+ 3')
}.type(ButtonType.Capsule)
.onClick(()=>console.log('+3 clicked!'))
Image('3.jpg')
}
}.alignItems(HorizontalAlign.Center)// center align components inside Column
A struct decorated by **@Component** has the componentization capability and can serve as an independent component. This type of component is also called a custom component, and its UI structure is described in the **build** method. Custom components have the following features:
- Composability: Custom components can be used with preset or other components, as well as common attributes and methods.
- Chain call<sup>9+</sup>: Universal attributes can be invoked in chain call mode to change the component style.
- Reusable: Custom components can be reused by other components and used as different instances in different parent components or containers.
- Lifecycle: Custom components provide callbacks for service logic processing throughout the lifecycle.
- Data-driven update: The UI of custom components can be automatically updated based on the data of state variables.
For details about componentization, see [About @Component](ts-custom-component-initialization.md).
> **NOTE**
>
> - The **build** method must be defined for a custom component.
>- Custom constructors are prohibited for custom components.
The following code illustrates how to create a custom component named **MyComponent**:
```ts
@Component
structMyComponent{
build(){
Column(){
Text('my component')
.fontColor(Color.Red)
}.alignItems(HorizontalAlign.Center)// center align Text inside Column
}
}
```
The **build** method of **MyComponent** is executed during initial rendering. When the component status changes, the **build** method will be executed again.
The following code illustrates how to use **MyComponent**:
```ts
@Component
structParentComponent{
build(){
Column(){
MyComponent()
Text('we use component')
.fontSize(20)
}
}
}
```
**MyComponent** can be applied multiple times and reused in different components, as shown in the code below:
```ts
@Component
structParentComponent{
build(){
Row(){
Column(){
MyComponent()
Text('first column')
.fontSize(20)
}
Column(){
MyComponent()
Text('second column')
.fontSize(20)
}
}
}
aboutToAppear(){
console.log('ParentComponent: Just created, about to become rendered first time.')
}
aboutToDisappear(){
console.log('ParentComponent: About to be removed from the UI.')
}
}
```
Universal attributes can be invoked in chain call mode to diversify component styles.
> **NOTE**
>
> This feature is supported since API version 9.
>
> The chain call for custom components does not support trailing closures in the following scenario: When the custom component is initialized, the component name is followed by a pair of braces ({}) to form a trailing closure (as in `Index(){}`). You can consider a trailing closure as a container and add content to it, as in `{Column(){Text("content")}`.
The custom component decorated by @Entry functions as the default entry component of the respective page. When the page is loaded, the custom component decorated by @Entry is created and displayed first.
> **NOTE**
>
> A source file can contain at most one custom component decorated by @Entry.
Example of using @Entry:
```ts
// Only MyComponent decorated by @Entry is rendered and displayed. "hello world" is displayed, but "goodbye" is not displayed.
The @Extend decorator adds new attribute functions to preset components, such as **\<Text>**, **\<Column>**, and **\<Button>**. You can use the @Extend decorator to quickly define and reuse the custom styles of a component.
```ts
// xxx.ets
@Extend(Text)functionfancy(fontSize:number){
.fontColor(Color.Red)
.fontSize(fontSize)
.fontStyle(FontStyle.Italic)
}
@Entry
@Component
structFancyUse{
build(){
Row({space:10}){
Text("Fancy")
.fancy(16)
Text("Fancy")
.fancy(24)
}
}
}
```
> **NOTE**
>
> The @Extend decorator cannot be used in the struct definition of a custom component.
You can use **@Preview** to decorate a custom component so that it can be previewed in real time in DevEco Studio. This component is created and displayed when the page where it is located is loaded. Dynamic pictures and dynamic preview are not yet supported.
> **NOTE**
>
> In a source file, at most 10 custom components can be decorated by **@Preview**. For details, see [@Preview](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-previewing-app-service-0000001218760596#section146052489820).
The **@Styles** decorator adds new attribute functions to basic components, such as **\<Text>**, **\<Column>**, and **\<Button>**. Currently, **@Styles** supports only universal attributes. You can use the **@Styles** decorator to quickly define and reuse the custom styles of a component.
**@Styles** can be defined inside or outside a component. When it is defined outside a component, the keyword **function** must be added before the API name.
```ts
// xxx.ets
@StylesfunctionglobalFancy(){
.backgroundColor(Color.Red)
}
@Entry
@Component
structFancyUse{
@StylescomponentFancy(){
.backgroundColor(Color.Blue)
}
build(){
Column({space:10}){
Text("Fancy")
.globalFancy()
.width(100)
.height(100)
.fontSize(30)
Text("Fancy")
.componentFancy()
.width(100)
.height(100)
.fontSize(30)
}
}
}
```
**@Styles** can also be used inside the **StateStyles** attribute to assign state-specific attributes to components.
In **StateStyles**, styles defined outside the component can be directly called. However, the keyword **this** must be used to call styles defined in the component.
Two-way binding can be established between the @Link decorated variable and the @State decorated variable of the parent component. The @Link data has the following features:
- Support for multiple types: The value of the @Link decorated variable can be of the same type as the @State decorated variable; that is, the value can be of the following types: class, number, string, boolean, or arrays of these types.
- Private: Data is accessed only within the component.
- Single data source: The variable of the parent component for initializing the @Link decorated variable must be the @State decorated variable.
- Two-way binding: When a child component changes the @Link decorated variable, the @State decorated variable of its parent component is also changed.
- Support for initialization with the variable reference passed to the @Link decorated variable: When creating a new instance of the component, you must use the naming parameter to initialize all @Link decorated variables. The @Link decorated variable can be initialized by using the reference of the @State or @Link decorated variable. Wherein, the @State decorated variable can be referenced using the ` '$' ` operator.
> **NOTE**
>
> The @Link decorated variable cannot be initialized within the component.
## Simple Type Example
```ts
// xxx.ets
@Entry
@Component
structPlayer{
@StateisPlaying:boolean=false
build(){
Column(){
PlayButton({buttonPlaying:$isPlaying})
Text(`Player is ${this.isPlaying?'':'not'} playing`)
}
}
}
@Component
structPlayButton{
@LinkbuttonPlaying:boolean
build(){
Column(){
Button(){
Image(this.buttonPlaying?'play.png':'pause.png')
}.onClick(()=>{
this.buttonPlaying=!this.buttonPlaying
})
}
}
}
```
The @Link semantics are derived from the `'$'` operator. In other words, `$isPlaying` is the two-way binding of the internal state ` this.isPlaying ` . When you click **PlayButton**, the **\<Image>** and **\<Text>** components of **PlayButton** are refreshed at the same time.
## Complex Type Example
```ts
// xxx.ets
@Entry
@Component
structParent{
@Statearr:number[]=[1,2,3]
build(){
Column(){
Child({items:$arr})
ForEach(this.arr,
item=>Text(`${item}`),
item=>item.toString())
}
}
}
@Component
structChild{
@Linkitems:number[]
build(){
Column(){
Button(){
Text('Button1: push')
}.onClick(()=>{
this.items.push(100)
})
Button(){
Text('Button2: replace whole item')
}.onClick(()=>{
this.items=[100,200,300]
})
}
}
}
```
In the example above, click **Button1** and **Button2** to change the list of text items displayed in the parent component.
## Example of Using @Link, @State, and @Prop Together
```ts
// xxx.ets
@Entry
@Component
structParentView{
@Statecounter:number=0
build(){
Column(){
ChildA({counterVal:this.counter})// pass by value
ChildB({counterRef:$counter})// $ creates a Reference that can be bound to counterRef
}
}
}
@Component
structChildA{
@PropcounterVal:number
build(){
Button(){
Text(`ChildA: (${this.counterVal}) + 1`)
}.onClick(()=>{this.counterVal+=1})
}
}
@Component
structChildB{
@LinkcounterRef:number
build(){
Button(){
Text(`ChildB: (${this.counterRef}) + 1`)
}.onClick(()=>{this.counterRef+=1})
}
}
```
In the preceding example, ParentView contains two child components: ChildA and ChildB. They are initialized by the state variable counter of ParentView.
- ChildB uses @Link to establish two-way state binding. When the value of the counterRef state variable is changed in ChildB, the change is synchronized to ParentView and ChildA.
- ChildA uses @Prop to establish one-way state binding from ParentView to itself. When ChildA changes the state, it is re-rendered, but the change is not updated to ParentView or ChildB.
@Prop and @State have the same semantics but different initialization modes. Variables decorated by @Prop must be initialized using the @State decorated variable provided by their parent components. The @Prop decorated variable can be modified in the component, but the modification is not updated to the parent component; that is, @Prop uses one-way data binding.
The @Prop state data has the following features:
- Support for simple types: The number, string, and boolean types are supported.
- Private: Data is accessed only within the component.
- Support for multiple instances: A component can have multiple attributes decorated by @Prop.
- Support for initialization with a value passed to the @Prop decorated variable: When a new instance of the component is created, all @Prop decorated variables must be initialized. Initialization inside the component is not supported.
## Example
```ts
// xxx.ets
@Entry
@Component
structParentComponent{
@StatecountDownStartValue:number=10// 10 Nuggets default start value in a Game
build(){
Column(){
Text(`Grant ${this.countDownStartValue} nuggets to play.`)
Button(){
Text('+1 - Nuggets in New Game')
}.onClick(()=>{
this.countDownStartValue+=1
})
Button(){
Text('-1 - Nuggets in New Game')
}.onClick(()=>{
this.countDownStartValue-=1
})
// When creating a child component, you must provide the initial value of its @Prop decorated variable in the constructor parameter and initialize the regular variable CostOfOneAttump (not Prop).
In the preceding example, when you press +1 or -1, the status of the parent component changes and the build method is executed again. In this case, a new CountDownComponent is created. The countDownStartValue property of the parent component is used to initialize the @Prop decorated variable of the child component. When you tap the Try again button of the child component, the value of the @Prop decorated variable count is changed. As a result, the CountDownComponent is rendered again. However, the change of the count value does not affect the countDownStartValue value of the parent component.
> **NOTE**
>
> When a new component instance is created, all its @Prop decorated variables must be initialized.
The @State decorated variable is the internal state data of the component. When the state data is modified, the build method of the component is called to refresh the UI. Note that the @State decorator cannot listen for data changes at the inner layer.
The @State data has the following features:
- Support for multiple types: The following types are supported: strong types by value and by reference, including class, number, boolean, string, as well as arrays of these types, that is, Array<class>, Array<string>, Array<boolean>, and Array<number>. object and any are not allowed.
- Support for multiple instances: Multiple instances can coexist in a component. The internal state data of different instances is independent.
- Private: An attribute marked with @State can only be accessed within the component.
- Local initialization required: Initial values must be allocated to all @State decorated variables through the initialization process. Otherwise, they may become undefined in the framework.
- Support for setting of initial attribute values based on the state variable name: When creating a component instance, you can explicitly specify the initial value of the @State decorated attribute based on the variable name.
## Simple Example of @State Decorated Attribute
```ts
// xxx.ets
@Entry
@Component
structMyComponent{
@Statecount:number=0
// MyComponent provides a method for modifying the @State status data member.
privatetoggleClick(){
this.count+=1
}
build(){
Column(){
Button(){
Text(`click times: ${this.count}`)
.fontSize(10)
}.onClick(this.toggleClick.bind(this))
}
}
}
```
## Complex Example of @State Decorated Variable
```ts
// Customize the status data class.
// xxx.ets
classModel{
value:string
constructor(value:string){
this.value=value
}
}
@Entry
@Component
structEntryComponent{
build(){
Column(){
MyComponent({count:1,increaseBy:2})// MyComponent1 in this document
MyComponent({title:{value:'Hello, World 2'},count:7})//MyComponent2 in this document
}
}
}
@Component
structMyComponent{
@Statetitle:Model={value:'Hello World'}
@Statecount:number=0
privatetoggle:string='Hello World'
privateincreaseBy:number=1
build(){
Column(){
Text(`${this.title.value}`).fontSize(30)
Button(){
Text(`Click to change title`).fontSize(20).fontColor(Color.White)
})// Modify the internal state of MyComponent using the anonymous method.
Button(){
Text(`Click to increase count=${this.count}`).fontSize(20).fontColor(Color.White)
}.onClick(()=>{
this.count+=this.increaseBy
})// Modify the internal state of MyComponent using the anonymous method.
}
}
}
```
In the preceding example:
- Two @State decorated variables, count and title, have been defined for MyComponent. If the value of count or title changes, the build method of MyComponent needs to be called to render the component again.
- The EntryComponent has multiple MyComponent instances. The internal status change of the first MyComponent does not affect the second MyComponent.
- When creating a MyComponent instance, initialize the variables in the component based on the variable name. For example:
```ts
MyComponent({title:{value:'Hello, World 2'},count:7})
If the API definition of a component contains any mandatory parameter, set the parameters in the parentheses next to the component. Use constants to assign values to the parameters.
Examples:
- Set the mandatory parameter src of the <Image> component as follows:
```ts
Image('http://xyz/a.jpg')
```
- Set the mandatory parameter content of the **\<Text>** component as follows:
```ts
Text('123')
```
You can also use variables or expressions to assign values to parameters. The result type returned by an expression must meet the parameter type requirements. For example, to pass a variable or expression to construct the Image and Text components:
```ts
// imagePath, where imageUrl is a private data variable defined in the component.
Image(this.imagePath)
Image('http://'+this.imageUrl)
// count is a private data variable defined in the component.
// (``) and (${}) are the template character string features supported by the TS language and comply with the
// features of the corresponding language. This specification is not limited.
You can use event methods to configure events supported by components. Since API version 9, you can obtain the context associated with the current component from the callback. For details, see [Obtaining the Context on an eTS Page](../ability/context-userguide.md).
- Example of using a lambda expression to configure the event of a component:
```ts
// Counter is a private data variable defined in the component.
Button('add counter')
.onClick(()=>{
this.counter+=2
})
```
- When using an anonymous function expression to configure the event of a component, **bind** must be used to ensure that the contained components are referenced by **this** in the function body.
```ts
// Counter is a private data variable defined in the component.
Button('add counter')
.onClick(function(){
this.counter+=2
}.bind(this))
```
- Example of using a component's member function to configure the event of the component:
The build function meets the definition of the **Builder** API and is used to define the declarative UI description of components. Components must comply with the preceding **Builder** API constraints. Custom or preset components are combined in declarative mode in the build method. The **build** API is called when a component is created or updated.
```ts
interfaceBuilder{
build:()=>void
}
```
> **NOTE**
>
> The build method supports only composite components and uses the rendering control syntax.
The TypeScript-based declarative development paradigm provides a wide array of basic components, which can be combined and extended in a declarative manner to describe the UI of an application. It also provides basic data binding and event processing mechanisms to help you implement the application interaction logic.
## HelloWorld Example
```ts
// An example of displaying Hello World. After you click the button, Hello UI is displayed.
// xxx.ets
@Entry
@Component
structHello{
@StatemyText:string='World'
build(){
Column(){
Text('Hello')
.fontSize(30)
Text(this.myText)
.fontSize(32)
Divider()
Button(){
Text('Click me')
.fontColor(Color.Red)
}.onClick(()=>{
this.myText='UI'
})
.width(500)
.height(200)
}
}
}
```
## Basic Concepts
The preceding sample code shows the structure of a simple page. It involves the following basic concepts:
- Decorator: a special kind of declaration that can be applied to classes, structures, methods, and variables. In the sample code, @Entry, @Component, and @State are decorators.
- Custom component: a reusable UI unit, which can be combined with other components. In the sample code, struct Hello decorated by @Component is a custom component.
- UI description: declaratively describes the UI structure. In the sample code, the block of code in the build() method provides the UI description.
- Built-in component: the default basic or layout component preset in the framework. You can directly invoke these components, such as <Column>, <Text>, <Divider>, and <Button> components in the sample code.
- Attribute method: a method used to configure component attributes, such as fontSize(), width(), height(), and color().
- Event method: a method used to add the component response logic to an event. In the sample code, the onClick method is added for the Button component for defining the click response logic.
As the data provider, @Provide can update the data of child nodes and trigger page rendering. After @Consume detects that the @Provide data is updated, it will initiate re-rendering of the current view.
Table 1 @Provide
| Name | Description |
| -------- | -------- |
| Decorator parameter | A constant of the string type, which is used to set an alias for a decorated variable. If an alias is specified, implement the data update for this alias. If there is no alias, use the variable name as the alias. @Provide("_alias_") is recommended. |
| Synchronization mechanism | The @Provide decorated variable is similar to the @state variable. You can modify the variable to re-render the page. You can also modify the @Consume decorated variable to modify the @State decorated variable reversely. |
| Initial value | The initial value must be set. |
| Page re-rendering scenarios | The following will trigger page re-rendering:<br/>- Changes of variables in primitive types (boolean, string, and number)<br/>- Changes of the @Observed decorated classes or their attributes<br/>- Adding, deleting, or updating elements in an array |
Table 2 @Consume
| Type | Description |
| -------- | -------- |
| Initial value | No default value can be set. |
> **NOTE**
>
> To avoid infinite loops caused by circular reference, exercise caution when using @Provide and @Consume.
The description of other attributes is the same as that of @Provide.
This section introduces to you two new decorators: @Observed and @ObjectLink.
- @Observed applies to a class, indicating that the data changes in the class are managed by the UI page, for example, @Observed class ClassA {}.
- @ObjectLink applies to an object decorated by @Observed, for example, @ObjectLink a: ClassA.
## Background
When you need to set bidirectional synchronization in a child component for a variable (parent_a) of its parent component, you can use @State to decorate the variable (parent_a) in the parent component and use @Link to decorate the corresponding variable (child_a) in the child component. In this way, data can be synchronized between the parent component and the specific child component, and between the parent component and its other child components. As shown below, bidirectional synchronization is configured for variables of ClassA in the parent and child components. If attribute c of the variable in child component 1 has its value changed, the parent component will be notified to synchronize the change. If attribute c in the parent component has its value changed, all child components will be notified to synchronize the change.
In the preceding example, full synchronization is performed for a data object. If you want to synchronize partial information of a data object in a parent component, and if the information is a class object, use @ObjectLink and @Observed instead, as shown below.
- @Observed applies to classes, and @ObjectLink applies to variables.
- The variables decorated by @ObjectLink must be of the class type.
- The classes must be decorated by @Observed.
- Parameters of the primitive types are not supported. You can use @Prop to perform unidirectional synchronization.
- @ObjectLink decorated variables are immutable.
- Attribute changes are allowed. If an object is referenced by multiple @ObjectLink decorated variables, all custom components that have these variables will be notified for re-rendering.
- Default values cannot be set for @ObjectLink decorated variables.
- The parent component must be initialized with a TypeScript expression that involves variables decorated by @State, @Link, @StorageLink, @Provide, or @Consume.
- @ObjectLink decorated variables are private variables and can be accessed only within the component.
## Examples
### Example 1
```ts
// When the data of the ClassA object in the parent component ViewB's class object ClassB is synchronized with that of the child component ViewA, use @ObjectLink to synchronize the changes in the value of c are synchronized to the parent component.
@Observed
classClassA{
publicname:string;
publicc:number;
constructor(c:number,name:string='OK'){
this.name=name;
this.c=c;
}
}
classClassB{
publica:ClassA;
constructor(a:ClassA){
this.a=a;
}
}
@Component
structViewA{
label:string="ep1";
@ObjectLinka:ClassA;
build(){
Column(){
Text(`ViewA [${this.label}]: a.c=${this.a.c}`)
.fontSize(20)
Button(`+1`)
.width(100)
.margin(2)
.onClick(()=>{
this.a.c+=1;
})
Button(`reset`)
.width(100)
.margin(2)
.onClick(()=>{
this.a=newClassA(0);// Error: Variable a decorated by @ObjectLink is immutable.
// When the data of class object ClassA in the parent component ViewB is synchronized with that of the child component ViewA, use @ObjectLink and @Observed to synchronize data changes to the parent component and its other child components.
@Watch is used to listen for changes of state variables. The syntax structure is as follows:
```ts
@State@Watch("onChanged")count:number=0
```
As shown above, add an @Watch decorator to the target state variable to register an onChanged callback. When the state variable count is changed, the onChanged callback will be triggered.
@Watch can be used to listen for changes of variables decorated by @State, @Prop, @Link, @ObjectLink, @Provide, @Consume, @StorageProp, or @StorageLink.
If the API definition of a component does not contain mandatory parameters, you do not need to configure any content in the parentheses next to the component. For example, the Divider component does not contain parameters:
```ts
Column(){
Text('item 1')
Divider()// No parameter configuration of the divider component
The development framework provides **ForEach** to iterate arrays and create components for each array item. If a large number of elements are involved in **ForEach**, the page loading may become slow. For best possible results, you are advised to use **[LazyForEach](ts-rending-control-syntax-lazyforeach.md)** instead. **ForEach** is defined as follows:
| arr | any[] | Yes | - | Must be an array. An empty array is allowed. If the array is empty, no child component is created. The functions that return array-type values are also allowed, for example, **arr.slice (1, 3)**. The set functions cannot change any state variables including the array itself, such as **Array.splice**, **Array.sort**, and **Array.reverse**.|
| itemGenerator | (item: any, index?: number) => void | Yes | - | Lambda function used to generate one or more child components for a given array item. A component and its child component list must be enclosed in braces ({...}).|
| keyGenerator | (item: any, index?: number) => string | No | - | Anonymous parameter used to generate a unique and stable key value for a given array item. When the position of a subitem in the array is changed, the key value of the subitem cannot be changed. When a subitem in the array is replaced with a new item, the key value of the current item must be different from that of the new item. This key-value generator is optional. However, for performance reasons, it is strongly recommended that the key-value generator be provided, so that the development framework can better identify array changes. If the array is reversed while no key-value generator is provided, all nodes in **ForEach** will be rebuilt.|
> **NOTE**
> - **ForEach** must be used in container components.
>
> - The generated child components are allowed in the parent container component of **ForEach**. The child component generator function can contain the **if/else** conditional statement, and the **if/else** conditional statement can contain **ForEach**.
>
> - The call sequence of subitem generator functions may be different from that of the data items in the array. During the development, do not assume whether the subitem generator and key value generator functions are executed and the execution sequence. Below is an example of incorrect usage:
> - State variables can be used in the if conditional statement.
>
> - You can use the if conditional statement to implement rendering of child components.
>
> - The if conditional statement must be used in container components.
>
> - Some container components limit the type or number of child components. When if is placed in these components, the limitation applies to components created in if and else statements. For example, when if is used in the <Grid> component, whose child components can only be <GridItem>, only the <GridItem> component can be used in the if conditional statement.
## Example
Example of using the if conditional statement:
```ts
Column(){
if(this.count>0){
Text('count is positive')
}
}
```
Example of using the if, else if, and else conditional statements:
The development framework provides LazyForEach to iterate data from provided data sources and create corresponding components during each iteration. LazyForEach is defined as follows:
```ts
LazyForEach(
dataSource:IDataSource,// Data source to be iterated
| dataSource | IDataSource | Yes | - | Object used to implement the IDataSource API. You need to implement related APIs. |
| itemGenerator | (item: any) => void | Yes | - | Used to generate the lambda function of the child components. It generates one or more child components for a given array item. A single component and its child component list must be contained in the braces ({...}) |
| keyGenerator | (item: any) => string | No | - | Used as an anonymous parameter for generating a unique and stable key value for a given array item. When the position of a subitem in the array is changed, the key value of the subitem cannot be changed. When a subitem in the array is replaced with a new item, the key value of the current item must be different from that of the new item. This key-value generator is optional. However, for performance reasons, it is strongly recommended that the key-value generator be provided, so that the development framework can better identify array changes. If the array is reversed while no key-value generator is provided, all nodes in LazyForEach will be rebuilt. |
Table 2 Description of IDataSource
| Name | Description |
| -------- | -------- |
| totalCount(): number | Obtains the total number of data records. |
| getData(index: number): any | Obtains the data corresponding to the specified index. |
| registerDataChangeListener(listener: DataChangeListener): void | Registers the data change listener. |
| unregisterDataChangeListener(listener: DataChangeListener): void | Unregisters the data change listener. |
Table 3 Description of DataChangeListener
| Name | Description |
| -------- | -------- |
| onDataReloaded(): void | Reloads all data. |
| onDataAdded(index: number): void | Notifies the component that data is added to the position indicated by the specified index. |
| onDataMoved(from: number, to: number): void | Notifies the component that data is moved from the **from** position to the **to** position. |
| onDataDeleted(index: number): void | Notifies the component that data is deleted from the position indicated by the specified index. |
| onDataChanged(index: number): void | Notifies the component that data in the position indicated by the specified index is changed. |
| onDataAdd(index: number): void<sup>8+</sup> | Notifies the component that data is added to the position indicated by the specified index. |
| onDataMove(from: number, to: number): void<sup>8+</sup> | Notifies the component that data is moved from the **from** position to the **to** position. |
| onDataDelete(index: number): void<sup>8+</sup> | Notifies the component that data is deleted from the position indicated by the specified index. |
| onDataChange(index: number): void<sup>8+</sup> | Notifies the component that data in the position indicated by the specified index is changed. |
> **NOTE**
>
> - LazyForEach must be used in the container component. Only the **\<List>**, **\<Grid>**, and \**<Swiper>** components support LazyForEach (that is, only the visible part and a small amount of data before and after the visible part are loaded for caching). For other components, all data is loaded at a time.
>
> - LazyForEach must create one and only one child component in each iteration.
>
> - The generated child component must be in the parent container component of LazyForEach.
>
> - LazyForEach can be included in an if/else conditional statement, but cannot contain an if/else conditional statement.
>
> - For the purpose of high-performance rendering, when the onDataChanged method of the DataChangeListener object is used to update the UI, the component update is triggered only when the state variable is used in the component specified in the UI description of itemGenerator.
>
> - The calling sequence of the subitem generator function may be different from that of the data items in the data source. During the development, do not assume whether the subitem generator and key value generator functions are executed and the execution sequence. The following is an example of incorrect usage:
A decorator **@Decorator** can decorate a class, structure, or class attribute. Multiple decorators can be applied to the same target element and defined on a single line or multiple lines. It is recommended that the decorators be defined on multiple lines.
In the example below, the elements decorated by **@Component** take on the form of a component, and the variables decorated by **@State** can be used to represent states.
```ts
@Component
structMyComponent{
@Statecount:number=0
}
```
Multiple decorators can be defined on a single line, as shown below:
```ts
@Entry@ComponentstructMyComponent{
}
```
However, you are advised to define the decorators on multiple lines, as shown below:
| @Component | struct | The decorated structure has the component-based capability. The **build** method must be implemented to update the UI.|
| @Entry | struct | The decorated component is used as the entry of a page. The component is rendered and displayed when the page is loaded. |
| @Preview | struct | Custom components decorated by **@Preview** can be previewed in DevEco Studio. When the target page is loaded, the custom components decorated by **@Preview** are created and displayed.|
| @Builder | Methods | In the decorated method, you can use the declarative UI description to quickly generate multiple layouts in a custom component.|
| @Extend | Methods | This decorator adds attribute functions to a preset component, allowing you to quickly define and reuse the custom style of the component.|
| @CustomDialog | struct | This decorator is used to decorate custom pop-up dialog boxes. |
| @State | Primitive data types, classes, and arrays | If the decorated state data is modified, the **build** method of the component will be called to update the UI. |
| @Prop | Primitive data types | This decorator is used to establish one-way data binding between the parent and child components. When the data associated with the parent component is modified, the UI of the current component is updated.|
| @Link | Primitive data types, classes, and arrays | This decorator is used to establish two-way data binding between the parent and child components. The internal state data of the parent component is used as the data source. Any changes made to one component will be reflected to the other.|
| @Observed | Classes | This decorator is used to indicate that the data changes in the class will be managed by the UI page. |
| @ObjectLink | Objects of **@Observed** decorated classes | When the decorated state variable is modified, the parent and sibling components that have the state variable will be notified for UI re-rendering.|
| @Consume | Primitive data types, classes, and arrays | When the **@Consume** decorated variable detects the update of the **@Provide** decorated variable, the re-rendering of the current custom component is triggered.|
| @Provide | Primitive data types, classes, and arrays | As the data provider, **@Provide** can update the data of child nodes and trigger page rendering.|
| @Watch | Variables decorated by **@State**, **@Prop**, **@Link**, **@ObjectLink**, **@Provide**, **@Consume**, **@StorageProp**, or **@StorageLink** | This decorator is used to listen for the changes of the state variables. The application can register a callback method through **@Watch**. |
## Chain Call
You can configure the UI structure and its attributes and events and separate them with a dot(.) to implement chain call.
```ts
Column(){
Image('1.jpg')
.alt('error.jpg')
.width(100)
.height(100)
}.padding(10)
```
## struct
Components can be implemented based on **struct**s. Components cannot inherit from each other. The **struct**s implemented components can be created and destroyed more quickly than **class** implemented components.
```ts
@Component
structMyComponent{
@Statedata:string=''
build(){
}
}
```
## Instantiating a struct Without the new Keyword
You can omit the **new** keyword when instantiating a **struct**.
```ts
// Definition
@Component
structMyComponent{
build(){
}
}
// Usage
Column(){
MyComponent()
}
// Equivalent to
newColumn(){
newMyComponent()
}
```
## Restrictions on Using TypeScript in Generators
TypeScript has the following restrictions on generators:
- Expressions can be used only in character strings (${expression}), **if** conditions, **ForEach** parameters, and component parameters.
- No expressions should cause any application state variables (**@State**, **@Link**, and **@Prop**) to change. Otherwise, undefined and potentially unstable framework behavior may occur.
- The generator function cannot contain local variables.
None of the above restrictions apply to anonymous function implementations of event-handling functions (such as **onClick**)
Incorrect:
```ts
build(){
leta:number=1// invalid: variable declaration not allowed
Column(){
Text(`Hello ${this.myName.toUpperCase()}`)// ok.
ForEach(this.arr.reverse(),...,...)// invalid: Array.reverse modifies the @State array variable in place
}
buildSpecial()// invalid: no function calls
Text(this.calcTextValue())// this function call is ok.
}
```
## Two-Way Binding of Variables
**$$** supports two-way binding for simple variables and **@State**, **@Link**, and **@Prop** decorated variables.
Currently, **$$** supports only the rendering between the **show** parameter of the **[bindPopup](../reference/arkui-ts/ts-universal-attributes-popup.md)** attribute and the **@State** decorated variable, the **checked** attribute of the **\<Radio>** component, and the **refreshing** parameter of the **\<Refresh>** component.
```ts
// xxx.ets
@Entry
@Component
structbindPopup{
@StatecustomPopup:boolean=false
build(){
Column(){
Button(){
Text('Popup')
}
.onClick(()=>{
this.customPopup=!this.customPopup
})
.bindPopup(
$$this.customPopup,{
message:"showPopup"
}
)
}
}
}
```
## Restrictions on Declaring Multiple Data Types of State Variables
If a **@State**, **@Provide**, **@Link**, or **@Consume** decorated state variable supports multiple data types, they must be all simple data types or references at one time.
This section defines the core mechanism and functions of the TypeScript-based declarative development paradigm. It acquaints you with the declarative UI descriptions, componentization mechanisms, UI state management, rendering control syntax, and syntactic sugar.
Follow the provided guidelines for UI development. For details about the components, see components.
> **NOTE**
> - All examples use the TypeScript (TS) language. If you are using another language, comply with the syntax requirements for that language.
>
> - The components used in the examples are preset in the UI framework and are used only to explain the UI description specifications.
>
> - Universal attribute and event methods generally apply to all components, and the attribute and event methods within a component apply only to this component.
In the declarative UI programming paradigm, the UI is a function in the specific application state, and you update a UI by modifying the current application state. The development framework provides comprehensive application state management capabilities, as shown in the figure below.
- @State: state attribute of the component. Each time the @State decorated variable changes, the component re-renders and updates the UI.
- @Link: allows a component to depend on some state attributes of its parent component. Each time the data in one component is updated, the state of the other component is updated, and the parent and child components are rendered again.
- @Prop: works in a way similar to that of @Link. The difference is that the changes made by a child component are not synchronized to the parent component.
> **NOTE**
>
> The state variable cannot use an ID as its name, as in **@Prop id:number**.
## Application State Data
AppStorage is the central store of the application states in the entire UI. The UI framework creates a singleton AppStorage object for the application and provides the corresponding decorators and APIs for the application.
- @StorageLink: works in a way similar to that of @Consume. The difference is that the link object with the specified name is obtained from the AppStorage. It establishes two-way binding between the UI component and AppStorage to synchronize data.
- @StorageProp: synchronizes UI component attributes with the AppStorage unidirectionally. That is, the value change in the AppStorage will trigger an update of the corresponding UI component, but the change of the UI component will not cause an update of the attribute value in the AppStorage.
- Service logic implementation API: adds, reads, modifies, or deletes the state attributes of applications. The changes made by this API will be synchronized to the UI component for UI update.
> This component is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
**LocalStorage** is a storage unit in an application. Its lifecycle is determined by the ability to which it is bound. **LocalStorage** provides storage for variable and non-variable state attributes within the scope of an application. The variable and non-variable state attributes work together to build an application UI, including the UI of abilities.
Application layer: Multiple **LocalStorage** instances can be created for an application. Each ability of an application corresponds to a **LocalStorage** instance.
Ability: An application can have multiple abilities. Only one **LocalStorage** instance can be allocated to the child components of an ability. Once allocated a **LocalStorage** instance, the child components have access to objects stored in the **LocalStorage**.
A component can access only one **LocalStorage** instance, and a **LocalStorage** instance can be allocated to multiple components.
## @LocalStorageLink Decorator
Two-way data binding can be established between a component and the **LocalStorage** through the component's state variable decorated by **@LocalStorageLink(*key*)**. Wherein, **key** is the attribute key value in the **LocalStorage**. When a component that contains a **@LocalStorageLink** decorated state variable is created, the state variable is initialized with the value predefined in the **LocalStorage**. If no initial value is assigned in the **LocalStorage**, the state variable will use the value defined by **@LocalStorageLink**. Changes made to this variable in the component will be first synchronized to the **LocalStorage**, and then to other components of the bound ability.
## @LocalStorageProp Decorator
One-way data binding can be established between a component and the **LocalStorage** through the component's state variable decorated by **@LocalStorageProp(*key*)**. Wherein, **key** is the attribute key value in the **LocalStorage**. When a component that contains a **@LocalStorageProp** decorated state variable is created, the state variable is initialized with the value predefined in the **LocalStorage**. Changes made to the value in the **LocalStorage** will cause all UI components of the bound ability to update the state.
> **NOTE**
>
> If a **LocalStorage** instance has initial values assigned when being created, these values will be used for the **@LocalStorageLink** and **@LocalStorageProp** decorated state variables in the component. Otherwise, the initial values assigned for **@LocalStorageLink** and **@LocalStorageProp** will be used instead.
## LocalStorage
### constructor
constructor(initializingProperties?: Object)
Creates and initializes a **LocalStorage** instance.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| boolean | Updates the value of the attribute and returns **true** if an attribute that has the same name as the specified key exists; creates an attribute with the specified value of the T type as its default value and returns **false** otherwise. **true** cannot be returned for **undefined** or **null**.|
### link
link\<T>(propName: string): T
Establishes two-way data binding between an attribute and this **LocalStorage** instance.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| -------- | ------ | :--: | ---- | ----------- |
| propName | string | Yes | - | Key of the target attribute.|
| [@Link](ts-component-states-link.md) | Returns the value corresponding to the specified key if the key is stored in the **LocalStorage**; creates and returns a **Link** instance with the specified value as its default value otherwise.|
### prop
prop\<T>(propName: string): T
Establishes one-way data binding with an attribute to update its status.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| [@Prop](ts-component-states-prop.md) | Returns one-way binding to an attribute with a given key if the attribute exists; returns **undefined** otherwise. This means that attribute changes made through the **LocalStorage** will be synchronized to the variable or component, but attribute changes made by the variable or component will not be synchronized to the **LocalStorage**. Note that the variables returned are immutable variables, which are applicable to mutable and immutable state variables. |
### setAndProp
setAndProp\<T>(propName: string, defaultValue: T): T
Sets up one-way data binding with the **localStorage**. This API works in a way similar to the **Prop** API.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| [@Prop](ts-component-states-prop.md) | Returns the value corresponding to the specified key if the key is stored in the **LocalStorage**; creates and returns a **Prop** instance with the specified value as its default value otherwise.|
### delete
delete(propName: string): boolean
Deletes the key-value pair specified by key.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
