diff --git a/en/application-dev/reference/arkui-js/figures/en-us_image_0000001214837129.png b/en/application-dev/reference/arkui-js/figures/en-us_image_0000001214837129.png new file mode 100644 index 0000000000000000000000000000000000000000..2ebf9f94f716640932ce35490ca5bca760c16d8b Binary files /dev/null and b/en/application-dev/reference/arkui-js/figures/en-us_image_0000001214837129.png differ diff --git a/en/application-dev/reference/arkui-js/js-components-common-styles.md b/en/application-dev/reference/arkui-js/js-components-common-styles.md index efa11d67495646d34ef6250230ca4fcdb6497f55..3f3c990bb338a347741a187bfaa4b47ea8fa34ee 100644 --- a/en/application-dev/reference/arkui-js/js-components-common-styles.md +++ b/en/application-dev/reference/arkui-js/js-components-common-styles.md @@ -1,617 +1,87 @@ -# Universal Styles +# Universal Styles -You can set component appearance in the **style** attribute or **.css** files. +> **NOTE**
+> Universal styles are supported since API version 4. Updates will be marked with a superscript to indicate their earliest API version. + +You can set universal styles for components in the **style** attribute or **.css** files. + + +| Name | Type | Default Value | Description | +| ---------------------------------------- | ---------------------------------------- | ------------ | ---------------------------------------- | +| width | \ \| \ | - | Component width.
If this attribute is not set, the width required for the element content is used.
| +| height | \ \| \ | - | Component height.
If this attribute is not set, the height required for the element content is used.
| +| min-width5+ | \ \| \6+ | 0 | Minimum component width. | +| min-height5+ | \ \| \6+ | 0 | Minimum component height. | +| max-width5+ | \ \| \6+ | - | Maximum component width, which has no restriction by default. | +| max-height5+ | \ \| \6+ | - | Maximum component height, which has no restriction by default. | +| padding | \ \| \5+ | 0 | Shorthand attribute to set the padding for all sides in a declaration.
The attribute can have one to four values:
- If you set only one value, it specifies the padding for all the 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] | \ \| \5+ | 0 | Left, top, right, and bottom padding. | +| padding-[start\|end] | \ \| \5+ | 0 | Start and end padding. | +| margin | \ \| \5+ | 0 | Shorthand attribute to set the margin 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 specifies the top and bottom margins, and the second value specifies the left and right margins.
- If you set three values, the first value specifies the top margin, the second value specifies the left and right margins, and the third value specifies the bottom margin.
- If you set four values, they respectively specify the margin for top, right, bottom, and left sides (in clockwise order).| +| margin-[left\|top\|right\|bottom] | \ \| \5+ | 0 | Left, top, right, and bottom margins. | +| margin-[start\|end] | \ \| \5+ | 0 | Start and end margins. | +| border | - | 0 | Shorthand attribute to set all borders. Set **border-width**, **border-style**, and **border-color** in sequence. Default values are used for attributes that are not set.| +| border-style | string | solid | 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 | Styles of the left, top, right, and bottom borders. The available values are **dotted**, **dashed**, and **solid**.| +| border-[left\|top\|right\|bottom] | - | - | Shorthand attribute to set the borders for every side respectively. Set **border-width**, **border-style**, and **border-color** in sequence. Default values are used for attributes that are not set.| +| border-width | \ | 0 | Shorthand attribute to set the width for all borders, or separately set the width for each border. | +| border-[left\|top\|right\|bottom]-width | \ | 0 | Attribute to set widths of left, top, right, and bottom borders. | +| border-color | \ | black | Shorthand attribute to set the color for all borders, or separately set the color for each border. | +| border-[left\|top\|right\|bottom]-color | \ | black | Attribute to set colors for left, top, right, and bottom borders. | +| border-radius | \ | - | Attribute to set the radius for 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.
In the four-value syntax, the values apply to lower-left corner, lower-right corner, upper-left corner, and upper-right corner, respectively.| +| border-[top\|bottom]-[left\|right]-radius | \ | - | Attribute to respectively set the radii of upper-left, upper-right, lower-right, and lower-left rounded corners | +| background | \ | - | Background. This attribute supports [gradient styles](../arkui-js/js-components-common-gradient.md) only and is not compatible with **background-color** or **background-image**.| +| background-color | \ | - | Background color. | +| background-image | string | - | Background image. Both online and local image resources are supported. Currently, this attribute is not compatible with **background-color** or **background**.
Example:
- background-image: url("/common/background.png")
The SVG format is not supported.| +| background-size | - string
- \ \
- \ \ | auto | Background image size.
- The **string** values are as follows:
- **contain**: Expands the image to the maximum size so that its height and width are fully applicable to the content area.
- **cover**: Extends the background image to a large enough size so that it completely covers the background area. Some parts of the image may not be displayed in the background area.
- **auto**: Retains the original aspect ratio of the image.
- The two **** 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 **** 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 | How a background image is repeatedly drawn. By default, a background image is repeated both horizontally and vertically.
- **repeat**: The image is repeated along the x-axis and y-axis at the same time.
- **repeat-x**: The image is repeated along the x-axis.
- **repeat-y**: The image is repeated along the y-axis.
- **no-repeat**: The image is not repeated.| +| background-position | - string string
- \ \
- \ \ | 0px 0px | - 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 ****: The first value indicates the horizontal position, and the second value indicates the vertical position. For the upper left corner, the value is **0 0**. The unit is pixel. If only one value is specified, the other one is **50%**.
- Using **\**: 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 **\** and **\**. | +| box-shadow5+ | string | 0 | Syntax: **box-shadow: h-shadow v-shadow blur spread color**
Shadow style of the current component. The value includes the horizontal position (mandatory), vertical position (mandatory), fuzzy radius (optional, default value: **0**), extension distance (optional, default value: **0**), and color (optional, default value: **black**) of the shadow.
Example:
- box-shadow :10px 20px 5px 10px \#888888
- box-shadow :100px 100px 30px red
- box-shadow :-100px -100px 0px 40px | +| filter5+ | string | - | Syntax: **filter: blur(px)**
Radius of the blur area within the component layout. If this style is not set, the default value **0** (no blur) is used. Percentage values are not supported.
Example:
- filter: blur(10px) | +| backdrop-filter5+ | string | - | Syntax: **backdrop-filter: blur(px)**
Radius of the background blur area within the component layout. If this style is not set, the default value **0** (no blur) is used. Percentage values are not supported.
Example:
- backdrop-filter: blur(10px) | +| window-filter5+ | string | - | Syntax: window-filter: blur(percent), style5+
Blur degree and style for windows within the component layout. If this style is not set, the default value **0%** (no blur area) is used. Different blur degrees and styles for multiple blur areas are not supported. Available blur styles are as follows: **small_light** (default value), **medium_light**, **large_light**, **xlarge_light**, **small_dark**, **medium_dark**, **large_dark**, and **xlarge_dark**.
Example:
- window-filter: blur(50%)
- window-filter: blur(10%), large_light | +| opacity | number | 1 | Opacity of an element. The value ranges from **0** to **1**. The value **1** means opaque, and **0** means completely transparent. | +| display | string | flex | Type of the box containing an element. Available values are as follows:
- **flex**: Flexible layout.
- **none**: The box is disabled.
- **inline**9+: Inline box, where the element is displayed as an inline element and does not start on a new line.
- **block**9+: Block box, where the element is displayed as a block-level element and always starts on a new line. This is the default value for container components.
- **inline-block**9+: Inline-block box, where the element is displayed on one line and you can set a width and height on the element. This is the default value for basic components.| +| visibility | string | visible | Whether to display the box containing an element. The invisible box occupies layout space. (To remove the box, set the **display** attribute to **none**.) Available values are as follows:
- **visible**: The element is visible.
- **hidden**: The box is hidden but still takes up space.
If both **visibility** and **display** are set, only **display** takes effect.| +| flex | number \| string | - | How to divide available space of the parent component for each 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**.
This style takes effect only when the container is any of the following components: **\
**, **\**, **\**, **\**, and **\5+**.| +| flex-grow | number | 0 | 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.
This style takes effect only when the container is any of the following components: **\
**, **\**, **\**, **\**, and **\5+**.| +| flex-shrink | number | 1 | 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.
This style takes effect only when the container is any of the following components: **\
**, **\**, **\**, **\**, and **\5+**.| +| flex-basis | \ | - | Initial length of the flex item on the main axis.
This style takes effect only when the container is any of the following components: **\
**, **\**, **\**, **\**, and **\5+**.| +| align-self6+ | string | - | Alignment mode on the cross axis of the parent element. This style overwrites the align-items style of the parent element. The align-items style is used only in the div and list styles of the parent container. 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 center of the cross axis.
- **baseline**: Items are aligned on the peracross axis.| +| position | string | relative | 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. The setting takes effect only when the parent component is **\
** or **\**.
- **relative**: The element is positioned relative to its normal position.| +| [left\|top\|right\|bottom] | \ \| \6+ | - | **left | top | right | bottom** must be used together with **position** to determine the offset of an element.
- The **left** attribute specifies the left edge position of the element. This attribute defines the offset between the left edge of the margin area of a positioned element and left edge of its containing block.
- 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. | +| [start \| end]6+ | \ \| \ | - | **start | end** must be used together with **position** to determine the offset of an element.
- The **start** attribute specifies the start edge position of the element. This attribute defines the offset between the start edge of a positioned element and that of a block included in the element.
- The **end** attribute specifies the end edge position of the element. This attribute defines the offset between the end edge of a positioned element and that of a block included in the element. | +| z-index6+ | number | - | Rendering sequence of child nodes under the same parent node. A child node with a larger value will be rendered later.
z-index does not support auto, and other styles such as opacity do not affect the rendering sequence of z-index.| +| image-fill6+ | \ | - | Fill color for SVG images. The following components are supported: **button** (icon attribute), **piece** (icon attribute), **search** (icon attribute), **input** (headericon attribute), **textarea** (headericon attribute), **image** (src attribute), and **toolbar-item** (icon attribute)
The **fill** color value in the SVG image file is replaced with the value of **image-fill** during rendering, and is valid only for the fill attribute that is declared in the SVG image.| +| clip-path6+ | [ \ \|\| \ ] \| none | - | Clip area of a component. Only the content within this area is displayed.
**\**: applicable scope of the clip area's width and height. The default value is **border-box**. Available values are as follows:
- **margin-box**: The width and height includes the margin.
- **border-box**: The width and height includes the border.
- **padding-box**: The width and height includes the padding.
- **content-box**: The width and height does not include any margin, border, or padding.
- **\**: shape of the clip area. Available values include:
- **inset**, in the format of inset( \{1,4} [ round \<'border-radius'> ]? ).
- **circle**, in the format of circle( [ \ ]? [ at \ \ ]? ).
- **ellipse**, in the format of ellipse( [ \{2} ]? [ at \ \ ]? ).
- **polygon**, in the format of polygon( [ \ \ ]\# ).
- **path**, in the format of path( \ ).| +| mask-image6+ | - \
- string | - | Image used for the mask of a component:
Gradient color mask, for example:
linear-gradient(to left, black, white)
Solid color mask, for example:
linear-gradient(to right, grey , grey)
Mask filled by a local SVG image, for example, **url(common/mask.svg)**| +| mask-size6+ | - string
- \\
- \ \ | auto | Display size of the mask image. The setting is valid only when **mask-image** is set to an image source.
The **string** values are as follows:
- **contain**: Expands the image to the maximum size so that its height and width are fully applicable to the content area.
- **cover**: Extends the image to a large enough size so that it completely covers the background area. Some parts of the image may not be displayed in the background area.
- **auto**: Retains the original aspect ratio of the image.
The two **** values are as follows: 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 **** values indicate the image size in relative to the original image size. 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.| +| mask-position6+ | - string string
- \ \
- \ \ | 0px 0px | Display position of the mask image. The setting is valid only when **mask-image** is set to an image source. 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.
The **string** values are as follows:
- **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 **\**: The first value indicates the horizontal position, and the second value indicates the vertical position. For the upper left corner, the value is **0 0**. The unit is pixel. If only one value is specified, the other one is **50%**.
Using **\**: 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 **\** and **\**.| +| border-image-source7+ | string | - | Border image of the specified element.
Example:
border-image-source: url("/common/images/border.png") | +| border-image-slice7+ | \ \| \ | 0 | Padding of the image.
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).| +| border-image-width7+ | \ \| \ | 0 | Width of the border image.
If you set only one value, it specifies the width for four sides.
If you set two values, the first value specifies the top and bottom width, and the second value specifies the left and right width.
If you set three values, the first value specifies the top width, the second value specifies the left and right width, and the third value specifies the bottom width.
If you set four values, they respectively specify the width for top, right, bottom, and left sides (in clockwise order).| +| border-image-outset7+ | \ \| \ | 0 | How far the border image can extend beyond the border box.
If you set only one value, it specifies the distance of the boarder image beyond the border on four sides.
If you set two values, the first value specifies the distance of the boarder image's top and bottom sides beyond the boarder, and the second value specifies the distance of the boarder image's left and right sides beyond the boarder.
If you set three values, the first value specifies the distance of the boarder image's top side beyond the boarder, the second value specifies the distance of the boarder image's left and right sides beyond the boarder, and the third value specifies the distance of the boarder image's bottom side beyond the boarder.
If you set four values, they respectively specify the distance of the boarder image's top, right, bottom, and left sides beyond the boarder (in clockwise order).| +| border-image-repeat7+ | string | stretch | How the border image fills the border box.
**stretch**: stretches the image to fill the border box.
**repeat**: tiles the image to fill the border box.
**round**: tiles the image to fill the border box. When the image cannot be tiled for an integer number of times, it can be scaled based on the site requirements.
| +| border-image7+ | string | - | Shorthand attribute. The options are as follows:
- Attributes of the image border. The parameters include **border-image-source**, **border-image-slice**, **border-image-width**, **border-image-outset**, and **border-image-repeat**, respectively meaning the padding, width of the border image, how far the border image can extend beyond the border box, and how the border image fills the border box. The default values are used if the parameters are not set.
- Gradient color border.
Example:
border-image: linear-gradient(red, yellow) 10px | +| box-sizing9+ | string | border-box | Border type of the component.
**content-box**: standard box. Its width and height contain only the width and height of the content, and does not include the border and padding.
**border-box**: The width and height include the content, border, and padding, that is, the actual width of the component content area = width - (border + padding).| - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Default Value

-

Description

-

width

-

<length> | <percentage>

-

-

-

Component width.

-

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

-

height

-

<length> | <percentage>

-

-

-

Component height.

-

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

-

min-width5+

-

<length> | <percentage>6+

-

0

-

Minimum component width

-

min-height5+

-

<length> | <percentage>6+

-

0

-

Minimum component height

-

max-width5+

-

<length> | <percentage>6+

-

-

-

Maximum component width, which has no restriction by default

-

max-height5+

-

<length> | <percentage>6+

-

-

-

Maximum component height, which has no restriction by default

-

padding

-

<length> | <percentage>5+

-

0

-

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

-

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

-

padding-[start|end]

-

<length> | <percentage>5+

-

0

-

Start and end padding.

-

margin

-

<length> | <percentage>5+

-

0

-

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

-

Left, top, right, and bottom margins.

-

margin-[start|end]

-

<length> | <percentage>5+

-

0

-

Start and end margins.

-

border

-

-

-

0

-

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

-

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

-

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

-

border-[left|top|right|bottom]

-

-

-

-

-

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

-

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

-

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

-

border-color

-

<color>

-

black

-

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

-

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

-

border-radius

-

<length>

-

-

-

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.

-
NOTE:

In the four-value syntax, the values apply to lower-left corner, lower-right corner, upper-left corner, and upper-right corner, respectively.

-
-

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

-

<length>

-

-

-

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

-

background

-

<linear-gradient>

-

-

-

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

-

background-color

-

<color>

-

-

-

Background color.

-

background-image

-

string

-

-

-

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")
    NOTE:

    The SVG format is not supported.

    -
    -
-

background-size

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

auto

-

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

-

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

-
  • 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>.
-

box-shadow5+

-

string

-

0

-

Shadow style of the current component. The value consists of the horizontal position (mandatory), vertical position (mandatory), fuzzy radius (optional, default value: 0), extension distance (optional, default value: 0), and color (optional, default value: black) of the shadow.

-

Syntax: box-shadow: h-shadow v-shadow blur spread color

-

Example:

-
  • box-shadow :10px 20px 5px 10px #888888
  • box-shadow :100px 100px 30px red
  • box-shadow :-100px -100px 0px 40px
-

filter5+

-

string

-

-

-

Radius of the blur area within the component layout. If the radius is not set, the default value 0 (no blur area) is used. Percentage values are not supported.

-

Syntax: filter: blur(px)

-

Example:

-

filter: blur(10px)

-

backdrop-filter5+

-

string

-

-

-

Radius of the background blur area within the component layout. If the radius is not set, the default value 0 (no background blur) is used. Percentage values are not supported.

-

Syntax: backdrop-filter: blur(px)

-

Example:

-

backdrop-filter: blur(10px)

-

opacity

-

number

-

1

-

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

-

display

-

string

-

-

flex

-

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

-

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

-

number | string

-

-

-

How to divide available space of the parent component for each 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

-

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

-

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>

-

-

-

-

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>.

-
-

align-self6+

-

string

-

-

-

Alignment mode on the cross axis of the parent element. This style overwrites the align-items style of the parent element. The align-items style is used only in the div and list styles of the parent container. Text alignment mode. Available values include:

-
  • 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.
  • baseline: Items are aligned on the peracross axis.
-

position

-

string

-

relative

-

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> | <percentage>6+

-

-

-

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.
-

[start | end]6+

-

<length> | <percentage>

-

-

-

start | end must be used together with position to determine the offset of an element.

-
  • The start attribute specifies the start edge position of the element. This attribute defines the offset between the start edge of a positioned element and that of a block included in the element.
  • The end attribute specifies the end edge position of the element. This attribute defines the offset between the end edge of a positioned element and that of a block included in the element.
-

z-index6+

-

number

-

-

-

Rendering sequence of child nodes under the same parent node. The larger the value is, the later the rendering data is.

-
NOTE:

z-index does not support auto, and other styles such as opacity do not affect the rendering sequence of z-index.

-
-

image-fill6+

-

<color>

-

-

-

Indicates the fill color for SVG images. The following components (and attributes) are supported: button (icon attribute), piece (icon attribute), search (icon attribute), input (headericon attribute), textarea (headericon attribute), and image (src attribute), and toolbar-item (icon attribute).

-

The fill color value in the SVG image file is replaced with the value of image-fill during rendering, and is valid only for the fill attribute that is declared in the SVG image.

-

clip-path6+

-

[ <geometry-box> || <basic-shape> ] | none

-

-

-

Clip area of a component. Only the content within this area is displayed.

-

<geometry-box>: applicable scope of the clip area's width and height. The default value is border-box. Available values include:

-
  • margin-box: The width and height includes the margin.
  • border-box: The width and height includes the border.
  • padding-box: The width and height includes the padding.
  • content-box: The width and height does not include any margin, border, or padding.
-

<basic-shape>: shape of the clip area. Available values include:

-
  • inset, in the format of inset( <percentage>{1,4} [ round <'border-radius'> ]? ).
  • circle, in the format of circle( [&lt;percentage&gt;]? [ at <percentage> <percentage> ]? ).
  • ellipse, in the format of ellipse([&lt;percentage&gt;{2}]? [ at <percentage> <percentage> ]? ).
  • polygon, in the format of polygon( [ <percentage><percentage>]# )
  • path, in the format of path( <string> ).
-

mask-image6+

-
  • <linear-gradient>
  • string
-

-

-

Image used for the mask of a component:

-

Gradient color mask, for example:

-

linear-gradient(to left, black, white)

-

Solid color mask, for example:

-

linear-gradient(to right, grey , grey)

-

Mask filled by a local SVG image, for example, url(common/mask.svg)

-

mask-size6+

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

auto

-

Display size of the mask image. The setting is valid only when mask-image is set to an image source.

-

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 image to a large enough size so that it 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.
-

length indicates the width and height of the 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.

-

When you set the width and height with percentage values, the image size is set in relative to the original size. 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.

-

mask-position6+

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

0px 0px

-

Display position of the mask image. The setting is valid only when mask-image is set to an image source. 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.

-

The string values are as follows:

-
  • 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>.

-

border-image-source7+

-

string

-

-

-

Border image of the specified element.

-

Example:

-

border-image-source: url("/common/images/border.png")

-

border-image-slice7+

-

<length> | <percentage>

-

0

-

Padding of the image.

-

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).

-

border-image-width7+

-

<length> | <percentage>

-

0

-

Width of the border image.

-

If you set only one value, it specifies the width for four sides.

-

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

-

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

-

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

-

border-image-outset7+

-

<length> | <percentage>

-

0

-

How far the border image can extend beyond the border box.

-

If you set only one value, it specifies the distance of the boarder image beyond the border on four sides.

-

If you set two values, the first value specifies the distance of the boarder image's top and bottom sides beyond the boarder, and the second value specifies the distance of the boarder image's left and right sides beyond the boarder.

-

If you set three values, the first value specifies the distance of the boarder image's top side beyond the boarder, the second value specifies the distance of the boarder image's left and right sides beyond the boarder, and the third value specifies the distance of the boarder image's bottom side beyond the boarder.

-

If you set four values, they respectively specify the distance of the boarder image's top, right, bottom, and left sides beyond the boarder (in clockwise order).

-

border-image-repeat7+

-

string

-

stretch

-

How the border image fills the border box.

-

stretch: stretches the image to fill the border box.

-

repeat: tiles the image to fill the border box.

-

round: tiles the image to fill the border box. When the image cannot be tiled for an integer number of times, it can be scaled based on the site requirements.

-

border-image7+

-

string

-

-

-

Shorthand attribute. The options are as follows:

- -
  • Gradient color border.

    Example

    -

    border-image: linear-gradient(red, yellow) 10px

    -
-
->![](../../public_sys-resources/icon-note.gif) **NOTE:** ->The above-mentioned common styles are not mandatory. +> **NOTE**
+> The aforementioned universal styles are not mandatory. + +## Example + +### box-sizing + +```html +
+ + contentBox + + + borderBox + +
+``` +![en-us_image_0000001214837129](figures/en-us_image_0000001214837129.png) diff --git a/en/application-dev/reference/arkui-js/js-components-container-div.md b/en/application-dev/reference/arkui-js/js-components-container-div.md index 75dce6325edf1a515693b4f39445e296a2111c02..72233839d037680ed96b107f69c09f3e58c8b27a 100644 --- a/en/application-dev/reference/arkui-js/js-components-container-div.md +++ b/en/application-dev/reference/arkui-js/js-components-container-div.md @@ -1,705 +1,408 @@ -# div +# div -The **** component is a basic container that is used as the root node of the page structure or is used to group the content. +> **NOTE**
+> This component is supported since API version 4. Updates will be marked with a superscript to indicate their earliest API version. -## Required Permissions +The **\
** component is a basic container that is used as the root node of the page structure or is used to group the content. + +## Required Permissions None -## Child Components -Supported +## Child Components -## Attributes - -Attributes in [Universal Attributes](js-components-common-attributes.md) are supported. - -## Styles - -In addition to the styles in [Universal Styles](js-components-common-styles.md), the following styles are supported. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Default Value

-

Mandatory

-

Description

-

flex-direction

-

string

-

row

-

No

-

Main axis direction of the flex container. Available values are as follows:

-
  • column: Items are placed vertically from top to bottom.
  • row: Items are placed horizontally from left to right.
-

flex-wrap

-

string

-

nowrap

-

No

-

Whether flex items in the container are displayed in a single line or multiple lines. Currently, dynamic modification is not supported. Available values are as follows:

-
  • nowrap: Items are displayed on a single axis.
  • wrap: Items are displayed on multiple axes.
-

justify-content

-

string

-

flex-start

-

No

-

How items are aligned along the main axis of the current line in a flex container. Available values are as follows:

-
  • flex-start: Items are packed towards the start row.
  • flex-end: Items are packed towards the end row.
  • center: Items are centered along the row.
  • space-between: Items are positioned with space between the rows.
  • space-around: Items are positioned with space before, between, and after the rows.
  • space-evenly5+: Items are arranged with even space between each two.
-

align-items

-

string

-

stretch

-

No

-

How items are aligned along the cross axis of the current line in a flex container. 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.
-

align-content

-

string

-

flex-start

-

No

-

Multi-row alignment mode when there is extra space in the cross axis. Available values are as follows:

-
  • flex-start: All rows are packed towards the start of the cross axis. The start edge of the cross axis of the first row is aligned with the start edge of the cross axis of the container. All subsequent rows are aligned with the previous row.
  • flex-end: All rows are packed towards the end of the cross axis. The end of the cross axis of the last row is aligned with the end of the cross axis of the container. All subsequent rows are aligned with the previous row.
  • center: All rows are packed towards the center of the container. Rows are close to each other and aligned with the center of the container. The spacing between the start of the container's cross axis and the first row is equal to the spacing between the end of the container's cross axis and the last row.
  • space-between: All rows are evenly distributed in the container. The spacing between two adjacent rows is the same. The start and end edges of the container's cross axis are aligned with the edges of the first and last rows, respectively.
  • space-around: All rows are evenly distributed in the container, and the spacing between two adjacent lines is the same. The spacing between the start edge of the container's cross axis and the first row and that between the end edge and the last row are half of the spacing between two adjacent rows.
-

display

-

string

-

flex

-

No

-

Type of the view box of the element. Currently, dynamic modification is not supported. Available values are as follows:

-
  • flex: flexible layout
  • grid: grid layout
  • none: not rendered
-

grid-template-[columns|rows]

-

string

-

1 row, 1 column

-

No

-

Number of rows and columns in the current grid layout. If this attribute is not set, one row and one column are displayed by default. This attribute is valid only when display is set to grid.

-

For example, set grid-template-columns to:

-
  • 50px 100px 60px: There are three columns. The first column is 50 px, the second column is 100 px, and the third column is 60 px.
  • 1fr 1fr 2fr: There are three columns, and the width allowed by the parent component is divided into four equal shares. The first column occupies one share, the second column occupies one share, and the third column occupies two shares.
  • 30% 20% 50%: There are three columns. The first column occupies 30% of the total width allowed by the parent component, the second column occupies 20%, and the third column occupies 50%.
  • repeat (2,100px): There are two columns. The first column is 100 px, and the second column is 100 px.
  • repeat(auto-fill,100px)5+: Each column is 100 px and repeats to fill the cross axis. The number of columns is calculated based on the column size and the cross axis size.
  • auto 1fr 1fr: There are three columns. The first column is adaptive to the width required by its child components. The remaining space is divided into two equal shares, one share occupied by each of the rest two columns.
-

grid-[columns|rows]-gap

-

<length>

-

0

-

No

-

Size of the gap between two consecutive rows or columns in a grid layout. You can also use grid-gap to set the same size of the gap between rows and columns. This attribute is valid only when display is set to grid.

-

grid-row-[start|end]

-

number

-

-

-

No

-

Start and end row numbers of the current item in the grid layout. This attribute is valid only when display of the parent component is grid. (The display attribute of the parent component can be set to grid only for the <div> container.)

-

grid-column-[start|end]

-

number

-

-

-

No

-

Start and end column numbers of the current item in the grid layout. This attribute is valid only when display of the parent component is grid. (The display attribute of the parent component can be set to grid only for the <div> container.)

-

grid-auto-flow5+

-

string

-

-

-

No

-

Using an algorithm to lay out the grid automatically. Available values are as follows:

-
  • row: Elements are filled row by row. When there is no horizontal space in a row, a new row is added.
  • column: Elements are filled column by column. When there is no vertical space in a column, a new column is added.
-

overflow6+

-

string

-

visible

-

No

-

Display mode when the content exceeds the container size. Available values are as follows:

-
  • visible: Displays the extra content outside the container.
  • hidden: Truncates the extra content.
  • scroll: Scrolls the content vertically, with a scrollbar provided.
-
NOTE:
  • overflow works for elements whose size is fixed.
-
-

align-items6+

-

string

-

-

-

No

-

How items are aligned along the cross axis in a flex container. 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.
  • baseline: In a vertical layout, items are aligned to the start of the cross axis, which means that this value is equivalent of flex-start. In a horizontal layout, items are aligned with the text baseline if there is text involved, and aligned to the bottom otherwise.
-

scrollbar-color6+

-

<color>

-

-

-

No

-

Color of the scrollbar.

-

scrollbar-width6+

-

<length>

-

-

-

No

-

Width of the scrollbar.

-

overscroll-effect6+

-

string

-

-

-

No

-

Scrolling edge 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.
  • none: No effect after the scroll bar is moved to the edge.
-
- -## Events - -In addition to the events in [Universal Events](js-components-common-events.md), the following events are supported. - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Parameters

-

Description

-

reachstart6+

-

-

-

Triggered when the page scrolls to the beginning. This event is triggered only when flex-direction is row.

-

reachend6+

-

-

-

Triggered when the page scrolls to the end. This event is triggered only when flex-direction is row.

-

reachtop6+

-

-

-

Triggered when the page scrolls to the top. This event is triggered only when flex-direction is column.

-

reachbottom6+

-

-

-

Triggered when the page scrolls to the bottom. This event is triggered only when flex-direction is column.

-
- -## Methods - -In addition to the methods in [Universal Methods](js-components-common-methods.md), the following events are supported. - - - - - - - - - - - - - - - - - - - -

Name

-

Parameters

-

Return values

-

Description

-

getScrollOffset6+

-

-

-

ScrollOffset

-

Obtains the scrolling offset of the element content.

-
NOTE:
  • To use this method, overflow must be set to scroll. By default, the scrolling direction is the same as the container layout direction.
-
-

scrollBy6+

-

ScrollParam

-

-

-

Indicates the scrolling offset of the element content.

-
NOTE:
  • To use this method, overflow must be set to scroll.
-
-
- - -**Table 1** ScrollOffset6+ - - - - - - - - - - - - - - - - -

Name

-

Type

-

Description

-

x

-

number

-

Offset in the x-axis direction, in px.

-

y

-

number

-

Offset in the y-axis direction, in px.

-
- -**Table 2** ScrollParam6+ - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Description

-

dx

-

number

-

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

-

dy

-

number

-

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

-

smooth

-

boolean

-

Whether to perform smooth processing.

-
- -## Example - -1. Flex style - - ``` - -
-
-
-
-
-
-
- ``` - - ``` - /* xxx.css */ - .container { - flex-direction: column; - justify-content: center; - align-items: center; - width: 454px; - height: 454px; - } - .flex-box { - justify-content: space-around; - align-items: center; - width: 400px; - height: 140px; - background-color: #ffffff; - } - .flex-item { - width: 120px; - height: 120px; - border-radius: 16px; - } - .color-primary { - background-color: #007dff; - } - .color-warning { - background-color: #ff7500; - } - .color-success { - background-color: #41ba41; - } - ``` - - ![](figures/en-us_image_0000001127285076.png) - -2. Flex wrap style - - ``` - -
-
-
-
-
-
-
- ``` - - ``` - /* xxx.css */ - .container { - flex-direction: column; - justify-content: center; - align-items: center; - width: 454px; - height: 454px; - } - .flex-box { - justify-content: space-around; - align-items: center; - flex-wrap: wrap; - width: 300px; - height: 250px; - background-color: #ffffff; - } - .flex-item { - width: 120px; - height: 120px; - border-radius: 16px; - } - .color-primary { - background-color: #007dff; - } - .color-warning { - background-color: #ff7500; - } - .color-success { - background-color: #41ba41; - } - ``` - - ![](figures/22.png) - -3. Grid style - - ``` - -
-
-
-
-
-
- ``` - - ``` - /* xxx.css */ - .common { - width: 400px; - height: 400px; - background-color: #ffffff; - align-items: center; - justify-content: center; - margin: 24px; - } - .grid-parent { - display: grid; - grid-template-columns: 35% 35%; - grid-columns-gap: 24px; - grid-rows-gap: 24px; - grid-template-rows: 35% 35%; - } - .grid-child { - width: 100%; - height: 100%; - border-radius: 8px; - } - .grid-left-top { - grid-row-start: 0; - grid-column-start: 0; - grid-row-end: 0; - grid-column-end: 0; - background-color: #3f56ea; - } - .grid-left-bottom { - grid-row-start: 1; - grid-column-start: 0; - grid-row-end: 1; - grid-column-end: 0; - background-color: #00aaee; - } - .grid-right-top { - grid-row-start: 0; - grid-column-start: 1; - grid-row-end: 0; - grid-column-end: 1; - background-color: #00bfc9; - } - .grid-right-bottom { - grid-row-start: 1; - grid-column-start: 1; - grid-row-end: 1; - grid-column-end: 1; - background-color: #47cc47; - } - ``` - - ![](figures/11.png) - -4. Dragging7+ - - ``` - -
-
-
-
- ``` - - ``` - /* xxx.css */ - .container { - flex-direction: column; - } - .content{ - width: 200px; - height: 200px; - background-color: red; - } - ``` - - ``` - // xxx.js - import prompt from '@system.prompt'; - export default { - data:{ - left:0, - top:0, - }, - dragstart(e){ - prompt.showToast({ - message: 'Start to be dragged' - }) - }, - drag(e){ - this.left = e.globalX; - this.top = e.globalY; - }, - dragend(e){ - prompt.showToast({ - message: 'End Drag' - }) - }, - } - ``` - - ![](figures/9.gif) - - ``` - -
-
-
-
-
- ``` - - ``` - /* xxx.css */ - .container { - flex-direction: column; - width: 100%; - position: relative; - max-width: 100%; - } - .content{ - width: 200px; - height: 200px; - background-color: red; - position: absolute; - } - ``` - - ``` - // xxx.js - import prompt from '@system.prompt'; - export default { - data:{ - left:0, - top:0, - }, - drag(e){ - this.left = e.globalX; - this.top = e.globalY; - }, - dragenter(e){ - prompt.showToast({ - message: 'enter' - }) - }, - dragover(e){ - prompt.showToast({ - message: 'over' - }) - }, - dragleave(e){ - prompt.showToast({ - message: 'leave' - }) - }, - drop(e){ - prompt.showToast({ - message: 'drop' - }) - } - } - ``` - - ![](figures/6.gif) - -5. Pinching7+ - - ``` - -
-
-
-
- ``` - - ``` - /* xxx.css */ - .container { - flex-direction: column; - justify-content: center; - align-items: center; - width: 454px; - height: 454px;} - .content{ - width: 400px; - height: 400px; - background-color: aqua; - margin:30px - } - ``` - - ``` - // xxx.js - import prompt from '@system.prompt'; - export default { - pinchstart(e){ - prompt.showToast({ - message: 'pinchstart!!!' - }) - }, - pinchupdate(e){ - prompt.showToast({ - message: 'Two-finger pinch update' - }) - }, - pinchend(e){ - prompt.showToast({ - message: 'Finished with two fingers pinching' - }) - }, - pinchcancel(e){ - prompt.showToast({ - message: 'Finger pinching is interrupted' - }) - } - } - ``` +Supported - ![](figures/5.gif) +## Attributes + +The [universal attributes](../arkui-js/js-components-common-attributes.md) are supported. + + +## Styles + +In addition to the [universal styles](../arkui-js/js-components-common-styles.md), the following styles are supported. + +| Name | Type | Default Value | Mandatory | Description | +| ------------------------------ | -------------- | ------------ | ---- | ---------------------------------------- | +| flex-direction | string | row | No | Main axis direction of the flex container, which defines how items are placed in the container. Available values are as follows:
- **column**: Items are placed vertically from top to bottom.
- **row**: Items are placed horizontally from left to right.| +| flex-wrap | string | nowrap | No | Whether items in the flex container are displayed in a single line or multiple lines. The value cannot be dynamically updated. Available values are as follows:
- **nowrap**: Items are displayed on a single axis.
- **wrap**: Items are displayed on multiple axes.| +| justify-content | string | flex-start | No | How items are aligned along the main axis of the flex container. Available values are as follows:
- **flex-start**: Items are packed towards the start row.
- **flex-end**: Items are packed towards the end row.
- **center**: Items are centered along the row.
- **space-between**: Items are positioned with space between the rows.
- **space-around**: Items are positioned with space before, between, and after the rows.
- **space-evenly**5+: Items are arranged with even space between each two.| +| align-items | string | stretch
| No | How items are aligned along the cross axis of the flex container. 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 center of the cross axis.| +| align-content | string | flex-start | No | Multi-row alignment mode when there is extra space in the cross axis. Available values are as follows:
- **flex-start**: All rows are packed towards the start of the cross axis. The start edge of the cross axis of the first row is aligned with the start edge of the cross axis of the container. All subsequent rows are aligned with the previous row.
- **flex-end**: All rows are packed towards the end of the cross axis. The end of the cross axis of the last row is aligned with the end of the cross axis of the container. All subsequent rows are aligned with the previous row.
- **center**: All rows are packed towards the center of the container. Rows are close to each other and aligned with the center of the container. The spacing between the start edge of the container's cross axis and the first row is equal to the spacing between the end edge of the container's cross axis and the last row.
- **space-between**: All rows are evenly distributed in the container. The spacing between two adjacent rows is the same. The start and end edges of the container's cross axis are aligned with the edges of the first and last rows, respectively.
- **space-around**: All rows are evenly distributed in the container, and the spacing between two adjacent lines is the same. The spacing between the start edge of the container's cross axis and the first row and that between the end edge and the last row are half of the spacing between two adjacent rows.| +| display | string | flex | No | Type of the view box of the item. The value cannot be dynamically updated. Available values are as follows:
- **flex**: flexible layout.
- **grid**: grid layout.
- **none**: The box is disabled.
- **inline-flex**9+: layout with the **flex** and **inline-block** effects.| +| grid-template-[columns\|rows] | string | 1 row, 1 column | No | Number of rows and columns in the current grid layout. If this attribute is not set, one row and one column are displayed by default. This attribute is valid only when **display** is set to **grid**.
Below are some example values of **grid-template-columns**:
- **50px 100px 60px**: There are three columns. The first column is 50 px, the second column is 100 px, and the third column is 60 px.
- **1fr 1fr 2fr**: There are three columns, and the width allowed by the parent component is divided into four equal shares. The first column occupies one share, the second column occupies one share, and the third column occupies two shares.
- **30% 20% 50%**: There are three columns. The first column occupies 30% of the total width allowed by the parent component, the second column occupies 20%, and the third column occupies 50%.
- **repeat (2,100px)**: There are two columns. The first column is 100 px, and the second column is 100 px.
- **repeat(auto-fill,100px)**5+: Each column is 100 px and repeats to fill the cross axis. The number of columns is calculated based on the column size and the cross axis size.
- **auto 1fr 1fr**: There are three columns. The first column is adaptive to the width required by its child components. The remaining space is divided into two equal shares, one share occupied by each of the rest two columns.| +| grid-[columns\|rows]-gap | \ | 0 | No | Size of the gap between two consecutive rows or columns in a grid layout. You can also use **grid-gap** to set the same size of the gap between rows and columns. This attribute is valid only when **display** is set to **grid**.| +| grid-row-[start\|end] | number | - | No | Start and end row numbers of the current item in the grid layout. This attribute is valid only when the item's parent component is a **\
** container whose **display** style is set to **grid**.| +| grid-column-[start\|end] | number | - | No | Start and end column numbers of the current item in the grid layout. This attribute is valid only when the item's parent component is a **\
** container whose **display** style is set to **grid**.| +| grid-auto-flow5+ | string | - | No | How grid items are laid out automatically. Available values are as follows:
- **row**: Elements are filled row by row. When there is no horizontal space in a row, a new row is added.
- **column**: Elements are filled column by column. When there is no vertical space in a column, a new column is added.| +| overflow6+ | string | visible | No | Display mode when the content exceeds the container size. Available values are as follows:
- **visible**: Displays the extra content outside the container.
- **hidden**: Truncates the excess content.
- **scroll**: Scrolls the content vertically, with a scrollbar provided.
**scroll** works for elements whose size is fixed. By default, the scrolling direction is the same as the container direction.| +| align-items6+ | string | - | No | How items are aligned along the cross axis in a flex container. 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 center of the cross axis.
- **baseline**: In a vertical layout, items are aligned to the start of the cross axis, which means that this value is equivalent of **flex-start**. In a horizontal layout, items are aligned with the text baseline if there is text involved, and aligned to the bottom otherwise.| +| scrollbar-color6+ | \ | - | No | Color of the scrollbar. | +| scrollbar-width6+ | \ | - | No | Width of the scrollbar. | +| overscroll-effect6+ | string | - | No | How the scrollbar behaves when it reaches the edge of the scrolling area. 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.
- **none**: No effect after the scroll bar is moved to the edge.| + + +## Events + +In addition to the [universal events](../arkui-js/js-components-common-events.md), the following events are supported. + +| Name | Parameter | Description | +| ------------------------ | ---- | ---------------------------------------- | +| reachstart6+ | - | Triggered when the page scrolls to the beginning. This event is triggered only when **flex-direction** is **row**.| +| reachend6+ | - | Triggered when the page scrolls to the end. This event is triggered only when **flex-direction** is **row**.| +| reachtop6+ | - | Triggered when the page scrolls to the top. This event is triggered only when **flex-direction** is **column**.| +| reachbottom6+ | - | Triggered when the page scrolls to the bottom. This event is triggered only when **flex-direction** is **column**.| + +## Methods + +In addition to the [universal methods](js-components-common-methods.md), the following methods are supported. + +| Name | Name | Return Value | Description | +| ---------------------------- | ----------- | ------------ | --------------------------------------- | +| getScrollOffset6+ | - | ScrollOffset | Obtains the scrolling offset of the element content.
To use this method, **overflow** must be set to **scroll**.| +| scrollBy6+ | ScrollParam | - | Sets the scrolling offset of the element content.
To use this method, **overflow** must be set to **scroll**.| + +**Table 1** ScrollOffset6+ + +| Name | Type | Description | +| ---- | ------ | --------------- | +| x | number | Offset in the x-axis direction, in px.| +| y | number | Offset in the y-axis direction, in px.| + +**Table 2** ScrollParam6+ + +| Name | Type | Description | +| ------ | ------- | ---------------- | +| dx | number | Offset for scrolling in the horizontal direction, in px.| +| dy | number | Offset for scrolling in the vertical direction, in px.| +| smooth | boolean | Whether to perform smooth processing. | + + +## Example + +1. Flex style + ```html + +
+
+
+
+
+
+
+ ``` + + ```css + /* xxx.css */ + .container { + flex-direction: column; + justify-content: center; + align-items: center; + width: 454px; + height: 454px; + } + .flex-box { + justify-content: space-around; + align-items: center; + width: 400px; + height: 140px; + background-color: #ffffff; + } + .flex-item { + width: 120px; + height: 120px; + border-radius: 16px; + } + .color-primary { + background-color: #007dff; + } + .color-warning { + background-color: #ff7500; + } + .color-success { + background-color: #41ba41; + } + ``` + + ![en-us_image_0000001127285076](figures/en-us_image_0000001127285076.png) + +2. Flex wrap style + ```html + +
+
+
+
+
+
+
+ ``` + + ```css + /* xxx.css */ + .container { + flex-direction: column; + justify-content: center; + align-items: center; + width: 454px; + height: 454px; + } + .flex-box { + justify-content: space-around; + align-items: center; + flex-wrap: wrap; + width: 300px; + height: 250px; + background-color: #ffffff; + } + .flex-item { + width: 120px; + height: 120px; + border-radius: 16px; + } + .color-primary { + background-color: #007dff; + } + .color-warning { + background-color: #ff7500; + } + .color-success { + background-color: #41ba41; + } + ``` + + ![22](figures/22.png) + +3. Grid style + + ```html + +
+
+
+
+
+
+ ``` + + ```css + /* xxx.css */ + .common { + width: 400px; + height: 400px; + background-color: #ffffff; + align-items: center; + justify-content: center; + margin: 24px; + } + .grid-parent { + display: grid; + grid-template-columns: 35% 35%; + grid-columns-gap: 24px; + grid-rows-gap: 24px; + grid-template-rows: 35% 35%; + } + .grid-child { + width: 100%; + height: 100%; + border-radius: 8px; + } + .grid-left-top { + grid-row-start: 0; + grid-column-start: 0; + grid-row-end: 0; + grid-column-end: 0; + background-color: #3f56ea; + } + .grid-left-bottom { + grid-row-start: 1; + grid-column-start: 0; + grid-row-end: 1; + grid-column-end: 0; + background-color: #00aaee; + } + .grid-right-top { + grid-row-start: 0; + grid-column-start: 1; + grid-row-end: 0; + grid-column-end: 1; + background-color: #00bfc9; + } + .grid-right-bottom { + grid-row-start: 1; + grid-column-start: 1; + grid-row-end: 1; + grid-column-end: 1; + background-color: #47cc47; + } + ``` + + ![11](figures/11.png) + +4. Dragging7+ + ```html + +
+
+
+
+ ``` + + ```css + /* xxx.css */ + .container { + flex-direction: column; + } + .content{ + width: 200px; + height: 200px; + background-color: red; + } + ``` + + ```js + // xxx.js + import prompt from '@system.prompt'; + export default { + data:{ + left:0, + top:0, + }, + dragstart(e){ + prompt.showToast({ + message: 'Start to be dragged' + }) + }, + drag(e){ + this.left = e.globalX; + this.top = e.globalY; + }, + dragend(e){ + prompt.showToast({ + message: 'End Drag' + }) + }, + } + ``` + + ![9](figures/9.gif) + + ```html + +
+
+
+
+
+ ``` + + ```css + /* xxx.css */ + .container { + flex-direction: column; + width: 100%; + position: relative; + max-width: 100%; + } + .content{ + width: 200px; + height: 200px; + background-color: red; + position: absolute; + } + ``` + + ```js + // xxx.js + import prompt from '@system.prompt'; + export default { + data:{ + left:0, + top:0, + }, + drag(e){ + this.left = e.globalX; + this.top = e.globalY; + }, + dragenter(e){ + prompt.showToast({ + message: 'enter' + }) + }, + dragover(e){ + prompt.showToast({ + message: 'over' + }) + }, + dragleave(e){ + prompt.showToast({ + message: 'leave' + }) + }, + drop(e){ + prompt.showToast({ + message: 'drop' + }) + } + } + ``` + + ![6](figures/6.gif) + +5. Pinching7+ + ```html + +
+
+
+
+ ``` + + ```css + /* xxx.css */ + .container { + flex-direction: column; + justify-content: center; + align-items: center; + width: 454px; + height: 454px;} + .content{ + width: 400px; + height: 400px; + background-color: aqua; + margin:30px + } + ``` + + ```js + // xxx.js + import prompt from '@system.prompt'; + export default { + pinchstart(e){ + prompt.showToast({ + message: 'pinchstart!!!' + }) + }, + pinchupdate(e){ + prompt.showToast({ + message: 'Two-finger pinch update' + }) + }, + pinchend(e){ + prompt.showToast({ + message: 'Finished with two fingers pinching' + }) + }, + pinchcancel(e){ + prompt.showToast({ + message: 'Finger pinching is interrupted' + }) + } + } + ``` + + ![5](figures/5.gif)