Skip to content

D
Docs

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

通知 161
Star 293
Fork 28
D
Docs
未验证 提交 e475a982 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!18240 翻译完成 17277+17318：ui文件夹更新 

Merge pull request !18240 from ester.zhou/TR-17277
上级 fb5d659b b027ebc9
隐藏空白更改
内联 并排
Showing with 1946 addition and 0 deletion
en/application-dev/ui/arkts-common-components-switch.md 0 → 100644
浏览文件 @ e475a982
# Toggle
The **\<Toggle>** component provides a clickable element in the check box, button, or switch type, typically used to switch between two states. For details, see [Toggle](../reference/arkui-ts/ts-basic-components-toggle.md).
## Creating a Toggle
You can create a toggle by calling the following API:
```ts
Toggle(options: { type: ToggleType, isOn?: boolean })
```
Creates a toggle. In this API, **ToggleType** indicates the toggle type, which can be **Button**, **Checkbox**, or **Switch**, and **isOn** specifies whether the toggle is turned on. The API can be called in either of the following ways:
- Create a toggle that does not contain child components.
This can be achieved by calling the API with **ToggleType** set to **Checkbox** or **Switch**.
```ts
Toggle({ type: ToggleType.Checkbox, isOn: false })
Toggle({ type: ToggleType.Checkbox, isOn: true })
```
![en-us_image_0000001562940485](figures/en-us_image_0000001562940485.png)
```ts
Toggle({ type: ToggleType.Switch, isOn: false })
Toggle({ type: ToggleType.Switch, isOn: true })
```
![en-us_image_0000001511421228](figures/en-us_image_0000001511421228.png)
- Create a toggle that contains child components.
This can be achieved by calling the API with **ToggleType** set to **Button**. If the child component has text set, the text content is displayed inside the button.
```ts
Toggle({ type: ToggleType.Button, isOn: false }) {
Text('status button')
.fontColor('#182431')
.fontSize(12)
}.width(100)
Toggle({ type: ToggleType.Button, isOn: true }) {
Text('status button')
.fontColor('#182431')
.fontSize(12)
}.width(100)
```
![en-us_image_0000001511900404](figures/en-us_image_0000001511900404.png)
## Setting Styles
- Use the **selectedColor** attribute to set the background color of the toggle for when it is turned on.
```ts
Toggle({ type: ToggleType.Button, isOn: true }) {
Text('status button')
.fontColor('#182431')
.fontSize(12)
}.width(100).selectedColor(Color.Pink)
Toggle({ type: ToggleType.Checkbox, isOn: true })
.selectedColor(Color.Pink)
Toggle({ type: ToggleType.Switch, isOn: true })
.selectedColor(Color.Pink)
```
![en-us_image_0000001563060657](figures/en-us_image_0000001563060657.png)
- Use the **switchPointColor** attribute to set the color of the circular slider. This attribute is valid only when **type** of the toggle is set to **ToggleType.Switch**.
```ts
Toggle({ type: ToggleType.Switch, isOn: false })
.switchPointColor(Color.Pink)
Toggle({ type: ToggleType.Switch, isOn: true })
.switchPointColor(Color.Pink)
```
![en-us_image_0000001511421232](figures/en-us_image_0000001511421232.png)
## Adding Events
The **\<Toggle>** component supports the [universal events](../reference/arkui-ts/ts-universal-events-click.md). In addition, it can be bound to the **onChange** event so that it responds with custom behavior after being turned on or off.
```ts
Toggle({ type: ToggleType.Switch, isOn: false })
.onChange((isOn: boolean) => {
if(isOn) {
// Operation
}
})
```
## Example Scenario
In this example, the **\<Toggle>** component is used to enable or disable Bluetooth.
```ts
// xxx.ets
import promptAction from '@ohos.promptAction';
@Entry
@Component
struct ToggleExample {
build() {
Column() {
Row() {
Text("Bluetooth Mode")
.height(50)
.fontSize(16)
}
Row() {
Text("Bluetooth")
.height(50)
.padding({left: 10})
.fontSize(16)
.textAlign(TextAlign.Start)
.backgroundColor(0xFFFFFF)
Toggle({ type: ToggleType.Switch })
.margin({left: 200, right: 10})
.onChange((isOn: boolean) => {
if(isOn) {
promptAction.showToast({ message: 'Bluetooth is on.' })
} else {
promptAction.showToast({ message: 'Bluetooth is off.' })
}
})
}
.backgroundColor(0xFFFFFF)
}
.padding(10)
.backgroundColor(0xDCDCDC)
.width('100%')
.height('100%')
}
}
```
![en-us_image_0000001511740448](figures/en-us_image_0000001511740448.png)
en/application-dev/ui/arkts-graphics-display.md 0 → 100644
浏览文件 @ e475a982
# Displaying Images
More often than not, you may need to display images in your application, for example, logos in buttons, online images, and local images. To do so, you need to use the **\<Image>** component, which supports a wide range of image formats, including PNG, JPG, BMP, SVG, and GIF. For details, see [Image](../reference/arkui-ts/ts-basic-components-image.md).
You can call the API in the following format to create an image:
```ts
Image(src: string | Resource | media.PixelMap)
```
Obtains a local or online image from the image data source specified by **src**. For details about how to load the data source, see [Loading Image Resources](#loading-image-resources).
## Loading Image Resources
The **\<Image>** component supports two types of images: archived and pixel map.
### Archived Type Data Source
Data sources of the archived type can be classified into local resources, online resources, **Resource** objects, media library data share resources, and Base64 resources.
- Local resources
Create a folder and place a local image in any position in the **ets** folder.
In the **\<Image>** component, import the local image path to display the image. The root directory is the **ets** folder.
```ts
Image('images/view.jpg')
.width(200)
```
- Online resources
To use online images, first apply for the **ohos.permission.INTERNET** permission. For details, see [Applying for Permissions](../security/accesstoken-guidelines.md). Under this scenario, the **src** parameter of the **\<Image>** component is the URL of the online image.
```ts
Image('https://www.example.com/example.JPG') // Replace the URL with the actual URL.
```
- **Resource** objects
**Resource** objects can be used to import images across bundles and modules. All images in the **resources** folder can be read and converted to the **Resource** objects through **$r**.
**Figure 1** resources folder
![image-resource](figures/image-resource.jpg)
API:
```
Image($r('app.media.icon'))
```
You can also place the images in the **rawfile** folder.
**Figure 2** rawfile folder
![image-rawfile](figures/image-rawfile.jpg)
API:
```
Image($rawfile('snap'))
```
- Media library data share resources
To display images from the media library, use a path string that starts with **datashare://**.
1. Call the API to obtain the image URL in the media library.
​
```ts
import picker from '@ohos.file.picker';
@Entry
@Component
struct Index {
@State imgDatas: string[] = [];
// Obtain the image URL set.
getAllImg() {
let photoPicker = new picker.PhotoViewPicker();
let result = new Array<string>();
try {
let PhotoSelectOptions = new picker.PhotoSelectOptions();
PhotoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE;
PhotoSelectOptions.maxSelectNumber = 5;
let photoPicker = new picker.PhotoViewPicker();
photoPicker.select(PhotoSelectOptions).then((PhotoSelectResult) => {
this.imgDatas = PhotoSelectResult.photoUris;
console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult));
}).catch((err) => {
console.error(`PhotoViewPicker.select failed with. Code: ${err.code}, message: ${err.message}`);
});
} catch (err) {
console.error(`PhotoViewPicker failed with. Code: ${err.code}, message: ${err.message}`); }
}
// Call the preceding function in aboutToAppear to obtain the URLs of all images in the gallery and store the URLs in imgDatas.
async aboutToAppear() {
this.getAllImg();
}
// Use the URL of imgDatas to load the image.
build() {
Column() {
Grid() {
ForEach(this.imgDatas, item => {
GridItem() {
Image(item)
.width(200)
}
}, item => JSON.stringify(item))
}
}.width('100%').height('100%')
}
}
```
2. Check the format of the URL obtained from the media library is as follows:
​
```ts
Image('file://media/5')
.width(200)
```
- base64
As shown above, the URL format is data:image/[png|jpeg|bmp|webp];base64,[base64 data], in which **[base64 data]** indicates Base64 string data.
Base64 strings are widely used on web pages for storing pixel data of images.
### Pixel Map
A pixel map is a pixel image obtained after image decoding. For details, see [Image Development](../media/image-overview.md). In the following example, the data returned by the loaded online image is decoded into a pixel map, which is then displayed on the **\<Image>** component.
1. Create a **PixelMap** state variable.
```ts
@State image: PixelMap = undefined;
```
2. Reference multimedia.
Request an online image and implement transcoding to generate a pixel map.
1. Reference the network access permission and media library permission.
​
```ts
import http from '@ohos.net.http';
import ResponseCode from '@ohos.net.http';
import image from '@ohos.multimedia.image';
```
2. Enter the online image address.
​
```ts
http.createHttp().request("https://www.example.com/xxx.png",
(error, data) => {
if (error){
console.error(`http reqeust failed with. Code: ${error.code}, message: ${error.message}`);
} else {
}
}
)
```
3. Transcode the data returned by the online image address to a pixel map.
​
```ts
let code = data.responseCode;
if(ResponseCode.ResponseCode.OK === code) {
let imageSource = image.createImageSource(data.result);
let options = {
alphaType: 0, // Alpha type.
editable: false, // Whether the image is editable.
pixelFormat: 3, // Pixel format.
scaleMode: 1, // Scale mode.
size: {height: 100, width: 100}
} // Image size.
imageSource.createPixelMap(options).then((pixelMap) => {
this.image = pixelMap
})
```
4. Display the image.
​
```ts
Button ("Get Online Image")
.onClick(() => {
this.httpRequest()
})
Image(this.image).height(100).width(100)
```
## Display the vector image.
The **\<Image>** component can display vector images in SVG format. The supported SVG labels are **svg**, **rect**, **circle**, **ellipse**, **path**, **line**, **polyline**, **polygon**, and **animate**.
You can use the **fillColor** attribute to change the fill color of an SVG image.
```ts
Image($r('app.media.cloud')).width(50)
.fillColor(Color.Blue)
```
**Figure 3** Original image
![screenshot_20230223_141141](figures/screenshot_20230223_141141.png)
**Figure 4** SVG image after the fill color is set
![screenshot_20230223_141404](figures/screenshot_20230223_141404.png)
## Adding Attributes
Setting attributes for the **\<Image>** component can spruce up the image with custom effects. The following are examples of common attributes. For details about all attributes, see [Image](../reference/arkui-ts/ts-basic-components-image.md).
### Setting the Image Scale Mode
The **objectFit** attribute is used to scale an image to fit it into a container whose height and width are determined.
```ts
@Entry
@Component
struct MyComponent {
scroller: Scroller = new Scroller()
build() {
Scroll(this.scroller) {
Row() {
Image($r('app.media.img_2')).width(200).height(150)
.border({ width: 1 })
.objectFit(ImageFit.Contain).margin(15) // The image is scaled with its aspect ratio retained to fit within the display boundaries.
.overlay('Contain', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
Image($r('app.media.ic_img_2')).width(200).height(150)
.border({ width: 1 })
.objectFit(ImageFit.Cover).margin(15)
// The image is scaled with its aspect ratio retained for both sides to be greater than or equal to the display boundaries.
.overlay('Cover', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
Image($r('app.media.img_2')).width(200).height(150)
.border({ width: 1 })
// The image is scaled automatically to fit the display area.
.objectFit(ImageFit.Auto).margin(15)
.overlay('Auto', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
}
Row() {
Image($r('app.media.img_2')).width(200).height(150)
.border({ width: 1 })
.objectFit(ImageFit.Fill).margin(15)
// The image is scaled to fill the display area, and its aspect ratio is not retained.
.overlay('Fill', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
Image($r('app.media.img_2')).width(200).height(150)
.border({ width: 1 })
// The image content is displayed with its aspect ratio retained. The size is smaller than or equal to the original size.
.objectFit(ImageFit.ScaleDown).margin(15)
.overlay('ScaleDown', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
Image($r('app.media.img_2')).width(200).height(150)
.border({ width: 1 })
// The original size is retained.
.objectFit(ImageFit.None).margin(15)
.overlay('None', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
}
}
}
}
```
![en-us_image_0000001511421240](figures/en-us_image_0000001511421240.png)
### Synchronously Loading Images
Generally, the image loading process is performed asynchronously to avoid blocking the main thread and to streamline UI interaction. In certain cases, however, the image may flicker when refreshed. If this occurs, you can use the **syncLoad** attribute to load the image synchronously to avoid flickering. You are not advised to use this attribute when the image loading takes a long time. Otherwise, the page may fail to respond.
```ts
Image($r('app.media.icon'))
.syncLoad(true)
```
## Adding Events
By binding the **onComplete** event to the **\<Image>** component, you can obtain necessary information about the image after the image is successfully loaded. You can also bind the **onError** event to obtain error information when the image fails to be loaded.
```ts
@Entry
@Component
struct MyComponent {
@State widthValue: number = 0
@State heightValue: number = 0
@State componentWidth: number = 0
@State componentHeight: number = 0
build() {
Column() {
Row() {
Image($r('app.media.ic_img_2'))
.width(200)
.height(150)
.margin(15)
.onComplete((msg: {
width: number,
height: number,
componentWidth: number,
componentHeight: number
}) => {
this.widthValue = msg.width
this.heightValue = msg.height
this.componentWidth = msg.componentWidth
this.componentHeight = msg.componentHeight
})
// If the image fails to be obtained, print the result.
.onError(() => {
console.info('load image fail')
})
.overlay('\nwidth: ' + String(this.widthValue) + ', height: ' + String(this.heightValue) + '\ncomponentWidth: ' + String(this.componentWidth) + '\ncomponentHeight: ' + String(this.componentHeight), {
align: Alignment.Bottom,
offset: { x: 0, y: 60 }
})
}
}
}
}
```
![en-us_image_0000001511740460](figures/en-us_image_0000001511740460.png)
en/application-dev/ui/arkts-layout-development-create-list.md 0 → 100644
浏览文件 @ e475a982
# Creating a List
## Overview
A list is a container that displays a collection of items. If the list items go beyond the screen, the list can scroll to reveal the content off the screen. A list is applicable for presenting similar data types or data type sets, such as images and text. For example, it can be used to present a collection of contacts, songs, and items to shop.
Use lists to easily and efficiently display structured, scrollable information. You can provide a single view of rows or columns by arranging the [\<ListItemGroup>](../reference/arkui-ts/ts-container-listitemgroup.md) or [\<ListItem>](../reference/arkui-ts/ts-container-listitem.md) child components linearly in a vertical or horizontal direction in the [\<List>](../reference/arkui-ts/ts-container-list.md) component, or use [ForEach](../quick-start/arkts-rendering-control-foreach.md) to iterate over a group of rows or columns, or mix any number of single views and **ForEach** structures to build a list. The **\<List>** component supports the generation of child components in various [rendering](../quick-start/arkts-rendering-control-overview.md) modes, including conditional rendering, rendering of repeated content, and lazy data loading.
## Layout and Constraints
A list automatically arranges child components in the direction it scrolls. Adding or removing child components from the list will trigger re-arrangement of the child components.
As shown in the following figure, in a vertical list, **\<ListItemGroup>** or **\<ListItem>** components are automatically arranged vertically.
**\<ListItemGroup>** is used to display list data by group. Its child component is also **\<ListItem>**. **\<ListItem>** represents a list item, which can contain a single child component.
**Figure 1** Relationships between \<List>, \<ListItemGroup>, and \<ListItem>
![en-us_image_0000001562940589](figures/en-us_image_0000001562940589.png)
>**NOTE**
>
>A **\<List>** component can contain only **\<ListItemGroup>** or **\<ListItem>** as its child components. **\<ListItemGroup>** and **\<ListItem>** must be used together with **\<List>**.
### Layout
Apart from the aforementioned features, the list is also able to adapt to the number of elements in the cross axis direction.
When used in vertical layout, the list can contain one or more scrollable columns, as shown below.
**Figure 2** Vertical scrolling list (left: one column; right: multiple columns)
![en-us_image_0000001511580940](figures/en-us_image_0000001511580940.png)
When used in horizontal layout, the list can contain one or more scrollable rows, as shown below.
**Figure 3** Horizontal scrolling list (left: one column; right: multiple columns)
![en-us_image_0000001511421344](figures/en-us_image_0000001511421344.png)
### Constraints
The main axis direction of a list refers to the direction in which the child component columns are laid out and in which the list scrolls. An axis perpendicular to the main axis is referred to as a cross axis, and the direction of the cross axis is perpendicular to a direction of the main axis.
As shown below, the main axis of a vertical list is in the vertical direction, and the cross axis is in the horizontal direction. The main axis of a horizontal list is in the horizontal direction, and the cross axis is in the horizontal direction.
**Figure 4** Main axis and cross axis of the list
![en-us_image_0000001562940581](figures/en-us_image_0000001562940581.png)
If a size is set for the main axis or cross axis of the **\<List>** component, it is used as the size of the component in the corresponding direction.
If no size is set for the main axis of the **\<List>** component, the size of the **\<List>** component in the main axis direction automatically adapts to the total size of its child components, as long as the total size of the child components in the main axis direction does not exceed the size of the parent component of **\<List>**.
In the example shown below, no height is set for vertical list B, and the height of its parent component A is 200 vp. If the total height of all child components C is 150 vp, the height of list B is 150 vp.
**Figure 5** Main axis height constraint example 1 (A: parent component of \<List>; B: \<List> component; C: all child components of \<List>)
![en-us_image_0000001511580956](figures/en-us_image_0000001511580956.png)
If the total size of the child components in the main axis direction is greater than the size of the parent component of **\<List>**, the size of the **\<List>** component in the main axis direction automatically adapts to the size of its parent component.
In the example shown below, still no height is set for vertical list B, and the height of its parent component A is 200 vp. If the total height of all child components C is 300 vp, the height of list B is 200 vp.
**Figure 6** Main axis height constraint example 2 (A: parent component of \<List>; B: \<List> component; C: all child components of \<List>)
![en-us_image_0000001511740548](figures/en-us_image_0000001511740548.png)
If no size is set for the cross axis of the **\<List>** component, the size of the **\<List>** component in the cross axis direction automatically adapts to the size of its parent component.
## Developing the Layout
### Setting the Main Axis Direction
By default, the main axis of the **\<List>** component runs in the vertical direction. This means that you can create a vertical scrolling list without the need to manually set the list direction.
To create a horizontal scrolling list, set the **listDirection** attribute to **Axis.Horizontal**. The default value of **listDirection** is **Axis.Vertical**.
```ts
List() {
...
}
.listDirection(Axis.Horizontal)
```
### Setting the Cross Axis Layout
The cross axis layout of the **\<List>** component can be set using the **lanes** and **alignListItem** attributes. The **lanes** attribute controls the number of list items along the cross axis, and the **alignListItem** attribute controls the alignment mode of child components along the cross axis.
The lanes attribute of the **\<List>** component is useful in building a list that auto-adapts the numbers of rows or columns on devices of different sizes. Its value type is number or [LengthConstrain](../reference/arkui-ts/ts-types.md#lengthconstrain). If you are building a two-column vertical list shown on the right in Figure 2, set the **lanes** attribute to **2**. The default value of **lanes** is **1**.
```ts
List() {
...
}
.lanes(2)
```
If set to a value of the LengthConstrain type, the **lanes** attribute determines the number of rows or columns based on the LengthConstrain settings and the size of the **\<List>** component.
```ts
List() {
...
}
.lanes({ minLength: 200, maxLength: 300 })
```
For example, if the **lanes** attribute is set to **{ minLength: 200, maxLength: 300 }** for a vertical list, then:
- When the list width is 300 vp, the list contains one column, because **minLength** is 200 vp.
- When the list width changes to 400 vp, which is twice that of the **minLength** value, the list is automatically adapted to two-column.
>**NOTE**
>
>When the **lanes** attribute is set to a value of the LengthConstrain type, the value is used only to calculate the number of rows or columns in the list and does not affect the size of the list items.
With regard to a vertical list, when the **alignListItem** attribute is set to **ListItemAlign.Center**, list items are center-aligned horizontally; when the **alignListItem** attribute is at its default value **ListItemAlign.Start**, list items are aligned toward the start edge of the cross axis in the list.
```ts
List() {
...
}
.alignListItem(ListItemAlign.Center)
```
## Displaying Data in the List
The list displays a collection of items horizontally or vertically and can scroll to reveal content off the screen. In the simplest case, a **\<List>** component is statically made up of **\<ListItem>** components.
**Figure 7** Example of a city list
![en-us_image_0000001563060761](figures/en-us_image_0000001563060761.png)
```ts
@Component
struct CityList {
build() {
List() {
ListItem() {
Text('Beijing').fontSize(24)
}
ListItem() {
Text('Hangzhou').fontSize(24)
}
ListItem() {
Text('Shanghai').fontSize(24)
}
}
.backgroundColor('#FFF1F3F5')
.alignListItem(ListItemAlign.Center)
}
}
```
Each **\<ListItem>** component can contain only one root child component. Therefore, it does not allow use of child components in tile mode. If tile mode is required, you need to encapsulate the child components into a container or create a custom component.
**Figure 8** Example of a contacts list
![en-us_image_0000001511421328](figures/en-us_image_0000001511421328.png)
As shown above, as a list item, each contact has a profile picture and a name. To present it, you can encapsulate **\<Image>** and **\<Text>** components into a **\<Row>** container.
```ts
List() {
ListItem() {
Row() {
Image($r('app.media.iconE'))
.width(40)
.height(40)
.margin(10)
Text ('Tom')
.fontSize(20)
}
}
ListItem() {
Row() {
Image($r('app.media.iconF'))
.width(40)
.height(40)
.margin(10)
Text ('Tracy')
.fontSize(20)
}
}
}
```
## Iterating List Content
Compared with a static list, a dynamic list is more common in applications. You can use [ForEach](../quick-start/arkts-rendering-control-foreach.md) to obtain data from the data source and create components for each data item.
For example, when creating a contacts list, you can store the contact name and profile picture data in a **Contact** class structure to the **contacts** array, and nest **ListItem**s in **ForEach**, thereby reducing repeated code needed for tiling similar list items.
```ts
import util from '@ohos.util';
class Contact {
key: string = util.generateRandomUUID(true);
name: string;
icon: Resource;
constructor(name: string, icon: Resource) {
this.name = name;
this.icon = icon;
}
}
@Entry
@Component
struct SimpleContacts {
private contacts = [
new Contact ('Tom', $r ("app.media.iconA")),
new Contact ('Tracy', $r ("app.media.iconB")),
...
]
build() {
List() {
ForEach(this.contacts, (item: Contact) => {
ListItem() {
Row() {
Image(item.icon)
.width(40)
.height(40)
.margin(10)
Text(item.name).fontSize(20)
}
.width('100%')
.justifyContent(FlexAlign.Start)
}
}, item => item.key)
}
.width('100%')
}
}
```
In the **\<List>** component, **ForEach** can be used to render **\<ListItemGroup>** items as well as **\<ListItem>** items. For details, see [Adding Grouping Support](#adding-grouping-support).
## Customizing the List Style
### Setting the Spacing
When initializing a list, you can use the **space** parameter to add spacing between list items. In the following example, a 10vp spacing is added between list items along the main axis:
```ts
List({ space: 10 }) {
...
}
```
### Adding Dividers
A divider separates UI items to make them easier to identify. In the following figure, a divider is added between the setting items. Note that since the icons are easy to identify in their own right, the divers do not extend below the icons.
**Figure 9** Using dividers between the setting items
![en-us_image_0000001511580960](figures/en-us_image_0000001511580960.png)
To add dividers between items in a **\<List>** component, you can use its **divider** attribute, sprucing up the dividers with the following style attributes:<br> **strokeWidth** and **color**: indicate the stroke width and color of the diver, respectively.
**startMargin** and **endMargin**: indicate the distance between the divider and the start edge and end edge of the list, respectively.
```ts
List() {
...
}
.divider({
strokeWidth: 1,
startMargin: 60,
endMargin: 10,
color: '#ffe9f0f0'
})
```
This example draws a divider with a stroke thickness of 1 vp from a position 60 vp away from the start edge of the list to a position 10 vp away from the end edge of the list. The effect is shown in Figure 8.
>**NOTE**
>
>1. The stroke width of the divider causes some space between list items. If the content spacing set for the list is smaller than the stroke width of the divider, the latter is used instead.
>
>2. When a list contains multiple columns, the **startMargin** and **endMargin** attributes of the divider apply to each column.
>
>3. The divider is drawn between list items. No divider is drawn above the first list item and below the last list item.
### Adding a Scrollbar
When the total height (width) of list items exceeds the screen height (width), the list can scroll vertically (horizontally). The scrollbar of a list enables users to quickly navigate the list content, as shown below.
**Figure 10** Scrollbar of a list
![en-us_image_0000001511740544](figures/en-us_image_0000001511740544.gif)
When using the **\<List>** component, you can use the **scrollBar** attribute to control the display of the list scrollbar. The value type of **scrollBar** is [BarState](../reference/arkui-ts/ts-appendix-enums.md#barstate). When the value is **BarState.Auto**, the scrollbar is displayed as required: It is displayed when the scrollbar area is touched and becomes thicker when being dragged; it automatically disappears after 2 seconds of inactivity.
```ts
List() {
...
}
.scrollBar(BarState.Auto)
```
## Adding Grouping Support
By allowing data to be displayed in groups in the list, you make the list easier to scan and navigate. Grouping is common in real-world applications. For example, the contacts list below use grouping.
**Figure 11** Contacts list with grouping
![en-us_image_0000001511580948](figures/en-us_image_0000001511580948.png)
You can use **\<ListItemGroup>** to group items in the **\<List>** component to build a two-dimensional list.
A **\<List>** component allows one or more **\<ListItemGroup>** child components. By default, the width of **\<ListItemGroup>** is equal to that of **\<List>**. When initializing **\<ListItemGroup>**, you can use the **header** parameter to set its header.
```ts
@Component
struct ContactsList {
...
@Builder itemHead(text: string) {
// Header of the list group, corresponding to the group A and B locations.
Text(text)
.fontSize(20)
.backgroundColor('#fff1f3f5')
.width('100%')
.padding(5)
}
build() {
List() {
ListItemGroup({ header: this.itemHead('A') }) {
// Render the repeated list items of group A.
...
}
...
ListItemGroup({ header: this.itemHead('B') }) {
// Render the repeated list items of group B.
...
}
...
}
}
}
```
If the structures of multiple **\<ListItemGroup>** components are similar, you can combine the data of these components into an array and use **ForEach** to render them cyclically. For example, in the contacts list, the **contacts** data of each group (for details, see [Iterating List Content](#iterating-list-content)) and the **title** data of the corresponding group are combined and defined as the **contactsGroups** array.
```ts
contactsGroups: object[] = [
{
title: 'A',
contacts: [
new Contact('Alice', $r('app.media.iconA')),
new Contact ('Ann', $r ('app.media.iconB')),
new Contact('Angela', $r('app.media.iconC')),
],
},
{
title: 'B',
contacts: [
new Contact ('Ben', $r ('app.media.iconD')),
new Contact ('Bryan', $r ('app.media.iconE')),
],
},
...
]
```
Then, with rendering of **contactsGroups** in **ForEach**, a contact list with multiple groups is implemented.
```ts
List() {
// Render the <ListItemGroup> components cyclically. contactsGroups is the data set of contacts and titles of multiple groups.
ForEach(this.contactsGroups, item => {
ListItemGroup({ header: this.itemHead(item.title) }) {
// Render <ListItem> components cyclically.
ForEach(item.contacts, (contact) => {
ListItem() {
...
}
}, item => item.key)
}
...
})
}
```
## Adding a Sticky Header
The sticky header is a common pattern for keeping the header in the same place on the screen while the user scrolls down the list. As shown in the following figure, when you scroll through group A in the contacts list, the header of group B is always below group A. When you start scrolling through group B, the header of group B is fixed at the top of the screen. After group B has been scrolled to the bottom, the header of group B is replaced by the header of next group.
Sticky headers not only signify the representation and usage of data in the respective groups, but also help users navigate through a large amount of information, thereby avoiding unnecessary scrolling between the top of the area where the header is located and the area of interest.
**Figure 12** Sticky header
![en-us_image_0000001511740552](figures/en-us_image_0000001511740552.gif)
You can set a sticky header or footer for a **\<ListItemGroup>** component by setting the **sticky** attribute of its parent **\<List>** component.
Setting the **sticky** attribute to **StickyStyle.Header** implements a sticky header. To implement a sticky footer, use the **footer** parameter to initialize the footer of **\<ListItemGroup>** and set the **sticky** attribute to **StickyStyle.Footer**.
```ts
@Component
struct ContactsList {
// Define the contactsGroups array.
...
@Builder itemHead(text: string) {
// Header of the list group, corresponding to the group A and B locations.
Text(text)
.fontSize(20)
.backgroundColor('#fff1f3f5')
.width('100%')
.padding(5)
}
build() {
List() {
// Render the <ListItemGroup> components cyclically. contactsGroups is the data set of contacts and titles of multiple groups.
ForEach(this.contactsGroups, item => {
ListItemGroup({ header: this.itemHead(item.title) }) {
// Render <ListItem> components cyclically.
ForEach(item.contacts, (contact) => {
ListItem() {
...
}
}, item => item.key)
}
...
})
}
.sticky(StickyStyle.Header) // Set a sticky header.
}
}
```
## Controlling the Scrolling Position
In some cases you may want to control the scrolling position of a list. For example, when there are a huge number of items in the news page list, you may want to allow users to quickly jump to the top or bottom of the list after they have scrolled to a certain point. Below is an example.
**Figure 13** Returning to the top of the list
![en-us_image_0000001511900520](figures/en-us_image_0000001511900520.gif)
When the **\<List>** component is initialized, you can use the **scroller** parameter to bind a [Scroller](../reference/arkui-ts/ts-container-scroll.md#scroller) object to control the scrolling of the list. In this example of a news page list, the **scrollToIndex** API of the **Scroller** object is used to scroll the list to the list item with the specified index. This allows the user to return to the top of the list by clicking a specific button.
First, you need to create a **Scroller** object **listScroller**.
```ts
private listScroller: Scroller = new Scroller();
```
Then, use **listScroller** to initialize the **scroller** parameter to bind it with the **\<List>** component. Set **scrollToIndex** to **0**, meaning to return to the top of the list.
```ts
Stack({ alignContent: Alignment.BottomEnd }) {
// use listScroller to initialize the scroller parameter to bind it with the <List> component.
List({ space: 20, scroller: this.listScroller }) {
...
}
...
Button() {
...
}
.onClick(() => {
// Specify where e to jump when the specific button is clicked, which is the top of the list in this example.
this.listScroller.scrollToIndex(0)
})
...
}
```
## Responding to the Scrolling Position
Many applications need to listen for the scrolling position change of the list and respond. For example, with regard to a contacts list, if scrolling spans more than one group, the alphabetical index bar at one side of the list also needs to be updated to highlight the letter corresponding to the current group.
Another common example is a scrolling list working with a multi-level index bar, as in the case of a product category page in a shopping application.
**Figure 14** Alphabetical index bar's response to contacts list scrolling
![en-us_image_0000001563060769](figures/en-us_image_0000001563060769.gif)
As shown above, when the contacts list scrolls from group A to B, the alphabetical index bar on the right also changes from A to B. This scenario can be implemented by listening for the **onScrollIndex** event of the **\<List>** component. The alphabet index bar is implemented using the [\<AlphabetIndexer>](../reference/arkui-ts/ts-container-alphabet-indexer.md) component.
When the list scrolls, the **selectedIndex** value of the letter to highlight in the alphabet index bar is recalculated based on the **firstIndex** value of the item to which the list has scrolled. In the **\<AlphabetIndexer>** component, the index of the highlighted item is set through the **selected** attribute. When the value of **selectedIndex** changes, the **\<AlphabetIndexer>** component is re-rendered to highlight the corresponding letter.
```ts
...
const alphabets = ['#', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K',
'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z'];
@Entry
@Component
struct ContactsList {
@State selectedIndex: number = 0;
private listScroller: Scroller = new Scroller();
...
build() {
Stack({ alignContent: Alignment.End }) {
List({ scroller: this.listScroller }) {
...
}
.onScrollIndex((firstIndex: number) => {
// Recalculate the value of this.selectedIndex in the alphabetical index bar based on the index of the item to which the list has scrolled.
...
})
...
// <AlphabetIndexer> component
AlphabetIndexer({ arrayValue: alphabets, selected: 0 })
.selected(this.selectedIndex)
...
}
}
}
```
>**NOTE**
>
>During index calculation, each **\<ListItemGroup>** component is taken as a whole and assigned an index, and the indexes of the list items within are not included in the calculation.
## Responding to Swipe on List Items
Swipe menus are common in many applications. For example, a messaging application generally provides a swipe-to-delete feature for its message list. This feature allows users to delete a message by swiping left on it in the list and touching the delete button, as shown in the following figure.
**Figure 15** Swipe-to-delete feature
![en-us_image_0000001563060773](figures/en-us_image_0000001563060773.gif)
To implement the swipe feature, you can use the **swipeAction** attribute of **\<ListItem>**. In initialization of the **swipeAction** attribute, the **SwipeActionOptions** parameter is mandatory, wherein the **start** parameter indicates the component that appears from the start edge when the list item slides right, and the **end** parameter indicates the component that appears from the end edge when the list item slides left.
In the example of the message list, the **end** parameter is set to a custom delete button. In initialization of the **end** attribute, the index of the sliding list item is passed to the delete button. When the user touches the delete button, the data corresponding to the list item is deleted based on the index.
```ts
@Entry
@Component
struct MessageList {
@State messages: object[] = [
// Initialize the message list data.
...
];
@Builder itemEnd(index: number) {
// Set the component that appears from the end edge when the list item slides left.
Button({ type: ButtonType.Circle }) {
Image($r('app.media.ic_public_delete_filled'))
.width(20)
.height(20)
}
.onClick(() => {
this.messages.splice(index, 1);
})
...
}
build() {
...
List() {
ForEach(this.messages, (item, index) => {
ListItem() {
...
}
.swipeAction({ end: this.itemEnd.bind(this, index) }) // Set the swipe attributes.
}, item => item.id.toString())
}
...
}
}
```
## Adding a Mark to a List Item
A mark is an intuitive, unintrusive visual indicator to draw attention and convey a specific message. For example, when a new message is received in the message list, a mark is displayed in the upper right corner of the contact's profile picture, indicating that there is a new message from that contact, as shown in the following figure.
**Figure 16** Adding a mark to a list item
![en-us_image_0000001511580952](figures/en-us_image_0000001511580952.png)
To add a mark, you can use the [\<Badge>](../reference/arkui-ts/ts-container-badge.md) component in **\<ListItem>**. The **\<Badge>** component is a container that can be attached to another component for tagging.
In this example, when implementing the **\<Image>** component for presenting the profile picture of a list item, add it to **\<Badge>** as a child component.
In the **\<Badge>** component, the **count** and **position** parameters are used to set the number of notifications and the position to display the badge, respectively. You can also use the **style** parameter to spruce up the mark.
```ts
Badge({
count: 1,
position: BadgePosition.RightTop,
style: { badgeSize: 16, badgeColor: '#FA2A2D' }
}) {
// The <Image> component implements the contact profile picture.
...
}
...
```
## Implementing Pull-Down-to-Refresh and Pull-Up-to-Load
The pull-down-to-refresh and pull-up-to-load features are widely used in mobile applications, such as news applications. In effect, the implementation of these two features follows the same process: (1) As response to a [touch event](../reference/arkui-ts/ts-universal-events-touch.md), a refresh or load view is displayed at the top or bottom of the page; (2) when the refresh or load is complete, the refresh or load view is hidden.
The following describes the implementation of the pull-and-refresh feature:
1. Listen for the finger press event and record the value of the initial position.
2. Listen for the finger movement event, and record and calculate the difference between the value of the current position and the initial value. If the difference is greater than 0, the finger moves downward. Set the maximum value for the movement.
3. Listen for the finger lift event. If the movement reaches the maximum value, trigger data loading and display the refresh view. After the loading is complete, hide the view.
You can also use the third-party component [PullToRefresh](https://gitee.com/openharmony-sig/PullToRefresh) to implement this feature.
## Editing a List
The list editing mode is frequently used in various scenarios, such as to-do list management, file management, and note management. In editing mode, adding and deleting list items are the most basic functions. The core is to add and delete data in the data set corresponding to the list items.
The following uses to-do list management as an example to describe how to quickly add and delete list items.
### Adding a List Item
As shown below, when a user touches **Add**, a page is displayed for the user to set options for the new list item. After the user touches **OK**, the corresponding item is added to the list.
**Figure 17** Adding a to-do task
![en-us_image_0000001511740556](figures/en-us_image_0000001511740556.gif)
The process of implementing the addition feature is as follows:
1. Define the list item data structure and initialize the list data to build the overall list layout and list items.
In this example, first define the to-do data structure.
```ts
import util from '@ohos.util';
export class ToDo {
key: string = util.generateRandomUUID(true);
name: string;
constructor(name: string) {
this.name = name;
}
}
```
Then, initialize the to-do list data and options:
```ts
@State toDoData: ToDo[] = [];
private availableThings: string[] = ['Reading', 'Fitness', 'Travel','Music','Movie', 'Singing'];
```
Finally, build the list layout and list items:
```ts
List({ space: 10 }) {
ForEach(this.toDoData, (toDoItem) => {
ListItem() {
...
}
}, toDoItem => toDoItem.key)
}
```
2. Provide the entry for adding a list item, that is, add a click event to the add button.
3. Respond to the user's confirmation of adding and update the list data.
The code snippet for steps 2 and 3 is as follows:
```ts
Text('+')
.onClick(() => {
TextPickerDialog.show({
range: this.availableThings,
onAccept: (value: TextPickerResult) => {
this.toDoData.push(new ToDo(this.availableThings[value.index])); // Add the list item data.
},
})
})
```
### Deleting a List Item
As shown below, when the user long presses a list item to enter the deletion mode, a page is displayed for the user to delete the list item. After the user selects the list item and touches the delete button, the list item is deleted.
**Figure 18** Deleting a to-do task
![en-us_image_0000001562820877](figures/en-us_image_0000001562820877.gif)
The process of implementing the deletion feature is as follows:
1. Generally, the deletion feature is available only after the list enters the editing mode. Therefore, the entry to the editing mode needs to be provided.
In this example, by listening for the long press event of a list item, the list enters the editing mode when the user long presses a list item.
```ts
// ToDoListItem.ets
Flex({ justifyContent: FlexAlign.SpaceBetween, alignItems: ItemAlign.Center }) {
...
}
.gesture(
GestureGroup(GestureMode.Exclusive,
LongPressGesture()
.onAction(() => {
if (!this.isEditMode) {
this.isEditMode = true; // Enter the editing mode.
this.selectedItems.push(this.toDoItem); // Record the list item selected when the user long presses the button.
}
})
)
)
```
2. Respond to the selection by the user and record the list items to be deleted.
In this example of the to-do list, respond to the selection by correctly displaying the check mark and record all the selected list items.
```ts
// ToDoListItem.ets
if (this.isEditMode) {
Checkbox()
.onChange((isSelected) => {
if (isSelected) {
this.selectedItems.push(this.toDoItem) // When an item is selected, record the selected item.
} else {
let index = this.selectedItems.indexOf(this.toDoItem)
if (index !== -1) {
this.selectedItems.splice(index, 1) // When an item is deselected, delete the item from the selectedItems array.
}
}
})
...
}
```
3. Respond to the user's clicking the delete button and delete the corresponding items from the list.
```ts
// ToDoList.ets
Button ('Delete')
.onClick(() => {
// Delete the toDoData data corresponding to the selected list items.
let leftData = this.toDoData.filter((item) => {
return this.selectedItems.find((selectedItem) => selectedItem !== item);
})
this.toDoData = leftData;
this.isEditMode = false;
})
...
```
## Handling a Long List
[ForEach](../quick-start/arkts-rendering-control-foreach.md) is applicable to short lists. With regard to a long list with a large number of list items, using **ForEach** will greatly slow down page loading, as it loads all list items at a time. Therefore, for better list performance, use [LazyForEach](../quick-start/arkts-rendering-control-lazyforeach.md) instead to implement on-demand iterative data loading.
For details about the implementation, see the example in [LazyForEach: Lazy Data Loading](../quick-start/arkts-rendering-control-lazyforeach.md).
When the list is rendered in lazy loading mode, to improve the list scrolling experience and minimize white blocks during list scrolling, you can use the **cachedCount** parameter of the **\<List>** component. This parameter sets the number of list items preloaded outside of the screen and is valid only in **LazyForEach**.
```ts
List() {
LazyForEach(this.dataSource, item => {
ListItem() {
...
}
})
}.cachedCount(3)
```
The following uses a vertical list as an example:
- If lazy loading is used for list items and the list contains only one column, the number of the list items to cache before and after the currently displayed one equals the value of **cachedCount**. If the list contains multiple columns, the number of the list items to cache is the value of **cachedCount** multiplied by the number of columns.
- If lazy loading is used for list item groups, the number of the list item groups to cache before and after the currently displayed one equals the value of **cachedCount**, regardless of the number of columns.
>**NOTE**
>
>1. 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.
>
>2. When a list uses data lazy loading, all list items except the list items in the display area and the cached list items are destroyed.
en/application-dev/ui/arkts-layout-development-linear.md 0 → 100644
浏览文件 @ e475a982
# Linear Layout
## Overview
Linear layout is the most frequently used layout in development, built with the [\<Row>](../reference/arkui-ts/ts-container-row.md) and [\<Column>](../reference/arkui-ts/ts-container-column.md) linear containers. The linear layout is the basis of other layouts. Its child components are arranged in sequence linearly in the horizontal direction, as in a **\<Row>** container, or vertical direction, as in a **\<Column>** container.
**Figure 1** Child component arrangement in a \<Column> container
![arrangement-child-elements-column](figures/arrangement-child-elements-column.png)
**Figure 2** Child component arrangement in a \<Row> container
![arrangement-child-elements-row](figures/arrangement-child-elements-row.png)
## Basic Concepts
- Layout container: container component that is able to lay out other elements as its child elements. The layout container calculates the size of its child elements and arranges the layout.
- Layout child element: element inside the layout container.
- Main axis: axis along which child elements are laid out by default in the linear layout container. The main axis is horizontal for the **\<Row>** container and vertical for the **\<Column>** container.
- Cross axis: axis that runs perpendicular to the main axis. The cross axis is vertical for the **\<Row>** container and horizontal for the **\<Column>** container.
- Spacing: vertical distance between child elements.
## Spacing of Layout Child Elements in Arrangement Direction
In the layout container, use the **space** attribute to equally space child elements in the arrangement direction.
### In \<Column> Container
**Figure 3** Layout child element spacing in the arrangement direction in the \<Column> container
![arrangement-direction-column](figures/arrangement-direction-column.png)
```ts
Column({ space: 20 }) {
Text('space: 20').fontSize(15).fontColor(Color.Gray).width('90%')
Row().width('90%').height(50).backgroundColor(0xF5DEB3)
Row().width('90%').height(50).backgroundColor(0xD2B48C)
Row().width('90%').height(50).backgroundColor(0xF5DEB3)
}.width('100%')
```
![arrangement-direction-column-sample](figures/arrangement-direction-column-sample.png)
### In \<Row> Container
**Figure 4** Layout child element spacing in the arrangement direction in the \<Row> container
![arrangement-direction-row](figures/arrangement-direction-row.png)
```ts
Row({ space: 35 }) {
Text('space: 35').fontSize(15).fontColor(Color.Gray)
Row().width('10%').height(150).backgroundColor(0xF5DEB3)
Row().width('10%').height(150).backgroundColor(0xD2B48C)
Row().width('10%').height(150).backgroundColor(0xF5DEB3)
}.width('90%')
```
![en-us_image_0000001562700509](figures/en-us_image_0000001562700509.png)
## Alignment of Layout Child Elements Along Cross Axis
In the layout container, use the **alignItems** attribute to set the alignment mode of child elements along the cross axis. The alignment performance is consistent across screens of various sizes. The value is of the [VerticalAlign Type](../reference/arkui-ts/ts-appendix-enums.md#verticalalign) type when the cross axis is in the vertical direction and the [HorizontalAlign](../reference/arkui-ts/ts-appendix-enums.md#horizontalalign) type when the cross axis is in the horizontal direction.
The layout container also provides the **alignSelf** attribute to control the alignment mode of a single child element along the main axis. This attribute has a higher priority than the **alignItems** attribute. This means that, if **alignSelf** is set, it will overwrite the **alignItems** setting on the corresponding child element.
### Horizontal Alignment of Layout Child Elements in \<Column> Container
**Figure 5** Horizontal alignment of layout child elements in the \<Column> container
![horizontal-arrangement-child-column](figures/horizontal-arrangement-child-column.png)
- **HorizontalAlign.Start**: Child elements are left aligned horizontally.
```ts
Column({}) {
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
Column() {
}.width('80%').height(50).backgroundColor(0xD2B48C)
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
}.width('100%').alignItems(HorizontalAlign.Start).backgroundColor('rgb(242,242,242)')
```
![en-us_image_0000001511580964](figures/en-us_image_0000001511580964.png)
- **HorizontalAlign.Center**: Child elements are center-aligned horizontally.
```ts
Column({}) {
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
Column() {
}.width('80%').height(50).backgroundColor(0xD2B48C)
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
}.width('100%').alignItems(HorizontalAlign.Center).backgroundColor('rgb(242,242,242)')
```
![en-us_image_0000001562820897](figures/en-us_image_0000001562820897.png)
- **HorizontalAlign.End**: Child elements are right-aligned horizontally.
```ts
Column({}) {
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
Column() {
}.width('80%').height(50).backgroundColor(0xD2B48C)
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
}.width('100%').alignItems(HorizontalAlign.End).backgroundColor('rgb(242,242,242)')
```
![en-us_image_0000001511421348](figures/en-us_image_0000001511421348.png)
### Vertical Alignment of Layout Child Elements in \<Row> Container
**Figure 6** Vertical alignment of layout child elements in \<Row> container
![horizontal-arrangement-child-row](figures/horizontal-arrangement-child-row.png)
- **VerticalAlign.Top**: Child elements are top-aligned vertically.
```ts
Row({}) {
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
Column() {
}.width('20%').height(30).backgroundColor(0xD2B48C)
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
}.width('100%').height(200).alignItems(VerticalAlign.Top).backgroundColor('rgb(242,242,242)')
```
![en-us_image_0000001563060765](figures/en-us_image_0000001563060765.png)
- **VerticalAlign.Center**: Child elements are center-aligned vertically.
```ts
Row({}) {
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
Column() {
}.width('20%').height(30).backgroundColor(0xD2B48C)
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
}.width('100%').height(200).alignItems(VerticalAlign.Center).backgroundColor('rgb(242,242,242)')
```
![en-us_image_0000001562700505](figures/en-us_image_0000001562700505.png)
- **VerticalAlign.Bottom**: Child elements are bottom-aligned vertically.
```ts
Row({}) {
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
Column() {
}.width('20%').height(30).backgroundColor(0xD2B48C)
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
}.width('100%').height(200).alignItems(VerticalAlign.Bottom).backgroundColor('rgb(242,242,242)')
```
![en-us_image_0000001563060781](figures/en-us_image_0000001563060781.png)
## Arrangement of Layout Child Elements Along Main Axis
In the layout container, you can use the **justifyContent** attribute to set the arrangement mode of child elements along the main axis. The arrangement may begin from the start point or end point of the main axis, or the space of the main axis can be evenly divided.
### In \<Column> Container
**Figure 7** Arrangement of layout child elements along main axis in the \<Column> container
![vertial-arrangement-child-column](figures/vertial-arrangement-child-column.png)
- **justifyContent(FlexAlign.Start)**: The items are aligned with each other toward the start edge of the container along the main axis.
```ts
Column({}) {
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
Column() {
}.width('80%').height(50).backgroundColor(0xD2B48C)
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
}.width('100%').height(300).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.Start)
```
![en-us_image_0000001562700501](figures/en-us_image_0000001562700501.png)
- **justifyContent(FlexAlign.Center)**: The elements are aligned with each other toward the center of the container along 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.
```ts
Column({}) {
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
Column() {
}.width('80%').height(50).backgroundColor(0xD2B48C)
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
}.width('100%').height(300).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.Center)
```
![en-us_image_0000001562700517](figures/en-us_image_0000001562700517.png)
- **justifyContent(FlexAlign.End)**: The elements are aligned with each other toward the end edge of the container along the main axis.
```ts
Column({}) {
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
Column() {
}.width('80%').height(50).backgroundColor(0xD2B48C)
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
}.width('100%').height(300).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.End)
```
![en-us_image_0000001562940585](figures/en-us_image_0000001562940585.png)
- **justifyContent(FlexAlign.Spacebetween)**: The elements are evenly distributed along the main axis. The space between any two adjacent elements is the same. The first element is aligned with the main-start, the last element is aligned with the main-end, and the remaining elements are distributed so that the space between any two adjacent elements is the same.
```ts
Column({}) {
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
Column() {
}.width('80%').height(50).backgroundColor(0xD2B48C)
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
}.width('100%').height(300).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.SpaceBetween)
```
![en-us_image_0000001511900532](figures/en-us_image_0000001511900532.png)
- **justifyContent(FlexAlign.SpaceAround)**: The elements are evenly distributed along the main axis. The space between any two adjacent elements is the same. The space between the first element and main-start, and that between the last element and cross-main are both half the size of the space between two adjacent elements.
```ts
Column({}) {
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
Column() {
}.width('80%').height(50).backgroundColor(0xD2B48C)
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
}.width('100%').height(300).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.SpaceAround)
```
![en-us_image_0000001562700525](figures/en-us_image_0000001562700525.png)
- **justifyContent(FlexAlign.SpaceEvenly)**: The elements are evenly distributed along the main axis. The space between the first element and main-start, the space between the last element and main-end, and the space between any two adjacent elements are the same.
```ts
Column({}) {
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
Column() {
}.width('80%').height(50).backgroundColor(0xD2B48C)
Column() {
}.width('80%').height(50).backgroundColor(0xF5DEB3)
}.width('100%').height(300).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.SpaceEvenly)
```
![en-us_image_0000001563060785](figures/en-us_image_0000001563060785.png)
### In \<Row> Container
**Figure 8** Arrangement of layout child elements along main axis in the \<Row> container
![vertial-arrangement-child-row](figures/vertial-arrangement-child-row.png)
- **justifyContent(FlexAlign.Start)**: The items are aligned with each other toward the start edge of the container along the main axis.
```ts
Row({}) {
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
Column() {
}.width('20%').height(30).backgroundColor(0xD2B48C)
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
}.width('100%').height(200).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.Start)
```
![en-us_image_0000001511421356](figures/en-us_image_0000001511421356.png)
- **justifyContent(FlexAlign.Center)**: The elements are aligned with each other toward the center of the container along 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.
```ts
Row({}) {
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
Column() {
}.width('20%').height(30).backgroundColor(0xD2B48C)
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
}.width('100%').height(200).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.Center)
```
![en-us_image_0000001511900516](figures/en-us_image_0000001511900516.png)
- **justifyContent(FlexAlign.End)**: The elements are aligned with each other toward the end edge of the container along the main axis.
```ts
Row({}) {
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
Column() {
}.width('20%').height(30).backgroundColor(0xD2B48C)
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
}.width('100%').height(200).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.End)
```
![en-us_image_0000001562940601](figures/en-us_image_0000001562940601.png)
- **justifyContent(FlexAlign.Spacebetween)**: The elements are evenly distributed along the main axis. The space between any two adjacent elements is the same. The first element is aligned with the main-start, the last element is aligned with the main-end, and the remaining elements are distributed so that the space between any two adjacent elements is the same.
```ts
Row({}) {
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
Column() {
}.width('20%').height(30).backgroundColor(0xD2B48C)
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
}.width('100%').height(200).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.SpaceBetween)
```
![en-us_image_0000001562700521](figures/en-us_image_0000001562700521.png)
- **justifyContent(FlexAlign.SpaceAround)**: The elements are evenly distributed along the main axis. The space between any two adjacent elements is the same. The space between the first element and main-start, and that between the last element and cross-main are both half the size of the space between two adjacent elements.
```ts
Row({}) {
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
Column() {
}.width('20%').height(30).backgroundColor(0xD2B48C)
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
}.width('100%').height(200).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.SpaceAround)
```
![en-us_image_0000001562820893](figures/en-us_image_0000001562820893.png)
- **justifyContent(FlexAlign.SpaceEvenly)**: The elements are evenly distributed along the main axis. The space between the first element and main-start, the space between the last element and main-end, and the space between any two adjacent elements are the same.
```ts
Row({}) {
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
Column() {
}.width('20%').height(30).backgroundColor(0xD2B48C)
Column() {
}.width('20%').height(30).backgroundColor(0xF5DEB3)
}.width('100%').height(200).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.SpaceEvenly)
```
![en-us_image_0000001511421352](figures/en-us_image_0000001511421352.png)
## Adaptive Stretching
In linear layout, adaptive stretching is achieved by using the [\<Blank>](../reference/arkui-ts/ts-basic-components-blank.md) component, which automatically fills the empty spaces in the container – **\<Row>** or **\<Column>** – along the main axis. Just add the width and height as a percentage, and then when the screen width and height change, adaptive stretching takes effect.
```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%')
}
}
```
**Figure 9** Portrait mode
![en-us_image_0000001562820881](figures/en-us_image_0000001562820881.png)
**Figure 10** Landscape mode
![en-us_image_0000001511421332](figures/en-us_image_0000001511421332.png)
## Adaptive Scaling
Adaptive scaling means that the size of a child component is automatically adjusted according to a preset ratio to fit into the container across devices of various screen sizes. In linear layout, adaptive scaling can be achieved using either of the following methods:
- When the container size is determined, use **layoutWeight** to set the weight of a child component during layout. The container space is then allocated along the main axis among the component and sibling components based on the set layout weight, and the component size setting is ignored.
```ts
@Entry
@Component
struct layoutWeightExample {
build() {
Column() {
Text('1:2:3').width('100%')
Row() {
Column() {
Text('layoutWeight(1)')
.textAlign(TextAlign.Center)
}.layoutWeight(2).backgroundColor(0xF5DEB3).height('100%')
Column() {
Text('layoutWeight(2)')
.textAlign(TextAlign.Center)
}.layoutWeight(4).backgroundColor(0xD2B48C).height('100%')
Column() {
Text('layoutWeight(6)')
.textAlign(TextAlign.Center)
}.layoutWeight(6).backgroundColor(0xF5DEB3).height('100%')
}.backgroundColor(0xffd306).height('30%')
Text('2:5:3').width('100%')
Row() {
Column() {
Text('layoutWeight(2)')
.textAlign(TextAlign.Center)
}.layoutWeight(2).backgroundColor(0xF5DEB3).height('100%')
Column() {
Text('layoutWeight(5)')
.textAlign(TextAlign.Center)
}.layoutWeight(5).backgroundColor(0xD2B48C).height('100%')
Column() {
Text('layoutWeight(3)')
.textAlign(TextAlign.Center)
}.layoutWeight(3).backgroundColor(0xF5DEB3).height('100%')
}.backgroundColor(0xffd306).height('30%')
}
}
}
```
**Figure 11** Landscape mode
![en-us_image_0000001511421336](figures/en-us_image_0000001511421336.png)
**Figure 12** Portrait mode
![en-us_image_0000001511580968](figures/en-us_image_0000001511580968.png)
- When the container size is determined, set the width of a child component in percentage. The container space is then allocated among the component and sibling components based on the set percentage.
```ts
@Entry
@Component
struct WidthExample {
build() {
Column() {
Row() {
Column() {
Text('left width 20%')
.textAlign(TextAlign.Center)
}.width('20%').backgroundColor(0xF5DEB3).height('100%')
Column() {
Text('center width 50%')
.textAlign(TextAlign.Center)
}.width('50%').backgroundColor(0xD2B48C).height('100%')
Column() {
Text('right width 30%')
.textAlign(TextAlign.Center)
}.width('30%').backgroundColor(0xF5DEB3).height('100%')
}.backgroundColor(0xffd306).height('30%')
}
}
}
```
**Figure 13** Landscape mode
![en-us_image_0000001563060777](figures/en-us_image_0000001563060777.png)
**Figure 14** Portrait mode
![en-us_image_0000001511740564](figures/en-us_image_0000001511740564.png)
## Adaptive Extension
Adaptive extension allows users to drag the scrollbar to display the page content outside the screen. It is applicable to the scenario where the content extends beyond the viewport in linear layout. Below are the methods to implement adaptive extension in linear layout:
- [Add a scrollbar to a \<List> component](arkts-layout-development-create-list.md#adding-a-scrollbar): If the list items cannot be fully displayed on one screen, you can place the child elements in different components and employ a scrollbar to display them. Use the **scrollBar** attribute to set the scrollbar status and the **edgeEffect** attribute to set the rebound effect when the scrollbar has reached the edge.
- Use a **\<Scroll>** component: When one screen is not able to accommodate the full content, you can wrap a **\<Scroll>** component at the outer layer of the **\<Column>** or **\<Row>** component to implement.
Example of using a **\<Scroll>** component in the vertical layout:
```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) // The scrollbar is always displayed.
.scrollBarColor(Color.Gray) // The scrollbar color is gray.
.scrollBarWidth(10) // The scrollbar width is 10.
.edgeEffect(EdgeEffect.Spring) // The spring effect is produced when the scrollbar has reached the edge.
}
}
```
![en-us_image_0000001511900524](figures/en-us_image_0000001511900524.gif)
Example of using a **\<Scroll>** component in the horizontal layout:
```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 })
})
}.height('100%')
}
.backgroundColor(0xDCDCDC)
.scrollable(ScrollDirection.Horizontal) // Horizontal scrolling.
.scrollBar(BarState.On) // The scrollbar is always displayed.
.scrollBarColor(Color.Gray) // The scrollbar color is gray.
.scrollBarWidth(10) // The scrollbar width is 10.
.edgeEffect(EdgeEffect.Spring) // The spring effect is produced when the scrollbar has reached the edge.
}
}
```
![en-us_image_0000001562940609](figures/en-us_image_0000001562940609.gif)
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或