Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
提交 672d91e1 编写于 作者: E ester.zhou
浏览文件
操作

Update docs (11137) 

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>
上级 ee3914ba
隐藏空白更改
内联 并排
Showing with 5440 addition and 497 deletion
en/application-dev/quick-start/Readme-EN.md
浏览文件 @ 672d91e1
# Quick Start
- Getting Started
- [Preparations](start-overview.md)
- [Before You Start](start-overview.md)
- [Getting Started with ArkTS in Stage Model](start-with-ets-stage.md)
- [Getting Started with ArkTS in FA Model](start-with-ets-fa.md)
- [Getting Started with JavaScript in FA Model](start-with-js-fa.md)
- [Getting Started with JavaScript in FA Model](start-with-js-fa.md)
- Development Fundamentals
- [Application Package Structure Configuration File (FA Model)](package-structure.md)
- [Application Package Structure Configuration File (Stage Model)](stage-structure.md)
- [SysCap](syscap.md)
- [HarmonyAppProvision Configuration File](app-provision-structure.md)
- [Resource Categories and Access](resource-categories-and-access.md)
- Learning ArkTS
- [Getting Started with ArkTS](arkts-get-started.md)
- ArkTS Syntax (Declarative UI)
- [Basic UI Description](arkts-basic-ui-description.md)
- State Management
- [Basic Concepts](arkts-state-mgmt-concepts.md)
- [State Management with Page-level Variables](arkts-state-mgmt-page-level.md)
- [State Management with Application-level Variables](arkts-state-mgmt-application-level.md)
- [Dynamic UI Element Building](arkts-dynamic-ui-elememt-building.md)
- [Rendering Control](arkts-rendering-control.md)
- [Restrictions and Extensions](arkts-restrictions-and-extensions.md)
\ No newline at end of file
en/application-dev/quick-start/arkts-basic-ui-description.md 0 → 100644
浏览文件 @ 672d91e1
# Basic UI Description
In ArkTS, you define a custom component by using decorators **@Component** and **@Entry** to decorate a data structure declared with the **struct** keyword. A custom component provides a **build** function, where you must write the basic UI description in chain call mode. For details about the UI description, see [UI Description Specifications](#ui-description-specifications).
## Basic Concepts
- struct: a data structure that can be used to implement custom components and cannot have inheritance. The **new** keyword can be omitted when initializing a struct.
- Decorator: a special type of declaration that can be applied to classes, structures, or class attributes to add new functionality to them. 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.
```ts
@Entry
@Component
struct MyComponent {
}
```
- **build** function: a function that complies with the **Builder** API definition and is used to define the declarative UI description of components. A **build** function must be defined for custom components, and custom constructors are prohibited for custom components.
```ts
interface Builder {
build: () => void
}
```
- **@Component**: a decorator applied to a struct to equip it with the component-based capability. The **build** method must be implemented for UI creation.
- **@Entry**: a decorator applied to a struct to make it the entry to a page, which is rendered and displayed when the page is loaded.
- **@Preview**: a decorator applied to struct to make it previewable in the DevEco Studio Previewer. The decorated component is created and displayed when the residing page is loaded.
> **NOTE**
>
> In a single source file, you can use up to 10 **@Preview** decorators to decorate custom components. For details, see [Previewing ArkTS Components](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-previewing-app-service-0000001218760596#section146052489820).
- Chain call: a syntax for configuring the attribute methods, event methods, and more of UI components by using the dot notation.
## UI Description Specifications
### Structs Without Parameters
A struct without parameters is a component whose API definition has empty parentheses. No parameter needs to be passed to this type of component, for example, the **Divider** component in the following snippet:
```ts
Column() {
Text('item 1')
Divider()
Text('item 2')
}
```
### Structs with Mandatory Parameters
A struct with mandatory parameters is a component whose API definition expects parameters enclosed in the parentheses. You can use constants to assign values to the parameters.
Sample code:
- Set the mandatory parameter **src** of the **\<Image>** component as follows:
```ts
Image('https://xyz/test.jpg')
```
- Set the mandatory parameter **content** of the **\<Text>** component as follows:
```ts
Text('test')
```
You can use variables or expressions to assign values to parameters. The result type returned by an expression must meet the parameter type requirements. For details about the variables, see [State Management with Page-level Variables](arkts-state-mgmt-page-level.md) and [State Management with Application-level Variables](arkts-state-mgmt-application-level.md). For example, set a variable or expression to construct the **\<Image>** and **\<Text>** components:
```ts
Image(this.imagePath)
Image('https://' + this.imageUrl)
Text(`count: ${this.count}`)
```
### Attribute Configuration
Component attributes are configured using an attribute method, which follows the corresponding component and is bound to the component using the "**.**" operator.
- Example of configuring the font size attribute of the **\<Text>** component:
```ts
Text('test')
.fontSize(12)
```
- Example of configuring multiple attributes at the same time by using the "**.**" operator to implement chain call:
```ts
Image('test.jpg')
.alt('error.jpg')
.width(100)
.height(100)
```
- Example of passing variables or expressions in addition to constants:
```ts
Text('hello')
.fontSize(this.size)
Image('test.jpg')
.width(this.count % 2 === 0 ? 100 : 200)
.height(this.offset + 100)
```
- For attributes of built-in components, ArkUI also provides some predefined [enumeration types](../reference/arkui-ts/ts-appendix-enums.md), which you can pass as parameters to methods if they meet the parameter type requirements. For example, you can configure the font color and weight attributes of the **\<Text>** component as follows:
```ts
Text('hello')
.fontSize(20)
.fontColor(Color.Red)
.fontWeight(FontWeight.Bold)
```
### Event Configuration
Events supported by components are configured using event methods, which each follow the corresponding component and are bound to the component using the "**.**" operator.
- Example of using a lambda expression to configure the event of a component:
```ts
Button('add counter')
.onClick(() => {
this.counter += 2
})
```
- Example of 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
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:
```ts
myClickHandler(): void {
this.counter += 2
}
...
Button('add counter')
.onClick(this.myClickHandler)
```
### Child Component Configuration
For a component that supports child components, for example, a container component, add the UI descriptions of the child components inside parentheses. The **\<Column>**, **\<Row>**, **\<Stack>**, **\<Grid>**, and **\<List>** components are all container components.
- Simple example of the **\<Column>** component:
```ts
Column() {
Text('Hello')
.fontSize(100)
Divider()
Text(this.myText)
.fontSize(100)
.fontColor(Color.Red)
}
```
- Example of nesting multiple child components in the **\<Column>** component:
```ts
Column() {
Row() {
Image('test1.jpg')
.width(100)
.height(100)
Button('click +1')
.onClick(() => {
console.info('+1 clicked!')
})
}
Divider()
Row() {
Image('test2.jpg')
.width(100)
.height(100)
Button('click +2')
.onClick(() => {
console.info('+2 clicked!')
})
}
Divider()
Row() {
Image('test3.jpg')
.width(100)
.height(100)
Button('click +3')
.onClick(() => {
console.info('+3 clicked!')
})
}
}
```
en/application-dev/quick-start/arkts-dynamic-ui-elememt-building.md 0 → 100644
浏览文件 @ 672d91e1
# Dynamic UI Element Building
After you've created a custom component (as described in [Basic UI Description](arkts-basic-ui-description.md)), you can customize the internal UI structure for the component, by drawing on the capability of dynamic UI element building.
## @Builder
The **@Builder** decorator is used to decorate a function for quickly generating multiple layouts in a custom component. This function can be declared outside the **build** function and used in the **build** function or other **@Builder** decorated functions. The following example shows how to use **@Builder**.
```ts
// xxx.ets
@Component
struct CompB {
@State CompValue: string = ''
aboutToAppear() {
console.info('CompB aboutToAppear.')
}
aboutToDisappear() {
console.info('CompB aboutToDisappear.')
}
build() {
Column() {
Button(this.CompValue)
.margin(5)
}
}
}
@Entry
@Component
struct CompA {
size1: number = 100
@State CompValue1: string = "Hello,CompValue1"
@State CompValue2: string = "Hello,CompValue2"
@State CompValue3: string = "Hello,CompValue3"
// Use the custom component CompB in the @Builder decorated function CompC.
@Builder CompC(value: string) {
CompB({ CompValue: value })
}
@Builder SquareText(label: string) {
Text(label)
.fontSize(18)
.width(1 * this.size1)
.height(1 * this.size1)
}
// Use the @Builder decorated function SquareText in the @Builder decorated function RowOfSquareTexts.
@Builder RowOfSquareTexts(label1: string, label2: string) {
Row() {
this.SquareText(label1)
this.SquareText(label2)
}
.width(2 * this.size1)
.height(1 * this.size1)
}
build() {
Column() {
Row() {
this.SquareText("A")
this.SquareText("B")
}
.width(2 * this.size1)
.height(1 * this.size1)
this.RowOfSquareTexts("C", "D")
Column() {
// Use the @Builder decorated custom components three times.
this.CompC(this.CompValue1)
this.CompC(this.CompValue2)
this.CompC(this.CompValue3)
}
.width(2 * this.size1)
.height(2 * this.size1)
}
.width(2 * this.size1)
.height(2 * this.size1)
}
}
```
![builder](figures/builder.PNG)
## @BuilderParam<sup>8+</sup>
The **@BuilderParam** decorator is used to decorate the function type attributes (for example, **@BuilderParam noParam: () => void**) in a custom component. When the custom component is initialized, the attributes decorated by **@BuilderParam** must be assigned values.
### Background
In certain circumstances, you may need to add a specific function, such as a click-to-jump action, to a custom component. However, embedding an event method directly inside of the component will add the function to all places where the component is imported. This is where the **@BuilderParam** decorator comes into the picture. When initializing a custom component, you can assign a **@Builder** decorated method to the **@BuilderParam** decorated attribute, thereby adding the specific function to the custom component.
### Component Initialization Through Parameters
When initializing a custom component through parameters, assign a **@Builder** decorated method to the **@BuilderParam** decorated attribute — **content**, and call the value of **content** in the custom component. If no parameter is passed when assigning a value to the **@BuilderParam** decorated attribute (for example, **noParam: this.specificNoParam**), define the type of the attribute as a function without a return value (for example, **@BuilderParam noParam: () => void**). If any parameter is passed when assigning a value to the **@BuilderParam** decorated attribute (for example, **withParam: this.SpecificWithParam('WithParamA')**), define the type of the attribute as **any** (for example, **@BuilderParam withParam: any**).
```ts
// xxx.ets
@Component
struct CustomContainer {
header: string = ''
@BuilderParam noParam: () => void
@BuilderParam withParam: any
footer: string = ''
build() {
Column() {
Text(this.header)
.fontSize(30)
this.noParam()
this.withParam()
Text(this.footer)
.fontSize(30)
}
}
}
@Entry
@Component
struct CustomContainerUser {
@Builder specificNoParam() {
Column() {
Text('noParam').fontSize(30)
}
}
@Builder SpecificWithParam(label: string) {
Column() {
Text(label).fontSize(30)
}
}
build() {
Column() {
CustomContainer({
header: 'HeaderA',
noParam: this.specificNoParam,
withParam: this.SpecificWithParam('WithParamA'),
footer: 'FooterA'
})
Divider()
.strokeWidth(3)
.margin(10)
CustomContainer({
header: 'HeaderB',
noParam: this.specificNoParam,
withParam: this.SpecificWithParam('WithParamB'),
footer: 'FooterB'
})
}
}
}
```
![builder1](figures/builder1.PNG)
### Component Initialization Through Trailing Closure
In a custom component, the **@BuilderParam** decorated attribute can be initialized using a trailing closure. During initialization, the component name is followed by a pair of braces ({}) to form a trailing closure (**CustomContainer(){}**). You can consider a trailing closure as a container and add content to it. For example, you can add a component (**{Column(){...}**) to the closure. The syntax of the closure is the same as that of **build**. In this scenario, the custom component has one and only one **@BuilderParam** decorated attribute.
Example: Add a **\<Column>** component and a click event to the closure, and call the **specificParam** method decorated by **@Builder** in the new **\<Column>** component. After the **\<Column>** component is clicked, the value of the **CustomContainer** component's **header** attribute will change from **header** to **changeHeader**. When the component is initialized, the content of the trailing closure will be assigned to the **closer** attribute decorated by **@BuilderParam**.
```ts
// xxx.ets
@Component
struct CustomContainer {
header: string = ''
@BuilderParam closer: () => void
build() {
Column() {
Text(this.header)
.fontSize(30)
this.closer()
}
}
}
@Builder function specificParam(label1: string, label2: string) {
Column() {
Text(label1)
.fontSize(30)
Text(label2)
.fontSize(30)
}
}
@Entry
@Component
struct CustomContainerUser {
@State text: string = 'header'
build() {
Column() {
CustomContainer({
header: this.text,
}) {
Column() {
specificParam('testA', 'testB')
}.backgroundColor(Color.Yellow)
.onClick(() => {
this.text = 'changeHeader'
})
}
}
}
}
```
![builder2](figures/builder2.gif)
## @Styles
The **@Styles** decorator helps avoid repeated style setting, by extracting multiple style settings into one method. When declaring a component, you can invoke this method and use the **@Styles** decorator to quickly define and reuse the custom styles of a component. **@Styles** supports only universal attributes.
**@Styles** can be defined inside or outside a component declaration. When it is defined outside a component declaration, the component name must be preceded by the keyword **function**.
```ts
// xxx.ets
@Styles function globalFancy () {
.width(150)
.height(100)
.backgroundColor(Color.Pink)
}
@Entry
@Component
struct FancyUse {
@Styles componentFancy() {
.width(100)
.height(200)
.backgroundColor(Color.Yellow)
}
build() {
Column({ space: 10 }) {
Text('FancyA')
.globalFancy()
.fontSize(30)
Text('FancyB')
.globalFancy()
.fontSize(20)
Text('FancyC')
.componentFancy()
.fontSize(30)
Text('FancyD')
.componentFancy()
.fontSize(20)
}
}
}
```
![styles](figures/styles.PNG)
**@Styles** can also be used inside the **[StateStyles](../reference/arkui-ts/ts-universal-attributes-polymorphic-style.md)** attribute declaration of a component, to assign state-specific attributes to the component.
In **StateStyles**, **@Styles** decorated methods defined outside the component can be directly called, while those defined inside can be called only with the keyword **this**.
```ts
// xxx.ets
@Styles function globalFancy () {
.width(120)
.height(120)
.backgroundColor(Color.Green)
}
@Entry
@Component
struct FancyUse {
@Styles componentFancy() {
.width(80)
.height(80)
.backgroundColor(Color.Red)
}
build() {
Row({ space: 10 }) {
Button('Fancy')
.stateStyles({
normal: {
.width(100)
.height(100)
.backgroundColor(Color.Blue)
},
disabled: this.componentFancy,
pressed: globalFancy
})
}
}
}
```
![styles1](figures/styles1.gif)
## @Extend
The **@Extend** decorator adds new attribute methods to built-in components, such as **\<Text>**, **\<Column>**, and **\<Button>**. In this way, the built-in components are extended instantly.
```ts
// xxx.ets
@Extend(Text) function fancy (fontSize: number) {
.fontColor(Color.Red)
.fontSize(fontSize)
.fontStyle(FontStyle.Italic)
.fontWeight(600)
}
@Entry
@Component
struct FancyUse {
build() {
Row({ space: 10 }) {
Text("Fancy")
.fancy(16)
Text("Fancy")
.fancy(24)
Text("Fancy")
.fancy(32)
}
}
}
```
> **NOTE**
>
> - The **@Extend** decorator cannot be defined inside the struct of a custom component.
> - The **@Extend** decorator supports only attribute methods.
![extend](figures/extend.PNG)
## @CustomDialog
The **@CustomDialog** decorator is used to decorate custom dialog boxes, enabling their content and styles to be dynamically set.
```ts
// xxx.ets
@CustomDialog
struct DialogExample {
controller: CustomDialogController
action: () => void
build() {
Row() {
Button('Close CustomDialog')
.onClick(() => {
this.controller.close()
this.action()
})
}.padding(20)
}
}
@Entry
@Component
struct CustomDialogUser {
dialogController: CustomDialogController = new CustomDialogController({
builder: DialogExample({ action: this.onAccept }),
cancel: this.existApp,
autoCancel: true
});
onAccept() {
console.info('onAccept');
}
existApp() {
console.info('Cancel dialog!');
}
build() {
Column() {
Button('Click to open Dialog')
.onClick(() => {
this.dialogController.open()
})
}
}
}
```
![customdialog](figures/customDialog.gif)
en/application-dev/quick-start/arkts-get-started.md 0 → 100644
浏览文件 @ 672d91e1
# Getting Started with ArkTS
As its name implies, ArkTS is a superset of TypeScript. It is the preferred, primary programming language for application development in OpenHarmony.
- ArkTS offers all the features of TS.
- ArkTS extends TS mainly by adding [declarative UI](arkts-basic-ui-description.md) capabilities, which allow you to develop high-performance applications in a more natural and intuitive manner.
The declarative UI capabilities offered by ArkTS include the following:
- [Basic UI description](arkts-basic-ui-description.md): A wide variety of decorators, custom components, and UI description mechanisms work with the built-in components, event methods, and attribute methods in ArkUI, jointly underpinning UI development.
- [State management](arkts-state-mgmt-page-level.md): In the multi-dimensional state management mechanism for ArkUI, UI-related data can be used not only within a component, but also be transferred between different component levels (for example, between parent and child components, between grandparent and grandchild components, or globally) in a device or even across devices. In addition, data transfer can be classified as one-way (read-only) or two-way (mutable). You can use these capabilities at your disposal to implement linkage between data and the UI.
- [Dynamic UI element building](arkts-dynamic-ui-elememt-building.md): In ArkTS, you can dynamically build UI elements, customizing the internal UI structure of components or extending the native components with custom component styles.
- [Rendering control](arkts-rendering-control.md): ArkTS provides conditional rendering and loop rendering. Conditional rendering can render state-specific content based on the application status. Loop rendering iteratively obtains data from the data source and creates the corresponding component during each iteration.
- [Restrictions and extensions](arkts-restrictions-and-extensions.md): ArkTS provides extensions, such as two-way binding. However, it is not without its restrictions.
- ArkTS will continue to evolve to accommodate changing application development and running requirements, and gradually adds more features, such as parallelism and concurrency enhancement, typed system enhancement, and distributed development paradigm.
Below is sample code to illustrate the building blocks of ArkTS. It implements a simple UI with two text segments, one divider, and one button. When the user clicks the button, the text content changes from "Hello World" to "Hello ArkUI".
![arkts-get-started](figures/arkts-get-started.png)
As shown above, ArkTS has the following building blocks:
- Decorators: used to decorate classes, structures, methods, and variables for custom definitions. In the preceding sample code, **@Entry**, **@Component**, and **@State** are decorators. Specifically, **@Component** indicates a custom component, **@Entry** indicates an entry component, and **@State** indicates a state variable in the component, whose change will trigger re-rendering of the UI.
- Custom components: reusable UI units that can be used in flexible combinations. In the preceding sample code, the structure **Hello** decorated by **@Component** is a custom component.
- UI description: declarative description of the UI structure, such as the code block of the **build()** method.
- Built-in components: basic, container, media, drawing, and canvas components preset in ArkTS. You can directly invoke such components as **\<Column>**, **\<Text>**, **\<Divider>**, and **\<Button>** components in the sample code.
- Attribute methods: methods used to configure component attributes, such as **fontSize()**, **width()**, **height()**, and **color()**. You can configure multiple attributes of a component in method chaining mode.
- Event methods: methods used to add the logic for a component to respond to an event. In the sample code, **onClick()** following **Button** is an event method. You can configure response logic for multiple events in method chaining mode.
en/application-dev/quick-start/arkts-rendering-control.md
浏览文件 @ 672d91e1
......@@ -125,8 +125,8 @@ interface DataChangeListener {
| Name | Type | Mandatory| Description |
| ------------- | --------------------- | ---- | ------------------------------------------------------------ |
| dataSource | IDataSource | Yes | Object used to implement the **IDataSource** API. You need to implement related APIs. |
| itemGenerator | (item: any) => void | Yes | A lambda function used to generate one or more child components for each data item in an array. A single child component or a list of child components must be included in parentheses.|
| keyGenerator | (item: any) => string | No | An anonymous function used to generate a unique and fixed key value for each data item in an array. This key value must remain unchanged for the data item even when the item is relocated in the array. When the item is replaced by a new item, the key value of the new item must be different from that of the existing 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. For example, if no key-value generator is provided, a reverse of an array will result in rebuilding of all nodes in **LazyForEach**.|
| itemGenerator | (item: any, index?: number) => void | Yes | A lambda function used to generate one or more child components for each data item in an array. A single child component or a list of child components must be included in parentheses.|
| keyGenerator | (item: any, index?: number) => string | No | An anonymous function used to generate a unique and fixed key value for each data item in an array. This key value must remain unchanged for the data item even when the item is relocated in the array. When the item is replaced by a new item, the key value of the new item must be different from that of the existing 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. For example, if no key-value generator is provided, a reverse of an array will result in rebuilding of all nodes in **LazyForEach**.|
### Description of IDataSource
......@@ -142,14 +142,14 @@ interface DataChangeListener {
| Name | Description |
| -------------------------------------------------------- | -------------------------------------- |
| onDataReloaded(): void | Invoked when all data is reloaded. |
| onDataAdded(index: number): void (deprecated) | Invoked when data is added to the position indicated by the specified index. |
| onDataMoved(from: number, to: number): void (deprecated) | Invoked when data is moved from the **from** position to the **to** position.|
| onDataDeleted(index: number): void (deprecated) | Invoked when data is deleted from the position indicated by the specified index. |
| onDataChanged(index: number): void (deprecated) | Invoked when data in the position indicated by the specified index is changed. |
| onDataAdd(index: number): void 8+ | Invoked when data is added to the position indicated by the specified index. |
| onDataMove(from: number, to: number): void 8+ | Invoked when data is moved from the **from** position to the **to** position.|
| onDataDelete(index: number): void 8+ | Invoked when data is deleted from the position indicated by the specified index. |
| onDataChange(index: number): void 8+ | Invoked when data in the position indicated by the specified index is changed. |
| onDataAdded(index: number): void<sup>deprecated</sup> | Invoked when data is added to the position indicated by the specified index. This API is deprecated since API version 8. You are advised to use **onDataAdd**. |
| onDataMoved(from: number, to: number): void<sup>deprecated</sup> | Invoked when data is moved from the **from** position to the **to** position. This API is deprecated since API version 8. You are advised to use **onDataMove**.|
| onDataDeleted(index: number): void<sup>deprecated</sup> | Invoked when data is deleted from the position indicated by the specified index. This API is deprecated since API version 8. You are advised to use **onDataDelete**. |
| onDataChanged(index: number): void<sup>deprecated</sup> | Invoked when data in the position indicated by the specified index is changed. This API is deprecated since API version 8. You are advised to use **onDataChange**. |
| onDataAdd(index: number): void<sup>8+</sup> | Invoked when data is added to the position indicated by the specified index. |
| onDataMove(from: number, to: number): void<sup>8+</sup> | Invoked when data is moved from the **from** position to the **to** position.|
| onDataDelete(index: number): void<sup>8+</sup> | Invoked when data is deleted from the position indicated by the specified index. |
| onDataChange(index: number): void<sup>8+</sup> | Invoked when data in the position indicated by the specified index is changed. |
## Example
......
en/application-dev/quick-start/arkts-restrictions-and-extensions.md 0 → 100644
浏览文件 @ 672d91e1
# Restrictions and Extensions
## Restrictions on Using ArkTS in Generators
ArkTS has the following restrictions on generators:
- Expressions can be used only in character strings (${expression}), **if/else** statements, **ForEach** parameters, and component parameters.
- No expressions should cause any application state variables (that is, variables decorated by **@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 applies to anonymous function implementations of event methods (such as **onClick**).
## Two-Way Binding of Variables
ArkTS supports two-way binding through **$$**, which is usually used for variables whose state values change frequently.
- **$$** supports variables of primitive types and variables decorated by **@State**, **@Link**, or **@Prop**.
- **$$** supports only the **show** parameter of the **[bindPopup](../reference/arkui-ts/ts-universal-attributes-popup.md)** attribute method, the **checked** attribute of the **[\<Radio>](../reference/arkui-ts/ts-basic-components-radio.md)** component, and the **refreshing** parameter of the **[\<Refresh>](../reference/arkui-ts/ts-container-refresh.md)** component.
- When the variable bound to **$$** changes, only the current component is rendered, which improves the rendering speed.
```ts
// xxx.ets
@Entry
@Component
struct bindPopupPage {
@State customPopup: boolean = false
build() {
Column() {
Button('Popup')
.margin(20)
.onClick(() => {
this.customPopup = !this.customPopup
})
.bindPopup($$this.customPopup, {
message: "showPopup"
})
}
}
}
```
![popup](figures/popup.gif)
## Restrictions on Data Type Declarations of State Variables
The data type declaration of the **@State**, **@Provide**, **@Link**, or **@Consume** decorated state variables can consist of only one of the primitive data types or reference data types.
Example:
```ts
// xxx.ets
@Entry
@Component
struct IndexPage {
// Incorrect: @State message: string | Resource = 'Hello World'
@State message: string = 'Hello World'
build() {
Row() {
Column() {
Text(`${this.message}`)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
.height('100%')
}
}
```
![hello](figures/hello.PNG)
## Initialization and Restrictions of Custom Components' Member Variables
The member variables of a component can be initialized in either of the following ways:
- Local initialization:
```ts
@State counter: Counter = new Counter()
```
- Initialization using constructor parameters:
```ts
MyComponent({counter: $myCounter})
```
The allowed method depends on the decorator of the state variable, as shown in the following table.
| Decorator | Local Initialization| Initialization Using Constructor Parameters|
| ------------ | ----- | ----------- |
| @State | Mandatory | Optional |
| @Prop | Forbidden | Mandatory |
| @Link | Forbidden | Mandatory |
| @StorageLink | Mandatory | Forbidden |
| @StorageProp | Mandatory | Forbidden |
| @Provide | Mandatory | Optional |
| @Consume | Forbidden | Forbidden |
| @ObjectLink | Forbidden | Mandatory |
| Normal member variable | Recommended | Optional |
As indicated by the preceding table:
- The **@State** decorated variables must be initialized locally. Their initial values can be overwritten by the constructor parameters.
- The **@Prop** and **@Link** decorated variables must be initialized only by constructor parameters.
Comply with the following rules when using constructors to initialize member variables:
| From the Variable in the Parent Component (Below) to the Variable in the Child Component (Right)| @State | @Link | @Prop | Normal Variable|
| -------------------------------------------- | ------ | ------ | ------ | -------- |
| @State | Not allowed| Allowed | Allowed | Allowed |
| @Link | Not allowed| Allowed | Not recommended| Allowed |
| @Prop | Not allowed| Not allowed| Allowed | Allowed |
| @StorageLink | Not allowed| Allowed | Not allowed| Not allowed |
| @StorageProp | Not allowed| Not allowed| Not allowed| Allowed |
| Normal variable | Allowed | Not allowed| Not allowed| Allowed |
As indicated by the preceding table:
- The normal variables of the parent component can be used to initialize the **@State** decorated variables of the child component, but not the **@Link** or **@Prop** decorated variables.
- The **@State** decorated variable of the parent component can be used to initialize the **@Prop**, **@Link** (using **$**), or normal variables of the child component, but not the **@State** decorated variables of the child component.
- The **@Link** decorated variables of the parent component can be used to initialize the **@Link** decorated or normal variables of the child component. However, initializing the **@State** decorated members of the child component can result in a syntax error. In addition, initializing the **@Prop** decorated variables is not recommended.
- The **@Prop** decorated variables of the parent component can be used to initialize the normal variables or **@Prop** decorated variables of the child component, but not the **@State** or **@Link** decorated variables.
- Passing **@StorageLink** and **@StorageProp** from the parent component to the child component is prohibited.
- In addition to the preceding rules, the TypeScript strong type rules need to be followed.
en/application-dev/quick-start/arkts-state-mgmt-application-level.md 0 → 100644
浏览文件 @ 672d91e1
# State Management with Application-level Variables
This topic covers how to manage the application status with application-level variables. For details about the APIs, see [State Management with Application-level Variables](../reference/arkui-ts/ts-state-management.md).
## AppStorage
The [AppStorage](../reference/arkui-ts/ts-state-management.md#appstorage) is a singleton object in an application that provides central storage for changing state attributes of an application. It is created by the UI framework when the application is started and destroyed when the application exits.
The **AppStorage** contains all the state attributes that need to be accessed throughout the application. It retains all attributes and their values as long as the application remains running, and the attribute values can be accessed through unique key values.
Components can synchronize the application state data with the **AppStorage** through 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 mutable. If needed, **AppStorage** can also use immutable (read-only) attributes.
> **NOTE**
>
> [Worker](../reference/apis/js-apis-worker.md) can interact with the main thread only through [postMessage](../reference/apis/js-apis-worker.md#postmessage).
### @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.
### Example
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 button, the value of **languageCode** in the **AppStorage** will be changed, and the change is synchronized to the **this.languageCode** variable.
```ts
// xxx.ets
@Entry
@Component
struct ComponentA {
@StorageLink('varA') varA: number = 2
@StorageProp('languageCode') languageCode: string = 'en'
private label: string = 'count'
aboutToAppear() {
this.label = (this.languageCode === 'en') ? 'Number' : 'Count'
}
build() {
Column() {
Row({ space: 20 }) {
Button(`${this.label}: ${this.varA}`)
.onClick(() => {
AppStorage.Set<number>('varA', AppStorage.Get<number>('varA') + 1)
})
Button(`language: ${this.languageCode}`)
.onClick(() => {
if (AppStorage.Get<string>('languageCode') === 'zh') {
AppStorage.Set<string>('languageCode', 'en')
} else {
AppStorage.Set<string>('languageCode', 'zh')
}
this.label = (this.languageCode === 'en') ? 'Number' : 'Count'
})
}
.margin({ bottom: 50 })
Row() {
Button (`Change @StorageLink decorated variable: ${this.varA}`).height(40).fontSize(14)
.onClick(() => {
this.varA++
})
}.margin({ bottom: 50 })
Row() {
Button (`Change @StorageProp decorated variable: ${this.languageCode}`).height(40).fontSize(14)
.onClick(() => {
if (this.languageCode === 'zh') {
this.languageCode = 'en'
} else {
this.languageCode = 'zh'
}
})
}
}
}
}
```
![appstorage](figures/appstorage.gif)
## LocalStorage
> **NOTE**
>
> This API is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
The **LocalStorage** is a storage unit in an application. Its lifecycle follows its associated ability. In the stage model, the **LocalStorage** provides global data isolation between abilities and applies to where a data sharing scope smaller than that provided by the **AppStorage** is required. The **LocalStorage** also provides storage for application-wide mutable and immutable state attributes, which are used for building part of the application UI, such as an ability UI. The **LocalStorage** resolves the data interference between the application and the abilities and, in multi-instance scenarios, data interference between different **Ability** instances under the same **Ability** class. In distributed migration scenarios, **Ability**, as the minimum unit for the system to schedule applications, allows for easier component data migration when working with the **LocalStorage**.
At the application layer, multiple **LocalStorage** instances can be created for an application, each corresponding to an ability of the application.
An application can have multiple abilities. At most one **LocalStorage** instance can be allocated to the components in an ability. In addition, all components in the ability inherit access to the objects stored in the **LocalStorage** instance.
A component can access a maximum of one **LocalStorage** instance, and one **LocalStorage** instance can be assigned 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 initial value 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 the **@LocalStorageLink** decorated variable in a component will be first synchronized to the **LocalStorage**, and then to other bound UI components under the same 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 initial value in the **LocalStorage**. Changes made to the value in the **LocalStorage** will cause all UI components under the current 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.
### Example 1: Creating a LocalStorage Instance in an Ability
The **LocalStorage** is loaded through the **loadContent** API. For details, see [loadContent](../reference/apis/js-apis-window.md#loadcontent9-1).
```ts
// MainAbility.ts
import Ability from '@ohos.application.Ability'
export default class MainAbility extends Ability {
storage: LocalStorage
onCreate() {
this.storage = new LocalStorage()
this.storage.setOrCreate('storageSimpleProp', 121)
console.info('[Demo MainAbility onCreate]')
}
onDestroy() {
console.info('[Demo MainAbility onDestroy]')
}
onWindowStageCreate(windowStage) {
// storage is passed to the loadContent API as a parameter.
windowStage.loadContent('pages/index', this.storage)
}
onWindowStageDestroy() {
console.info('[Demo] MainAbility onWindowStageDestroy')
}
onForeground() {
console.info('[Demo] MainAbility onForeground')
}
onBackground() {
console.info('[Demo] MainAbility onBackground')
}
}
```
The **@Component** decorated component obtains data.
```ts
// index.ets
let storage = LocalStorage.GetShared()
@Entry(storage)
@Component
struct LocalStorageComponent {
@LocalStorageLink('storageSimpleProp') simpleVarName: number = 0
build() {
Column() {
Button(`LocalStorageLink: ${this.simpleVarName.toString()}`)
.margin(20)
.onClick(() => {
this.simpleVarName += 1
})
Text(JSON.stringify(this.simpleVarName))
.fontSize(50)
LocalStorageComponentProp()
}.width('100%')
}
}
@Component
struct LocalStorageComponentProp {
@LocalStorageProp('storageSimpleProp') simpleVarName: number = 0
build() {
Column() {
Button(`LocalStorageProp: ${this.simpleVarName.toString()}`)
.margin(20)
.onClick(() => {
this.simpleVarName += 1
})
Text(JSON.stringify(this.simpleVarName))
.fontSize(50)
}.width('100%')
}
}
```
![appstorage1](figures/appstorage1.gif)
### Example 2: Defining LocalStorage on the Entry Page
```ts
// xxx.ets
let storage = new LocalStorage({ "PropA": 47 })
@Entry(storage)
@Component
struct ComA {
@LocalStorageLink("PropA") storageLink: number = 1
build() {
Column() {
Text(`Parent from LocalStorage ${this.storageLink}`)
.fontSize(18)
.margin(20)
.onClick(() => this.storageLink += 1)
Child()
}
}
}
@Component
struct Child {
@LocalStorageLink("PropA") storageLink: number = 1
build() {
Text(`Child from LocalStorage ${this.storageLink}`)
.fontSize(18)
.margin(20)
.onClick(() => this.storageLink += 1)
}
}
```
![appstorage2](figures/appstorage2.gif)
## PersistentStorage
[PersistentStorage](../reference/arkui-ts/ts-state-management.md#persistentstorage) provides a set of static methods 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 that matches the specific key.
> **NOTE**
>
> - When using the **PersistProp** API in **PersistentStorage**, ensure that the input key exists in the **AppStorage**.
> - The **DeleteProp** API in **PersistentStorage** takes effect only for the data that has been linked during the current application startup.
```ts
// xxx.ets
PersistentStorage.PersistProp('highScore', '0')
@Entry
@Component
struct PersistentComponent {
@StorageLink('highScore') highScore: string = '0'
@State currentScore: number = 0
build() {
Column() {
if (this.currentScore === Number(this.highScore)) {
Text(`new highScore : ${this.highScore}`).fontSize(18)
}
Button(`goal!, currentScore : ${this.currentScore}`)
.margin(20)
.onClick(() => {
this.currentScore++
if (this.currentScore > Number(this.highScore)) {
this.highScore = this.currentScore.toString()
}
})
}.width('100%')
}
}
```
![appstorage3](figures/appstorage3.gif)
## Environment
[Environment](../reference/arkui-ts/ts-state-management.md#environment) is a singleton object created by the framework when the application is started. It provides the **AppStorage** with an array of environment state attributes required by the application. These attributes, such as the system language and color mode, describe the device environment where the application runs. **Environment** and its attributes are immutable, and all attribute values are of simple types. The following example shows how to obtain whether accessibility is enabled from **Environment**:
```ts
Environment.EnvProp('accessibilityEnabled', 'default')
var enable = AppStorage.Get('accessibilityEnabled')
```
**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.
en/application-dev/quick-start/arkts-state-mgmt-concepts.md 0 → 100644
浏览文件 @ 672d91e1
# Basic Concepts
In the multi-dimensional state management mechanism for ArkUI, UI-related data can be used not only within a component, but also be transferred between different component levels (for example, between parent and child components, between grandparent and grandchild components, or globally). In addition, data transfer can be classified as one-way (read-only) or two-way (mutable). You can use these capabilities at your disposal to implement linkage between data and the UI.
![](figures/CoreSpec_figures_state-mgmt-overview.png)
## State Management with Page-level Variables
| Decorator | Decorates... | Description |
| ----------- | ------------------------- | ------------------------------------------------------------ |
| @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 re-rendered.|
| @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 | Class | 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 re-rendering.|
## State Management with Application-level Variables
**AppStorage** is the central store of the application states in the entire UI. ArkUI 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 target object is obtained from the **AppStorage** based on the given name. **@StorageLink** establishes two-way binding between the decorated 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 data of applications. The changes made by this API will be synchronized to the UI component for UI update.
- **PersistentStorage**: provides a set of static methods 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 that matches the specific key.
- **Environment**: provides the **AppStorage** with an array of environment state attributes that are required by the application and describe the device environment where the application runs. It is a singleton object created by the framework when the application is started.
en/application-dev/quick-start/arkts-state-mgmt-page-level.md 0 → 100644
浏览文件 @ 672d91e1
# State Management with Page-level Variables
This topic covers how to manage the states with page-level variables with the **@State**, **@Prop**, **@Link**, **@Provide**, **@Consume**, **@ObjectLink**, **@Observed**, and **@Watch** decorators.
For details about the constraints of the **@State**, **@Provide**, **@Link**, and **@Consume** decorated state variables, see [Restrictions on Data Type Declarations of State Variables](./arkts-restrictions-and-extensions.md).
## @State
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.
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\<number>**, **Array\<boolean>**, and **Array\<string>**. **object** and **any** are not supported.
- 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. Uninitialized variables may cause undefined framework exceptions.
- 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.
**Example**
In the following 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** instance does not affect the second **MyComponent** instance.
- 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 })
```
```ts
// xxx.ets
class Model {
value: string
constructor(value: string) {
this.value = value
}
}
@Entry
@Component
struct EntryComponent {
build() {
Column() {
MyComponent ({ count: 1,increaseBy:2 }) // First MyComponent instance
MyComponent({ title: { value:'Hello World 2' }, count: 7 }) // Second MyComponent instance
}
}
}
@Component
struct MyComponent {
@State title: Model = { value: 'Hello World' }
@State count: number = 0
private toggle: string = 'Hello World'
private increaseBy: number = 1
build() {
Column() {
Text(`${this.title.value}`).fontSize(30)
Button('Click to change title')
.margin(20)
.onClick(() => {
// Change the value of the internal status variable title.
this.title.value = (this.toggle == this.title.value) ? 'Hello World' : 'Hello ArkUI'
})
Button(`Click to increase count=${this.count}`)
.margin(20)
.onClick(() => {
// Change the value of the internal status variable count.
this.count += this.increaseBy
})
}
}
}
```
## @Prop
**@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** decorated state variable 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**
In the preceding example, when the user presses **+1** or **-1**, the status of the parent component changes and the **build** method is executed again. In this case, a new **CountDownComponent** instance is created. The **countDownStartValue** attribute of the parent component is used to initialize the **@Prop** decorated variable of the child component. When the **count - costOfOneAttempt** button of the child component is touched, 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.
```ts
// xxx.ets
@Entry
@Component
struct ParentComponent {
@State countDownStartValue: number = 10 // Initialize countDownStartValue
build() {
Column() {
Text(`Grant ${this.countDownStartValue} nuggets to play.`).fontSize(18)
Button('+1 - Nuggets in New Game')
.margin(15)
.onClick(() => {
this.countDownStartValue += 1
})
Button('-1 - Nuggets in New Game')
.margin(15)
.onClick(() => {
this.countDownStartValue -= 1
})
// When creating a child component, you must provide the initial value of its @Prop decorated variable count in the constructor parameter and initialize the regular variable costOfOneAttempt (not @Prop decorated).
CountDownComponent({ count: this.countDownStartValue, costOfOneAttempt: 2 })
}
}
}
@Component
struct CountDownComponent {
@Prop count: number
private costOfOneAttempt: number
build() {
Column() {
if (this.count > 0) {
Text(`You have ${this.count} Nuggets left`).fontSize(18)
} else {
Text('Game over!').fontSize(18)
}
Button('count - costOfOneAttempt')
.margin(15)
.onClick(() => {
this.count -= this.costOfOneAttempt
})
}
}
}
```
## @Link
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 **@Link** decorated variables support the data types the same as the **@State** decorated variables; 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 used for initializing the **@Link** decorated variable must be a **@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 an instance of the component, you must use the naming parameter to initialize all **@Link** decorated variables. **@Link** decorated variables can be initialized by using the reference of the **@State** or **@Link** decorated variable. Wherein, the **@State** decorated variables can be referenced using the **'$'** operator.
> **NOTE**
>
> **@Link** decorated variables cannot be initialized within the component.
**Simple Type Example**
The **@Link** semantics are derived from the '**$**' operator. In other words, **$isPlaying** is the two-way binding of the internal state **this.isPlaying**. When the button in the **PlayButton** child component is touched, the value of the **@Link** decorated variable is changed, and **PlayButton** together with the **\<Text>** and **\<Button>** components of the parent component is refreshed. Similarly, when the button in the parent component is touched, the value of **this.isPlaying** is changed, and **PlayButton** together with the **\<Text>** and **\<Button>** components of the parent component is refreshed.
```ts
// xxx.ets
@Entry
@Component
struct Player {
@State isPlaying: boolean = false
build() {
Column() {
PlayButton({ buttonPlaying: $isPlaying })
Text(`Player is ${this.isPlaying ? '' : 'not'} playing`).fontSize(18)
Button('Parent:' + this.isPlaying)
.margin(15)
.onClick(() => {
this.isPlaying = !this.isPlaying
})
}
}
}
@Component
struct PlayButton {
@Link buttonPlaying: boolean
build() {
Column() {
Button(this.buttonPlaying ? 'pause' : 'play')
.margin(20)
.onClick(() => {
this.buttonPlaying = !this.buttonPlaying
})
}
}
}
```
**Complex Type Example**
```ts
// xxx.ets
@Entry
@Component
struct Parent {
@State arr: number[] = [1, 2, 3]
build() {
Column() {
Child({ items: $arr })
Button('Parent Button: splice')
.margin(10)
.onClick(() => {
this.arr.splice(0, 1, 60)
})
ForEach(this.arr, item => {
Text(item.toString()).fontSize(18).margin(10)
}, item => item.toString())
}
}
}
@Component
struct Child {
@Link items: number[]
build() {
Column() {
Button('Child Button1: push')
.margin(15)
.onClick(() => {
this.items.push(100)
})
Button('Child Button2: replace whole item')
.margin(15)
.onClick(() => {
this.items = [100, 200, 300]
})
}
}
}
```
**Example of Using @Link, @State, and @Prop Together**
In the following example, **ParentView** contains two child components: **ChildA** and **ChildB**. The **counter** state variable of **ParentView** is used to initialize the **@Prop** decorated variable of **ChildA** and the **@Link** decorated variable of **ChildB**.
- **@Link** establishes two-way binding between **ChildB** and **ParentView**.Value changes of the **counterRef** state variable in **ChildB** will be synchronized to **ParentView** and **ChildA**.
- **@Prop** establishes one-way binding between **ChildA** and **ParentView**. Value changes of the **counterVal** state variable in **ChildA** will trigger a re-render of **ChildA**, but will not be synchronized to **ParentView** or **ChildB**.
```ts
// xxx.ets
@Entry
@Component
struct ParentView {
@State counter: number = 0
build() {
Column() {
ChildA({ counterVal: this.counter })
ChildB({ counterRef: $counter })
}
}
}
@Component
struct ChildA {
@Prop counterVal: number
build() {
Button(`ChildA: (${this.counterVal}) + 1`)
.margin(15)
.onClick(() => {
this.counterVal += 1
})
}
}
@Component
struct ChildB {
@Link counterRef: number
build() {
Button(`ChildB: (${this.counterRef}) + 1`)
.margin(15)
.onClick(() => {
this.counterRef += 1
})
}
}
```
## @Observed and @ObjectLink
When you need to set up bidirectional synchronization for a parent variable (**parent_a**) between the parent and child components, 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.
![en-us_image_0000001251090821](figures/en-us_image_0000001251090821.png)
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.
![en-us_image_0000001206450834](figures/en-us_image_0000001206450834.png)
### Configuration Requirements
- **@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 simple 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.
### Example
```ts
// xxx.ets
// Use @ObjectLink and @Observed to set up bidirectional synchronization for the class object ClassA between the parent component ViewB and the child component ViewA. In this way, changes made to ClassA in ViewA will be synchronized to ViewB and other child components bound to ClassA.
var nextID: number = 0
@Observed
class ClassA {
public name: string
public c: number
public id: number
constructor(c: number, name: string = 'OK') {
this.name = name
this.c = c
this.id = nextID++
}
}
@Component
struct ViewA {
label: string = 'ViewA1'
@ObjectLink a: ClassA
build() {
Row() {
Button(`ViewA [${this.label}] this.a.c= ${this.a.c} +1`)
.onClick(() => {
this.a.c += 1
})
}.margin({ top: 10 })
}
}
@Entry
@Component
struct ViewB {
@State arrA: ClassA[] = [new ClassA(0), new ClassA(0)]
build() {
Column() {
ForEach(this.arrA, (item) => {
ViewA({ label: `#${item.id}`, a: item })
}, (item) => item.id.toString())
ViewA({ label: `this.arrA[first]`, a: this.arrA[0] })
ViewA({ label: `this.arrA[last]`, a: this.arrA[this.arrA.length - 1] })
Button(`ViewB: reset array`)
.margin({ top: 10 })
.onClick(() => {
this.arrA = [new ClassA(0), new ClassA(0)]
})
Button(`ViewB: push`)
.margin({ top: 10 })
.onClick(() => {
this.arrA.push(new ClassA(0))
})
Button(`ViewB: shift`)
.margin({ top: 10 })
.onClick(() => {
this.arrA.shift()
})
}.width('100%')
}
}
```
## @Consume and @Provide
As the data provider, **@Provide** can update the data of child nodes and trigger page rendering. After **@Consume** detects that the **@Provide** decorated variable is updated, it will initiate re-rendering of the current custom component.
> **NOTE**
>
> To avoid infinite loops caused by circular reference, exercise caution when using **@Provide** and **@Consume**.
### @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** decorated variable. You can change the value of the variable to trigger a re-render. 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| Page re-rendering is triggered in the following scenarios:<br>- Changes of variables of simple types (boolean, string, and number)<br>- Changes of the **@Observed** decorated classes or their attributes<br>- Addition, deletion, or updating of elements in an array|
### @Consume
| Type | Description |
| ------ | ---------------- |
| Initial value| The default initial value cannot be set.|
### Example
```ts
// xxx.ets
@Entry
@Component
struct CompA {
@Provide("reviewVote") reviewVotes: number = 0;
build() {
Column() {
CompB()
Button(`CompA: ${this.reviewVotes}`)
.margin(10)
.onClick(() => {
this.reviewVotes += 1;
})
}
}
}
@Component
struct CompB {
build() {
Column() {
CompC()
}
}
}
@Component
struct CompC {
@Consume("reviewVote") reviewVotes: number
build() {
Column() {
Button(`CompC: ${this.reviewVotes}`)
.margin(10)
.onClick(() => {
this.reviewVotes += 1
})
}.width('100%')
}
}
```
## @Watch
**@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 value changes of variables decorated by **@State**, **@Prop**, **@Link**, **@ObjectLink**, **@Provide**, **@Consume**, **@StorageProp**, and **@StorageLink**.
> **NOTE**
>
> **@Watch** cannot be used to listen for in-depth data modification, such as changes of object values in an array.
```ts
// xxx.ets
@Entry
@Component
struct CompA {
@State @Watch('onBasketUpdated') shopBasket: Array<number> = [7, 12, 47, 3]
@State totalPurchase: number = 0
@State addPurchase: number = 0
aboutToAppear() {
this.updateTotal()
}
updateTotal(): number {
let sum = 0;
this.shopBasket.forEach((i) => {
sum += i
})
// Calculate the total amount of items in the shopping basket. If the amount exceeds 100, the specified discount will be applied.
this.totalPurchase = (sum < 100) ? sum : 0.9 * sum
return this.totalPurchase
}
// This method is triggered when the value of shopBasket is changed.
onBasketUpdated(propName: string): void {
this.updateTotal()
}
build() {
Column() {
Button('add to basket ' + this.addPurchase)
.margin(15)
.onClick(() => {
this.addPurchase = Math.round(100 * Math.random())
this.shopBasket.push(this.addPurchase)
})
Text(`${this.totalPurchase}`)
.fontSize(30)
}
}
}
```
en/application-dev/quick-start/deveco-studio-user-guide-for-openharmony.md
浏览文件 @ 672d91e1
......@@ -13,4 +13,4 @@ HUAWEI DevEco Studio For OpenHarmony (DevEco Studio for short) is a one-stop int
- **One-stop information acquisition**: A one-stop information acquisition platform that takes into account the developer journey of learning, development, and help seeking, in order to facilitate developer activities.
- **Efficient code debugging**: Various debugging capabilities such as TS, JS, and C/C++ code breakpoint setting, single-step execution, and variable viewing, improving the efficiency of analyzing application/service issues.
For more information, see [DevEco Studio (OpenHarmony) User Guide](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-deveco-studio-overview-0000001263280421).
For more information, see [DevEco Studio User Guide (OpenHarmony)](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-deveco-studio-overview-0000001263280421).
en/application-dev/quick-start/resource-categories-and-access.md
浏览文件 @ 672d91e1
# Resource Categories and Access
## Resource Categories
During application development, you may need to use different resources, such as colors, fonts, spacing, and images, based on the device or configuration. Depending on the resource type, you can achieve this using the following methods:
- Application resources: Configure device- or configuration-specific resources in the resource files.
Resource files used during application development must be stored in specified directories for management.
- System resources: Use the preset resource definitions.
## Resource Categories
### resources Directory
The **resources** directory consists of three types of sub-directories: the **base** sub-directory, qualifiers sub-directories, and the **rawfile** sub-directory. The common resource files used across projects in the stage model are stored in the **resources** directory under **AppScope**.
Resource files used during application development must be stored in specified directories for management. The **resources** directory consists of three types of subdirectories: the **base** subdirectory, qualifiers subdirectories, and the **rawfile** subdirectory. The common resource files used across projects in the stage model are stored in the **resources** directory under **AppScope**.
Example of the **resources** directory:
The **base** subdirectory is provided by default, and the qualifiers subdirectories are created on your own. When your application needs to use a resource, the system preferentially searches the qualifiers subdirectories that match the current device state. The system searches the **base** subdirectory for the target resource only when the **resources** directory does not contain any qualifiers subdirectories that match the current device state or the target resource is not found in the qualifiers subdirectories. The **rawfile** directory is not searched for resources.
Example of the **resources** directory:
```
resources
......@@ -17,7 +23,7 @@ resources
| | |---string.json
| |---media
| | |---icon.png
|---en_GB-vertical-car-mdpi // Example of a qualifiers sub-directory, which needs to be created on your own
|---en_GB-vertical-car-mdpi // Example of a qualifiers subdirectory, which needs to be created on your own
| |---element
| | |---string.json
| |---media
......@@ -27,20 +33,20 @@ resources
**Table 1** Classification of the resources directory
| Category | base Sub-directory | Qualifiers Sub-directory | rawfile Sub-directory |
| Category | base Subdirectory | Qualifiers Subdirectory | rawfile Subdirectory |
| ---- | ---------------------------------------- | ---------------------------------------- | ---------------------------------------- |
| Structure| The **base** sub-directory is a default directory. If no qualifiers sub-directories in the **resources** directory of the application match the device status, the resource file in the **base** sub-directory will be automatically referenced.<br>Resource group sub-directories are located at the second level of sub-directories to store basic elements such as strings, colors, and boolean values, as well as resource files such as media, animations, and layouts. For details, see [Resource Group Sub-directories](#resource-group-sub-directories).| You need to create qualifiers sub-directories on your own. Each directory name consists of one or more qualifiers that represent the application scenarios or device characteristics. For details, see [Qualifiers Sub-directories](#qualifiers-sub-directories).<br>Resource group sub-directories are located at the second level of sub-directories to store basic elements such as strings, colors, and boolean values, as well as resource files such as media, animations, and layouts. For details, see [Resource Group Sub-directories](#resource-group-sub-directories). | You can create multiple levels of sub-directories with custom directory names. They can be used to store various resource files.<br>However, resource files in the **rawfile** sub-directory will not be matched based on the device status.|
| Compilation| Resource files in the sub-directory are compiled into binary files, and each resource file is assigned an ID. | Resource files in the sub-directory are compiled into binary files, and each resource file is assigned an ID. | Resource files in the sub-directory are directly packed into the application without being compiled, and no IDs will be assigned to the resource files. |
| Reference| Resource files in the sub-directory are referenced based on the resource type and resource name. | Resource files in the sub-directory are referenced based on the resource type and resource name. | Resource files in the sub-directory are referenced based on the file path and file name. |
| Structure| The **base** subdirectory is a default directory. If no qualifiers subdirectories in the **resources** directory of the application match the device status, the resource file in the **base** subdirectory will be automatically referenced.<br>Resource group subdirectories are located at the second level of subdirectories to store basic elements such as strings, colors, and boolean values, as well as resource files such as media, animations, and layouts. For details, see [Resource Group Subdirectories](#resource-group-subdirectories).| You need to create qualifiers subdirectories on your own. Each directory name consists of one or more qualifiers that represent the application scenarios or device characteristics. For details, see [Qualifiers Sub-directories](#qualifiers-subdirectories).<br>Resource group subdirectories are located at the second level of subdirectories to store basic elements such as strings, colors, and boolean values, as well as resource files such as media, animations, and layouts. For details, see [Resource Group Subdirectories](#resource-group-subdirectories).| You can create multiple levels of subdirectories with custom directory names. They can be used to store various resource files.<br>However, resource files in the **rawfile** subdirectory will not be matched based on the device status.|
| Compilation| Resource files in the subdirectory are compiled into binary files, and each resource file is assigned an ID. | Resource files in the subdirectory are compiled into binary files, and each resource file is assigned an ID. | Resource files in the subdirectory are directly packed into the application without being compiled, and no IDs will be assigned to the resource files. |
| Reference| Resource files in the subdirectory are referenced based on the resource type and resource name. | Resource files in the subdirectory are referenced based on the resource type and resource name. | Resource files in the subdirectory are referenced based on the file path and file name. |
### Qualifiers Sub-directories
### Qualifiers Subdirectories
The name of a qualifiers sub-directory consists of one or more qualifiers that represent the application scenarios or device characteristics, covering the mobile country code (MCC), mobile network code (MNC), language, script, country or region, screen orientation, device type, night mode, and screen density. The qualifiers are separated using underscores (\_) or hyphens (\-). Before creating a qualifiers sub-directory, familiarize yourself with the directory naming conventions and the rules for matching qualifiers sub-directories and the device status.
The name of a qualifiers subdirectory consists of one or more qualifiers that represent the application scenarios or device characteristics, covering the mobile country code (MCC), mobile network code (MNC), language, script, country or region, screen orientation, device type, night mode, and screen density. The qualifiers are separated using underscores (\_) or hyphens (\-). Before creating a qualifiers subdirectory, familiarize yourself with the directory naming conventions and the rules for matching qualifiers subdirectories and the device status.
**Naming Conventions for Qualifiers Sub-directories**
- Qualifiers are ordered in the following sequence: **\_MCC_MNC-language_script_country/region-orientation-device-color mode-density**. You can select one or multiple qualifiers to name your sub-directory based on your application scenarios and device characteristics.
- Qualifiers are ordered in the following sequence: **\_MCC_MNC-language_script_country/region-orientation-device-color mode-density_**. You can select one or multiple qualifiers to name your subdirectory based on your application scenarios and device characteristics.
- Separation between qualifiers: The language, script, and country/region qualifiers are separated using underscores (\_); the MNC and MCC qualifiers are also separated using underscores (\_); other qualifiers are separated using hyphens (\-). For example, **zh_Hant_CN** and **zh_CN-car-ldpi**.
......@@ -63,19 +69,19 @@ The name of a qualifiers sub-directory consists of one or more qualifiers that r
- Qualifiers are matched with the device resources in the following priorities: MCC&MNC > locale (options: language, language_script, language_country/region, and language_script_country/region) > screen orientation > device type > color mode > screen density.
- If the qualifiers sub-directories contain the **MCC, MNC, language, script, screen orientation, device type, and color mode** qualifiers, their values must be consistent with the current device status so that the sub-directories can be used for matching the device resources. For example, the qualifiers sub-directory **zh_CN-car-ldpi** cannot be used for matching the resource files labeled **en_US**.
- If the qualifiers subdirectories contain the **MCC, MNC, language, script, screen orientation, device type, and color mode** qualifiers, their values must be consistent with the current device status so that the subdirectories can be used for matching the device resources. For example, the qualifiers subdirectory **zh_CN-car-ldpi** cannot be used for matching the resource files labeled **en_US**.
### Resource Group Sub-directories
### Resource Group Subdirectories
You can create resource group sub-directories (including element, media, and profile) in the **base** and qualifiers sub-directories to store resource files of specific types.
You can create resource group subdirectories (including element, media, and profile) in the **base** and qualifiers subdirectories to store resource files of specific types.
**Table 3** Resource group sub-directories
**Table 3** Resource group subdirectories
| Resource Group Sub-directory | Description | Resource File |
| Resource Group Subdirectory | Description | Resource File |
| ------- | ---------------------------------------- | ---------------------------------------- |
| element | Indicates element resources. Each type of data is represented by a JSON file. The options are as follows:<br>- **boolean**: boolean data<br>- **color**: color data<br>- **float**: floating-point data<br>- **intarray**: array of integers<br>- **integer**: integer data<br>- **pattern**: pattern data<br>- **plural**: plural form data<br>- **strarray**: array of strings<br>- **string**: string data| It is recommended that files in the **element** sub-directory be named the same as the following files, each of which can contain only data of the same type:<br>- boolean.json<br>- color.json<br>- float.json<br>- intarray.json<br>- integer.json<br>- pattern.json<br>- plural.json<br>- strarray.json<br>- string.json |
| element | Indicates element resources. Each type of data is represented by a JSON file. The options are as follows:<br>- **boolean**: boolean data<br>- **color**: color data<br>- **float**: floating-point data<br>- **intarray**: array of integers<br>- **integer**: integer data<br>- **pattern**: pattern data<br>- **plural**: plural form data<br>- **strarray**: array of strings<br>- **string**: string data| It is recommended that files in the **element** subdirectory be named the same as the following files, each of which can contain only data of the same type:<br>- boolean.json<br>- color.json<br>- float.json<br>- intarray.json<br>- integer.json<br>- pattern.json<br>- plural.json<br>- strarray.json<br>- string.json |
| media | Indicates media resources, including non-text files such as images, audios, and videos. | The file name can be customized, for example, **icon.png**. |
| rawfile | Indicates other types of files, which are stored in their raw formats after the application is built as an HAP file. They will not be integrated into the **resources.index** file.| The file name can be customized. |
......@@ -190,33 +196,25 @@ The content of the **plural.json** file is as follows:
**Creating a Resource File**
You can create a sub-directory and its files under the **resources** directory based on the preceding descriptions of the qualifiers sub-directories and resource group sub-directories.
You can create a subdirectory and its files under the **resources** directory based on the preceding descriptions of the qualifiers subdirectories and resource group subdirectories.
DevEco Studio provides a wizard for you to create resource directories and resource files.
- Creating a Resource Directory and Resource File
Right-click the **resources** directory and choose **New > Resource File**.
If no qualifier is selected, the file is created in a resource type sub-directory under **base**. If one or more qualifiers are selected, the system automatically generates a sub-directory and creates the file in this sub-directory.
The created sub-directory is automatically named in the format of **Qualifiers.Resource type**. For example, if you create a sub-directory by setting **Orientation** to **Vertical** and **Resource type** to **Graphic**, the system automatically generates a sub-directory named **vertical.graphic**.
Right-click the **resources** directory and choose **New > Resource File**. If no qualifier is selected, the file is created in a resource type subdirectory under **base**. If one or more qualifiers are selected, the system automatically generates a subdirectory and creates the file in this subdirectory. To select a qualifier, highlight it under **Available qualifiers** and click the right arrow. To deselect a qualifier, highlight it under **Selected qualifiers** and click the left arrow. In **File name**, enter the name of the resource file to create. In **Resource type**, select the type of the resource group, which is **element** by default. In **Root Element**, select a resource type. The created subdirectory is automatically named in the format of *Qualifiers.Resource group type*. For example, if you create a subdirectory by setting **Color Mode** to **Dark** and **Resource type** to **Element**, the system automatically generates a subdirectory named **dark.element**.
![create-resource-file-1](figures/create-resource-file-1.png)
- Creating a Resource Directory
Right-click the **resources** directory and choose **New > Resource Directory**. This operation creates a sub-directory only.
Select a resource group type and set qualifiers. Then the system automatically generates the sub-directory name. The sub-directory is automatically named in the format of **Qualifiers.Resource group**. For example, if you create a sub-directory by setting **Orientation** to **Vertical** and **Resource type** to **Graphic**, the system automatically generates a sub-directory named **vertical.graphic**.
Right-click the **resources** directory and choose **New > Resource Directory** to create a subdirectory only. By default, the **base** subdirectory is created. You can create qualifiers subdirectories as required, by specifying the qualifier and resource group type.
![create-resource-file-2](figures/create-resource-file-2.png)
- Creating a Resource File
Right-click a sub-directory under **resources** and choose **New > *XXX* Resource File**. This operation creates a resource file under this sub-directory.
For example, you can create an element resource file in the **element** sub-directory.
Right-click a subdirectory under **resources** and choose **New > *XXX* Resource File**. This operation creates a resource file under this subdirectory. For example, you can create an element resource file in the **element** subdirectory.
![create-resource-file-3](figures/create-resource-file-3.png)
......@@ -224,7 +222,7 @@ DevEco Studio provides a wizard for you to create resource directories and resou
To reference an application resource in a project, use the **"$r('app.type.name')"** format. **app** indicates the resource defined in the **resources** directory of the application. **type** indicates the resource type (or the location where the resource is stored). The value can be **color**, **float**, **string**, **plural**, or **media**. **name** indicates the resource name, which you set when defining the resource.
When referencing resources in the **rawfile** sub-directory, use the **"$rawfile('filename')"** format. Wherein, **filename** indicates the relative path of a file in the **rawfile** directory, which must contain the file name extension in the file name and cannot start with a slash (/).
When referencing resources in the **rawfile** subdirectory, use the **"$rawfile('filename')"** format. Wherein **filename** indicates the relative path of a file in the **rawfile** subdirectory, which must contain the file name extension and cannot start with a slash (/).
> **NOTE**
>
......@@ -266,9 +264,14 @@ Image($rawfile('newDir/newTest.png')) // Reference an image in the rawfile
System resources include colors, rounded corners, fonts, spacing, character strings, and images. By using system resources, you can develop different applications with the same visual style.
To reference a system resource, use the **"$r('sys.type.resource_id')"** format. Wherein: **sys** indicates a system resource; **type** indicates the resource type, which can be **color**, **float**, **string**, or **media**; **resource_id** indicates the resource ID.
> **NOTE**
>
> - Use of system resources is supported in the declarative development paradigm, but not in the web-like development paradigm.
>
> - For details about the implementation of preconfigured resources, visit the [OpenHarmony/resources repository](https://gitee.com/openharmony/resources/tree/master/systemres/main/resources). The directory structure there is similar to that of the **resources** directory in the project. Resource qualifiers are used to match resources with different devices and device states.
```ts
Text('Hello')
.fontColor($r('sys.color.ohos_id_color_emphasize'))
......@@ -281,3 +284,4 @@ Image($r('sys.media.ohos_app_icon'))
.height(200)
.width(300)
```
en/application-dev/quick-start/start-overview.md
浏览文件 @ 672d91e1
......@@ -2,10 +2,8 @@
This document is intended for novices at developing OpenHarmony applications. It will introduce you to the OpenHarmony project directory structure and application development process, by walking you through a stripped-down, real-world example – building two pages and implementing redirection between them. The following figure shows how the pages look on the DevEco Studio Previewer.
![en-us_image_0000001364254729](figures/en-us_image_0000001364254729.png)
Before you begin, there are two basic concepts that will help you better understand OpenHarmony: UI framework and ability.
......
en/application-dev/quick-start/start-with-ets-fa.md
浏览文件 @ 672d91e1
......@@ -5,31 +5,33 @@
>
> To use ArkTS, your DevEco Studio must be V3.0.0.601 Beta1 or later.
>
> For best possible results, use [DevEco Studio V3.0.0.993](https://developer.harmonyos.com/cn/develop/deveco-studio#download) for your development.
> For best possible results, use [DevEco Studio V3.1.0.100](https://developer.harmonyos.com/cn/develop/deveco-studio) for your development.
## Creating an eTS Project
## Creating an ArkTS Project
1. If you are opening DevEco Studio for the first time, click **Create Project**. If a project is already open, choose **File** > **New** > **Create Project** from the menu bar. On the **OpenHarmony** tab of the **Choose Your Ability Template** page, select **Empty Ability** and click **Next**.
![01](figures/01.png)
2. In the project configuration page, set **Compile SDK** to **8** or **9** (in the latter case, you also need to set **Model** to **FA**) and **Language** to **eTS** and retain the default values for other parameters.
2. In the project configuration page, set **Compile SDK** to **8** or **9** (in the latter case, you also need to set **Model** to **FA**) and **Language** to **ArkTS** and retain the default values for other parameters.
![02](figures/02.png)
> **NOTE**
>
>
> If you are using DevEco Studio V3.0 Beta3 or later, you can use the [low-code development](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-low-code-development-0000001218440652) mode apart from the traditional coding approach.
>
>
> On the low-code development pages, you can design your application UI in an efficient, intuitive manner, with a wide array of UI editing features.
>
>
> To use the low-code development mode, turn on **Enable Super Visual** on the page shown above.
3. Click **Finish**. DevEco Studio will automatically generate the sample code and resources that match your project type. Wait until the project is created.
## eTS Project Directory Structure
## ArkTS Project Directory Structure (FA Model)
![en-us_image_0000001384652328](figures/en-us_image_0000001384652328.png)
- **entry**: OpenHarmony project module, which can be built into an OpenHarmony Ability Package ([HAP](../../glossary.md#hap)).
- **src > main > ets**: a collection of eTS source code.
......@@ -40,11 +42,11 @@
- **src > main > resources**: a collection of resource files used by your application/service, such as graphics, multimedia, character strings, and layout files. For details about resource files, see [Resource Categories and Access](resource-categories-and-access.md#resource-categories).
- **src > main > config.json**: module configuration file. This file describes the global configuration information of the application/service, the device-specific configuration information, and the configuration information of the HAP file. For details about the configuration file, see [Application Package Structure Configuration File (FA Model)](package-structure.md).
- **build-profile.json5**: current module information and build configuration options, including **buildOption** and **targets**.
- **hvigorfile.js**: module-level compilation and build task script. You can customize related tasks and code implementation.
- **hvigorfile.ts**: module-level build script. You can customize related tasks and code implementation.
- **build-profile.json5**: application-level configuration information, including the signature and product configuration.
- **hvigorfile.js**: application-level compilation and build task script.
- **hvigorfile.ts**: application-level build script.
## Building the First Page
......@@ -114,18 +116,18 @@
3. On the toolbar in the upper right corner of the editing window, click **Previewer**. Below is how the first page looks in the Previewer.
![en-us_image_0000001364254741](figures/en-us_image_0000001364254741.png)
![en-us_image_0000001311334976](figures/en-us_image_0000001311334976.png)
## Building the Second Page
1. Create the second page.
- Create the second page file: In the **Project** window, choose **entry** > **src** > **main** > **ets** > **MainAbility**. Right-click the **pages** folder, choose **New** > **eTS File**, name the page **second**, and click **Finish**. Below is the structure of the **second** folder.
- Create the second page file: In the **Project** window, choose **entry** > **src** > **main** > **ets** > **MainAbility**. Right-click the **pages** folder, choose **New** > **ArkTS File**, name the page **second**, and click **Finish**. Below is the structure of the **second** folder.
![en-us_image_0000001311334932](figures/en-us_image_0000001311334932.png)
> **NOTE**
>
> You can also right-click the **pages** folder and choose **New** > **Page** from the shortcut menu. In this scenario, you do not need to manually configure page routes.
- Configure the route for the second page, by setting **pages/second** under **module - js - pages** in the **config.json** The sample code is as follows: The sample code is as follows:
......@@ -184,7 +186,7 @@
## Implementing Page Redirection
You can implement page redirection through the [page router](../reference/apis/js-apis-router.md#routerpush), which finds the target page based on the page URL. Import the **router** module and then perform the steps below:
You can implement page redirection through the [page router](../reference/apis/js-apis-router.md), which finds the target page based on the page URL. Import the **router** module and then perform the steps below:
1. Implement redirection from the first page to the second page.
......@@ -192,6 +194,7 @@ You can implement page redirection through the [page router](../reference/apis/j
```ts
// index.ets
// Import the router module.
import router from '@ohos.router';
@Entry
......@@ -236,6 +239,7 @@ You can implement page redirection through the [page router](../reference/apis/j
```ts
// second.ets
// Import the router module.
import router from '@ohos.router';
@Entry
......@@ -273,9 +277,9 @@ You can implement page redirection through the [page router](../reference/apis/j
}
```
3. Open the **index.ets** file and click ![en-us_image_0000001311175120](figures/en-us_image_0000001311175120.png) in the Previewer to refresh the file. The display effect is shown in the figure below.
3. Open the **index.ets** file and click ![en-us_image_0000001311015192](figures/en-us_image_0000001311015192.png) in the Previewer to refresh the file. The display effect is shown in the figure below.
![en-us_image_0000001364173989](figures/en-us_image_0000001364173989.png)
![en-us_image_0000001364254729](figures/en-us_image_0000001364254729.png)
## Running the Application on a Real Device
......@@ -286,8 +290,8 @@ You can implement page redirection through the [page router](../reference/apis/j
![06](figures/06.png)
3. On the toolbar in the upper right corner of the editing window, click ![en-us_image_0000001311494580](figures/en-us_image_0000001311494580.png). The display effect is shown in the figure below.
3. On the toolbar in the upper right corner of the editing window, click ![en-us_image_0000001364054485](figures/en-us_image_0000001364054485.png). The display effect is shown in the figure below.
![en-us_image_0000001363934577](figures/en-us_image_0000001363934577.png)
![en-us_image_0000001364254729](figures/en-us_image_0000001364254729.png)
Congratulations! You have finished developing your OpenHarmony application in ArkTS in the FA model. To learn more about OpenHarmony application development, see [Application Development Overview](../application-dev-guide.md).
en/application-dev/quick-start/start-with-ets-stage.md
浏览文件 @ 672d91e1
......@@ -2,13 +2,13 @@
> **NOTE**
>
>
> To use ArkTS, your DevEco Studio must be V3.0.0.900 Beta3 or later.
>
> For best possible results, use [DevEco Studio V3.0.0.993](https://developer.harmonyos.com/cn/develop/deveco-studio#download) for your development.
>
> For best possible results, use [DevEco Studio V3.1.0.100](https://developer.harmonyos.com/cn/develop/deveco-studio) for your development.
## Creating an eTS Project
## Creating an ArkTS Project
1. If you are opening DevEco Studio for the first time, click **Create Project**. If a project is already open, choose **File** > **New** > **Create Project** from the menu bar. On the **OpenHarmony** tab of the **Choose Your Ability Template** page, select **Empty Ability** and click **Next**.
......@@ -29,36 +29,32 @@
3. Click **Finish**. DevEco Studio will automatically generate the sample code and resources that match your project type. Wait until the project is created.
## eTS Project Directory Structure
## ArkTS Project Directory Structure (Stage Model)
![en-us_image_0000001364054489](figures/en-us_image_0000001364054489.png)
- **AppScope > app.json5**: application-level configuration information.
- **entry**: OpenHarmony project module, which can be built into an OpenHarmony Ability Package ([HAP](../../glossary.md#hap)).
- **src > main > ets**: a collection of eTS source code.
- **src > main > ets > Application > AbilityStage.ts**: implementation of AbilityStage APIs.
- **src > main > ets > MainAbility**: entry to your application/service.
- **src > main > ets > MainAbility > MainAbility.ets**: ability lifecycle file.
- **src > main > ets > pages**: pages contained in **MainAbility**.
- **src > main > ets > entryability**: entry to your application/service.
- **src > main > ets > pages**: pages included in your application/service.
- **src > main > resources**: a collection of resource files used by your application/service, such as graphics, multimedia, character strings, and layout files. For details about resource files, see [Resource Categories and Access](resource-categories-and-access.md#resource-categories).
- **src > main > module.json5**: module configuration file. This file describes the global configuration information of the application/service, the device-specific configuration information, and the configuration information of the HAP file. For details about the configuration file, see [Application Package Structure Configuration File (Stage Model)](stage-structure.md).
- **build-profile.json5**: current module information and build configuration options, including **buildOption** and **targets**.
- **hvigorfile.js**: module-level compilation and build task script. You can customize related tasks and code implementation.
- **hvigorfile.ts**: module-level build script. You can customize related tasks and code implementation.
- **build-profile.json5**: application-level configuration information, including the signature and product configuration.
- **hvigorfile.js**: application-level compilation and build task script.
- **hvigorfile.ts**: application-level build script.
## Building the First Page
1. Use the **\<Text>** component.
After the project synchronization is complete, choose **entry** > **src** > **main** > **ets** > **pages** in the **Project** window and open the **index.ets** file. You can see that the file contains a **\<Text>** component. The sample code in the **index.ets** file is shown below:
After the project synchronization is complete, choose **entry** > **src** > **main** > **ets** > **pages** in the **Project** window and open the **Index.ets** file. You can see that the file contains a **\<Text>** component. The sample code in the **Index.ets** file is shown below:
```ts
// index.ets
// Index.ets
@Entry
@Component
struct Index {
......@@ -80,10 +76,10 @@
2. Add a **\<Button>** component.
On the default page, add a **\<Button>** component to respond to user clicks and implement redirection to another page. The sample code in the **index.ets** file is shown below:
On the default page, add a **\<Button>** component to respond to user clicks and implement redirection to another page. The sample code in the **Index.ets** file is shown below:
```ts
// index.ets
// Index.ets
@Entry
@Component
struct Index {
......@@ -125,29 +121,30 @@
1. Create the second page.
- Create the second page file: In the **Project** window, choose **entry** > **src** > **main** > **ets**. Right-click the **pages** folder, choose **New** > **eTS File**, name the page **second**, and click **Finish**. Below is the structure of the **second** folder.
- Create the second page file: In the **Project** window, choose **entry** > **src** > **main** > **ets**. Right-click the **pages** folder, choose **New** > **ArkTS File**, name the page **Second**, and click **Finish**. Below is the structure of the **Second** folder.
![09](figures/09.png)
> **NOTE**
>
> You can also right-click the **pages** folder and choose **New** > **Page** from the shortcut menu. In this scenario, you do not need to manually configure page routes.
- Configure the route for the second page: In the **Project** window, choose **entry** > **src** > **main** > **resources** > **base** > **profile**. In the **main_pages.json** file, set **pages/second** under **src**. The sample code is as follows:
- Configure the route for the second page: In the **Project** window, choose **entry** > **src** > **main** > **resources** > **base** > **profile**. In the **main_pages.json** file, set **pages/Second** under **src**. The sample code is as follows:
```json
{
"src": [
"pages/index",
"pages/second"
"pages/Index",
"pages/Second"
]
}
```
2. Add **\<Text>** and **\<Button>** components.
Add **\<Text>** and **\<Button>** components and set their styles, as you do for the first page. The sample code in the **second.ets** file is shown below:
Add **\<Text>** and **\<Button>** components and set their styles, by referring to the first page. The sample code in the **Second.ets** file is shown below:
```ts
// second.ets
// Second.ets
@Entry
@Component
struct Second {
......@@ -182,14 +179,15 @@
## Implementing Page Redirection
You can implement page redirection through the [page router](../reference/apis/js-apis-router.md#routerpush), which finds the target page based on the page URL. Import the **router** module and then perform the steps below:
You can implement page redirection through the [page router](../reference/apis/js-apis-router.md), which finds the target page based on the page URL. Import the **router** module and then perform the steps below:
1. Implement redirection from the first page to the second page.
In the **index.ets** file of the first page, bind the **onClick** event to the **Next** button so that clicking the button redirects the user to the second page. The sample code in the **index.ets** file is shown below:
In the **index.ets** file of the first page, bind the **onClick** event to the **Next** button so that clicking the button redirects the user to the second page. The sample code in the **Index.ets** file is shown below:
```ts
// index.ets
// Index.ets
// Import the router module.
import router from '@ohos.router';
@Entry
......@@ -218,7 +216,7 @@ You can implement page redirection through the [page router](../reference/apis/j
.height('5%')
// Bind the onClick event to the Next button so that clicking the button redirects the user to the second page.
.onClick(() => {
router.push({ url: 'pages/second' })
router.push({ url: 'pages/Second' })
})
}
.width('100%')
......@@ -230,10 +228,11 @@ You can implement page redirection through the [page router](../reference/apis/j
2. Implement redirection from the second page to the first page.
In the **second.ets** file of the second page, bind the **onClick** event to the **Back** button so that clicking the button redirects the user back to the first page. The sample code in the **second.ets** file is shown below:
In the **Second.ets** file of the second page, bind the **onClick** event to the **Back** button so that clicking the button redirects the user back to the first page. The sample code in the **Second.ets** file is shown below:
```ts
// second.ets
// Second.ets
// Import the router module.
import router from '@ohos.router';
@Entry
......@@ -271,9 +270,9 @@ You can implement page redirection through the [page router](../reference/apis/j
}
```
3. Open the **index.ets** file and click ![en-us_image_0000001311015192](figures/en-us_image_0000001311015192.png) in the Previewer to refresh the file. The display effect is shown in the figure below.
3. Open the **Index.ets** file and click ![en-us_image_0000001311015192](figures/en-us_image_0000001311015192.png) in the Previewer to refresh the file. The display effect is shown in the figure below.
![en-us_image_0000001364254773](figures/en-us_image_0000001364254773.png)
![en-us_image_0000001364254729](figures/en-us_image_0000001364254729.png)
## Running the Application on a Real Device
......@@ -286,6 +285,6 @@ You can implement page redirection through the [page router](../reference/apis/j
3. On the toolbar in the upper right corner of the editing window, click ![en-us_image_0000001364054485](figures/en-us_image_0000001364054485.png). The display effect is shown in the figure below.
![en-us_image_0000001311334972](figures/en-us_image_0000001311334972.png)
![en-us_image_0000001364254729](figures/en-us_image_0000001364254729.png)
Congratulations! You have finished developing your OpenHarmony application in ArkTS in the stage model. To learn more about OpenHarmony application development, see [Application Development Overview](../application-dev-guide.md).
en/application-dev/quick-start/start-with-js-fa.md
浏览文件 @ 672d91e1
......@@ -17,11 +17,11 @@
![04](figures/04.png)
> **NOTE**
>
>
> If you are using DevEco Studio V2.2 Beta1 or later, you can use the [low-code development](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-low-code-development-0000001218440652) mode apart from the traditional coding approach.
>
>
> On the low-code development pages, you can design your application UI in an efficient, intuitive manner, with a wide array of UI editing features.
>
>
> To use the low-code development mode, turn on **Enable Super Visual** on the page shown above.
3. Click **Finish**. DevEco Studio will automatically generate the sample code and resources that match your project type. Wait until the project is created.
......@@ -29,6 +29,8 @@
## JavaScript Project Directory Structure
![en-us_image_0000001435376433](figures/en-us_image_0000001435376433.png)
- **entry**: OpenHarmony project module, which can be built into an OpenHarmony Ability Package ([HAP](../../glossary.md#hap)).
- **src > main > js**: a collection of JavaScript source code.
- **src > main > js > MainAbility**: entry to your application/service.
......@@ -39,11 +41,11 @@
- **src > main > resources**: a collection of resource files used by your application/service, such as graphics, multimedia, character strings, and layout files. For details about resource files, see [Resource Limitations and Access](../ui/js-framework-resource-restriction.md).
- **src > main > config.json**: module configuration file. This file describes the global configuration information of the application/service, the device-specific configuration information, and the configuration information of the HAP file. For details about the configuration file, see [Application Package Structure Configuration File (FA Model)](package-structure.md).
- **build-profile.json5**: current module information and build configuration options, including **buildOption** and **targets**.
- **hvigorfile.js**: module-level compilation and build task script. You can customize related tasks and code implementation.
- **hvigorfile.ts**: module-level build script. You can customize related tasks and code implementation.
- **build-profile.json5**: application-level configuration information, including the signature and product configuration.
- **hvigorfile.js**: application-level compilation and build task script.
- **hvigorfile.ts**: application-level build script.
## Building the First Page
......@@ -177,7 +179,7 @@
## Implementing Page Redirection
You can implement page redirection through the [page router](../reference/apis/js-apis-router.md#routerpush), which finds the target page based on the page URL. Import the **router** module and then perform the steps below:
You can implement page redirection through the [page router](../reference/apis/js-apis-router.md), which finds the target page based on the page URL. Import the **router** module and then perform the steps below:
1. Implement redirection from the first page to the second page.
......@@ -185,6 +187,7 @@ You can implement page redirection through the [page router](../reference/apis/j
```js
// index.js
// Import the router module.
import router from '@ohos.router';
export default {
......@@ -202,6 +205,7 @@ You can implement page redirection through the [page router](../reference/apis/j
```js
// second.js
// Import the router module.
import router from '@ohos.router';
export default {
......@@ -211,7 +215,7 @@ You can implement page redirection through the [page router](../reference/apis/j
}
```
3. Open any file in the **index** folder and click ![en-us_image_0000001364174013](figures/en-us_image_0000001364174013.png) in the Previewer to refresh the file. The display effect is shown in the figure below.
3. Open any file in the **index** folder and click ![en-us_image_0000001311015192](figures/en-us_image_0000001311015192.png) in the Previewer to refresh the file. The display effect is shown in the figure below.
![en-us_image_0000001311175132](figures/en-us_image_0000001311175132.png)
......@@ -224,8 +228,8 @@ You can implement page redirection through the [page router](../reference/apis/j
![06](figures/06.png)
3. On the toolbar in the upper right corner of the editing window, click ![en-us_image_0000001311494604](figures/en-us_image_0000001311494604.png). The display effect is shown in the figure below.
3. On the toolbar in the upper right corner of the editing window, click ![en-us_image_0000001364054485](figures/en-us_image_0000001364054485.png). The display effect is shown in the figure below.
![en-us_image_0000001363934589](figures/en-us_image_0000001363934589.png)
![en-us_image_0000001311175132](figures/en-us_image_0000001311175132.png)
Congratulations! You have finished developing your OpenHarmony application in JavaScript in the FA model. To learn more about OpenHarmony application development, see [Application Development Overview](../application-dev-guide.md).
en/application-dev/reference/arkui-ts/ts-appendix-enums.md
浏览文件 @ 672d91e1
# Built-in Enums
# Enums
## Color
| Color | Value | Illustration |
| ------------------------ | ------------- | ---------------------------------------- |
| Black | 0x000000 | ![en-us_image_0000001219864153](figures/en-us_image_0000001219864153.png) |
| Blue | 0x0000ff | ![en-us_image_0000001174104404](figures/en-us_image_0000001174104404.png) |
| Brown | 0xa52a2a | ![en-us_image_0000001219744201](figures/en-us_image_0000001219744201.png) |
| Gray | 0x808080 | ![en-us_image_0000001174264376](figures/en-us_image_0000001174264376.png) |
| Grey | 0x808080 | ![en-us_image_0000001174264376](figures/en-us_image_0000001174264376.png) |
| Green | 0x008000 | ![en-us_image_0000001174422914](figures/en-us_image_0000001174422914.png) |
| Orange | 0xffa500 | ![en-us_image_0000001219662661](figures/en-us_image_0000001219662661.png) |
| Pink | 0xffc0cb | ![en-us_image_0000001219662663](figures/en-us_image_0000001219662663.png) |
| Red | 0xff0000 | ![en-us_image_0000001219662665](figures/en-us_image_0000001219662665.png) |
| White | 0xffffff | ![en-us_image_0000001174582866](figures/en-us_image_0000001174582866.png) |
| Yellow | 0xffff00 | ![en-us_image_0000001174582864](figures/en-us_image_0000001174582864.png) |
| Transparent<sup>9+</sup> | rgba(0,0,0,0) | Transparent |
| Color | Value | Illustration |
| ------------------------ | -------- | ------------------------------------------------------------ |
| Black | 0x000000 | ![en-us_image_0000001219864153](figures/en-us_image_0000001219864153.png) |
| Blue | 0x0000ff | ![en-us_image_0000001174104404](figures/en-us_image_0000001174104404.png) |
| Brown | 0xa52a2a | ![en-us_image_0000001219744201](figures/en-us_image_0000001219744201.png) |
| Gray | 0x808080 | ![en-us_image_0000001174264376](figures/en-us_image_0000001174264376.png) |
| Grey | 0x808080 | ![en-us_image_0000001174264376](figures/en-us_image_0000001174264376.png) |
| Green | 0x008000 | ![en-us_image_0000001174422914](figures/en-us_image_0000001174422914.png) |
| Orange | 0xffa500 | ![en-us_image_0000001219662661](figures/en-us_image_0000001219662661.png) |
| Pink | 0xffc0cb | ![en-us_image_0000001219662663](figures/en-us_image_0000001219662663.png) |
| Red | 0xff0000 | ![en-us_image_0000001219662665](figures/en-us_image_0000001219662665.png) |
| White | 0xffffff | ![en-us_image_0000001174582866](figures/en-us_image_0000001174582866.png) |
| Yellow | 0xffff00 | ![en-us_image_0000001174582864](figures/en-us_image_0000001174582864.png) |
| Transparent<sup>9+</sup> | rgba(0,0,0,0) | Transparent |
## ImageFit
| Name | Description |
| --------- | ---------------------------------------- |
| Contain | The image is scaled with its aspect ratio retained for the content to be completely displayed within the display boundaries. |
| Cover | The image is scaled with its aspect ratio retained for both sides to be greater than or equal to the display boundaries. |
| Auto | The image is scaled automatically to fit the display area. |
| Fill | The image is scaled to fill the display area, and its aspect ratio is not retained. |
| ScaleDown | The image is displayed with its aspect ratio retained, in a size smaller than or equal to the original size. |
| None | The original size is retained. |
| Name | Description |
| --------- | ------------------------------------------------------------ |
| Contain | The image is scaled with its aspect ratio retained for the content to be completely displayed within the display boundaries. |
| Cover | The image is scaled with its aspect ratio retained for both sides to be greater than or equal to the display boundaries.|
| Auto | The image is scaled automatically to fit the display area. |
| Fill | The image is scaled to fill the display area, and its aspect ratio is not retained. |
| ScaleDown | The image is displayed with its aspect ratio retained, in a size smaller than or equal to the original size. |
| None | The original size is retained. |
## BorderStyle
| Name | Description |
| ------ | ---------------------------------------- |
| Dotted | Dotted border. The radius of a dot is half of **borderWidth**. |
| Dashed | Dashed border. |
| Solid | Solid border. |
| Name | Description |
| ------ | ----------------------------------------------- |
| Dotted | Dotted border. The radius of a dot is half of **borderWidth**.|
| Dashed | Dashed border. |
| Solid | Solid border. |
## LineJoinStyle
| Name | Description |
| ----- | ------------------------------- |
| Bevel | Bevel is used to connect paths. |
| Miter | Miter is used to connect paths. |
| Round | Round is used to connect paths. |
| Name | Description |
| ----- | -------------------- |
| Bevel | Bevel is used to connect paths.|
| Miter | Miter is used to connect paths.|
| Round | Round is used to connect paths.|
## TouchType
| Name | Description |
| ------ | ---------------------------------------- |
| Down | A finger is pressed. |
| Up | A finger is lifted. |
| Move | A finger moves on the screen in pressed state. |
| Cancel | A touch event is canceled. |
| Name | Description |
| ------ | ------------------------------ |
| Down | A finger is pressed. |
| Up | A finger is lifted. |
| Move | A finger moves on the screen in pressed state.|
| Cancel | A touch event is canceled. |
## MouseButton
| Name | Description |
| ------- | ---------------------------------------- |
| Left | Left button on the mouse. |
| Right | Right button on the mouse. |
| Middle | Middle button on the mouse. |
| Back | Back button on the left of the mouse. |
| Forward | Forward button on the left of the mouse. |
| None | No button. |
| Name | Description |
| ------- | ---------------- |
| Left | Left button on the mouse. |
| Right | Right button on the mouse. |
| Middle | Middle button on the mouse. |
| Back | Back button on the left of the mouse.|
| Forward | Forward button on the left of the mouse.|
| None | No button. |
## MouseAction
| Name | Description |
| ------- | ---------------------------------------- |
| Press | The mouse button is pressed. |
| Release | The mouse button is released. |
| Move | The mouse cursor moves. |
| Hover | The mouse pointer is hovered on an element. |
| Name | Description |
| ------- | -------------- |
| Press | The mouse button is pressed.|
| Release | The mouse button is released.|
| Move | The mouse cursor moves. |
| Hover | The mouse pointer is hovered on an element. |
## Curve
| Name | Description |
| ------------------- | ---------------------------------------- |
| Linear | The animation speed keeps unchanged. |
| Ease | The animation starts slowly, accelerates, and then slows down towards the end. The cubic-bezier curve (0.25, 0.1, 0.25, 1.0) is used. |
| EaseIn | The animation starts at a low speed and then picks up speed until the end. The cubic-bezier curve (0.42, 0.0, 1.0, 1.0) is used. |
| EaseOut | The animation ends at a low speed. The cubic-bezier curve (0.0, 0.0, 0.58, 1.0) is used. |
| EaseInOut | The animation starts and ends at a low speed. The cubic-bezier curve (0.42, 0.0, 0.58, 1.0) is used. |
| FastOutSlowIn | The animation uses the standard cubic-bezier curve (0.4, 0.0, 0.2, 1.0). |
| LinearOutSlowIn | The animation uses the deceleration cubic-bezier curve (0.0, 0.0, 0.2, 1.0). |
| FastOutLinearIn | The animation uses the acceleration cubic-bezier curve (0.4, 0.0, 1.0, 1.0). |
| ExtremeDeceleration | The animation uses the extreme deceleration cubic-bezier curve (0.0, 0.0, 0.0, 1.0). |
| Sharp | The animation uses the sharp cubic-bezier curve (0.33, 0.0, 0.67, 1.0). |
| Rhythm | The animation uses the rhythm cubic-bezier curve (0.7, 0.0, 0.2, 1.0). |
| Smooth | The animation uses the smooth cubic-bezier curve (0.4, 0.0, 0.4, 1.0). |
| Friction | The animation uses the friction cubic-bezier curve (0.2, 0.0, 0.2, 1.0). |
| Name | Description |
| ------------------- | ------------------------------------------------------------ |
| Linear | The animation speed keeps unchanged. |
| Ease | The animation starts slowly, accelerates, and then slows down towards the end. The cubic-bezier curve (0.25, 0.1, 0.25, 1.0) is used.|
| EaseIn | The animation starts at a low speed and then picks up speed until the end. The cubic-bezier curve (0.42, 0.0, 1.0, 1.0) is used. |
| EaseOut | The animation ends at a low speed. The cubic-bezier curve (0.0, 0.0, 0.58, 1.0) is used. |
| EaseInOut | The animation starts and ends at a low speed. The cubic-bezier curve (0.42, 0.0, 0.58, 1.0) is used.|
| FastOutSlowIn | The animation uses the standard cubic-bezier curve (0.4, 0.0, 0.2, 1.0). |
| LinearOutSlowIn | The animation uses the deceleration cubic-bezier curve (0.0, 0.0, 0.2, 1.0). |
| FastOutLinearIn | The animation uses the acceleration cubic-bezier curve (0.4, 0.0, 1.0, 1.0). |
| ExtremeDeceleration | The animation uses the extreme deceleration cubic-bezier curve (0.0, 0.0, 0.0, 1.0). |
| Sharp | The animation uses the sharp cubic-bezier curve (0.33, 0.0, 0.67, 1.0). |
| Rhythm | The animation uses the rhythm cubic-bezier curve (0.7, 0.0, 0.2, 1.0). |
| Smooth | The animation uses the smooth cubic-bezier curve (0.4, 0.0, 0.4, 1.0). |
| Friction | The animation uses the friction cubic-bezier curve (0.2, 0.0, 0.2, 1.0). |
## AnimationStatus
| Name | Description |
| ------- | -------------------------------------- |
| Initial | The animation is in the initial state. |
| Running | The animation is being played. |
| Paused | The animation is paused. |
| Stopped | The animation is stopped. |
| Name | Description |
| ------- | ------------------ |
| Initial | The animation is in the initial state. |
| Running | The animation is being played.|
| Paused | The animation is paused.|
| Stopped | The animation is stopped.|
## FillMode
| Name | Description |
| --------- | ---------------------------------------- |
| None | Before execution, the animation does not apply any styles to the target component. After execution, the animation restores the target component to its default state. |
| Forwards | The target component retains the state set by the last keyframe encountered during execution of the animation. |
| Backwards | The animation applies the values defined in the first relevant keyframe once it is applied to the target component, and retains the values during the period set by **delay**. The first relevant keyframe depends on the value of **playMode**. If **playMode** is **Normal** or **Alternate**, the first relevant keyframe is in the **from** state. If **playMode** is **Reverse** or **AlternateReverse**, the first relevant keyframe is in the **to** state. |
| Both | The animation follows the rules for both **Forwards** and **Backwards**, extending the animation attributes in both directions. |
| Name | Description |
| --------- | ------------------------------------------------------------ |
| None | Before execution, the animation does not apply any styles to the target component. After execution, the animation restores the target component to its default state.|
| Forwards | The target component retains the state set by the last keyframe encountered during execution of the animation. |
| Backwards | The animation applies the values defined in the first relevant keyframe once it is applied to the target component, and retains the values during the period set by **delay**. The first relevant keyframe depends on the value of **playMode**. If **playMode** is **Normal** or **Alternate**, the first relevant keyframe is in the **from** state. If **playMode** is **Reverse** or **AlternateReverse**, the first relevant keyframe is in the **to** state.|
| Both | The animation follows the rules for both **Forwards** and **Backwards**, extending the animation attributes in both directions.|
## PlayMode
| Name | Description |
| ---------------- | ---------------------------------------- |
| Normal | The animation is played forwards. |
| Reverse | The animation is played backwards. |
| Alternate | The animation is played forwards for an odd number of times (1, 3, 5...) and backwards for an even number of times (2, 4, 6...). |
| AlternateReverse | The animation is played backwards for an odd number of times (1, 3, 5...) and forwards for an even number of times (2, 4, 6...). |
| Name | Description |
| ---------------- | ------------------------------------------------------------ |
| Normal | The animation is played forwards. |
| Reverse | The animation is played backwards. |
| Alternate | The animation is played forwards for an odd number of times (1, 3, 5...) and backwards for an even number of times (2, 4, 6...).|
| AlternateReverse | The animation is played backwards for an odd number of times (1, 3, 5...) and forwards for an even number of times (2, 4, 6...).|
## KeyType
| Name | Description |
| ---- | -------------------- |
| Down | The key is pressed. |
| Up | The key is released. |
| Name| Description |
| ---- | ---------- |
| Down | The key is pressed.|
| Up | The key is released.|
## KeySource
| Name | Description |
| -------- | ------------------------------- |
| Unknown | Unknown input device. |
| Keyboard | The input device is a keyboard. |
| Name | Description |
| -------- | -------------------- |
| Unknown | Unknown input device. |
| Keyboard | The input device is a keyboard.|
## Edge
| Name | Description |
| -------------------------------- | ---------------------------------------- |
| Top | Top edge in the vertical direction. |
| Center<sup>(deprecated) </sup> | Center position in the vertical direction.<br>This API is deprecated since API version 9. |
| Bottom | Bottom edge in the vertical direction. |
| Baseline<sup>(deprecated) </sup> | Text baseline position in the cross axis direction.<br>This API is deprecated since API version 9. |
| Start | Start position in the horizontal direction. |
| Middle<sup>(deprecated) </sup> | Center position in the horizontal direction.<br>This API is deprecated since API version 9. |
| End | End position in the horizontal direction. |
| Name | Description |
| -------- | ---------------------- |
| Top | Top edge in the vertical direction. |
| Center<sup>(deprecated) </sup> | Center position in the vertical direction.<br> This API is deprecated since API version 9. |
| Bottom | Bottom edge in the vertical direction. |
| Baseline<sup>(deprecated) </sup> | Text baseline position in the cross axis direction.<br> This API is deprecated since API version 9.|
| Start | Start position in the horizontal direction. |
| Middle<sup>(deprecated) </sup> | Center position in the horizontal direction.<br> This API is deprecated since API version 9. |
| End | End position in the horizontal direction. |
## Week
| Name | Description |
| ---- | ----------- |
| Mon | Monday. |
| Tue | Tuesday. |
| Wed | Wednesday. |
| Thur | Thursday. |
| Fri | Friday. |
| Sat | Saturday. |
| Sun | Sunday. |
| Name | Description |
| -------- | ---------------------- |
| Mon | Monday. |
| Tue | Tuesday. |
| Wed | Wednesday. |
| Thur | Thursday. |
| Fri | Friday. |
| Sat | Saturday. |
| Sun | Sunday. |
## Direction
| Name | Description |
| ---- | ---------------------------------------- |
| Ltr | Components are arranged from left to right. |
| Rtl | Components are arranged from right to left. |
| Auto | The default layout direction is used. |
| Name| Description |
| ---- | ---------------------- |
| Ltr | Components are arranged from left to right. |
| Rtl | Components are arranged from right to left. |
| Auto | The default layout direction is used.|
## BarState
| Name | Description |
| ---- | ---------------------------------------- |
| Off | Not displayed. |
| On | Always displayed. |
| Auto | Displayed when the screen is touched and hidden after 2s. |
| Name| Description |
| ---- | -------------------------------- |
| Off | Not displayed. |
| On | Always displayed. |
| Auto | Displayed when the screen is touched and hidden after 2s.|
## EdgeEffect
| Name | Description |
| ------ | ---------------------------------------- |
| Spring | Spring effect. When at one of the edges, the component can move beyond the bounds through touches, and produces a bounce effect when the user releases their finger. |
| Fade | Fade effect. When at one of the edges, the component produces a fade effect. |
| None | No effect when the component is at one of the edges. |
| Name | Description |
| ------ | ------------------------------------------------------------ |
| Spring | Spring effect. When at one of the edges, the component can move beyond the bounds through touches, and produces a bounce effect when the user releases their finger.|
| Fade | Fade effect. When at one of the edges, the component produces a fade effect. |
| None | No effect when the component is at one of the edges. |
## Alignment
| Name | Description |
| ----------- | ------------------------------------- |
| TopStart | Top start. |
| Top | Horizontally centered on the top. |
| TopEnd | Top end. |
| Start | Vertically centered start. |
| Center | Horizontally and vertically centered. |
| End | Vertically centered end. |
| BottomStart | Bottom start. |
| Name | Description |
| ----------- | ---------------- |
| TopStart | Top start. |
| Top | Horizontally centered on the top. |
| TopEnd | Top end. |
| Start | Vertically centered start.|
| Center | Horizontally and vertically centered.|
| End | Vertically centered end. |
| BottomStart | Bottom start. |
| Bottom | Horizontally centered on the bottom. |
| BottomEnd | Bottom end. |
| BottomEnd | Bottom end. |
## TransitionType
| Name | Description |
| ------ | ---------------------------------------- |
| All | The transition takes effect in all scenarios. |
| Insert | The transition takes effect when a component is inserted. |
| Delete | The transition takes effect when a component is deleted. |
| Name | Description |
| ------ | -------------------------------------------------- |
| All | The transition takes effect in all scenarios.|
| Insert | The transition takes effect when a component is inserted. |
| Delete | The transition takes effect when a component is deleted. |
## RelateType
| Name | Description |
| ---- | ---------------------------------------- |
| FILL | The current child component is scaled to fill the parent component. |
| FIT | The current child component is scaled to adapt to the parent component. |
| Name | Description |
| ------ | ------------------------------- |
| FILL | The current child component is scaled to fill the parent component. |
| FIT | The current child component is scaled to adapt to the parent component. |
## Visibility
| Name | Description |
| ------- | ---------------------------------------- |
| Hidden | The component is hidden, and a placeholder is used for it in the layout. |
| Visible | The component is visible. |
| None | The component is hidden. It is not involved in the layout, and no placeholder is used for it. |
| Name | Description |
| ------- | -------------------------------- |
| Hidden | The component is hidden, and a placeholder is used for it in the layout. |
| Visible | The component is visible. |
| None | The component is hidden. It is not involved in the layout, and no placeholder is used for it.|
## LineCapStyle
| Name | Description |
| ------ | ---------------------------------------- |
| Butt | The ends of the line are squared off, and the line does not extend beyond its two endpoints. |
| Round | The line is extended at the endpoints by a half circle whose diameter is equal to the line width. |
| Square | The line is extended at the endpoints by a rectangle whose width is equal to half the line width and height equal to the line width. |
| Name | Description |
| ------ | -------------------- |
| Butt | The ends of the line are squared off, and the line does not extend beyond its two endpoints.|
| Round | The line is extended at the endpoints by a half circle whose diameter is equal to the line width.|
| Square | The line is extended at the endpoints by a rectangle whose width is equal to half the line width and height equal to the line width.|
## Axis
| Name | Description |
| ---------- | --------------------- |
| Vertical | Vertical direction. |
| Horizontal | Horizontal direction. |
| Name | Description |
| ---------- | ------------ |
| Vertical | Vertical direction.|
| Horizontal | Horizontal direction.|
## HorizontalAlign
| Name | Description |
| ------ | ---------------------------------------- |
| Start | Aligned with the start edge in the same direction as the language in use. |
| Center | Aligned with the center. This is the default alignment mode. |
| End | Aligned with the end edge in the same direction as the language in use. |
| Name | Description |
| ------ | ------------------------ |
| Start | Aligned with the start edge in the same direction as the language in use.|
| Center | Aligned with the center. This is the default alignment mode.|
| End | Aligned with the end edge in the same direction as the language in use. |
## FlexAlign
| Name | Description |
| ------------ | ---------------------------------------- |
| Start | The child components are aligned with the start edge of the main axis. The first component is aligned with the main-start, and subsequent components are aligned with the previous one. |
| Center | The child components are aligned in the center of the main axis. The space between the first component and the main-start is the same as that between the last component and the main-end. |
| End | The child components are aligned with the end edge of the main axis. The last component is aligned with the main-end, and other components are aligned with the next one. |
| SpaceBetween | The child components are evenly distributed along the main axis. The space between any two adjacent components is the same. The first component is aligned with the main-start, the last component is aligned with the main-end, and the remaining components are distributed so that the space between any two adjacent components is the same. |
| SpaceAround | The child components are evenly distributed along the main axis. The space between any two adjacent components is the same. The space between the first component and main-start, and that between the last component and cross-main are both half the size of the space between two adjacent components. |
| SpaceEvenly | The child components are evenly distributed along the main axis. The space between the first component and main-start, the space between the last component and main-end, and the space between any two adjacent components are the same. |
| Name | Description |
| ------------ | ------------------------------------------------------------ |
| Start | The child components are aligned with the start edge of the main axis. The first component is aligned with the main-start, and subsequent components are aligned with the previous one.|
| Center | The child components are aligned in the center of the main axis. The space between the first component and the main-start is the same as that between the last component and the main-end.|
| End | The child components are aligned with the end edge of the main axis. The last component is aligned with the main-end, and other components are aligned with the next one.|
| SpaceBetween | The child components are evenly distributed along the main axis. The space between any two adjacent components is the same. The first component is aligned with the main-start, the last component is aligned with the main-end, and the remaining components are distributed so that the space between any two adjacent components is the same.|
| SpaceAround | The child components are evenly distributed along the main axis. The space between any two adjacent components is the same. The space between the first component and main-start, and that between the last component and cross-main are both half the size of the space between two adjacent components.|
| SpaceEvenly | The child components are evenly distributed along the main axis. The space between the first component and main-start, the space between the last component and main-end, and the space between any two adjacent components are the same.|
## ItemAlign
| Name | Description |
| -------- | ---------------------------------------- |
| Auto | The default configuration in the flex container is used. |
| Start | The elements are in the flex container, top-aligned in the cross-axis direction. |
| Center | The elements are in the flex container, centered in the cross-axis direction. |
| End | The elements are in the flex container, bottom-aligned in the cross-axis direction. |
| Stretch | The elements are in the flex container, stretched and padded in the cross-axis direction. If the size is not set, the elements are stretched to the container size. |
| Baseline | The elements are in the flex container, text baseline aligned in the cross-axis direction. |
| Name | Description |
| -------- | ------------------------------------------------------------ |
| Auto | The default configuration in the flex container is used. |
| Start | The elements are in the flex container, top-aligned in the cross-axis direction. |
| Center | The elements are in the flex container, centered in the cross-axis direction. |
| End | The elements are in the flex container, bottom-aligned in the cross-axis direction. |
| Stretch | The elements are in the flex container, stretched and padded in the cross-axis direction. If the size is not set, the elements are stretched to the container size.|
| Baseline | The elements are in the flex container, text baseline aligned in the cross-axis direction. |
## FlexDirection
| Name | Description |
| ------------- | ---------------------------------------- |
| Row | The child components are arranged in the same direction as the main axis runs along the rows. |
| RowReverse | The child components are arranged opposite to the **Row** direction. |
| Column | The child components are arranged in the same direction as the main axis runs down the columns. |
| ColumnReverse | The child components are arranged opposite to the **Column** direction. |
| Name | Description |
| ------------- | ------------------------------ |
| Row | The child components are arranged in the same direction as the main axis runs along the rows.|
| RowReverse | The child components are arranged opposite to the **Row** direction. |
| Column | The child components are arranged in the same direction as the main axis runs down the columns.|
| ColumnReverse | The child components are arranged opposite to the **Column** direction. |
## FlexWrap
| Name | Description |
| ----------- | ---------------------------------------- |
| NoWrap | The child components in the flex container are arranged in a single line, and they cannot overflow. |
| Wrap | The child components in the flex container are arranged in multiple lines, and they may overflow. |
| WrapReverse | The child components in the flex container are reversely arranged in multiple lines, and they may overflow. |
| Name | Description |
| ----------- | ------------------------------------------------- |
| NoWrap | The child components in the flex container are arranged in a single line, and they cannot overflow. |
| Wrap | The child components in the flex container are arranged in multiple lines, and they may overflow. |
| WrapReverse | The child components in the flex container are reversely arranged in multiple lines, and they may overflow.|
## VerticalAlign
| Name | Description |
| ------ | ---------------------------------------- |
| Top | Top aligned. |
| Center | Center aligned. This is the default alignment mode. |
| Bottom | Bottom aligned. |
| Name | Description |
| ------ | ------------------------ |
| Top | Top aligned. |
| Center | Center aligned. This is the default alignment mode.|
| Bottom | Bottom aligned. |
## ImageRepeat
| Name | Description |
| -------- | ---------------------------------------- |
| X | The image is repeatedly drawn only along the horizontal axis. |
| Y | The image is repeatedly drawn only along the vertical axis. |
| XY | The image is repeatedly drawn along both axes. |
| NoRepeat | The image is not repeatedly drawn. |
| Name | Description |
| -------- | -------------------------- |
| X | The image is repeatedly drawn only along the horizontal axis.|
| Y | The image is repeatedly drawn only along the vertical axis.|
| XY | The image is repeatedly drawn along both axes. |
| NoRepeat | The image is not repeatedly drawn. |
## ImageSize
| Type | Description |
| ------- | ---------------------------------------- |
| Cover | Default value. The image is scaled with its aspect ratio retained for both sides to be greater than or equal to the display boundaries. |
| Contain | The image is scaled with its aspect ratio retained for the content to be completely displayed within the display boundaries. |
| Auto | The original image aspect ratio is retained. |
| Type | Description |
| ------- | ------------------------------------------------------------ |
| Cover | Default value. The image is scaled with its aspect ratio retained for both sides to be greater than or equal to the display boundaries.|
| Contain | The image is scaled with its aspect ratio retained for the content to be completely displayed within the display boundaries. |
| Auto | The original image aspect ratio is retained. |
## GradientDirection
| Name | Description |
| ----------- | ---------------------------------------- |
| Left | The gradient direction is from right to left. |
| Top | The gradient direction is from bottom to top. |
| Right | The gradient direction is from left to right. |
| Bottom | The gradient direction is from top to bottom. |
| Name | Description |
| ----------- | ---------- |
| Left | The gradient direction is from right to left.|
| Top | The gradient direction is from bottom to top.|
| Right | The gradient direction is from left to right.|
| Bottom | The gradient direction is from top to bottom.|
| LeftTop | The gradient direction is upper left. |
| LeftBottom | The gradient direction is lower left. |
| RightTop | The gradient direction is upper right. |
| RightBottom | The gradient direction is lower right. |
| None | No gradient. |
| RightTop | The gradient direction is upper right. |
| RightBottom | The gradient direction is lower right. |
| None | No gradient. |
## SharedTransitionEffectType
| Name | Description |
| -------- | ---------------------------------------- |
| Static | The element position remains unchanged on the target page, and transition opacity can be configured. Currently, this effect is only valid in redirecting to the target page. |
| Exchange | The element is relocated and scaled properly on the target page. |
| Name | Description |
| ----------- | ---------- |
| Static | The element position remains unchanged on the target page, and transition opacity can be configured. Currently, this effect is only valid in redirecting to the target page.|
| Exchange | The element is relocated and scaled properly on the target page.|
## FontStyle
| Name | Description |
| ------ | -------------------- |
| Normal | Standard font style. |
| Italic | Italic font style. |
| Name | Description |
| ------ | ---------------- |
| Normal | Standard font style.|
| Italic | Italic font style.|
## FontWeight
| Name | Description |
| ------- | --------------------------- |
| Lighter | The font weight is lighter. |
| Normal | The font weight is normal. |
| Regular | The font weight is regular. |
| Medium | The font weight is medium. |
| Name | Description |
| ------- | -------------- |
| Lighter | The font weight is lighter. |
| Normal | The font weight is normal.|
| Regular | The font weight is regular.|
| Medium | The font weight is medium.|
| Bold | The font weight is bold. |
| Bolder | The font weight is bolder. |
## TextAlign
| Name | Description |
| ------ | ----------------------- |
| Start | Aligned with the start. |
| Center | Horizontally centered. |
| End | Aligned with the end. |
| Name | Description |
| ------ | -------------- |
| Start | Aligned with the start.|
| Center | Horizontally centered.|
| End | Aligned with the end.|
## TextOverflow
| Name | Description |
| -------- | ---------------------------------------- |
| Name | Description |
| -------- | -------------------------------------- |
| Clip | Extra-long text is clipped. |
| Ellipsis | An ellipsis (...) is used to represent clipped text. |
| None | No clipping or ellipsis is used for extra-long text. |
| Ellipsis | An ellipsis (...) is used to represent clipped text.|
| None | No clipping or ellipsis is used for extra-long text. |
## TextDecorationType
| Name | Description |
| ----------- | ---------------------- |
| Underline | Line under the text. |
| LineThrough | Line through the text. |
| Overline | Line over the text. |
| None | No decorative lines. |
| Name | Description |
| ----------- | ------------------ |
| Underline | Line under the text. |
| LineThrough | Line through the text.|
| Overline | Line over the text. |
| None | No decorative lines.|
## TextCase
| Name | Description |
| --------- | ---------------------------------------- |
| Normal | The original case of the text is retained. |
| LowerCase | All letters in the text are in lowercase. |
| UpperCase | All letters in the text are in uppercase. |
| Name | Description |
| --------- | -------------------- |
| Normal | The original case of the text is retained.|
| LowerCase | All letters in the text are in lowercase. |
| UpperCase | All letters in the text are in uppercase. |
## ResponseType<sup>8+</sup>
| Name | Description |
| ---------- | ---------------------------------------- |
| LongPress | The menu is displayed when the component is long-pressed. |
| RightClick | The menu is displayed when the component is right-clicked. |
| Name | Description |
| ---------- | -------------------------- |
| LongPress | The menu is displayed when the component is long-pressed. |
| RightClick | The menu is displayed when the component is right-clicked.|
## HoverEffect<sup>8+</sup>
| Name | Description |
| --------- | --------------------------------------- |
| Auto | Default hover effect. |
| Scale | Scale effect. |
| Highlight | Background fade-in and fade-out effect. |
| None | No effect. |
| Name | Description |
| --------- | ---------------------------- |
| Auto | Default hover effect.|
| Scale | Scale effect. |
| Highlight | Background fade-in and fade-out effect. |
| None | No effect. |
## Placement<sup>8+</sup>
| Name | Description |
| ------------- | ---------------------------------------- |
| Left | The popup is on the left of the component, vertically aligned with the component on the left. |
| Right | The popup is on the right of the component, vertically aligned with the component on the right. |
| Top | The popup is at the top of the component, horizontally aligned with the component at the top. |
| Bottom | The popup is at the bottom of the component, horizontally aligned with the component at the bottom. |
| TopLeft | The popup is at the top of the component and, since API version 9, aligned with the left of the component. |
| TopRight | The popup is at the top of the component and, since API version 9, aligned with the right of the component. |
| BottomLeft | The popup is at the bottom of the component and, since API version 9, aligned with the left of the component. |
| BottomRight | The popup is at the bottom of the component and, since API version 9, aligned with the right of the component. |
| LeftTop9+ | The popup is on the left of the component and aligned with the top of the component. |
| LeftBottom9+ | The popup is on the left of the component and aligned with the bottom of the component. |
| RightTop9+ | The popup is on the right of the component and aligned with the top of the component. |
| RightBottom9+ | The popup is on the right of the component and aligned with the bottom of the component. |
| Name | Description |
| ------------- | ------------------------------------------------------------ |
| Left | The popup is on the left of the component, vertically aligned with the component on the left. |
| Right | The popup is on the right of the component, vertically aligned with the component on the right. |
| Top | The popup is at the top of the component, horizontally aligned with the component at the top. |
| Bottom | The popup is at the bottom of the component, horizontally aligned with the component at the bottom. |
| TopLeft | The popup is at the top of the component and, since API version 9, aligned with the left of the component.|
| TopRight | The popup is at the top of the component and, since API version 9, aligned with the right of the component.|
| BottomLeft | The popup is at the bottom of the component and, since API version 9, aligned with the left of the component.|
| BottomRight | The popup is at the bottom of the component and, since API version 9, aligned with the right of the component.|
| LeftTop9+ | The popup is on the left of the component and aligned with the top of the component. |
| LeftBottom9+ | The popup is on the left of the component and aligned with the bottom of the component. |
| RightTop9+ | The popup is on the right of the component and aligned with the top of the component. |
| RightBottom9+ | The popup is on the right of the component and aligned with the bottom of the component. |
## CopyOptions<sup>9+</sup>
| Name | Description |
| ----------- | ---------------------------------- |
| None | Copy is not allowed. |
| InApp | Intra-application copy is allowed. |
| LocalDevice | Intra-device copy is allowed. |
| Name | Description |
| ----------- | -------------------- |
| None | Copy is not allowed. |
| InApp | Intra-application copy is allowed.|
| LocalDevice | Intra-device copy is allowed.|
## HitTestMode<sup>9+</sup>
| Name | Description |
| ----------- | ---------------------------------------- |
| Default | Both the node and its child node respond to the hit test of a touch event, but its sibling node is blocked from the hit test. |
| Block | The node responds to the hit test of a touch event, but its child node and sibling node are blocked from the hit test. |
| Transparent | Both the node and its child node respond to the hit test of a touch event, and its sibling node is also considered during the hit test. |
| None | The node does not respond to the hit test of a touch event, but its child node and sibling node are considered during the hit test. |
| Name | Description |
| ----------- | -------------------- |
| Default | Both the node and its child node respond to the hit test of a touch event, but its sibling node is blocked from the hit test. |
| Block | The node responds to the hit test of a touch event, but its child node and sibling node are blocked from the hit test. |
| Transparent | Both the node and its child node respond to the hit test of a touch event, and its sibling node is also considered during the hit test.|
| None | The node does not respond to the hit test of a touch event, but its child node and sibling node are considered during the hit test.|
en/application-dev/reference/arkui-ts/ts-container-grid.md
浏览文件 @ 672d91e1
......@@ -27,26 +27,46 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
| Name| Type| Description|
| -------- | -------- | -------- |
| columnsTemplate | string | Number of columns in the current grid layout. If this attribute is not set, one column is used by default.<br>For example, **'1fr 1fr 2fr'** indicates three columns, with the first column taking up 1/4 of the parent component's full width, the second column 1/4, and the third column 2/4. This attribute supports [auto-fill] (#auto-fill description).<br>Default value: **'1fr'**|
| rowsTemplate | string | Number of rows in the current grid layout. If this attribute is not set, one row is used by default.<br>For example, **'1fr 1fr 2fr'** indicates three rows, with the first row taking up 1/4 of the parent component's full height, the second row 1/4, and the third row 2/4. This attribute supports [auto-fill] (#auto-fill description).<br>Default value: **'1fr'**|
| columnsTemplate | string | Number of columns in the current grid layout. If this attribute is not set, one column is used by default.<br>For example, **'1fr 1fr 2fr'** indicates three columns, with the first column taking up 1/4 of the parent component's full width, the second column 1/4, and the third column 2/4.|
| rowsTemplate | string | Number of rows in the current grid layout. If this attribute is not set, one row is used by default.<br>For example, **'1fr 1fr 2fr'** indicates three rows, with the first row taking up 1/4 of the parent component's full height, the second row 1/4, and the third row 2/4.|
| columnsGap | Length | Gap between columns.<br>Default value: **0**|
| rowsGap | Length | Gap between rows.<br>Default value: **0**|
| scrollBar | [BarState](ts-appendix-enums.md#barstate) | Scrollbar status.<br>Default value: **BarState.Off**|
| scrollBarColor | string \| number \| Color | Color of the scrollbar.|
| scrollBarWidth | string \| number | Width of the scrollbar.|
| cachedCount | number | Number of grid items to be preloaded. For details, see [Minimizing White Blocks During Swiping](../../ui/ts-performance-improvement-recommendation.md#minimizing-white-blocks-during-swiping).<br>Default value: **1**|
| cachedCount | number | Number of grid items to be preloaded. For details, see [Minimizing White Blocks During Swiping](../../ui/ui-ts-performance-improvement-recommendation.md#minimizing-white-blocks-during-swiping).<br>Default value: **1**|
| editMode <sup>8+</sup> | boolean | Whether to enter editing mode. In editing mode, the user can drag the **\<[GridItem](ts-container-griditem.md)>** in the **\<Grid>** component.<br>Default value: **false**|
| layoutDirection<sup>8+</sup> | [GridDirection](#griddirection8) | Main axis direction of the grid.<br>Default value: **GridDirection.Row**|
| maxCount<sup>8+</sup> | number | When **layoutDirection** is **Row** or **RowReverse**: maximum number of rows that can be displayed.<br>When **layoutDirection** is **Column** or **ColumnReverse**: maximum number of columns that can be displayed.<br>Default value: **1**|
| minCount<sup>8+</sup> | number | When **layoutDirection** is **Row** or **RowReverse**: minimum number of rows that can be displayed.<br>When **layoutDirection** is **Column** or **ColumnReverse**: minimum number of columns that can be displayed.<br>Default value: **1**|
| cellLength<sup>8+</sup> | number | When **layoutDirection** is **Row** or **RowReverse**: fixed height per row.<br>When **layoutDirection** is **Column** or **ColumnReverse**: fixed width per column.<br>Default value: **0**|
| maxCount<sup>8+</sup> | number | When **layoutDirection** is **Row** or **RowReverse**: maximum number of columns that can be displayed.<br>When **layoutDirection** is **Column** or **ColumnReverse**: maximum number of rows that can be displayed.<br>Default value: **Infinity**|
| minCount<sup>8+</sup> | number | When **layoutDirection** is **Row** or **RowReverse**: minimum number of columns that can be displayed.<br>When **layoutDirection** is **Column** or **ColumnReverse**: maximum number of rows that can be displayed.<br>Default value: **1**|
| cellLength<sup>8+</sup> | number | When **layoutDirection** is **Row** or **RowReverse**: fixed height per row.<br>When **layoutDirection** is **Column** or **ColumnReverse**: fixed width per column.<br>Default value: size of the first element|
| multiSelectable<sup>8+</sup> | boolean | Whether to enable mouse frame selection.<br>Default value: **false**<br>- **false**: The mouse frame selection is disabled.<br>- **true**: The mouse frame selection is enabled.|
| supportAnimation<sup>8+</sup> | boolean | Whether to enable animation.<br>Default value: **false**|
Depending on the settings of the **rowsTemplate** and **columnsTemplate** attributes, the **\<Grid>** component supports the following layout modes:
1. **rowsTemplate** and **columnsTemplate** are both set
The **\<Grid>** displays only elements in a fixed number of rows and columns and cannot be scrolled. For example, if both **rowsTemplate** and **columnsTemplate** are set to **"1fr 1fr"**, only four elements (two rows and two columns) are displayed.
In this mode, the following attributes do not take effect: **layoutDirection**, **maxCount**, minCount, and **cellLength**.
2. Either **rowsTemplate** or **columnsTemplate** is set
The **\<Grid>** arranges elements in the specified direction and allows for scrolling to display excess elements. For example, if the **\<Grid>** has 10 elements and **columnsTemplate** is set to **"1fr 1fr 1fr"**, it contains three columns. The elements are arranged in the same direction as the main axis runs down the columns. Elements outside the **\<Grid>** area can be viewed through scrolling.
In this mode, the following attributes do not take effect: **layoutDirection**, **maxCount**, **minCount**, and **cellLength**.
3. Neither **rowsTemplate** nor **columnsTemplate** is set
The **\<Grid>** arranges elements in the direction specified by **layoutDirection **. The number of columns is jointly determined by the grid width, width of the first element, **minCount**, **maxCount**, and **columnsGap**. The number of rows is jointly determined by the grid height, height of the first element, **cellLength**, and **rowsGap**. Elements outside the determined range of rows and columns are not displayed and cannot be viewed through scrolling.
In this mode, only the following attributes take effect: **layoutDirection**, **maxCount**, **minCount**, **cellLength**, **editMode**, **columnsGap**, and **rowsGap**.
## GridDirection<sup>8+</sup>
| Name | Description |
| ------ | -------------------------------------- |
| ------ | -------------------------------------- |
| Row | Horizontal layout, where the child components are arranged from left to right as the main axis runs along the rows.|
| Column | Vertical layout, where the child components are arranged from top to bottom as the main axis runs down the columns.|
| RowReverse | Reverse horizontal layout, where the child components are arranged from right to left as the main axis runs along the rows.|
......@@ -65,16 +85,6 @@ In addition to the [universal events](ts-universal-events-click.md), the followi
| onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void) | Triggered when the dragged item exits the drop target of the grid.<br>- **event**: See [ItemDragInfo](#itemdraginfo).<br>- **itemIndex**: index of the dragged item.|
| onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void) | Triggered when the dragged item is dropped on the drop target of the grid.<br>- **event**: See [ItemDragInfo](#itemdraginfo).<br>- **itemIndex**: initial position of the dragged item.<br>- **insertIndex**: index of the position to which the dragged item will be dropped.<br>- **isSuccess**: whether the dragged item is successfully dropped.|
## Notes About auto-fill
In the **columnsTemplate** and **rowsTemplate** attributes of the **\<Grid>** component, **auto-fill** supports only the following formats:
```css
repeat(auto-fill, track-size)
```
The keywords **repeat** and **auto-fill** are used. **track-size** indicates the row height or column width, which can be in the unit of px, vp, %, or valid digits. The value must contain at least one valid row height or column width.
## ItemDragInfo
| Name | Type | Description |
......@@ -90,6 +100,7 @@ The keywords **repeat** and **auto-fill** are used. **track-size** indicates the
@Component
struct GridExample {
@State Number: String[] = ['0', '1', '2', '3', '4']
scroller: Scroller = new Scroller()
build() {
Column({ space: 5 }) {
......@@ -116,7 +127,7 @@ struct GridExample {
.height(300)
Text('scroll').fontColor(0xCCCCCC).fontSize(9).width('90%')
Grid() {
Grid(this.scroller) {
ForEach(this.Number, (day: string) => {
ForEach(this.Number, (day: string) => {
GridItem() {
......@@ -139,56 +150,13 @@ struct GridExample {
.width('90%')
.backgroundColor(0xFAEEE0)
.height(300)
Button('next page')
.onClick(() => {// Click to go to the next page.
this.scroller.scrollPage({ next: true })
})
}.width('100%').margin({ top: 5 })
}
}
```
![zh-cn_image_0000001219744183](figures/zh-cn_image_0000001219744183.gif)
**Example of auto-fill**
```ts
// grid-autofill.ets
@Entry
@Component
struct Index {
@State gridItemWidth: string = "100%"
@State gridItemHeight: string = "100%"
@State gridWidth: string = "100%"
@State gridHeight: string = "100%"
@State itemList: string[] = []
build() {
Column() {
Grid() {
ForEach(this.itemList, (item) => {
GridItem() {
Text(item.toString())
.fontSize(16)
.width('100%')
.textAlign(TextAlign.Center)
}
.width(this.gridItemWidth)
.height(this.gridItemHeight)
.backgroundColor(0xF9CF93)
}, item => item)
}
.columnsGap(1)
.rowsGap(1)
.border({ width: 4, color: 0xffdb7093, style: BorderStyle.Dashed, radius: 5 })
.width(this.gridWidth)
.height(this.gridHeight)
.columnsTemplate("15% repeat(auto-fill, 10% 50px 20%) 50px")
.rowsTemplate("150px repeat(auto-fill, 20% 25%)")
}.margin(5)
}
aboutToAppear() {
for(var i = 1; i < 50; i++) {
this.itemList.push(i.toString())
}
}
}
```
![grid-autofill](figures/grid-autofill.png)
![en-us_image_0000001219744183](figures/en-us_image_0000001219744183.gif)
en/application-dev/reference/arkui-ts/ts-container-list.md
浏览文件 @ 672d91e1
......@@ -23,7 +23,7 @@ List(value?:{space?: number | string, initialIndex?: number, scroller?: Scroller
| -------- | -------- | -------- | -------- |
| space | number \| string | No| Spacing between list items.<br>Default value: **0**|
| initialIndex | number | No| Item displayed at the beginning of the viewport when the current list is loaded for the first time, that is, the first item to be displayed. If the value set is greater than the sequence number of the last item, the setting does not take effect.<br>Default value: **0**|
| scroller | [Scroller](ts-container-scroll.md#scroller) | No| Controller bound to the list to control the scrolling.|
| scroller | [Scroller](ts-container-scroll.md#scroller) | No| Scroller, which can be bound to scrollable components.|
## Attributes
......@@ -32,16 +32,16 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
| Name| Type| Description|
| -------- | -------- | -------- |
| listDirection | [Axis](ts-appendix-enums.md#axis) | Direction in which the list items are arranged.<br>Default value: **Axis.Vertical**|
| divider | {<br>strokeWidth: [Length](ts-types.md#length),<br>color?:[ResourceColor](ts-types.md#resourcecolor),<br>startMargin?: Length,<br>endMargin?: Length<br>} \| null | Style of the divider for the list items. By default, there is no divider.<br>- **strokeWidth**: stroke width of the divider.<br>- **color**: color of the divider.<br>- **startMargin**: distance between the divider and the start edge of the list.<br>- **endMargin**: distance between the divider and the end edge of the list.|
| divider | {<br>strokeWidth: [Length](ts-types.md#length),<br>color?:[ResourceColor](ts-types.md),<br>startMargin?: Length,<br>endMargin?: Length<br>} \| null | Style of the divider for the list items. By default, there is no divider.<br>- **strokeWidth**: stroke width of the divider.<br>- **color**: color of the divider.<br>- **startMargin**: distance between the divider and the start edge of the list.<br>- **endMargin**: distance between the divider and the end edge of the list.|
| scrollBar | [BarState](ts-appendix-enums.md#barstate) | Scrollbar status.<br>Default value: **BarState.Off**|
| cachedCount | number | Number of list items to be preloaded. For details, see [Minimizing White Blocks During Swiping](../../ui/ts-performance-improvement-recommendation.md#minimizing-white-blocks-during-swiping).<br>Default value: **1**|
| cachedCount | number | Number of list items to be preloaded. For details, see [Minimizing White Blocks During Swiping](../../ui/ui-ts-performance-improvement-recommendation.md#minimizing-white-blocks-during-swiping).<br>Default value: **1**|
| editMode | boolean | Whether to enter editing mode.<br>Default value: **false**|
| edgeEffect | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | Scroll effect.<br>Default value: **EdgeEffect.Spring**|
| chainAnimation | boolean | Whether to display chained animations on this list when it slides or its top or bottom is dragged. The list items are separated with even space, and one item animation starts after the previous animation during basic sliding interactions. The chained animation effect is similar with spring physics.<br>Default value: **false**<br>- **false**: No chained animations are displayed.<br>- **true**: Chained animations are displayed.|
| multiSelectable<sup>8+</sup> | boolean | Whether to enable mouse frame selection.<br>Default value: **false**<br>- **false**: The mouse frame selection is disabled.<br>- **true**: The mouse frame selection is enabled.|
| lanes<sup>9+</sup> | number \| [LengthConstrain](ts-types.md#lengthconstrain) | In the following description, **listDirection** is set to **Axis.Vertical**:<br>Number of columns in which the list items are arranged along the cross axis.<br>Default value: **1**<br>The rules are as follows:<br>- If the value is set to a number, the column width is determined based on the specified number and the cross-axis width of the **\<List>** component.<br>- If the value is set to {minLength, maxLength}, the number of columns is adjusted adaptively based on the width of the **\<List>** component, ensuring that the width respects the {minLength, maxLength} constraints during adaptation. The **minLength** constraint is prioritized. For example, if **lanes** is set to **{minLength: 40vp, maxLength: 60vp}** and the width of the **\<List>** component is 70 vp, the list items are arranged in one column with their alignment compliant with the **alignListItem** settings. If the width of the **\<List>** component is changed to 80 vp, which is twice the value of **minLength**, the list items are arranged in two columns.|
| alignListItem<sup>9+</sup> | ListItemAlign | Alignment mode of list items along the cross axis when: Cross-axis width of the **\<List>** component > Cross-axis width of list items x Value of **lanes**.<br>Default value: **ListItemAlign.Start**|
| sticky<sup>9+</sup> | StickyStyle | Whether to pin the header to the top or the footer to the bottom in the **\<ListItemGroup>** component. This attribute is used together with the **\<ListItemGroup>** component.<br>Default value: **StickyStyle.None**<br>**NOTE**<br>The **sticky** attribute can be set to **StickyStyle.Header** or **StickyStyle.Footer** to support both the pin-to-top and pin-to-bottom features. |
| sticky<sup>9+</sup> | StickyStyle | Whether to pin the header to the top or the footer to the bottom in the **\<ListItemGroup>** component. This attribute is used together with the **\<ListItemGroup>** component.<br>Default value: **StickyStyle.None**<br>**NOTE**<br>The **sticky** attribute can be set to **StickyStyle.Header** or \| **StickyStyle.Footer** to support both the pin-to-top and pin-to-bottom features.|
## ListItemAlign<sup>9+</sup>
......@@ -66,7 +66,7 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
| Name| Description|
| -------- | -------- |
| onItemDelete(event: (index: number) => boolean) | Triggered when a list item is deleted.<br>- **index**: index of the deleted list item.|
| onScroll(event: (scrollOffset: number, scrollState: ScrollState) => void) | Triggered when the list scrolls.<br>- **scrollOffset**: scroll offset.<br>- **[scrollState](#scrollstate)**: current scroll state. |
| onScroll(event: (scrollOffset: number, scrollState: ScrollState) => void) | Triggered when the list scrolls.<br>- **scrollOffset**: scroll offset.<br>- **[scrollState](#scrollstate)**: current scroll state.|
| onScrollIndex(event: (start: number, end: number) => void) | Triggered when scrolling starts.<br>When calculating the index value, the **\<ListItemGroup>** accounts for one index value as a whole, and the index values of the list items within are not calculated.<br>- **start**: index of the scroll start position.<br>- **end**: index of the scroll end position.|
| onReachStart(event: () => void) | Triggered when the list reaches the start position.|
| onReachEnd(event: () => void) | Triggered when the list reaches the end position.|
......@@ -153,7 +153,7 @@ struct ListExample {
}
```
![en-us_image_0000001256978357](figures/en-us_image_0000001256978357.gif)
![en-us_image_0000001174264378](figures/en-us_image_0000001174264378.gif)
```ts
// xxx.ets
......@@ -183,7 +183,7 @@ struct ListLanesExample {
.width("90%")
.editMode(true)
.border({ width: 3, color: Color.Red })
.lanes({ minLength: 40, maxLength: 60 })
.lanes({ minLength: 40, maxLength: 40 })
.alignListItem(this.alignListItem)
Button("Change alignListItem: "+ this.alignListItem).onClick(() => {
......@@ -199,3 +199,5 @@ struct ListLanesExample {
}
}
```
![list](figures/list1.gif)
en/application-dev/reference/arkui-ts/ts-state-management.md 0 → 100644
浏览文件 @ 672d91e1
# State Management with Application-level Variables
The state management module provides APIs for data storage, persistent data management, Ability data storage, and environment status required by applications. The APIs for Ability data storage are supported since API version 9.
> **NOTE**
>
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## AppStorage
### Link
Link(propName: string): any
Establishes two-way data binding between an attribute and this **LocalStorage** instance.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | --- | --------------------- |
| propName | string | Yes | Name of the target attribute.|
**Return value**
| Type | Description |
| ----- | ------------------------------------------------------------ |
| @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.|
```ts
let simple = AppStorage.Link('simpleProp')
```
### SetAndLink
SetAndLink\<T>(propName: string, defaultValue: T): SubscribedAbstractProperty\<T>
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.
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ | ------ | --- | -------------------- |
| propName | string | Yes | Target key. |
| defaultValue | T | Yes | Default value to set.|
**Return value**
| Type | Description |
| ----- | ------------------------------------------------------------ |
| @Link | Returns the value corresponding to the key if the current key is stored in the **AppStorage**; creates and returns a **Link** instance corresponding to the default value if the key has not been created.|
```ts
let simple = AppStorage.SetAndLink('simpleProp', 121)
```
### Prop
Prop(propName: string): any
Establishes one-way data binding with an attribute to update its status.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | --- | ------------------- |
| propName | string | Yes | Target key.|
**Return value**
| Type | Description |
| ----- | ------------------------------------------------------------ |
| @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.|
```ts
let simple = AppStorage.Prop('simpleProp')
```
### SetAndProp
SetAndProp\<S>(propName: string, defaultValue: S): SubscribedAbstractProperty\<S>;
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.
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ | ------ | --- | --------------------------- |
| propName | string | Yes | Key in the key-value pair to be saved.|
| defaultValue | S | Yes | Default value to set. |
**Return value**
| Type | Description |
| ----- | ------------------------------------------------------------ |
| @Prop | Returns the value corresponding to the key if the current key is stored in the **AppStorage**; creates and returns a **Prop** instance corresponding to the default value otherwise. |
```ts
let simple = AppStorage.SetAndProp('simpleProp', 121)
```
### Has
Has(propName: string): boolean
Checks whether the attribute corresponding to the specified key exists.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | --- | -------------- |
| propName | string | Yes | Key of the attribute.|
**Return value**
| Type | Description |
| ------- | -------------------------- |
| boolean | Returns whether the attribute exists.|
```ts
let simple = AppStorage.Has('simpleProp')
```
### Get
Get\<T>(propName: string): T | undefined
Obtains the value of the specified key.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ------------------- |
| propName | string | Yes | Key of the value to obtain.|
**Return value**
| Type | Description |
| ------------------ | -------------------------- |
| boolean or undefined| Returns whether the value of the attribute exists.|
```ts
let simple = AppStorage.Get('simpleProp')
```
### Set
Set\<T>(propName: string, newValue: T): boolean
Replaces the value of a saved key.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | --- | ----------------- |
| propName | string | Yes | Key of the value to set. |
| newValue | T | Yes | Value to set.|
**Return value**
| Type | Description |
| ------- | ----------------------------------------------------- |
| boolean | Returns **true** and the value if the key exists; returns **false** otherwise.|
```ts
let simple = AppStorage.Set('simpleProp', 121);
```
### SetOrCreate
SetOrCreate\<T>(propName: string, newValue: T): void
Creates or updates the value of the specified key.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | --- | ------------------------- |
| propName | string | Yes | Key to set. |
| newValue | T | Yes | Value to be updated or created.|
**Return value**
| Type | 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 as its default value and returns **false** otherwise. **undefined** and **null** are not allowed to return **true**.|
```ts
let simple = AppStorage.SetOrCreate('simpleProp', 121)
```
### Delete
Delete(propName: string): boolean
Deletes the key-value pair that matches the specified key.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | --- | --------------------- |
| propName | string | Yes | Key of the target key-value pair.|
**Return value**
| Type | Description |
| ------- | ------------------------------------------------------------ |
| boolean | Returns **true** if the key-value pair exists and is successfully deleted; returns **false** otherwise.|
```ts
let simple = AppStorage.Delete('simpleProp')
```
### keys
keys(): IterableIterator\<string>
Searches for all keys.
**Return value**
| Type | Description |
| -------------- | ---------------------------- |
| array\<string> | Returns an array of strings containing all keys.|
```ts
let simple = AppStorage.Keys()
```
### staticClear
staticClear(): boolean
Deletes all attributes.
**Return value**
| Type | Description |
| ------- | ------------------------------------------------------------ |
| boolean | Returns **true** if all attributes are deleted; returns **false** if any of the attributes is being referenced by a state variable.|
```ts
let simple = AppStorage.staticClear()
```
### IsMutable
IsMutable(propName: string): boolean
Checks whether an attribute exists and can be changed.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | :--- | --------------------- |
| propName | string | Yes | Key of the target attribute.|
**Return value**
| Type | Description |
| ------- | ------------------------------------ |
| boolean | Returns whether the attribute exists and can be changed.|
```ts
let simple = AppStorage.IsMutable('simpleProp')
```
### Size
Size(): number
Checks the number of existing key-value pairs.
**Return value**
| Type | Description |
| ------ | ------------------ |
| number | Returns the number of key-value pairs.|
```ts
let simple = AppStorage.Size()
```
## LocalStorage<sup>9+</sup>
### constructor<sup>9+</sup>
constructor(initializingProperties?: Object)
Creates and initializes a **LocalStorage** object.
**Parameters**
| Name | Type | Mandatory| Description |
| ---------------------- | ------ | ---- | ------------------------------------------------------------ |
| initializingProperties | Object | No | All object attributes and their values returned by **object.keys(obj)**.|
```ts
this.storage = new LocalStorage()
```
### GetShared<sup>9+</sup>
static GetShared(): LocalStorage
Obtains the **LocalStorage** object being shared.
This API can be used only in the stage model.
**Return value**
| Type | Description |
| ----------------------------- | ---------------------- |
| [LocalStorage](#localstorage) | **LocalStorage** object.|
```ts
let storage = LocalStorage.GetShared()
```
### has<sup>9+</sup>
has(propName: string): boolean
Checks whether the **LocalStorage** contains the specified attribute.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | --- | -------------- |
| propName | string | Yes | Key of the attribute.|
**Return value**
| Type | Description |
| ------- | -------------------------- |
| boolean | Returns whether the attribute exists.|
```ts
this.storage = new LocalStorage()
this.storage.has('storageSimpleProp')
```
### get<sup>9+</sup>
get\<T>(propName: string): T
Obtains the value of the specified key.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | --- | ------------------- |
| propName | string | Yes | Key of the value to obtain.|
**Return value**
| Type | Description |
| -------------- | ------------------------------------------------------- |
| T \| undefined | Returns the value of the specified key if it exists; returns **undefined** otherwise.|
```ts
this.storage = new LocalStorage()
let simpleValue = this.storage.get('storageSimpleProp')
```
### set<sup>9+</sup>
set\<T>(propName: string, newValue: T): boolean
Sets a new value for the specified key.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | --- | ----------------- |
| propName | string | Yes | Key to set. |
| newValue | T | Yes | Value to set.|
**Return value**
| Type | Description |
| ------- | ----------------------------------------------------- |
| boolean | Returns **true** if the specified key exists and the value is set; returns **false** otherwise.|
```ts
this.storage = new LocalStorage()
this.storage.set('storageSimpleProp', 121)
```
### setOrCreate<sup>9+</sup>
setOrCreate\<T>(propName: string, newValue: T): boolean
Creates or updates the value of the specified key.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | :--- | ----------------------- |
| propName | string | Yes | Key of the value to create or update. |
| newValue | T | Yes | Value to be updated or created.|
**Return value**
| Type | 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 as its default value and returns false otherwise. **undefined** and **null** are not allowed.|
```ts
this.storage = new LocalStorage()
this.storage.setOrCreate('storageSimpleProp', 121)
```
### link<sup>9+</sup>
link\<T>(propName: string): T
Establishes two-way data binding between an attribute and this **LocalStorage** instance.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | --- | ---------------------- |
| propName | string | Yes | Name of the target attribute.|
**Return value**
| Type| Description |
| ---- | ------------------------------------------------------------ |
| T | 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 **LocalStorage**, and attribute changes made through the **LocalStorage** will be synchronized to the variable or component. returns **undefined** if the attribute with the given key does not exist.|
```ts
this.storage = new LocalStorage()
let localStorage = this.storage.link('storageSimpleProp')
```
### setAndLink<sup>9+</sup>
setAndLink\<T>(propName: string, defaultValue: T): T
Works in a way similar to the **Link** API.
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ | ------ | --- | -------------------- |
| propName | string | Yes | Target key. |
| defaultValue | T | Yes | Default value to set.|
**Return value**
| Type | Description |
| ------------------------------------ | ------------------------------------------------------------ |
| @Link | Returns the value corresponding to the key if the current key is stored in the **LocalStorage**; creates and returns a **Link** instance corresponding to the default value if the key has not been created.|
```ts
this.storage = new LocalStorage()
let localStorage = this.storage.setAndLink('storageSimpleProp', 121)
```
### prop<sup>9+</sup>
prop\<T>(propName: string): T
Establishes one-way data binding with an attribute to update its status.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | --- | ----------------------- |
| propName | string | Yes | Key of the attribute.|
**Return value**
| Type | Description |
| ------------------------------------ | ------------------------------------------------------------ |
| @Prop | 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 be synchronized to the **LocalStorage**. This API returns immutable variables and is applicable to mutable and immutable state variables. |
```ts
this.storage = new LocalStorage()
let localStorage = this.storage.prop('storageSimpleProp')
```
### setAndProp<sup>9+</sup>
setAndProp\<T>(propName: string, defaultValue: T): T
Works in a way similar to the **Prop** API.
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ | ------ | --- | ------------------------- |
| propName | string | Yes | Key of the target key-value pair.|
| defaultValue | T | Yes | Default value to set. |
**Return value**
| Type | Description |
| ------------------------------------ | ------------------------------------------------------------ |
| @Prop | Returns the value corresponding to the given key if the key is stored in the **LocalStorage**; creates and returns a **Prop** instance corresponding to the default value if the key has not been created.|
```ts
this.storage = new LocalStorage()
let localStorage = this.storage.setAndProp('storageSimpleProp', 121)
```
### delete<sup>9+</sup>
delete(propName: string): boolean
Deletes the key-value pair that matches the specified key.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | :--- | --------------------- |
| propName | string | Yes | Key of the target key-value pair.|
**Return value**
| Type | Description |
| ------- | ------------------------------------------------------------ |
| boolean | Returns **true** if the key-value pair exists and is successfully deleted; returns **false** if the key-value pair does not exist, fails to be deleted, or is being referenced by a state varaiable.|
```ts
this.storage = new LocalStorage()
this.storage.delete('storageSimpleProp')
```
### keys<sup>9+</sup>
keys(): IterableIterator\<string>
Searches for all keys.
**Return value**
| Type | Description |
| -------------- | -------------------------------------- |
| array\<string> | Returns an array of strings containing all keys that are not serializable.|
```ts
this.storage = new LocalStorage()
let simple = this.storage.keys()
```
### size<sup>9+</sup>
size(): number
Obtains the number of existing key-value pairs.
**Return value**
| Type | Description |
| ------ | ------------------ |
| number | Returns the number of key-value pairs.|
```ts
this.storage = new LocalStorage()
let simple = this.storage.size()
```
### Clear<sup>9+</sup>
clear(): boolean
Deletes all attributes.
**Return value**
| Type | Description |
| ------- | ------------------------------------------------------------ |
| boolean | Returns **true** if all attributes are deleted; returns **false** if any of the attributes is being referenced by a state variable.|
```ts
this.storage = new LocalStorage()
let simple = this.storage.clear()
```
## PersistentStorage
### constructor
constructor(appStorage: AppStorage, storage: Storage)
Creates a **persistentstorage** object.
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ---------- | --- | -------------------------------- |
| appStorage | AppStorage | Yes | Singleton object that saves all attributes and attribute values.|
| storage | Storage | Yes | **Storage** object. |
```ts
this.persistentstorage = new PersistentStorage(AppStorage,Storage)
```
### PersistProp
PersistProp(key:string,defaultValue:T): void
Changes the attribute that matches the specified key to persistent data in the **AppStorage**.
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ | ------ | --- | ----------------------- |
| key | string | Yes | Key of the target attribute. |
| defaultValue | T | Yes | Value of the target attribute.|
```ts
PersistentStorage.PersistProp('highScore', '0')
```
### DeleteProp
DeleteProp(key: string): void
Cancels two-way binding. The value of this attribute will be deleted from the persistent storage.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | --- | --------------------- |
| key | string | Yes | Key of the target attribute.|
```ts
PersistentStorage.DeleteProp('highScore')
```
### PersistProps
PersistProps(properties: {key: string, defaultValue: any}[]): void;
Changes the attributes that match the specified keys to persistent data in the **AppStorage**.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------------------------------- | -- | ------------------ |
| key | {key: string, defaultValue: any}[] | Yes | Keys of the target attributes.|
```ts
PersistentStorage.PersistProps([{key: 'highScore', defaultValue: '0'},{key: 'wightScore',defaultValue: '1'}])
```
### Keys
Keys(): Array\<string>
Returns the flags of all persistent attributes.
**Return value**
| Type | Description |
| ------------- | -------------------------- |
| Array\<string> | Returns the flags of all persistent attributes.|
```ts
let simple = PersistentStorage.Keys()
```
> **NOTE**
>
> - When using **PersistProp**, ensure that the input key exists in the **AppStorage**.
>
> - **DeleteProp** takes effect only for the data that has been linked during the current startup.
## Environment
### constructor
Creates an **Environment** object.
```ts
let simple = new Environment()
```
### EnvProp
EnvProp\<S>(key: string, value: S): 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 API to bind environment variables.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | --- | --------------- |
| key | string | Yes | Key of the target attribute. For details, see **Built-in environment variables**. |
| value | S | Yes | Value of the target attribute.|
**Return value**
| Type | Description |
| ------- | ---------------------------------- |
| boolean | Returns whether the attribute exists in the **AppStorage**.|
**Built-in environment variables**
| key | Type | Description |
| ------------ | ------------- | ------------------- |
| accessibilityEnabled | string | 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. |
| fontWeightScale | number | Font weight scale. |
| 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**. |
```ts
Environment.EnvProp('accessibilityEnabled', 'default')
```
### EnvProps
EnvProps(props: {key: string, defaultValue: any}[]): void
Associates this system item array with the **AppStorage**.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------------------------------- | --- | ------------------ |
| key | {key: string, defaultValue: any}[] | Yes | Keys of the target attributes.|
```ts
Environment.EnvProps([{key: 'accessibilityEnabled', defaultValue: 'default'},{key: 'accessibilityUnEnabled', defaultValue: 'undefault'}])
```
### Keys
Keys(): Array\<string>
Returns an array of associated system attributes.
**Return value**
| Type | Description |
| ------------- | ---------------------- |
| Array\<string> | Returns an array of associated system attributes.|
```ts
let simple = Environment.Keys()
```
en/application-dev/ui/Readme-EN.md
浏览文件 @ 672d91e1
......@@ -3,37 +3,30 @@
- [ArkUI Overview](arkui-overview.md)
- UI Development with eTS-based Declarative Development Paradigm
- [Overview](ui-ts-overview.md)
- Framework Overview
- File Organization
- [Directory Structure](ts-framework-directory.md)
- [Rules for Accessing Application Code Files](ts-framework-file-access-rules.md)
- Resource Management
- [Resource File Categories](ui-ts-basic-resource-file-categories.md)
- [Resource Access](ts-resource-access.md)
- [Pixel Units](ts-pixel-units.md)
- Componentization
- [Initialization of Custom Components' Member Variables](ts-custom-component-initialization.md)
- [Custom Component Lifecycle Callbacks](ts-custom-component-lifecycle-callbacks.md)
- [Component Creation and Re-initialization](ts-component-creation-re-initialization.md)
- Common Component Development Guidelines
- [Button](ui-ts-basic-components-button.md)
- [Web](ui-ts-components-web.md)
- Common Layout Development Guidelines
- [Flexible Layout](ui-ts-layout-flex.md)
- [Grid Layout](ui-ts-layout-grid-container.md)
- [Media Query](ui-ts-layout-mediaquery.md)
- Experiencing the Declarative UI
- [Creating a Declarative UI Project](ui-ts-creating-project.md)
- [Getting to Know Components](ui-ts-components.md)
- [Creating a Simple Page](ui-ts-creating-simple-page.md)
- Defining Page Layout and Connection
- [Declarative UI Development Guidelines](ui-ts-developing-intro.md)
- Declarative UI Development Examples
- [Creating a Simple Page](ui-ts-creating-simple-page.md)
- Building a Comprehensive Example
- [Building a Food Data Model](ui-ts-building-data-model.md)
- [Building a Food Category List Layout](ui-ts-building-category-list-layout.md)
- [Building a Food Category Grid Layout](ui-ts-building-category-grid-layout.md)
- [Implementing Page Redirection and Data Transmission](ui-ts-page-redirection-data-transmission.md)
- [Recommendations for Improving Performance](ts-performance-improvement-recommendation.md)
- [Implementing Page Redirection and Data Transmission](ui-ts-page-redirection-data-transmission.md)
- Adding a Splash Screen Animation
- [Using the Drawing Feature](ui-ts-drawing-feature.md)
- [Using the Animation Feature](ui-ts-animation-feature.md)
- [Common Components](ui-ts-components-intro.md)
- Common Layout Development
- Adaptive Layouts
- [Linear Layout](ui-ts-layout-linear.md)
- [Statck Layout](ui-ts-layout-stack.md)
- [Flex Layout](ui-ts-layout-flex.md)
- [Grid Layout](ui-ts-layout-grid.md)
- Responsive Layouts
- [Grid Layout](ui-ts-layout-grid-container-new.md)
- [Media Query](ui-ts-layout-mediaquery.md)
- [Custom Component Lifecycle Callbacks](ui-ts-custom-component-lifecycle-callbacks.md)
- [Web Component Development](ui-ts-components-web.md)
- [Recommendations for Improving Performance](ui-ts-performance-improvement-recommendation.md)
- UI Development with JavaScript-compatible Web-like Development Paradigm
- [Overview](ui-js-overview.md)
- Framework Overview
......
en/application-dev/ui/ui-ts-animation-feature.md 0 → 100644
浏览文件 @ 672d91e1
# Using the Animation Feature
The animation feature provides component animation and inter-page animation, and opens the animation capability APIs for [interpolation calculation](../reference/apis/js-apis-curve.md) and [matrix transformation](../reference/apis/js-apis-matrix4.md), allowing you to design animation effects to a great extent.
This section describes the following animation effects:
1. Animation on the splash screen: fade-in and fade-out of the logo.
2. Transition animation of shared elements on the food list page and food details page.
## AnimateTo for Splash Screen Animation
Component animations include attribute animations and **animateTo** explicit animations.
1. Attribute animation: animation for the universal attribute changes of a component.
2. Explicit animation: animation for a component changing from state A to state B, including the style, location information, and node addition and deletion. You only need to specify the start and end states, without the need for paying attention to the change process. The **animateTo** class also provides the callback for the playback state change events, which is an enhancement and encapsulation of the attribute animation.
The splash screen animation refers to the fade-in and fade-out of the logo. After the animation is complete, the food list page is displayed. The following describes how to use **animateTo** to implement the splash screen animation.
1. Configure the splash screen animation to automatically play. The expected effect is as follows: **animateTo** automatically starts to play the animation once the logo page is displayed. Call the **onAppear** API of **Shape** to set the explicit animation.
```ts
Shape() {
...
}
.onAppear(() => {
animateTo()
})
```
2. Create member variables of **opacity** and **scale** values and decorate them using the **@State** decorator, which indicates that the data is stateful and its change will trigger page refresh.
```ts
@Entry
@Component
struct Logo {
@State private opacityValue: number = 0
@State private scaleValue: number = 0
build() {
Shape() {
...
}
.scale({ x: this.scaleValue, y: this.scaleValue })
.opacity(this.opacityValue)
.onAppear(() => {
animateTo()
})
}
}
```
3. Sets the **animateTo** animation curve. The acceleration curve of the logo is slow first and then fast. The Bezier curve cubicBezier, **cubicBezier(0.4, 0, 1, 1)** is used.
Before using interpolation calculation in the **animateTo**, you must import the **Curves** module.
```ts
import Curves from '@ohos.curves'
```
The **@ohos.curves** module provides the linear curve. For initialization function of the linear, step, cubicBezier, and spring interpolation curves, an interpolation curve object can be created based on the input parameters.
```ts
@Entry
@Component
struct Logo {
@State private opacityValue: number = 0
@State private scaleValue: number = 0
private curve1 = Curves.cubicBezier(0.4, 0, 1, 1)
build() {
Shape() {
...
}
.scale({ x: this.scaleValue, y: this.scaleValue })
.opacity(this.opacityValue)
.onAppear(() => {
animateTo({
curve: this.curve1
})
})
}
}
```
4. Set the animation duration to 1s, set the delay to 0.1s, and set the closure function for displaying animation events. That is, set **opacityValue** and **scaleValue** to change from 0 to 1 from the start point to the end point. In this way, the logo fades in and out.
```ts
@Entry
@Component
struct Logo {
@State private opacityValue: number = 0
@State private scaleValue: number = 0
private curve1 = Curves.cubicBezier(0.4, 0, 1, 1)
build() {
Shape() {
...
}
.scale({ x: this.scaleValue, y: this.scaleValue })
.opacity(this.opacityValue)
.onAppear(() => {
animateTo({
duration: 2000,
curve: this.curve1,
delay: 100,
}, () => {
this.opacityValue = 1
this.scaleValue = 1
})
})
}
}
```
5. After the splash screen animation plays for 1 second, the **FoodCategoryList** page is displayed. Set the **onFinish** callback of **animateTo**. Invoke the **setTimeout** API of the timer. After a delay of 1s, call **router.replace** to display the **FoodCategoryList** page.
```ts
import router from '@ohos.router'
@Entry
@Component
struct Logo {
@State private opacityValue: number = 0
@State private scaleValue: number = 0
private curve1 = Curves.cubicBezier(0.4, 0, 1, 1)
build() {
Shape() {
...
}
.scale({ x: this.scaleValue, y: this.scaleValue })
.opacity(this.opacityValue)
.onAppear(() => {
animateTo({
duration: 2000,
curve: this.curve1,
delay: 100,
onFinish: () => {
setTimeout(() => {
router.replace({ url: "pages/FoodCategoryList" })
}, 1000);
}
}, () => {
this.opacityValue = 1
this.scaleValue = 1
})
})
}
}
```
The code is as follows:
```ts
import Curves from '@ohos.curves'
import router from '@ohos.router'
@Entry
@Component
struct Logo {
@State private opacityValue: number = 0
@State private scaleValue: number = 0
private curve1 = Curves.cubicBezier(0.4, 0, 1, 1)
private pathCommands1: string = 'M319.5 128.1 c103.5 0 187.5 84 187.5 187.5 v15 a172.5 172.5 0 0 3 -172.5 172.5 H198 a36 36 0 0 3 -13.8 -1 207 207 0 0 0 87 -372 h48.3 z'
private pathCommands2: string = 'M270.6 128.1 h48.6 c51.6 0 98.4 21 132.3 54.6 a411 411 0 0 3 -45.6 123 c-25.2 45.6 -56.4 84 -87.6 110.4 a206.1 206.1 0 0 0 -47.7 -288 z'
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Shape() {
Path()
.commands('M162 128.7 a222 222 0 0 1 100.8 374.4 H198 a36 36 0 0 3 -36 -36')
.fill(Color.White)
Path()
.commands(this.pathCommands1)
.fill('none')
.linearGradient(
{
angle: 30,
colors: [["#C4FFA0", 0], ["#ffffff", 1]]
})
.clip(new Path().commands(this.pathCommands1))
Path()
.commands(this.pathCommands2)
.fill('none')
.linearGradient(
{
angle: 50,
colors: [['#8CC36A', 0.1], ["#B3EB90", 0.4], ["#ffffff", 0.7]]
})
.clip(new Path().commands(this.pathCommands2))
}
.height('630px')
.width('630px')
.scale({ x: this.scaleValue, y: this.scaleValue })
.opacity(this.opacityValue)
.onAppear(() => {
animateTo({
duration: 2000,
curve: this.curve1,
delay: 100,
onFinish: () => {
setTimeout(() => {
router.replace({ url: "pages/FoodCategoryList" })
}, 1000);
}
}, () => {
this.opacityValue = 1
this.scaleValue = 1
})
})
Text('Healthy Diet')
.fontSize(26)
.fontColor(Color.White)
.margin({ top: 300 })
Text('Healthy life comes from a balanced diet')
.fontSize(17)
.fontColor(Color.White)
.margin({ top: 4 })
}
.width('100%')
.height('100%')
.linearGradient(
{
angle: 180,
colors: [['#BDE895', 0.1], ["#95DE7F", 0.6], ["#7AB967", 1]]
})
}
}
```
![animation-feature](figures/animation-feature.gif)
## Page Transition Animation
Implement the shared element transition between the food list page and the food details page. That is, after you click **FoodListItem** or **FoodGridItem**, the food thumbnail is zoomed in, and then you are redirected to the large image on the food details page.
1. Set the **sharedTransition** method for the **<Image>** component of **FoodListItem** and **FoodGridItem**. The transition ID is **foodItem.id**, the duration of the transition animation is 1s, and the delay is 0.1s. The change curve is **Curves.cubicBezier(0.2, 0.2, 0.1, 1.0)**. You need to import the **Curves** module first.
During the shared element transition, the attributes of the current element are carried. Therefore, create a **<Row>** component as the parent component of the **<Image>** component, and set the background color on the **<Row>** component.
Set **autoResize** to **false** for the **<Image>** component of **FoodListItem**. The **<Image>** component adjusts the size of the image source based on the final display area by default to optimize the image rendering performance. In the transition animation, the image will be reloaded during the zoom-in process. Therefore, to ensure the smoothness of the transition animation, set **autoResize** to **false**.
```ts
// FoodList.ets
import Curves from '@ohos.curves'
@Component
struct FoodListItem {
private foodItem: FoodData
build() {
Navigator({ target: 'pages/FoodDetail' }) {
Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
Row() {
Image(this.foodItem.image)
.objectFit(ImageFit.Contain)
.autoResize(false)
.height(40)
.width(40)
.sharedTransition(this.foodItem.id, { duration: 1000, curve: Curves.cubicBezier(0.2, 0.2, 0.1, 1.0), delay: 100 })
}
.margin({ right: 16 })
Text(this.foodItem.name)
.fontSize(14)
.flexGrow(1)
Text(this.foodItem.calories + ' kcal')
.fontSize(14)
}
.height(64)
}
.params({ foodData: this.foodItem })
.margin({ right: 24, left:32 })
}
}
@Component
struct FoodGridItem {
private foodItem: FoodData
build() {
Column() {
Row() {
Image(this.foodItem.image)
.objectFit(ImageFit.Contain)
.autoResize(false)
.height(152)
.width('100%')
.sharedTransition(this.foodItem.id, { duration: 1000, curve: Curves.cubicBezier(0.2, 0.2, 0.1, 1.0), delay: 100 })
}
Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
Text(this.foodItem.name)
.fontSize(14)
.flexGrow(1)
.padding({ left: 8 })
Text(this.foodItem.calories + 'kcal')
.fontSize(14)
.margin({ right: 6 })
}
.height(32)
.width('100%')
.backgroundColor('#FFe5e5e5')
}
.height(184)
.width('100%')
.onClick(() => {
router.push({ url: 'pages/FoodDetail', params: { foodId: this.foodItem } })
})
}
}
```
2. Sets the **sharedTransition** method for the **<Image>** component of **FoodImageDisplay** on the **FoodDetail** page. The setting method is the same as that mentioned above.
```ts
import Curves from '@ohos.curves'
@Component
struct FoodImageDisplay {
private foodItem: FoodData
build() {
Stack({ alignContent: Alignment.BottomStart }) {
Image(this.foodItem.image)
.objectFit(ImageFit.Contain)
.sharedTransition(this.foodItem.id, { duration: 1000, curve: Curves.cubicBezier(0.2, 0.2, 0.1, 1.0), delay: 100 })
Text(this.foodItem.name)
.fontSize(26)
.fontWeight(500)
.margin({ left: 26, bottom: 17.4 })
}
.height(357)
}
}
```
![animation-feature1](figures/animation-feature1.gif)
Now we have completed the drawing of the startup logo, splash screen animation, and transition animation between pages. By applying and combining the various animation APIs in the declarative development framework, you can create a more immersive experience for your applications.
en/application-dev/ui/ui-ts-building-category-grid-layout.md
浏览文件 @ 672d91e1
......@@ -119,7 +119,7 @@ The diet application allows food on the home page to display in list or grid mod
When you click the switch icon, the FoodList component is displayed. When you click the switch icon again, the FoodList component is hidden.
![en-us_image_0000001222807800](figures/en-us_image_0000001222807800.gif)
![en-us_image_0000001170411978](figures/en-us_image_0000001170411978.gif)
6. Create a tab to display all food categories (All). Create the **\<Tabs>** component and its child component **TabContent** in the **FoodCategory** component, and set **tabBar** to **All**. Set the width of the **TabBars** to **280** and the layout mode to **Scrollable**. This means that the TabBars can be scrolled when the total length exceeds 280. The **\<Tabs>** component is a container component that allows users to switch between content views through tabs. Each tab page corresponds to a TabContent.
......
en/application-dev/ui/ui-ts-components-intro.md 0 → 100644
浏览文件 @ 672d91e1
# Common Components
Components are the core of a UI page. Each component can provide visible and interactive functional units that are independent from each other. This is achieved by data and method encapsulation. You can use and reuse any component anywhere as needed.
The table below lists the components available in the declarative development paradigm.
| Component Type | Components |
| ---------------------------- | ---------------------------------------------------------- |
| [Basic components](../reference/arkui-ts/ts-basic-components-blank.md) | Blank, Button, Checkbox, CheckboxGroup, DataPanel, DatePicker, Divider, Gauge, Image, ImageAnimator, LoadingProgress, Marquee, Navigation, PatternLock, PluginComponent, Progress, QRCode, Radio, Rating, RemoteWindow, RichText, ScrollBar, Search, Select, Slider, Span, Stepper, StepperItem, Text, TextArea, TextClock, TextInput, TextPicker, TextTimer, TimePicker, Toggle, Web, XComponent |
| [Container components](../reference/arkui-ts/ts-container-ability-component.md) | AbilityComponent, AlphabetIndexer, Badge, Column, ColumnSplit, Counter, Flex, FlowItem, GridContainer, GridCol, GridRow, Grid, GridItem, List, ListItem, ListItemGroup, Navigator, Panel, Refresh, RelativeContainer, Row, RowSplit, Scroll, SideBarContainer, Stack, Swiper, Tabs, TabContent, WaterFlow |
| [Media components](../reference/arkui-ts/ts-media-components-video.md)| Video |
| [Drawing components](../reference/arkui-ts/ts-drawing-components-circle.md)| Circle, Ellipse, Line, Polyline, Polygon, Path, Rect, Shape |
| [Canvas components](../reference/arkui-ts/ts-components-canvas-canvas.md)| Canvas |
en/application-dev/ui/ui-ts-components-web.md
浏览文件 @ 672d91e1
# Web
# Web Component Development
The **\<Web>** component can be used to display web pages. For details, see [Web](../reference/arkui-ts/ts-basic-components-web.md).
......
en/application-dev/ui/ui-ts-custom-component-lifecycle-callbacks.md 0 → 100644
浏览文件 @ 672d91e1
# Custom Component Lifecycle Callbacks
The lifecycle callbacks of a custom component are used to notify users of the lifecycle of the component. These callbacks are private and are invoked by the development framework at a specified time at runtime. They cannot be manually invoked from applications.
> **NOTE**
>
> - Promise and asynchronous callback functions can be used in lifecycle functions, for example, network resource getters and timer setters.
>
> - Do not use **async await** in lifecycle functions.
## aboutToAppear
aboutToAppear?(): void
Invoked after a new instance of the custom component is created and before its **build** function is executed. You can change state variables in the **aboutToAppear** function. The change will take effect when you execute the **build** function next time.
## aboutToDisappear
aboutToDisappear?(): void
Invoked before the destructor of the custom component is consumed. Do not change state variables in the **aboutToDisappear** function as doing this can cause unexpected errors. For example, the modification of the **@Link** decorated variable may cause unstable application running.
**Example 1:**
```ts
// xxx.ets
@Entry
@Component
struct CountDownTimerComponent {
@State countDownFrom: number = 10
private timerId: number = -1
aboutToAppear(): void {
this.timerId = setInterval(() => {
if (this.countDownFrom <= 1) {
clearTimeout(this.timerId) // Clear the timer when the value of countDownFrom is less than or equal to 1.
}
this.countDownFrom -= 1
}, 1000) // The value of countDownFrom decreases by 1 every second.
}
aboutToDisappear(): void {
if (this.timerId > 0) {
clearTimeout(this.timerId)
this.timerId = -1
}
}
build() {
Column() {
Text(`${this.countDownFrom} sec left`)
.fontSize(30)
.margin(30)
}.width('100%')
}
}
```
![aboutToAppear](figures/aboutToAppear.gif)
The example above shows that lifecycle functions are critical for **CountDownTimerComponent** to manage its timer resources. Similar functions include loading resources asynchronously from the network.
## onPageShow
onPageShow?(): void
Invoked each time when a page is displayed. This callback is used in the routing process or scenarios where the application is switched to the foreground or background. Only the custom components decorated by **@Entry** take effect.
## onPageHide
onPageHide?(): void
Invoked each time when a page is hidden. This callback is used in the routing process or scenarios where the application is switched to the foreground or background. Only the custom components decorated by **@Entry** take effect.
## onBackPress
onBackPress?(): void
Invoked when a user clicks the back button. Only the custom components decorated by **@Entry** take effect. If **true** is returned, the page processes the return logic and no page routing is performed. If **false** is returned, the default route return logic is used. If the return value is not set, the value **false** is used.
**Example 2:**
```ts
// xxx.ets
@Entry
@Component
struct IndexComponent {
@State textColor: Color = Color.Black
onPageShow() {
this.textColor = Color.Blue
console.info('IndexComponent onPageShow')
}
onPageHide() {
this.textColor = Color.Transparent
console.info('IndexComponent onPageHide')
}
onBackPress() {
this.textColor = Color.Red
console.info('IndexComponent onBackPress')
}
build() {
Column() {
Text('Hello World')
.fontColor(this.textColor)
.fontSize(30)
.margin(30)
}.width('100%')
}
}
```
![lifecycle](figures/lifecycle.PNG)
## onLayout<sup>9+</sup>
onLayout?(children: Array\<LayoutChild\>, constraint: ConstraintSizeOptions): void
Invoked when the custom component lays out its child components. Through this callback the component receives its child component layout information and size constraint from the framework. The state variable cannot be changed in the **onLayout** function.
**Parameters**
| Name | Type | Description |
| ---------- | -------------------------------------------------------------------------------- | ---------------------- |
| children | Array\<[LayoutChild](#layoutchild9)\> | Child component layout information. |
| constraint | [ConstraintSizeOptions](../reference/arkui-ts/ts-types.md#constraintsizeoptions) | Size constraint information of the parent component.|
## onMeasure<sup>9+</sup>
onMeasure?(children: Array\<LayoutChild\>, constraint: ConstraintSizeOptions): void
Invoked when the custom component needs to determine its size. Through this callback the component receives its child component layout information and size constraint from the framework. The state variable cannot be changed in the onMeasure function.
**Parameters**
| Name | Type | Description |
| ---------- | -------------------------------------------------------------------------------- | ---------------------- |
| children | Array\<[LayoutChild](#layoutchild9)\> | Child component layout information. |
| constraint | [ConstraintSizeOptions](../reference/arkui-ts/ts-types.md#constraintsizeoptions) | Size constraint information of the parent component.|
## LayoutChild<sup>9+</sup>
Provides the child component layout information.
| Name | Type | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| name | string | Name of the child component. |
| id | string | ID of the child component. |
| constraint | [ConstraintSizeOptions](../reference/arkui-ts/ts-types.md#constraintsizeoptions) | Size constraint of the child component. |
| borderInfo | [LayoutBorderInfo](#layoutborderinfo9) | Border information of the child component. |
| position | [Position](../reference/arkui-ts/ts-types.md#position) | Position coordinates of the child component. |
| measure | (childConstraint: [ConstraintSizeOptions](../reference/arkui-ts/ts-types.md#constraintsizeoptions)) => void | Method called to apply the size constraint to the child component.|
| layout | (LayoutInfo: [LayoutInfo](#layoutinfo9)) => void | Method called to apply the layout information to the child component.|
## LayoutBorderInfo<sup>9+</sup>
Provides the border information of the child component.
| Name | Type | Description |
| ----------- | ---------------------------------------------------------- | ---------------------------------------------- |
| borderWidth | [EdgeWidths](../reference/arkui-ts/ts-types.md#edgewidths) | Edge widths in different directions of the child component.|
| margin | [Margin](../reference/arkui-ts/ts-types.md#margin) | Margin areas in different directions of the child component. |
| padding | [Padding](../reference/arkui-ts/ts-types.md#padding) | Padding areas in different directions of the child component. |
## LayoutInfo<sup>9+</sup>
Provides the layout information of the child component.
| Name | Type | Description |
| ---------- | -------------------------------------------------------------------------------- | ---------------- |
| position | [Position](../reference/arkui-ts/ts-types.md#position) | Position coordinates of the child component.|
| constraint | [ConstraintSizeOptions](../reference/arkui-ts/ts-types.md#constraintsizeoptions) | Size constraint of the child component.|
Example 3:
```ts
// xxx.ets
@Entry
@Component
struct Index {
build() {
Column() {
CustomLayout() {
ForEach([1, 2, 3], (index) => {
Text('Sub' + index)
.fontSize(30)
.borderWidth(2)
})
}
}
}
}
@Component
struct CustomLayout {
@BuilderParam builder: () => {}
onLayout(children: Array<LayoutChild>, constraint: ConstraintSizeOptions) {
let pos = 0
children.forEach((child) => {
child.layout({ position: { x: pos, y: pos }, constraint: constraint })
pos += 100
})
}
onMeasure(children: Array<LayoutChild>, constraint: ConstraintSizeOptions) {
let size = 100
children.forEach((child) => {
child.measure({ minHeight: size, minWidth: size, maxWidth: size, maxHeight: size })
size += 50
})
}
build() {
this.builder()
}
}
```
![customlayout](figures/customLayout.png)
en/application-dev/ui/ui-ts-developing-intro.md 0 → 100644
浏览文件 @ 672d91e1
# Declarative UI Development Guidelines
## Overview
For details about the declarative UI project structure, see [Project Directory Structure](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-project-overview-0000001218440650#section133380945818). The ArkTS files that end with the .ets extension describe the UI layouts, styles, event interactions, and page logics. TypeScript and JavaScript files can be imported as page files. The **resources** directory is located in **src/main**. For details about this directory, see [Resource Categories and Access](../quick-start/resource-categories-and-access.md).
Before developing a page, familiarize yourself with [ArkTS](../quick-start/arkts-get-started.md).
When developing a page, select a [layout](ui-ts-layout-linear.md) that meets your service requirements. Then add built-in components and update the component status based on the content to be implemented on the page. For details how to add lifecycle callbacks for custom components, see [Custom Component Lifecycle Callbacks](ui-ts-custom-component-lifecycle-callbacks.md).
You can also [draw shapes](../reference/arkui-ts/ts-drawing-components-circle.md) and [add animations](../reference/arkui-ts/ts-animatorproperty.md) to create a more vibrant viewing experience. You can also use [page routing](../reference/apis/js-apis-router.md) to implement redirection and data transfer between pages.
For a line-up of recommendations that you can take to improve your implementation, thereby avoiding possible performance drop, see [Recommendations for Improving Performance](ui-ts-performance-improvement-recommendation.md).
## Creating a Page
Select a layout to create a page and add basic built-in components to the page. In this example, the [flex layout](ui-ts-layout-flex.md) is used, and the **\<Text>** component is centered horizontally and vertically on the page.
```ts
// xxx.ets
@Entry
@Component
struct MyComponent {
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Text('Hello')
}
.width('100%')
.height('100%')
}
}
```
## Setting the Component Style
If a built-in component does not have attribute methods set, it takes the default style. To change the style of a component and thereby how it looks on the UI, modify the settings of styles, including component-specific styles and [universal styles](../reference/arkui-ts/ts-universal-attributes-size.md).
1. Change the display content of the **\<Text>** component to **Tomato** by modifying its constructor parameters.
2. Set the **fontSize** attribute to **26** and the **fontWeight** attribute to **500**. The **fontWeight** attribute can be set in any of the following modes:
a. Set the attribute to a value of the number type in the range from 100 to 900, at an interval of 100. The default value is **400**. A larger value indicates a larger font weight.
b. Set the attribute to any of its enumerated values: **FontWeight.Lighter**, **FontWeight.Normal**, **FontWeight.Regular**, **FontWeight.Medium**, **FontWeight.Bold**, or **FontWeight.Bolder**. **FontWeight.Normal** indicates the font weight of 400.
c. Set the attribute to a value of the string type that indicates a number, for example, **"400"** or a string that corresponds to one of the enumerated values in **FontWeight**, such as **"bold"**, **"bolder"**, **"lighter"**, **"regular"**, and **"medium"**. If the set value is invalid, the default font weight is used.
The attribute method must follow the component and be connected by the operator ".". You can also configure multiple attributes of the component in method chaining mode.
```ts
// xxx.ets
@Entry
@Component
struct MyComponent {
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Text('Tomato')
.fontSize(26)
.fontWeight(500)
}
.width('100%')
.height('100%')
}
}
```
![en-us_image_0000001168888224](figures/en-us_image_0000001168888224.png)
## Initialization of Components' Member Variables
The member variables of a custom component can be initialized in either of the following methods: [local initialization](../quick-start/arkts-restrictions-and-extensions.md#initialization-and-restrictions-of-custom-components'-member-variables) or [initialization using constructor parameters](../quick-start/arkts-restrictions-and-extensions.md#initialization-and-restrictions-of-custom-components'-member-variables). Select the appropriate method based on the decorator used by the variable.
**Example**
```ts
// xxx.ets
class ClassA {
public str: string
constructor(str: string) {
this.str = str
}
}
@Entry
@Component
struct Parent {
// Initialize the parentState variable in Parent locally.
@State parentState: ClassA = new ClassA('hello')
build() {
Column() {
Row() {
CompA({ aState: new ClassA('Tomato'), aLink: $parentState })
}
// aState has been initialized in CompA. Therefore, it can use the default value.
Row() {
CompA({ aLink: $parentState })
}
}.width('100%')
}
}
@Component
struct CompA {
// Initialize the aState variable in CompA locally. Initialize the aLink variable in Parent by using constructor parameters.
@State aState: any = new ClassA('CompA')
@Link aLink: ClassA
build() {
Row() {
Text(JSON.stringify(this.aState)).fontSize(20).margin(30)
Text(JSON.stringify(this.aLink)).fontSize(20).margin(30)
}
}
}
```
![component](figures/component.PNG)
## Updating the Component Status
The status of a component can be updated by dynamically changing the values of its member variables.
**Example**
```ts
// xxx.ets
@Entry
@Component
struct ParentComp {
@State isCountDown: boolean = true
build() {
Column() {
Text(this.isCountDown ? 'Count Down' : 'Stopwatch').fontSize(20).margin(20)
if (this.isCountDown) {
// The image resources are stored in the media directory.
Image($r("app.media.countdown")).width(120).height(120)
TimerComponent({ counter: 10, changePerSec: -1, showInColor: Color.Red })
} else {
// The image resources are stored in the media directory.
Image($r("app.media.stopwatch")).width(120).height(120)
TimerComponent({ counter: 0, changePerSec: +1, showInColor: Color.Black })
}
Button(this.isCountDown ? 'Switch to Stopwatch' : 'Switch to Count Down')
.onClick(() => {
this.isCountDown = !this.isCountDown
})
}.width('100%')
}
}
// Custom timer/countdown component.
@Component
struct TimerComponent {
@State counter: number = 0
private changePerSec: number = -1
private showInColor: Color = Color.Black
private timerId: number = -1
build() {
Text(`${this.counter}sec`)
.fontColor(this.showInColor)
.fontSize(20)
.margin(20)
}
aboutToAppear() {
this.timerId = setInterval(() => {
this.counter += this.changePerSec
}, 1000)
}
aboutToDisappear() {
if (this.timerId > 0) {
clearTimeout(this.timerId)
this.timerId = -1
}
}
}
```
![component](figures/component.gif)
**Initial creation and rendering:**
1. Create the parent component **ParentComp**.
2. Locally initialize the state variable **isCountDown** of **ParentComp**.
3. Execute the **build** function of **ParentComp**.
4. Create a **\<Column>** component.
1. Create a preset **\<Text>** component, set the text content, and add the **\<Text>** component instance to the **\<Column>** component.
2. With the **if** statement, create an element under the **true** condition.
1. Create a preset **\<Image>** component and set the image source address.
2. Create a **TimerComponent** using the given constructor.
1. Create a **TimerComponent** object.
2. Initialize the values of member variables locally.
3. Use the parameters provided by the **TimerComponent** constructor to update the values of member variables.
4. Execute the **aboutToAppear** function of **TimerComponent**.
5. Execute the **build** function of **TimerComponent** to create the corresponding UI description structure.
3. Create a preset **<Button>** component and set the corresponding content.
**Status update:**
When a user clicks a button:
1. The value of the **isCountDown** state variable of **ParentComp** is changed to **false**.
2. Execute the **build** function of **ParentComp**.
3. The **\<Column>** component is reused and reinitialized.
4. The child components of **\<Column>** reuse and reinitialize the objects in the memory.
1. Reuse the preset **\<Text>** component after re-initializing the component using new text content.
2. With the **if** statement, create an element under the **false** condition.
1. Destroy the component instances created under the **true** condition.
1. Destroy the **\<Image>** component instance.
2. Destroy the **TimerComponent** component instance. The **aboutToDisappear** function is called.
2. Create components under the false condition.
1. Create a preset **\<Image>** component and set the image source address.
2. Create a **TimerComponent** again using the given constructor.
3. Initialize the **TimerComponent** and call the **aboutToAppear** and **build** functions.
3. Reuse the **\<Button>** component and use the new image source address.
en/application-dev/ui/ui-ts-drawing-feature.md 0 → 100644
浏览文件 @ 672d91e1
# Using the Drawing Feature
The drawing feature is provided by the drawing component in the framework, with support for the SVG standard drawing commands.
This section describes how to use the drawing component to draw food composition labels (basic geometric shapes) and apply logos (custom graphics) on the details page.
## Drawing Basic Geometric Shapes
The drawing component encapsulates some common basic geometric shapes, such as rectangles, circles, and ellipses, eliminating the need to calculate routes.
In the food component table on the **FoodDetail** page, each food group is labeled with a round icon.
1. Create a **Circle** component and add a round icon before each food group as a label. Set the circle diameter to 6vp. Modify the **IngredientItem** method in the **ContentTable** component on the **FoodDetail** page by adding **Circle** before the food group name.
```ts
// FoodDetail.ets
@Component
struct ContentTable {
private foodItem: FoodData
@Builder IngredientItem(title:string, colorValue: string, name: string, value: string) {
Flex() {
Text(title)
.fontSize(17.4)
.fontWeight(FontWeight.Bold)
.layoutWeight(1)
Flex({ alignItems: ItemAlign.Center }) {
Circle({width: 6, height: 6})
.margin({right: 12})
.fill(colorValue)
Text(name)
.fontSize(17.4)
.flexGrow(1)
Text(value)
.fontSize(17.4)
}
.layoutWeight(2)
}
}
build() {
......
}
}
```
2. To use different label colors for different food groups, call **IngredientItem** in the **build** method to fill the circles with different colors.
```ts
// FoodDetail.ets
@Component
struct ContentTable {
private foodItem: FoodData
@Builder IngredientItem(title:string, colorValue: string, name: string, value: string) {
Flex() {
Text(title)
.fontSize(17.4)
.fontWeight(FontWeight.Bold)
.layoutWeight(1)
Flex({ alignItems: ItemAlign.Center }) {
Circle({width: 6, height: 6})
.margin({right: 12})
.fill(colorValue)
Text(name)
.fontSize(17.4)
.flexGrow(1)
Text(value)
.fontSize(17.4)
}
.layoutWeight(2)
}
}
build() {
Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.SpaceBetween, alignItems: ItemAlign.Start }) {
this.IngredientItem('Calories', '#FFf54040', 'Calories', this.foodItem.calories + 'kcal')
this.IngredientItem('Nutrition', '#FFcccccc', 'Protein', this.foodItem.protein + 'g')
this.IngredientItem(' ', '#FFf5d640', 'Fat', this.foodItem.fat + 'g')
this.IngredientItem(' ', '#FF9e9eff', 'Carbohydrates', this.foodItem.carbohydrates + 'g')
this.IngredientItem(' ', '#FF53f540', 'VitaminC', this.foodItem.vitaminC + 'mg')
}
.height(280)
.padding({ top: 30, right: 30, left: 30 })
}
}
```
![drawing-feature](figures/drawing-feature.png)
## Drawing Custom Graphs
In addition to drawing basic geometric shapes, you can also use the **\<Path>** component to draw a custom path. The following describes how to draw an application logo.
1. Create an eTS page **Logo.ets** in the **pages** folder.
![drawing-feature1](figures/drawing-feature1.png)
2. Delete the template code from **Logo.ets** and create a logo component.
```ts
@Entry
@Component
struct Logo {
build() {
}
}
```
3. Create a **\<Flex>** component as the root node, set the width and height to 100%, set the alignment mode on the main axis and cross axis to **Center**, and create a **\<Shape>** component as a child component of **\<Flex>**.
The **\<Shape>** component is the parent component of all drawing components. To combine multiple drawing components into a whole, create a **\<Shape>** as their parent component.
Draw a logo with the size of 630 px x 630 px. The declarative development paradigm supports multiple length units. In the preceding sections, **number** is used as a parameter, which means that the default length unit – virtual pixel (vp) is used. The virtual pixel count is related to the device resolution and screen density. For example, if the device resolution is 1176 x 2400 and the reference screen resolution is 3, with the formula of vp = px/resolution, the width of the device screen is 392 vp.
The drawing components follow the SVG standard and use px as the unit by default. Therefore, to facilitate consistency, px is also used as the unit of the logo. The declarative development framework also supports the px unit, with the input parameter of the string type. For example, to set the width to 630px (210vp), use **width('*630px*')** or **width(*210*)**.
```ts
@Entry
@Component
struct Logo {
build() {
Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Shape() {
}
.height('630px')
.width('630px')
}
.width('100%')
.height('100%')
}
}
```
4. Fill the page with gradient colors. Set the gradient mode to linear gradient, the offset angle to 180 degrees, and the color stops to #BDE895 -> 95DE7F -> #7AB967 in the ranges of [0, 0.1], (0.1, 0.6], and (0.6, 1], respectively.
```ts
.linearGradient(
{
angle: 180,
colors: [['#BDE895', 0.1], ["#95DE7F", 0.6], ["#7AB967", 1]]
})
```
![drawing-feature2](figures/drawing-feature2.png)
```ts
@Entry
@Component
struct Logo {
build() {
Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Shape() {
}
.height('630px')
.width('630px')
}
.width('100%')
.height('100%')
.linearGradient(
{
angle: 180,
colors: [['#BDE895', 0.1], ["#95DE7F", 0.6], ["#7AB967", 1]]
})
}
}
```
![drawing-feature3](figures/drawing-feature3.png)
5. Set the drawing command to draw the first path.
```ts
Path()
.commands('M162 128.7 a222 222 0 0 1 100.8 374.4 H198 a36 36 0 0 3 -36 -36')
```
The **Path** drawing commands comply with the SVG standard. The preceding command can be divided into the following:
```ts
M162 128.7
```
Start a new subpath at point (162, 128.7).
```ts
a222 222 0 0 1 100.8 374.4
```
Draw an elliptical arc, setting **rx** and **ry** to **222**, **x-axis-rotation** to **0**, **large-arc-flag** to **0**, and **sweep-flag** to **1** (which means to draw the arc counterclockwise). The lowercase **a** indicates a relative position. In this example, the end point coordinate is (162 + 100.8 = 262.8, 128.7 + 374.4 = 503.1).
```ts
H198
```
Draw a horizontal line from point (262.8, 503.1) to point (198, 503.1).
```ts
a36 36 0 0 3 -36 -36
```
Draw a circular arc. The input parameters are the same as those in drawing an elliptical arc. The end point is (198 - 36 = 162, 503.1 - 36 = 467.1).
```ts
V128.7
```
Draw a vertical line from point (162, 467.1) to point (162, 128.7).
```ts
z
```
Close the current subpath.
![drawing-feature4](figures/drawing-feature4.png)
In the sample code, the fill color is white.
```ts
.fill(Color.White)
```
```ts
@Entry
@Component
struct Logo {
build() {
Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Shape() {
Path()
.commands('M162 128.7 a222 222 0 0 1 100.8 374.4 H198 a36 36 0 0 3 -36 -36')
.fill(Color.White)
}
.height('630px')
.width('630px')
}
.width('100%')
.height('100%')
.linearGradient(
{
angle: 180,
colors: [['#BDE895', 0.1], ["#95DE7F", 0.6], ["#7AB967", 1]]
})
}
}
```
![drawing-feature5](figures/drawing-feature5.png)
6. Draw the second path. Fill the shape background with gradient colors. Because the gradient colors fill the entire box, you must use the **clip** method with the **Shape** as the input parameter so that the path is clipped.
```ts
Path()
.commands('M319.5 128.1 c103.5 0 187.5 84 187.5 187.5 v15 a172.5 172.5 0 0 3 -172.5 172.5 H198 a36 36 0 0 3 -13.8 -1 207 207 0 0 0 87 -372 h48.3 z')
.fill('none')
.linearGradient(
{
angle: 30,
colors: [["#C4FFA0", 0], ["#ffffff", 1]]
})
.clip(new Path().commands('M319.5 128.1 c103.5 0 187.5 84 187.5 187.5 v15 a172.5 172.5 0 0 3 -172.5 172.5 H198 a36 36 0 0 3 -13.8 -1 207 207 0 0 0 87 -372 h48.3 z'))
```
The path drawing command is long. You can call the command by using it as a member variable of the component through **this**.
```ts
@Entry
@Component
struct Logo {
private pathCommands1:string = 'M319.5 128.1 c103.5 0 187.5 84 187.5 187.5 v15 a172.5 172.5 0 0 3 -172.5 172.5 H198 a36 36 0 0 3 -13.8 -1 207 207 0 0 0 87 -372 h48.3 z'
build() {
......
Path()
.commands(this.pathCommands1)
.fill('none')
.linearGradient(
{
angle: 30,
colors: [["#C4FFA0", 0], ["#ffffff", 1]]
})
.clip(new Path().commands(this.pathCommands1))
......
}
}
```
![drawing-feature6](figures/drawing-feature6.png)
7. Draw the third path.
```ts
@Entry
@Component
struct Logo {
private pathCommands1:string = 'M319.5 128.1 c103.5 0 187.5 84 187.5 187.5 v15 a172.5 172.5 0 0 3 -172.5 172.5 H198 a36 36 0 0 3 -13.8 -1 207 207 0 0 0 87 -372 h48.3 z'
private pathCommands2:string = 'M270.6 128.1 h48.6 c51.6 0 98.4 21 132.3 54.6 a411 411 0 0 3 -45.6 123 c-25.2 45.6 -56.4 84 -87.6 110.4 a206.1 206.1 0 0 0 -47.7 -288 z'
build() {
Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Shape() {
Path()
.commands('M162 128.7 a222 222 0 0 1 100.8 374.4 H198 a36 36 0 0 3 -36 -36')
.fill(Color.White)
Path()
.commands(this.pathCommands1)
.fill('none')
.linearGradient(
{
angle: 30,
colors: [["#C4FFA0", 0], ["#ffffff", 1]]
})
.clip(new Path().commands(this.pathCommands1))
Path()
.commands(this.pathCommands2)
.fill('none')
.linearGradient(
{
angle: 50,
colors: [['#8CC36A', 0.1], ["#B3EB90", 0.4], ["#ffffff", 0.7]]
})
.clip(new Path().commands(this.pathCommands2))
}
.height('630px')
.width('630px')
}
.width('100%')
.height('100%')
.linearGradient(
{
angle: 180,
colors: [['#BDE895', 0.1], ["#95DE7F", 0.6], ["#7AB967", 1]]
})
}
}
```
![drawing-feature7](figures/drawing-feature7.png)
The drawing of the application logo is now completed. This logo combines three **\<Path>** components through SVG commands and takes the shape of an artistic leaf.
8. Add the application title and slogan.
```ts
@Entry
@Component
struct Logo {
private pathCommands1:string = 'M319.5 128.1 c103.5 0 187.5 84 187.5 187.5 v15 a172.5 172.5 0 0 3 -172.5 172.5 H198 a36 36 0 0 3 -13.8 -1 207 207 0 0 0 87 -372 h48.3 z'
private pathCommands2:string = 'M270.6 128.1 h48.6 c51.6 0 98.4 21 132.3 54.6 a411 411 0 0 3 -45.6 123 c-25.2 45.6 -56.4 84 -87.6 110.4 a206.1 206.1 0 0 0 -47.7 -288 z'
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Shape() {
Path()
.commands('M162 128.7 a222 222 0 0 1 100.8 374.4 H198 a36 36 0 0 3 -36 -36')
.fill(Color.White)
Path()
.commands(this.pathCommands1)
.fill('none')
.linearGradient(
{
angle: 30,
colors: [["#C4FFA0", 0], ["#ffffff", 1]]
})
.clip(new Path().commands(this.pathCommands1))
Path()
.commands(this.pathCommands2)
.fill('none')
.linearGradient(
{
angle: 50,
colors: [['#8CC36A', 0.1], ["#B3EB90", 0.4], ["#ffffff", 0.7]]
})
.clip(new Path().commands(this.pathCommands2))
}
.height('630px')
.width('630px')
Text('Healthy Diet')
.fontSize(26)
.fontColor(Color.White)
.margin({ top:300 })
Text('Healthy life comes from a balanced diet')
.fontSize(17)
.fontColor(Color.White)
.margin({ top:4 })
}
.width('100%')
.height('100%')
.linearGradient(
{
angle: 180,
colors: [['#BDE895', 0.1], ["#95DE7F", 0.6], ["#7AB967", 1]]
})
}
}
```
![drawing-feature8](figures/drawing-feature8.png)
en/application-dev/ui/ui-ts-layout-grid-container-new.md 0 → 100644
浏览文件 @ 672d91e1
# Grid Layout
As a tool to provide layout auxiliary lines, the grid system is handy in graphic and website design. When employed in the UI design of mobile devices, the grid system exhibits the following advantages:
1. Provides rules for layout design and resolves issues of dynamic layout across devices with different sizes.
2. Provides a unified positioning method for the system to ensure layout consistency across layouts on different devices.
3. Provides a flexible spacing adjustment method for applications to keep up with layout in special scenarios.
To implement a grid layout, **[GridRow](../reference/arkui-ts/ts-container-gridrow.md)** and **[GridCol](../reference/arkui-ts/ts-container-gridcol.md)** are prioritized
over the obsolete **[GridContainer](../reference/arkui-ts/ts-container-gridcontainer.md)**, because the former provides more flexibility and functionality. **GridRow** is a grid container item and must be used only with **GridCol** in the grid container.
## GridRow
The grid container works in terms of **columns**, **gutter**, **direction**, and **breakpoints**.
- **columns**: total number of columns in the grid container. This attribute is the main tool for placing items in the grid layout.
- **gutter**: spacing between elements. This attribute determines how close the content tracks are with each other.
- **direction**: alignment of child components in the grid container.
- **breakpoints**: ranges of application window widths, which are set based on the device screen widths. You can use the breakpoints to meet specific layout requirements.
After you set the breakpoints, the layout listens for changes in the application window size, determines which breakpoint range the application window is located, and adjusts to match the window size accordingly.
### Grid Breakpoints
The grid system defines breakpoints, which are screen width types in effect, based on the horizontal width (screen density pixels, in vp) of the screens. You can use the breakpoints to meet specific layout requirements.
By default, the grid system provides four breakpoints: xs, sm, md, and lg.
| Breakpoint | Value Range (vp)|
| --------| ------ |
| xs | [0, 320) |
| sm | [320, 520) |
| md | [520, 840) |
| lg | [840, +∞) |
In the **\<GridRow>** component, you can use **breakpoints** to customize the value range of breakpoints. A maximum of six breakpoints are supported.
In addition to the four default breakpoints, you can also enable the xl and xxl breakpoints for your application window layout.
| Breakpoint| Device Description |
| ----- | ---------------------------------------- |
| xs | Device of the minimum size. |
| sm | Small-sized device. |
| md | Medium-sized device. |
| lg | Large-sized device. |
| xl | Extra-large-sized device. |
| xxl | Ultra-large-sized device. |
- Set **breakpoints** with a monotonically increasing array based on the use case. Because **breakpoints** supports a maximum of six breakpoints, the maximum length of the monotonically increasing array is 5.
```ts
breakpoints: {value: ["100vp", "200vp"]}
```
Enables three breakpoints: xs, sm, and md. If the value is less than 100 vp, the breakpoint is xs. If the value is 100–200 vp, the breakpoint is sm. If the value is greater than 200 vp, the breakpoint is md.
```ts
breakpoints: {value: ["320vp", "520vp", "840vp", "1080vp"]}
```
Enables five breakpoints: xs, sm, md, lg, and xl. If the value is less than 320 vp, the breakpoint is xs. If the value is 320–520 vp, the breakpoint is sm. If the value is 520–840 vp, the breakpoint is md. If the value is 840–1080vp, the breakpoint is lg. If the value is greater than 1080 vp, the breakpoint is xl.
- The grid system implements breakpoints by listening for the changes in the window or container size, and sets the breakpoint references through **reference**. Considering that the application may be displayed in non-full-screen mode, design the breakpoints with the application window width as the reference.
In the following example, the default number of columns of a grid is 12. Breakpoints are used to divide the application window width into six ranges, where different grid items occupy a different number of columns. The following figure shows the effect.
```ts
GridRow({
breakpoints: {
value: ['200vp', '300vp', '400vp', '500vp', '600vp'],
reference: BreakpointsReference.WindowSize
}
}) {
ForEach(this.bgColors, (color, index) => {
GridCol({
span: {
xs: 2,
sm: 3,
md: 4,
lg: 6,
xl: 8,
xxl: 12
}
}) {
Row() {
Text(${index})
}.width("100%").height("50vp")
}.backgroundColor(color)
})
}
```
![](figures/breakpoints.gif)
### Columns
In the **\<GridRow>**, **columns** is used to set the total number of columns in the grid layout.
- The default value of **columns** is 12. If **columns** is not set, the grid layout is divided into 12 columns at any breakpoint.
```ts
GridRow() {
ForEach(this.bgColors, (item, index) => {
GridCol() {
Row() {
Text(`${index + 1}`)
}.width("100%").height("50")
}.backgroundColor(item)
})
}
```
![](figures/columns1.png)
- When **columns** is set to a number, the grid layout is divided into the specified number of columns regardless of the screen size. The following example sets the number of grid layout columns to 4 and 8 in sequence, where a child component occupies one column by default.
```ts
Row() {
GridRow({ columns: 4 }) {
ForEach(this.bgColors, (item, index) => {
GridCol() {
Row() {
Text(`${index + 1}`)
}.width("100%").height("50")
}.backgroundColor(item)
})
}
.width("100%").height("100%")
.onBreakpointChange((breakpoint) => {
this.currentBp = breakpoint
})
}
.height(160)
.border({ color: Color.Blue, width: 2 })
.width('90%')
Row() {
GridRow({ columns: 8 }) {
ForEach(this.bgColors, (item, index) => {
GridCol() {
Row() {
Text(`${index + 1}`)
}.width("100%").height("50")
}.backgroundColor(item)
})
}
.width("100%").height("100%")
.onBreakpointChange((breakpoint) => {
this.currentBp = breakpoint
})
}
.height(160)
.border({ color: Color.Blue, width: 2 })
.width('90%')
```
![](figures/columns2.png)
- When **columns** is set to a value of the **GridRowColumnOption** type, you can assign values specific to the screen size (xs, sm, md, lg, xl, xxl).
```ts
GridRow({ columns: { sm: 4, md: 8 }, breakpoints: { value: ['200vp', '300vp', '400vp', '500vp', '600vp'] } }) {
ForEach(this.bgColors, (item, index) => {
GridCol() {
Row() {
Text(`${index + 1}`)
}.width("100%").height("50")
}.backgroundColor(item)
})
}
```
![](figures/columns3.gif)
As shown above, if **columns** is only set for the sm and md screen size types, screen sizes smaller than sm use the default value 12, and screen sizes larger than md (lg, xl, and xxl) use the value of **columns** of the md type.
### Gutters
In the **\<GridRow>**, **gutter** is used to set the spacing between adjacent child components in the horizontal and vertical directions.
- When **gutter** is set to a number, the number applies to both the horizontal and vertical directions. In the following example, the horizontal and vertical spacing between adjacent child components are set to **10**.
```ts
GridRow({ gutter: 10 }){}
```
![](figures/gutter1.png)
- When **gutter** is set to a value of the **GutterOption** type, the **x** attribute of the value indicates the horizontal gutter, and the **y** attribute indicates the vertical gutter.
```ts
GridRow({ gutter: { x: 20, y: 50 } }){}
```
![](figures/gutter2.png)
### Alignment
In the **\<GridRow>**, **direction** is used to set the alignment of child components in the grid container.
- Child components are arranged from left to right by default.
```ts
GridRow({ direction: GridRowDirection.Row }){}
```
![](figures/direction1.png)
- Child components are arranged from right to left.
```ts
GridRow({ direction: GridRowDirection.RowReverse }){}
```
![](figures/direction2.png)
## GridCol
The **\<GridCol>** component is a child component of the **\<GridRow>** component. You can set the **span**, **offset**, and **order** attributes of this component by passing parameters or using setters.
- Setting **span**
```ts
GridCol({ span: 2 }){}
GridCol({ span: { xs: 1, sm: 2, md: 3, lg: 4 } }){}
GridCol(){}.span(2)
GridCol(){}.span({ xs: 1, sm: 2, md: 3, lg: 4 })
```
- Setting **offset**
```ts
GridCol({ offset: 2 }){}
GridCol({ offset: { xs: 2, sm: 2, md: 2, lg: 2 } }){}
GridCol(){}.offset(2)
GridCol(){}.offset({ xs: 1, sm: 2, md: 3, lg: 4 })
```
- Setting **order**
```ts
GridCol({ order: 2 }){}
GridCol({ order: { xs: 1, sm: 2, md: 3, lg: 4 } }){}
GridCol(){}.order(2)
GridCol(){}.order({ xs: 1, sm: 2, md: 3, lg: 4 })
```
The following describes how to set the attributes by passing parameters.
### span
Sets the number of columns occupied by a child component in the grid layout, which determines the child component width. The default value is **1**.
- When the value type is number, the number of columns occupied by the child component is the same across screen sizes.
```ts
GridRow({ columns: 8 }) {
ForEach(this.bgColors, (color, index) => {
GridCol({ span: 2 }) {
Row() {
Text(${index})
}.width("100%").height("50vp")
}
.backgroundColor(color)
})
}
```
![](figures/span1.png)
- When the value type is **GridColColumnOption**, you can assign values specific to the screen size (xs, sm, md, lg, xl, xxl).
```ts
GridRow({ columns: 8 }) {
ForEach(this.bgColors, (color, index) => {
GridCol({ span: { xs: 1, sm: 2, md: 3, lg: 4 } }) {
Row() {
Text(${index})
}.width("100%").height("50vp")
}
.backgroundColor(color)
})
}
```
![](figures/span2.gif)
### offset
Sets the column offset of a child component relative to the previous child component. The default value is **0**.
- When the value type is number, the column offset of the child component is the same across screen sizes.
```ts
GridRow() {
ForEach(this.bgColors, (color, index) => {
GridCol({ offset: 2 }) {
Row() {
Text("" + index)
}.width("100%").height("50vp")
}
.backgroundColor(color)
})
}
```
![](figures/offset1.png)
By default, a grid is divided into 12 columns and each child component occupies one column with an offset of two columns. Each row holds four child components, with three columns per child component plus the gutter.
- When the value type is **GridColColumnOption**, you can assign values specific to the screen size (xs, sm, md, lg, xl, xxl).
```ts
GridRow() {
ForEach(this.bgColors, (color, index) => {
GridCol({ offset: { xs: 1, sm: 2, md: 3, lg: 4 } }) {
Row() {
Text("" + index)
}.width("100%").height("50vp")
}
.backgroundColor(color)
})
}
```
![](figures/offset2.gif)
### order
Sets the sequence number of a child component in the grid layout. If a child component shares an **order** value with another child component or does not have **order** set, it is displayed based on its code sequence number. A child components with a larger **order** value is placed before the one with a smaller **order** value.
If **order** is not set for all child components, those that have **order** set are displayed after those that do not have **order** set and are sorted in descending order based on the value.
- When the value type is number, child components are sorted in the same order across screen sizes.
```ts
GridRow() {
GridCol({ order: 5 }) {
Row() {
Text("1")
}.width("100%").height("50vp")
}.backgroundColor(Color.Red)
GridCol({ order: 4 }) {
Row() {
Text("2")
}.width("100%").height("50vp")
}.backgroundColor(Color.Orange)
GridCol({ order: 3 }) {
Row() {
Text("3")
}.width("100%").height("50vp")
}.backgroundColor(Color.Yellow)
GridCol({ order: 2 }) {
Row() {
Text("4")
}.width("100%").height("50vp")
}.backgroundColor(Color.Green)
}
```
![](figures/order1.png)
- When the value type is **GridColColumnOption**, you can assign values specific to the screen size (xs, sm, md, lg, xl, xxl).
```ts
GridRow() {
GridCol({ order: { xs:1, sm:5, md:3, lg:7}}) {
Row() {
Text("1")
}.width("100%").height("50vp")
}.backgroundColor(Color.Red)
GridCol({ order: { xs:2, sm:2, md:6, lg:1} }) {
Row() {
Text("2")
}.width("100%").height("50vp")
}.backgroundColor(Color.Orange)
GridCol({ order: { xs:3, sm:3, md:1, lg:6} }) {
Row() {
Text("3")
}.width("100%").height("50vp")
}.backgroundColor(Color.Yellow)
GridCol({ order: { xs:4, sm:4, md:2, lg:5} }) {
Row() {
Text("4")
}.width("100%").height("50vp")
}.backgroundColor(Color.Green)
}
```
![](figures/order2.gif)
en/application-dev/ui/ui-ts-layout-grid.md 0 → 100644
浏览文件 @ 672d91e1
# Grid Layout
The grid layout is an important layout in adaptive layout. It excels at dividing a page and defining proportion.
You can implement a grid layout through the **[\<Grid>](../reference/arkui-ts/ts-container-grid.md)** container and the **[\<GridItem>](../reference/arkui-ts/ts-container-griditem.md)** child component.
**\<Grid>** sets grid-wide parameters, and **\<GridItem>** defines parameters specific to grid items. The grid layout has the following features:
1. When the size of the container changes, all child components and their spacings are adjusted proportionally.
2. The numbers of rows and columns in the grid layout as well as the proportion of each row and column are customizable.
3. The row and column spacing of child components in the grid layout can be set.
4. A child component can span the specified number of rows or columns.
## Grid Settings
### Number and Proportion of Rows and Columns
The number and proportion of rows and columns are set through the **columnsTemplate** and **rowTemplate** attributes.
The following describes how to set **columnsTemplate**. The value of this attribute is a string consisting of multiple 'number+fr' entries separated by spaces. The number of entries is the number of columns in the grid layout. The number before **fr** is used to calculate the proportion of the column to the grid layout width, thereby determining the column width.
```ts
struct GridExample {
@State Number: Array<string> = ['1', '2', '3', '4']
build() {
Column({ space: 5 }) {
Grid() {
ForEach(this.Number, (num: string) => {
GridItem() {
Text(`Column ${num}`)
.fontSize(16)
.textAlign(TextAlign.Center)
.backgroundColor(0xd0d0d0)
.width('100%')
.height('100%')
.borderRadius(5)
}
})
}
.columnsTemplate('1fr 1fr 1fr 1fr')
.rowsTemplate('1fr')
.columnsGap(10)
.rowsGap(20)
.width('90%')
.backgroundColor(0xF0F0F0)
.height(100)
}.width('100%')
}
}
```
Create a four-column grid, where each column has an equal width.
```ts
struct GridExample {
@State Number: Array<string> = ['1', '2', '3', '4']
build() {
Column({ space: 5 }) {
Grid() {
ForEach(this.Number, (num: string) => {
GridItem() {
Text(`Column ${num}`)
.fontSize(16)
.textAlign(TextAlign.Center)
.backgroundColor(0xd0d0d0)
.width('100%')
.height('100%')
.borderRadius(5)
}
})
}
.columnsTemplate('1fr 2fr 3fr 4fr')
.rowsTemplate('1fr')
.columnsGap(10)
.rowsGap(20)
.width('90%')
.backgroundColor(0xF0F0F0)
.height(100)
}.width('100%')
}
}
```
Create a four-column grid, where the proportions of the columns are 1:2:3:4.
```ts
struct GridExample {
@State Number: Array<string> = ['1', '2', '3']
build() {
Column({ space: 5 }) {
Grid() {
ForEach(this.Number, (num: string) => {
GridItem() {
Text(`Column ${num}`)
.fontSize(16)
.textAlign(TextAlign.Center)
.backgroundColor(0xd0d0d0)
.width('100%')
.height('100%')
.borderRadius(5)
}
})
}
.columnsTemplate('4fr 2fr 3fr')
.rowsTemplate('1fr')
.columnsGap(10)
.rowsGap(20)
.width('90%')
.backgroundColor(0xF0F0F0)
.height(100)
}.width('100%')
}
}
```
Create a three-column grid, where the proportions of the columns are 4:2:3.
The effect is as follows:
![](figures/columnTemplate.png)
### Alignment
Set **layoutDirection** to define how grid items are laid out along the main axis.
The layout options are **Row**, **RowReverse**, **Column**, and **ColumnReverse**.
The effect is as follows:
![](figures/gridlayout.png)
### Spacing Between Rows and Columns
Set **columnsGap** to define the vertical spacing of the grid items and **rowsGap** to define the horizontal spacing.
```ts
Grid()
.columnsTemplate('1fr 1fr 1fr 1fr')
.columnsGap(10)
.rowsGap(20)
```
![](figures/columnGap.png)
In the preceding example, the horizontal and vertical spacings between grid items are 10 and 20, respectively.
## GridItem Settings
### Setting the Number of Rows and Columns per Grid Item
The rows and columns of a grid layout are numbered in sequence, starting from 1.
If a grid item spans multiple rows, use **rowStart** to set the start row number and **rowEnd** to set the end row number. If the value of **rowStart** is the same as that of **rowEnd**, the grid item occupies only one grid. The sample code is as follows:
```ts
Grid() {
GridItem() {
Text('5')
.fontSize(16)
.textAlign(TextAlign.Center)
.textStyle()
}.rowStart(2).rowEnd(3) // The grid item spans the second and third columns.
GridItem() {
Text('4')
.fontSize(16)
.textAlign(TextAlign.Center)
.textStyle()
}.columnStart(4).columnEnd(5) // The grid item spans the fourth and fifth columns.
GridItem() {
Text('6')
.fontSize(16)
.textAlign(TextAlign.Center)
.textStyle()
}.columnStart(2).columnEnd(4) // The grid item spans the second to fourth columns.
GridItem() {
Text('9')
.fontSize(16)
.textAlign(TextAlign.Center)
.textStyle()
}.columnStart(3).columnEnd(4) // The grid item spans the third and fourth columns.
}
.columnsTemplate('1fr 1fr 1fr 1fr 1fr')
.rowsTemplate('1fr 1fr 1fr')
.columnsGap(10)
.rowsGap(20)
.width('90%')
.backgroundColor(0xF0F0F0)
.height('200vp')
.layoutDirection(GridDirection.Column)
```
![](figures/griditem.png)
## Example Scenario
Use the grid layout to implement a calculator. The sample code is as follows:
```ts
@Entry
@Component
struct GridExample {
@State Number: Array<string> = ['1', '2', '3', '+', '4', '5', '6', '-', '7', '8', '9', '*', '0', '.', '/']
@Styles textStyle(){
.backgroundColor(0xd0d0d0)
.width('100%')
.height('100%')
.borderRadius(5)
}
build() {
Column({ space: 5 }) {
Grid() {
GridItem() {
Text('0')
.fontSize(30)
.textStyle()
}.columnStart(1).columnEnd(4)
GridItem() {
Text ('Clear')
.fontSize(16)
.textAlign(TextAlign.Center)
.textStyle()
}.columnStart(1).columnEnd(2)
GridItem() {
Text ('Back')
.fontSize(16)
.textAlign(TextAlign.Center)
.textStyle()
}.columnStart(3).columnEnd(4)
ForEach(this.Number, (day: string) => {
if (day === '0') {
GridItem() {
Text(day)
.fontSize(16)
.textAlign(TextAlign.Center)
.textStyle()
}.columnStart(1).columnEnd(2)
} else {
GridItem() {
Text(day)
.fontSize(16)
.textAlign(TextAlign.Center)
.textStyle()
}
}
})
}
.columnsTemplate('1fr 1fr 1fr 1fr')
.rowsTemplate('2fr 1fr 1fr 1fr 1fr 1fr')
.columnsGap(10)
.rowsGap(15)
.width('90%')
.backgroundColor(0xF0F0F0)
.height('70%')
}.width('100%').margin({ top: 5 })
}
}
```
Below you can see how the calculator displays on a large-screen device.
![](figures/gridExp1.png)
Below you can see how the calculator displays on a small-screen device.
![](figures/gridExp2.png)
en/application-dev/ui/ui-ts-layout-linear.md 0 → 100644
浏览文件 @ 672d91e1
# Linear Layout
The linear layout is the most commonly used layout in development. The child components in a linear layout are arranged one by one in a linear direction, either vertically or horizontally.
You can implement a linear layout through the **[\<Row>](../reference/arkui-ts/ts-container-row.md)** and **[\<Column>](../reference/arkui-ts/ts-container-column.md)** containers. In the **\<Column>** container, child components are arranged vertically. In the **\<Row>** container, child components are arranged horizontally.
## Linear Layout Orientation
The orientation of a linear layout is subject to the container: **\<Row>** or **\<Column>**. You can use the container attributes to adjust the spacing between child components and the horizontal and vertical alignment modes.
1. The **space** attribute sets the spacing between child components so that they are evenly spaced along the main axis.
2. The **alignItems** attribute sets the alignment mode of the child components along the cross axis, which is consistent across screens of various sizes. When the cross axis is vertical, the value type is [VerticalAlign](../reference/arkui-ts/ts-appendix-enums.md#verticalalign). When the cross axis is horizontal, the value type is [HorizontalAlign](../reference/arkui-ts/ts-appendix-enums.md#horizontalalign).
3. The **justifyContent** attribute sets the alignment mode of the child components along the main axis, implementing adaptive layout. The value type is [FlexAlign](../reference/arkui-ts/ts-appendix-enums.md#flexalign).
The table below provides the usage and demo effects.
|Attribute|Description|Row Effect|Column Effect|
|------|---------------------------|----------------------------|---------------------------|
|space |- Horizontal spacing between child components in the horizontal layout<br> - Vertical spacing between child components in the vertical layout| ![](figures/rowspace.png) | ![](figures/columnspace.png) |
|alignItems |Alignment mode of child components along the cross axis of the container.|![](figures/rowalign.png) |![](figures/columnalign.png)|
|justifyContent |Alignment mode of child components along the main axis of the container.|![](figures/rowjustify.png) |![](figures/columnjustify.png)|
## Adaptive Stretching
In linear layout, the **[\<Blank>](../reference/arkui-ts/ts-basic-components-blank.md)** component is commonly used to automatically fill blank space along the main axis of the container, so as to achieve adaptive stretching.
```ts
@Entry
@Component
struct BlankExample {
build() {
Column() {
Row() {
Text('Bluetooth').fontSize(18)
Blank()
Toggle({ type: ToggleType.Switch, isOn: true })
}.backgroundColor(0xFFFFFF).borderRadius(15).padding({ left: 12 }).width('100%')
}.backgroundColor(0xEFEFEF).padding(20).width('100%')
}
}
```
![](figures/blank.gif)
## Adaptive Scaling
Adaptive scaling means that child components scale according to the preset ratio to adapt to the container size on devices of various sizes. Below are the methods to implement adaptive scaling in a linear layout:
1. When the size of the parent container is determined, child components are laid out along the main axis based on the **layoutWeight** attribute settings, with the size settings of the child components ignored. In this way, the child components are adaptively scaled to fill up remaining space, regardless of the screen size.
```ts
@Entry
@Component
struct layoutWeightExample {
build() {
Column() {
Text('1:2:3').width('100%')
Row() {
Column() {
Text('layoutWeight(1)')
.textAlign(TextAlign.Center)
}.layoutWeight(2).backgroundColor(0xffd306).height('100%')
Column() {
Text('layoutWeight(2)')
.textAlign(TextAlign.Center)
}.layoutWeight(4).backgroundColor(0xffed97).height('100%')
Column() {
Text('layoutWeight(6)')
.textAlign(TextAlign.Center)
}.layoutWeight(6).backgroundColor(0xffd306).height('100%')
}.backgroundColor(0xffd306).height('30%')
Text('2:5:3').width('100%')
Row() {
Column() {
Text('layoutWeight(2)')
.textAlign(TextAlign.Center)
}.layoutWeight(2).backgroundColor(0xffd306).height('100%')
Column() {
Text('layoutWeight(5)')
.textAlign(TextAlign.Center)
}.layoutWeight(5).backgroundColor(0xffed97).height('100%')
Column() {
Text('layoutWeight(3)')
.textAlign(TextAlign.Center)
}.layoutWeight(3).backgroundColor(0xffd306).height('100%')
}.backgroundColor(0xffd306).height('30%')
}
}
}
```
![](figures/layoutWeight.gif)
3. When the size of the parent container is determined, set the widths of the child component and sibling components in percentage.
```ts
@Entry
@Component
struct WidthExample {
build() {
Column() {
Row() {
Column() {
Text('left width 20%')
.textAlign(TextAlign.Center)
}.width('20%').backgroundColor(0xffd306).height('100%')
Column() {
Text('center width 50%')
.textAlign(TextAlign.Center)
}.width('50%').backgroundColor(0xffed97).height('100%')
Column() {
Text('right width 30%')
.textAlign(TextAlign.Center)
}.width('30%').backgroundColor(0xffd306).height('100%')
}.backgroundColor(0xffd306).height('30%')
}
}
}
```
![](figures/width.gif)
In the preceding example, the proportion of child components remains unchanged across devices of different sizes.
## Positioning
- Relative layout
You can use the **[offset](../reference/arkui-ts/ts-universal-attributes-location.md)** attribute to set the offset of a component relative to itself, thereby implmenting relative layout. Setting this attribute does not affect the layout of the parent container. It only adjusts the component position during drawing. The linear layout and offset can work together to meet most layout development requirements.
```ts
@Entry
@Component
struct OffsetExample {
@Styles eleStyle() {
.size({ width: 120, height: '50' })
.backgroundColor(0xbbb2cb)
.border({ width: 1 })
}
build() {
Column({ space: 20 }) {
Row() {
Text('1').size({ width: '15%', height: '50' }).backgroundColor(0xdeb887).border({ width: 1 }).fontSize(16)
Text('2 offset(15, 30)')
.eleStyle()
.fontSize(16)
.align(Alignment.Start)
.offset({ x: 15, y: 30 })
Text('3').size({ width: '15%', height: '50' }).backgroundColor(0xdeb887).border({ width: 1 }).fontSize(16)
Text('4 offset(-10%, 20%)')
.eleStyle()
.fontSize(16)
.offset({ x: '-5%', y: '20%' })
}.width('90%').height(150).border({ width: 1, style: BorderStyle.Dashed })
}
.width('100%')
.margin({ top: 25 })
}
}
```
![](figures/offset.gif)
- Absolute layout
In linear layout, you can use the **[position](../reference/arkui-ts/ts-universal-attributes-location.md)** attribute to set the offset of the upper left corner of a component relative to the upper left corner of the parent container, thereby implementing absolute layout. Absolute layout offers poorer adaptability to screen sizes than relative layout.
```ts
@Entry
@Component
struct PositionExample {
@Styles eleStyle(){
.backgroundColor(0xbbb2cb)
.border({ width: 1 })
.size({ width: 120, height: 50 })
}
build() {
Column({ space: 20 }) {
// Set the offset of the upper left corner of the child component relative to the upper left corner of the parent container.
Row() {
Text('position(30, 10)')
.eleStyle()
.fontSize(16)
.position({ x: 10, y: 10 })
Text('position(50%, 70%)')
.eleStyle()
.fontSize(16)
.position({ x: '50%', y: '70%' })
Text('position(10%, 90%)')
.eleStyle()
.fontSize(16)
.position({ x: '10%', y: '80%' })
}.width('90%').height('100%').border({ width: 1, style: BorderStyle.Dashed })
}
.width('90%').margin(25)
}
}
```
![](figures/position.gif)
## Adaptive Extension
Adaptive extension allows users to drag the scrollbar to display content when the content amount displayed on a page is subject to the screen size and the content extends beyond the viewport. Below are the methods to implement adaptive extension in a linear layout:
- **\<List>** component
If the list items cannot be fully displayed on one screen, you can use the scrollbar to let users view the list items in full. Use the **scrollBar** attribute to set the scrollbar status, and the **edgeEffect** to set the rebound effect when the scrollbar has reached the edge.
Vertical list:
```ts
@Entry
@Component
struct ListExample1 {
@State arr: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"]
@State alignListItem: ListItemAlign = ListItemAlign.Start
build() {
Column() {
List({ space: 20, initialIndex: 0 }) {
ForEach(this.arr, (item) => {
ListItem() {
Text('' + item)
.width('100%')
.height(100)
.fontSize(16)
.textAlign(TextAlign.Center)
.borderRadius(10)
.backgroundColor(0xFFFFFF)
}
.border({ width: 2, color: Color.Green })
}, item => item)
}
.border({ width: 2, color: Color.Red, style: BorderStyle.Dashed })
.scrollBar (BarState.On) // ScrollBar status
.edgeEffect(EdgeEffect.Spring) // Rebound effect when the scrollbar has reached the edge
}.width('100%').height('100%').backgroundColor(0xDCDCDC).padding(20)
}
}
```
![](figures/listcolumn.gif)
Horizontal List:
```ts
@Entry
@Component
struct ListExample2 {
@State arr: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"]
@State alignListItem: ListItemAlign = ListItemAlign.Start
build() {
Column() {
List({ space: 20, initialIndex: 0 }) {
ForEach(this.arr, (item) => {
ListItem() {
Text('' + item)
.height('100%')
.width(100)
.fontSize(16)
.textAlign(TextAlign.Center)
.borderRadius(10)
.backgroundColor(0xFFFFFF)
}
.border({ width: 2, color: Color.Green })
}, item => item)
}
.border({ width: 2, color: Color.Red, style: BorderStyle.Dashed })
.scrollBar (BarState.On) // Scrollbar status.
.edgeEffect(EdgeEffect.Spring) // Rebound effect when the scrollbar has reached the edge.
.listDirection(Axis.Horizontal) // Horizontal layout.
}.width('100%').height('100%').backgroundColor(0xDCDCDC).padding(20)
}
}
```
![](figures/listrow.gif)
- **\<Scroll>** component
In linear layout, the **\<Scroll>** component scrolls the content when the layout size of a component exceeds the size of its parent component. You can wrap a **\<Scroll>** component at the outer layer of the **\<Column>** or **\<Row>** component.
Vertical Scroll:
```ts
@Entry
@Component
struct ScrollExample {
scroller: Scroller = new Scroller();
private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
build() {
Scroll(this.scroller) {
Column() {
ForEach(this.arr, (item) => {
Text(item.toString())
.width('90%')
.height(150)
.backgroundColor(0xFFFFFF)
.borderRadius(15)
.fontSize(16)
.textAlign(TextAlign.Center)
.margin({ top: 10 })
}, item => item)
}.width('100%')
}
.backgroundColor(0xDCDCDC)
.scrollable(ScrollDirection.Vertical) // Vertical scrolling.
.scrollBar(BarState.On) // Scrollbar status.
.scrollBarColor(Color.Gray) // Scrollbar color.
.scrollBarWidth(30) // Scrollbar width.
.edgeEffect(EdgeEffect.Spring) // Rebound effect when the scrollbar has reached the edge.
}
}
```
![](figures/scrollcolumn.gif)
Horizontal scrolling:
```ts
@Entry
@Component
struct ScrollExample {
scroller: Scroller = new Scroller();
private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
build() {
Scroll(this.scroller) {
Row() {
ForEach(this.arr, (item) => {
Text(item.toString())
.height('90%')
.width(150)
.backgroundColor(0xFFFFFF)
.borderRadius(15)
.fontSize(16)
.textAlign(TextAlign.Center)
.margin({ left: 10 })
}, item => item)
}.height('100%')
}
.backgroundColor(0xDCDCDC)
.scrollable(ScrollDirection.Horizontal) // Horizontal scrolling.
.scrollBar(BarState.On) // Scrollbar status.
.scrollBarColor(Color.Gray) // Scrollbar color
.scrollBarWidth(30) // Scrollbar width.
.edgeEffect(EdgeEffect.Spring) // Rebound effect when the scrollbar has reached the edge.
}
}
```
![](figures/scrollrow.gif)
en/application-dev/ui/ui-ts-layout-stack.md 0 → 100644
浏览文件 @ 672d91e1
# Statck Layout
The stack layout reserves an area on the screen to display elements in a component and allows the elements to be stacked.
You can implement a stack layout through the **[\<Stack>](../reference/arkui-ts/ts-container-stack.md)** component, which provides a stack container where child components are successively stacked and the latter one overwrites the previous one.
## Alignment
Child components in the container can be aligned in any of the alignment modes described in the table below.
|Name| Description| Image|
|---|---|---|
|TopStart| Top start.|![](figures/stacktopstart.png)|
|Top |Horizontally centered on the top.|![](figures/stacktop.png)|
|TopEnd| Top end.|![](figures/stacktopend.png)|
|Start| Vertically centered start.|![](figures/stackstart.png)|
|Center| Horizontally and vertically centered.|![](figures/stackcenter.png)|
|End| Vertically centered end.|![](figures/stackend.png)|
|BottomStart |Bottom start.|![](figures/stackbottomstart.png)|
|Bottom| Horizontally centered on the bottom.|![](figures/stackbottom.png)|
|BottomEnd| Bottom end.|![](figures/stackbottomend.png)|
## Z-order Control
You can use the **[zIndex](../reference/arkui-ts/ts-universal-attributes-z-order.md)** attribute to set the z-order of a component in the stacking context,
so as to create a custom stacking order of the child components. A larger **zIndex** value indicates a higher display level.
- In the statck layout, if the size of a component is greater than that of the one before it, the one before it is hidden.
```ts
Stack({ alignContent: Alignment.BottomStart }) {
Column() {
Text ('Stacked component 1').textAlign (TextAlign.End).fontSize (20)
}.width(100).height(100).backgroundColor(0xffd306)
Column() {
Text ('Stacked component 2').fontSize (20)
}.width(150).height(150).backgroundColor(Color.Pink)
Column() {
Text ('Stacked component 3').fontSize (20)
}.width(200).height(200).backgroundColor(Color.Grey)
}.margin({ top: 100 }).width(350).height(350).backgroundColor(0xe0e0e0)
```
![](figures/stack2.png)
In the preceding figure, the size of the stacked component 3 is greater than that of all the components before it. Therefore, the first two components are completely hidden. To show these components, modify their **zIndex** attribute settings.
```ts
Stack({ alignContent: Alignment.BottomStart }) {
Column() {
Text ('Stacked component 1').textAlign (TextAlign.End).fontSize (20)
}.width(100).height(100).backgroundColor(0xffd306).zIndex(2)
Column() {
Text ('Stacked component 2').fontSize (20)
}.width(150).height(150).backgroundColor(Color.Pink).zIndex(1)
Column() {
Text ('Stacked component 3').fontSize (20)
}.width(200).height(200).backgroundColor(Color.Grey)
}.margin({ top: 100 }).width(350).height(350).backgroundColor(0xe0e0e0)
```
![](figures/stack1.png)
en/application-dev/ui/ui-ts-performance-improvement-recommendation.md 0 → 100644
浏览文件 @ 672d91e1
# Recommendations for Improving Performance
Poor-performing code may work, but will take away from your application performance. This topic presents a line-up of recommendations that you can take to improve your implementation, thereby avoiding possible performance drop.
## Lazy Loading
When developing a long list, use of loop rendering, as in the code snippet below, can greatly slow down page loading and increase server load.
```ts
@Entry
@Component
struct MyComponent {
@State arr: number[] = Array.from(Array(100), (v,k) =>k); // Construct an array of 0 to 99.
build() {
List() {
ForEach(this.arr, (item: number) => {
ListItem() {
Text(`item value: ${item}`)
}
}, (item: number) => item.toString())
}
}
}
```
The preceding code snippet loads all of the 100 list elements at a time during page loading. This is generally not desirable. Instead, what we need is to load data from the data source and create corresponding components on demand. This can be achieved through lazy loading. The sample code is as follows:
```ts
class BasicDataSource implements IDataSource {
private listeners: DataChangeListener[] = []
public totalCount(): number {
return 0
}
public getData(index: number): any {
return undefined
}
registerDataChangeListener(listener: DataChangeListener): void {
if (this.listeners.indexOf(listener) < 0) {
console.info('add listener')
this.listeners.push(listener)
}
}
unregisterDataChangeListener(listener: DataChangeListener): void {
const pos = this.listeners.indexOf(listener);
if (pos >= 0) {
console.info('remove listener')
this.listeners.splice(pos, 1)
}
}
notifyDataReload(): void {
this.listeners.forEach(listener => {
listener.onDataReloaded()
})
}
notifyDataAdd(index: number): void {
this.listeners.forEach(listener => {
listener.onDataAdd(index)
})
}
notifyDataChange(index: number): void {
this.listeners.forEach(listener => {
listener.onDataChange(index)
})
}
notifyDataDelete(index: number): void {
this.listeners.forEach(listener => {
listener.onDataDelete(index)
})
}
notifyDataMove(from: number, to: number): void {
this.listeners.forEach(listener => {
listener.onDataMove(from, to)
})
}
}
class MyDataSource extends BasicDataSource {
private dataArray: string[] = ['item value: 0', 'item value: 1', 'item value: 2']
public totalCount(): number {
return this.dataArray.length
}
public getData(index: number): any {
return this.dataArray[index]
}
public addData(index: number, data: string): void {
this.dataArray.splice(index, 0, data)
this.notifyDataAdd(index)
}
public pushData(data: string): void {
this.dataArray.push(data)
this.notifyDataAdd(this.dataArray.length - 1)
}
}
@Entry
@Component
struct MyComponent {
private data: MyDataSource = new MyDataSource()
build() {
List() {
LazyForEach(this.data, (item: string) => {
ListItem() {
Row() {
Text(item).fontSize(20).margin({ left: 10 })
}
}
.onClick(() => {
this.data.pushData('item value: ' + this.data.totalCount())
})
}, item => item)
}
}
}
```
![LazyForEach1](figures/LazyForEach1.gif)
The preceding code initializes only three list elements during page loading and loads a new list item each time a list element is clicked.
## Prioritizing Conditional Rendering over Visibility Control
Use of the visibility attribute to hide or show a component, as in the code snippet below, results in re-creation of the component, leading to performance drop.
```ts
@Entry
@Component
struct MyComponent {
@State isVisible: Visibility = Visibility.Visible;
build() {
Column() {
Button ("Show/Hide")
.onClick(() => {
if (this.isVisible == Visibility.Visible) {
this.isVisible = Visibility.None
} else {
this.isVisible = Visibility.Visible
}
})
Row().visibility(this.isVisible)
.width(300).height(300).backgroundColor(Color.Pink)
}.width('100%')
}
}
```
To avoid the preceding issue, use the **if** statement instead. The sample code is as follows:
```ts
@Entry
@Component
struct MyComponent {
@State isVisible: boolean = true;
build() {
Column() {
Button ("Show/Hide")
.onClick(() => {
this.isVisible = !this.isVisible
})
if (this.isVisible) {
Row()
.width(300).height(300).backgroundColor(Color.Pink)
}
}.width('100%')
}
}
```
![isVisible](figures/isVisible.gif)
## Prioritizing Flex over Column/Row
By default, the flex container needs to re-lay out flex items to comply with the **flexShrink** and **flexGrow** settings. This may result in drop in rendering performance.
```ts
@Entry
@Component
struct MyComponent {
build() {
Flex({ direction: FlexDirection.Column }) {
Flex().width(300).height(200).backgroundColor(Color.Pink)
Flex().width(300).height(200).backgroundColor(Color.Yellow)
Flex().width(300).height(200).backgroundColor(Color.Grey)
}
}
}
```
To avoid the preceding issue, replace **Flex** with **Column** and **Row**, which can create the same page layout as **Flex** does.
```ts
@Entry
@Component
struct MyComponent {
build() {
Column() {
Row().width(300).height(200).backgroundColor(Color.Pink)
Row().width(300).height(200).backgroundColor(Color.Yellow)
Row().width(300).height(200).backgroundColor(Color.Grey)
}
}
}
```
![flex1](figures/flex1.PNG)
## Setting Width and Height for \<List> Components
When a **\<List>** component is nested within a **\<Scroll>** component, all of its content will be loaded if its width and height is not specified, which may result in performance drop.
```ts
@Entry
@Component
struct MyComponent {
private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
build() {
Scroll() {
List() {
ForEach(this.arr, (item) => {
ListItem() {
Text(`item value: ${item}`).fontSize(30).margin({ left: 10 })
}.height(100)
}, (item) => item.toString())
}
}.backgroundColor(Color.Pink)
}
}
```
Therefore, in the above scenario, you are advised to set the width and height for the **\<List>** component as follows:
```ts
@Entry
@Component
struct MyComponent {
private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
build() {
Scroll() {
List() {
ForEach(this.arr, (item) => {
ListItem() {
Text(`item value: ${item}`).fontSize(30).margin({ left: 10 })
}.height(100)
}, (item) => item.toString())
}.width('100%').height(500)
}.backgroundColor(Color.Pink)
}
}
```
![list1](figures/list1.gif)
## Minimizing White Blocks During Swiping
To minimize white blocks during swiping, expand the UI loading range by increasing the value of **cachedCount** for the **\<List>** and **\<Grid>** components. **cachedCount** indicates the number of list or grid items preloaded outside of the screen.
If an item needs to request an online image, set **cachedCount** as appropriate so that the image is downloaded in advance before the item comes into view on the screen, thereby reducing the number of white blocks.
The following is an example of using **cachedCount**:
```ts
@Entry
@Component
struct MyComponent {
private source: MyDataSource = new MyDataSource();
build() {
List() {
LazyForEach(this.source, item => {
ListItem() {
Text("Hello" + item)
.fontSize(50)
.onAppear(() => {
console.log("appear:" + item)
})
}
})
}.cachedCount(3) // Increase the number of list or grid items preloaded outside of the screen.
}
}
class MyDataSource implements IDataSource {
data: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
public totalCount(): number {
return this.data.length
}
public getData(index: number): any {
return this.data[index]
}
registerDataChangeListener(listener: DataChangeListener): void {
}
unregisterDataChangeListener(listener: DataChangeListener): void {
}
}
```
![list2](figures/list2.gif)
**Instructions**
A greater **cachedCount** value may result in higher CPU and memory overhead of the UI. Adjust the value by taking into account both the comprehensive performance and user experience.
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或