1 Star 0 Fork 5.1K

youguilin / docs

forked from OpenHarmony / docs 
加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
list.md 243.89 KB
一键复制 编辑 原始数据 按行查看 历史
mamingshuai 提交于 2021-06-02 01:00 . update OpenHarmony 2.0 Canary

list

The <list> component provides a list container that presents a series of list items arranged in a column with the same width. Lists support presentations of the same data in a multiple and coherent row style, for example, images and texts.

Permission List

None

Child Component

<list-item> and <list-item-group>

Attribute

Name

Type

Default Value

Mandatory

Description

scrollpage

boolean

false

No

Whether to scroll the non-list part on the top of the list page out of the visible area with the list. The value can be true (scrolls the non-list part out) or false (does not scroll the non-list part out). This attribute is not available when the direction is row.

cachedcount

number

0

No

Minimum number of cached list items when the long list is loaded with delay.

When the number of list items cached outside the visible area is less than the value of this attribute, a requestitem event is triggered.

scrollbar

string

off

No

Display mode of the side scroll bar. (Currently, only the vertical scroll bar is supported.)

  • off: No display
  • auto: Displayed on demand (The side scroll bar is displayed when you touch it and disappears 2s later.)
  • on: Always displayed

scrolleffect

string

spring

No

Scroll effect. Available values are as follows:

  • spring: Similar to the physical dynamic effect of a spring. After scrolling to the edge, you can continue to scroll for a distance based on the initial speed or by touching the knob of the scrollbar. After you release your hand, the knob is rebounded.
  • fade: Similar to the physical dynamic effect of fade. When you scroll to the edge, a wave shape fades. The fade changes according to the speed and scrolling distance.
  • no: No effect after the scroll bar is moved to the edge.

indexer

boolean | Array<string>

false

No

Whether to display the alphabetical index bar on the sidebar. If this attribute is set to true or a customized indexer, the index bar is displayed at the right boundary of the list. Example:

"indexer" : "true" indicates the default alphabetical indexer.

"indexer" : "false" indicates no indexer.

"indexer": ["#", "A", ".", "E", ".", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z"] indicates a customized indexer. You must include "#" when using a customized indexer.

NOTE:
  • This attribute is valid only when flex-direction is set to column and columns is set to 1.
  • This attribute must be used together with the section attribute of <list-item>.

indexermulti5+

boolean

false

No

Whether to use a multi-language indexer.

This attribute is invalid if indexer is set to false.

indexerbubble5+

boolean

true

No

Whether to display the bubble effect when switching among indexes.

This attribute is invalid if indexer is set to false.

divider5+

boolean

false

No

Whether list items are separated by dividers.

For details about divider styles, see divider-color, divider-height, divider-length, and divider-origin in the Styles table.

shapemode

string

default

No

Shape of the side scroll bar.

  • default: not specified (following the theme)
  • rect: rectangle
  • round: circle

updateeffect

boolean

false

No

Whether a dynamic effect is displayed when an item in the list is deleted or added.

  • false: No dynamic effect is displayed.
  • true: A dynamic effect is displayed when an item is added or deleted.

chainanimation5+

boolean

false

No

Whether to display chained animations on this list when it slides or its top and bottom are 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.

  • false: Chained animations are displayed.
  • true: No chained animation is displayed.
    NOTE:
    • Dynamic modification is not supported.
    • This attribute does not take effect if an indexer is used.
    • If this attribute is true, the sticky attributes set for <list-item> components do not take effect.

initialindex

number

0

No

Item to be displayed at the start position of the viewport when the current list is loaded for the first time. The default value is 0, indicating that the first item is displayed.

The setting does not take effect in any of the following cases:

  • The value you set is greater than the index of the last item.
  • The initialoffset attribute is set.
  • indexer or scrollpage is set to true.

initialoffset

<length>

0

No

Start offset of the viewport when the current list is loaded for the first time. The offset must not exceed the scrolling range of the current list. If exceeded, the offset is truncated to the maximum value of the scrolling range. This attribute does not take effect if indexer or scrollpage is set to true.

selected5+

string

-

No

Selected item in the current list. The value can be a section value of any list items.

id

string

-

No

Unique ID of a component.

style

string

-

No

Style declaration of a component.

class

string

-

No

Style class of a component, which is used to refer to a style table.

ref

string

-

No

Used to register reference information of child elements or child components. The reference information is registered with the parent component on $refs.

disabled

boolean

false

No

Whether a component is disabled. If it is disabled, it cannot respond to user interaction.

data

string

-

No

Attribute set for a component to facilitate data storage and reading.

Event

Name

Parameter

Triggered when

indexerchange5+

{ local: booleanValue }

Triggered when the indexer switches between local and alphabetic indexers. This parameter takes effect only when both indexer and indexermulti are set to true. The value of booleanValue can be:

  • true: The local index is displayed.
  • false: The alphabetic index is displayed.

scroll

{ scrollX: scrollXValue, scrollY: scrollYValue, scrollState: stateValue }

Triggered to indicate the offset and status of list scrolling.

stateValue: 0: The list is not scrolling.

stateValue: 1: The list is scrolling along with user's touches.

stateValue: 2: The list is scrolling after the touches stop.

scrollbottom

-

Triggered when the list is scrolled to the bottom.

scrolltop

-

Triggered when the list is scrolled to the top.

scrollend

-

Triggered when the list stops scrolling.

scrolltouchup

-

Triggered when the list continues scrolling after the user lifts their fingers.

requestitem

-

Triggered for a request to create a list-item.

This event is triggered when the number of cached list items outside the visible area is less than the value of cachedcount during long list loading with delay.

touchstart

TouchEvent

The tapping starts

touchmove

TouchEvent

The tapping moves

touchcancel

TouchEvent

The tapping is interrupted

touchend

TouchEvent

The tapping ends

click

-

A component is clicked

longpress

-

A component is long pressed

swipe5+

SwipeEvent

A user quickly swipes on a component.

Style

Name

Type

Default Value

Mandatory

Description

divider-color5+

<color>

transparent

No

Item divider color. This style is valid only when the divider attribute of <list> is set to true.

divider-height5+

<length>

1

No

Item divider height. This style is valid only when the divider attribute of <list> is set to true.

divider-length5+

<length>

The main axis width

No

Item divider length. If this style is not set, the maximum length is the width of the main axis, and the actual length depends on the divider-origin parameter. This style is valid only when the divider attribute of the list is set to true.

divider-origin5+

<length>

0

No

Item divider offset relative to the start point of the main axis. This style is valid only when the divider attribute of the list is set to true.

flex-direction

string

column

No

Main axis direction of the flex container. It specifies how items are placed in the flex container.

  • column: The y-axis is the maim axis.
  • row: The x-axis is the main axis.

For the <list> component, the default value is column. For other components, the default value is row.

columns

number

1

No

Number of columns displayed in the cross axis direction of the list. The default value is 1.

NOTE:

When multiple columns are set, the columns are evenly distributed on the cross axis of the <list> component. The size of each column is the same.

align-items

string

stretch

No

Alignment of items in each column on the cross axis. Available values are as follows:

  • stretch: Items are stretched to the same height or width as the container in the cross axis direction.
  • flex-start: Items are aligned to the start of the cross axis.
  • flex-end: Items are aligned to the end of the cross axis.
  • center: Items are aligned in the middle of the cross axis.
    NOTE:

    This style takes effect only on items of each column. Columns are evenly distributed.

item-extent

<length> | <percentage>

-

No

Size of an internal item. When a percentage is set, the value indicates the percentage of the length in the main axis direction relative to the list viewpoint.

fade-color

<color>

grey

No

Color of the physical dynamic effect. This attribute is valid only when scrolleffect is set to fade.

width

<length> | <percentage>

-

No

Component width.

If this attribute is not set, the width required for the element content is used.

height

<length> | <percentage>

-

No

Component height.

If this length attribute is not set, the length required for the element content is used.

padding

<length> | <percentage>5+

0

No

Shorthand attribute to set all padding attributes.

The attribute can have one to four values:
  • If you set only one value, it specifies the padding for four sides.

  • If you set two values, the first value specifies the top and bottom padding, and the second value specifies the left and right padding.

  • If you set three values, the first value specifies the top padding, the second value specifies the left and right padding, and the third value specifies the bottom padding.

  • If you set four values, they respectively specify the padding for top, right, bottom, and left sides (in clockwise order).

padding-[left|top|right|bottom]

<length> | <percentage>5+

0

No

Left, top, right, and bottom padding (in px).

padding-[start|end]

<length> | <percentage>5+

0

No

Start and end padding.

margin

<length> | <percentage>5+

0

No

Shorthand attribute to set margins for all sides in a declaration. The attribute can have one to four values:

  • If you set only one value, it specifies the margin for all the four sides.

  • If you set two values, the first value is for the top and bottom sides and the second value for the left and right sides.

  • If you set three values, the first value is for the top, the second value for the left and right, and the third value for the bottom.

  • If you set four values, they are margins for top, right, bottom, and left sides, respectively.

margin-[left|top|right|bottom]

<length> | <percentage>5+

0

No

Left, top, right, and bottom margins.

margin-[start|end]

<length> | <percentage>5+

0

No

Start and end margins.

border

-

0

No

Shorthand attribute to set all borders. You can set border-width, border-style, and border-color in sequence. Default values are used for attributes that are not set.

border-style

string

solid

No

Shorthand attribute to set the style for all borders. Available values are as follows:

  • dotted: Dotted border. The radius of a dot is half of border-width.
  • dashed: Dashed border
  • solid: Solid border

border-[left|top|right|bottom]-style

string

solid

No

Styles of the left, top, right, and bottom borders. The available values are dotted, dashed, and solid.

border-[left|top|right|bottom]

-

-

No

Shorthand attribute to set the borders for every side respectively. You can set border-width, border-style, and border-color in sequence. Default values are used for attributes that are not set.

border-width

<length>

0

No

Shorthand attribute to set the width of all borders, or separately set the width of each border.

border-[left|top|right|bottom]-width

<length>

0

No

Attribute to set widths of left, top, right, and bottom borders.

border-color

<color>

black

No

Shorthand attribute to set the color of all borders, or separately set the color of each border.

border-[left|top|right|bottom]-color

<color>

black

No

Attribute to set colors of left, top, right, and bottom borders.

border-radius

<length>

-

No

Attribute to set the radius of round borders of an element. This attribute cannot be used to set the width, color, or style of a specific border. To set the width or color, you need to set border-width, border-color, or border-style for all the borders at the same time.

border-[top|bottom]-[left|right]-radius

<length>

-

No

Attribute to receptively set the radii of upper-left, upper-right, lower-right, and lower-left rounded corners

background

<linear-gradient>

-

No

This attribute supports Gradient Styles only but is not compatible with background-color or background-image.

background-color

<color>

-

No

Background color.

background-image

string

-

No

Background image. Currently, this attribute is not compatible with background-color or background. Local image resources are supported.

Example:

background-image: url("/common/background.png")

background-size

  • string
  • <length> <length>
  • <percentage> <percentage>

auto

No

Background image size.

  • The string values are as follows:
    • contain: Expands the image to the maximum size so that the height and width of the image are applicable to the content area.
    • cover: Extends the background image to a large enough size so that the background image completely covers the background area. Some parts of the image may not be displayed in the background area.
    • auto: The original image width-height ratio is retained.
  • The two <length> values are as follows:

    Width and height of the background image. The first value indicates the width, and the second value indicates the height. If you only set one value, the other value is set to auto by default.

  • The two <percentage> values are as follows:

    Width and height of the background image in percentage of the parent element. The first value indicates the width, and the second value indicates the height. If you only set one value, the other value is set to auto by default.

background-repeat

string

repeat

No

How a background image is repeatedly drawn. By default, a background image is repeated both horizontally and vertically.

  • repeat: Repeatedly draws images along the x-axis and y-axis at the same time.
  • repeat-x: Repeatedly draws images along the x-axis.
  • repeat-y: Repeatedly draws images along the y-axis.
  • no-repeat: The image is not drawn repeatedly.

background-position

  • string string
  • <length> <length>
  • <percentage> <percentage>

0px 0px

No

  • Using keywords: If only one keyword is specified, the other value is center by default. The two values define the horizontal position and vertical position, respectively.
    • left: leftmost in the horizontal direction
    • right: rightmost in the horizontal direction
    • top: top in the vertical direction
    • bottom: bottom in the vertical direction
    • center: center position
  • Using <length>: The first value indicates the horizontal position, and the second value indicates the vertical position. 0 0 indicates the upper left corner. The unit is pixel. If only one value is specified, the other one is 50%.
  • Using <percentage>: The first value indicates the horizontal position, and the second value indicates the vertical position. 0% 0% indicates the upper left corner. 100% 100% indicates the lower right corner. If only one value is specified, the other one is 50%.
  • Using both <percentage> and <length>.

opacity

number

1

No

Transparency of an element. The value ranges from 0 to 1. The value 1 means opaque, and 0 means completely transparent.

display

string

flex

No

How and whether to display the box containing an element. Available values are as follows:

  • flex: flexible layout
  • none: The element is hidden.

visibility

string

visible

No

Whether to display an element. Invisible borders occupy layout space. (To remove the borders, set the display attribute to none.) Available values are as follows:

  • visible: The element is visible.
  • hidden: The element is hidden but still takes up space.
NOTE:

If both visibility and display are set, only display takes effect.

flex

-

-

No

How to divide available space of the parent component for a child component.

You can set one, two5+, or three5+ values for this style.

Set one value in either of the following ways:

  • A unitless number to set flex-grow.
  • A valid width value5+ to set flex-basis.

Set two values5+ in the following ways:

The first value must be a unitless number used to set flex-grow. The second value must be either of the following:

  • A unitless number to set flex-shrink.
  • A valid width value to set flex-basis.

Set three values5+ in the following ways:

The first value must be a unitless number used to set flex-grow. The second value must be a unitless number used to set flex-shrink. The third value must be a valid width value used to set flex-basis.

NOTE:

This style takes effect only when the container is any of the following components: <div>, <list-item>, <refresh>, <stepper-item>5+, and <tabs>.

flex-grow

number

0

No

How much a child component will grow. The value specifies allocation of the remaining space on the main axis of the parent component. Size of available space = Container size - Total size of all child components. Value 0 indicates that the child component does not grow.

NOTE:

This style takes effect only when the container is any of the following components: <div>, <list-item>, <refresh>, <stepper-item>5+, and <tabs>.

flex-shrink

number

1

No

How much a child component will shrink. The shrink occurs only when the sum of default child component widths is greater than that of the parent component. Value 0 indicates that the child component does not shrink.

NOTE:

This style takes effect only when the container is any of the following components: <div>, <list-item>, <refresh>, <stepper-item>5+, and <tabs>.

flex-basis

<length>

-

No

Initial length of the flex item on the main axis.

NOTE:

This style takes effect only when the container is any of the following components: <div>, <list-item>, <refresh>, <stepper-item>5+, and <tabs>.

position

string

relative

No

Positioning type of an element. Dynamic changes are not supported.

  • fixed: The element is positioned related to the browser window.
  • absolute: The element is positioned absolutely to its parent element.
  • relative: The element is positioned relative to its normal position.
NOTE:

The absolute attribute takes effect only when the parent component is <div> or <stack>.

[left|top|right|bottom]

<length>

-

No

left|top|right|bottom must be used together with position to determine the offset position of an element.

  • The left attribute specifies the left edge position of the element. This attribute defines the offset between the left edge of a positioned element and that of a block included in the element.
  • The top attribute specifies the top edge position of the element. This attribute defines the offset between the top edge of a positioned element and that of a block included in the element.
  • The right attribute specifies the right edge position of the element. This attribute defines the offset between the right edge of a positioned element and that of a block included in the element.
  • The bottom attribute specifies the bottom edge position of the element. This attribute defines the offset between the bottom edge of a positioned element and that of a block included in the element.

Method

Name

Parameter

Description

scrollTo

{ index: number(specified position) }

Scrolls the list to the position of the item at the specified index.

scrollTop

{ smooth: boolean }

If smooth is set to false (default value), the list is directly scrolled to the top.

If smooth is set to true, the list is smoothly scrolled to the top.

scrollBottom

{ smooth: boolean }

If smooth is set to false (default value), the list is directly scrolled to the bottom.

If smooth is set to true, the list is smoothly scrolled to the bottom.

scrollPage

{ reverse: boolean, smooth: boolean }

If reverse is set to false (default value), the next page is displayed. If there is no next page, the list scrolls to the bottom.

If reverse is set to true, the previous page is displayed. If there is no previous page, the list scrolls to the top.

If smooth is set to false (default value), the list is directly scrolled to another page.

If smooth is set to true, the list is smoothly scrolled to another page.

scrollArrow

{ reverse: boolean, smooth: boolean }

If reverse is set to false (default value), the list scrolls towards the bottom for a certain distance. If there is no sufficient distance, the list scrolls to the bottom.

If reverse is set to true, the list scrolls towards the top for a certain distance. If there is no sufficient distance, the list scrolls to the top.

If smooth is set to false (default value), the list is directly scrolled.

If smooth is set to true, the list is smoothly scrolled.

collapseGroup

{ groupid: string }

Collapses a group.

groupid: ID of the group to collapse.

All groups are collapsed when groupid is not specified.

expandGroup

{ groupid: string }

Expands a group.

groupid: ID of the group to expand.

All groups are expanded when groupid is not specified.

currentOffset

-

Returns the offset of the current scrolling. The return value type is Object. For details, see Table 2.

Table 1 ListScrollByOptions

Name

Type

Mandatory/Optional

Default Value

Remarks

dx

number

No

0

Offset for scrolling the list in the horizontal direction, in px.

dy

number

No

0

Offset for scrolling the list in the vertical direction, in px.

smooth

boolean

No

true

Whether a sliding animation is displayed when the list position is changed.

Table 2 Attributes of the currentOffset return object

Name

Type

Remarks

x

number

Scrolling offset in the x-axis, in px

y

number

Scrolling offset in the y-axis, in px

Example

<!-- index.hml -->
<div class="container">
  <list class="todo-wraper">
    <list-item for="{{todolist}}" class="todo-item">
      <text class="todo-title">{{$item.title}}</text>
      <text class="todo-title">{{$item.date}}</text>
    </list-item>
  </list>
</div>
// index.js
export default {
  data: {
    todolist: [{
      title: 'Prepare for the interview',
      date: 'Dec 31, 2021 10:00:00',
    }, {
      title: 'Watch the movie',
      date: 'Dec 31, 2021 20:00:00',
    }],
  },
}
/* index.css */
.container {
  display: flex;
  justify-content: center;
  align-items: center;
  left: 0px;
  top: 0px;
  width: 454px;
  height: 454px;
}
.todo-wraper {
  width: 454px;
  height: 300px;
}
.todo-item {
  width: 454px;
  height: 80px;
  flex-direction: column;
}
.todo-title {
  width: 454px;
  height: 40px;
  text-align: center;
}

1
https://gitee.com/yougl/docs.git
git@gitee.com:yougl/docs.git
yougl
docs
docs
master

搜索帮助