diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/custom_layout10.png b/zh-cn/application-dev/reference/arkui-ts/figures/custom_layout10.png new file mode 100644 index 0000000000000000000000000000000000000000..21b248c0872ca6d415d73caca1bb07489f35302f Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/custom_layout10.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-custom-component-lifecycle.md b/zh-cn/application-dev/reference/arkui-ts/ts-custom-component-lifecycle.md index e5db57b1f4d231c8f3a37c700a03f284878d251a..ee8f7631090d5cc924cf5550c4b3391357cb219b 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-custom-component-lifecycle.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-custom-component-lifecycle.md @@ -81,37 +81,68 @@ struct IndexComponent { ![zh-cn_image_0000001563060749](figures/zh-cn_image_0000001563060749.png) -## onLayout9+ +## onLayout(deprecated) onLayout?(children: Array<LayoutChild>, constraint: ConstraintSizeOptions): void -框架会在自定义组件布局时，将该自定义组件的子节点信息和自身的尺寸范围通过onLayout传递给该自定义组件。不允许在onLayout函数中改变状态变量。 +ArkUI框架会在自定义组件布局时，将该自定义组件的子节点信息和自身的尺寸范围通过onLayout传递给该自定义组件。不允许在onLayout函数中改变状态变量。 -从API version 9开始，该接口支持在ArkTS卡片中使用。 +该接口从API version 9开始支持，从API version 10开始废弃，推荐使用[onPlaceChildren](#onplacechildren10)替代。 **参数：** -| 参数名 | 类型 | 说明 | -| ---------- | ---------------------------------------- | ---------------- | -| children | Array<[LayoutChild](#layoutchild9)> | 子组件布局信息。 | +| 参数名 | 类型 | 说明 | +|------------|------------------------------------------------------------|------------------| +| children | Array<[LayoutChild](#layoutchild(deprecated))> | 子组件布局信息。 | | constraint | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | 父组件constraint信息。 | +## onPlaceChildren10+ + +onPlaceChildren?(selfLayoutInfo: GeometryInfo, children: Array<Layoutable>, constraint: ConstraintSizeOptions):void + +ArkUI框架会在自定义组件布局时，将该自定义组件的子节点自身的尺寸范围通过onPlaceChildren传递给该自定义组件。不允许在onPlaceChildren函数中改变状态变量。 -## onMeasure9+ +从API version 10开始，该接口支持在ArkTS卡片中使用。 + +**参数：** + +| 参数名 | 类型 | 说明 | +|----------------|------------------------------------------------------------|------------------| +| selfLayoutInfo | [GeometryInfo](#geometryinfo10) | 父组件布局信息。 | +| children | Array<[Layoutable](#layoutable10)> | 子组件布局信息。 | +| constraint | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | 父组件constraint信息。 | + +## onMeasure(deprecated) onMeasure?(children: Array<LayoutChild>, constraint: ConstraintSizeOptions): void -框架会在自定义组件确定尺寸时，将该自定义组件的子节点信息和自身的尺寸范围通过onMeasure传递给该自定义组件。不允许在onMeasure函数中改变状态变量。 +ArkUI框架会在自定义组件确定尺寸时，将该自定义组件的子节点信息和自身的尺寸范围通过onMeasure传递给该自定义组件。不允许在onMeasure函数中改变状态变量。 -从API version 9开始，该接口支持在ArkTS卡片中使用。 +该接口从API version 9开始支持，从API version 10开始废弃，推荐使用[onMeasureSize](#onmeasuresize10+)替代。 **参数：** -| 参数名 | 类型 | 说明 | -| ---------- | ---------------------------------------- | ---------------- | -| children | Array<[LayoutChild](#layoutchild9)> | 子组件布局信息。 | +| 参数名 | 类型 | 说明 | +|------------|------------------------------------------------------------|------------------| +| children | Array<[LayoutChild](#layoutchild(deprecated))> | 子组件布局信息。 | | constraint | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | 父组件constraint信息。 | +## onMeasureSize10+ + +onMeasureSize?(selfLayoutInfo: GeometryInfo, children: Array<Measurable>, constraint: ConstraintSizeOptions):MeasureResult + +ArkUI框架会在自定义组件确定尺寸时，将该自定义组件的节点信息和尺寸范围通过onMeasureSize传递给该开发者。不允许在onMeasureSize函数中改变状态变量。 + +从API version 10开始，该接口支持在ArkTS卡片中使用。 + +**参数：** + +| 参数名 | 类型 | 说明 | +|----------------|------------------------------------------------------------|------------------| +| selfLayoutInfo | [GeometryInfo](#geometryinfo10) | 父组件布局信息。 | +| children | Array<[Measurable](#measurable10)> | 子组件布局信息。 | +| constraint | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | 父组件constraint信息。 | + ## aboutToReuse10+ aboutToReuse?(params: { [key: string]: unknown }): void @@ -123,9 +154,8 @@ aboutToReuse?(params: { [key: string]: unknown }): void **参数：** | 参数名 | 类型 | 说明 | -| ------ | -------------------------- | ---------- | -| params | { [key: string]: unknown } | 自定义组件的构造参数 | - +|--------|----------------------------|------------| +| params | { [key: string]: unknown } | 自定义组件的构造参数。| ```ts // xxx.ets @@ -170,48 +200,46 @@ struct Child { } ``` -## LayoutChild9+ +## LayoutChild(deprecated) 子组件布局信息。 -从API version 9开始，该接口支持在ArkTS卡片中使用。 +从API version 9开始，从API version 10开始废弃，该接口支持在ArkTS卡片中使用。 -| 参数 | 参数类型 | 描述 | -| ---------- | ---------------------------------------- | ------------------- | -| name | string | 子组件名称。 | -| id | string | 子组件id。 | -| constraint | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | 子组件约束尺寸。 | -| borderInfo | [LayoutBorderInfo](#layoutborderinfo9) | 子组件border信息。 | -| position | [Position](ts-types.md#position) | 子组件位置坐标。 | -| measure | (childConstraint:) => void | 调用此方法对子组件的尺寸范围进行限制。 | -| layout | (LayoutInfo： [LayoutInfo](#layoutinfo9)) => void | 调用此方法对子组件的位置信息进行限制。 | +| 参数 | 参数类型 | 描述 | +|------------|--------------------------------------------------------------------|---------------------| +| name | string | 子组件名称。 | +| id | string | 子组件id。 | +| constraint | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | 子组件约束尺寸。 | +| borderInfo | [LayoutBorderInfo](#layoutborderinfo(deprecated)) | 子组件border信息。 | +| position | [Position](ts-types.md#position) | 子组件位置坐标。 | +| measure | (childConstraint:) => void | 调用此方法对子组件的尺寸范围进行限制。 | +| layout | (LayoutInfo： [LayoutInfo](#layoutinfo(deprecated))) => void | 调用此方法对子组件的位置信息进行限制。 | -## LayoutBorderInfo9+ +## LayoutBorderInfo(deprecated) 子组件border信息。 -从API version 9开始，该接口支持在ArkTS卡片中使用。 +从API version 9开始，从API version 10开始废弃，该接口支持在ArkTS卡片中使用。 | 参数 | 参数类型 | 描述 | -| ----------- | ------------------------------------ | ----------------------- | +|-------------|--------------------------------------|-------------------------| | borderWidth | [EdgeWidths](ts-types.md#edgewidths) | 边框宽度类型，用于描述组件边框不同方向的宽度。 | | margin | [Margin](ts-types.md#margin) | 外边距类型，用于描述组件不同方向的外边距。 | | padding | [Padding](ts-types.md#padding) | 内边距类型，用于描述组件不同方向的内边距。 | - -## LayoutInfo9+ +## LayoutInfo(deprecated) 子组件layout信息。 -从API version 9开始，该接口支持在ArkTS卡片中使用。 +从API version 9开始，从API version 10开始废弃，该接口支持在ArkTS卡片中使用。 -| 参数 | 参数类型 | 描述 | -| ---------- | ---------------------------------------- | -------- | -| position | [Position](ts-types.md#position) | 子组件位置坐标。 | +| 参数 | 参数类型 | 描述 | +|------------|------------------------------------------------------------|----------| +| position | [Position](ts-types.md#position) | 子组件位置坐标。 | | constraint | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | 子组件约束尺寸。 | - ```ts // xxx.ets @Entry @@ -258,3 +286,122 @@ struct CustomLayout { ``` ![zh-cn_image_0000001511900496](figures/zh-cn_image_0000001511900496.png) + +## GeometryInfo10+ + +父组件布局信息。 + +从API version 10开始支持，该接口支持在ArkTS卡片中使用。 + +| 参数 | 参数类型 | 描述 | +|-------------|-----------|---------------------| +| borderWidth | [EdgeWidth](ts-types.md#edgewidths) | 父组件边框宽度。 | +| margin | [Margin](ts-types.md#margin) | 父组件margin信息。 | +| padding | [Padding](ts-types.md#padding) | 父组件padding信息。 | + + +## Layoutable10+ + +子组件布局信息。 + +从API version 10开始支持，该接口支持在ArkTS卡片中使用。 + +| 参数 | 参数类型 | 描述 | +|------------|---------------------------------------------------------|---------------------| +| measureResult| [MeasureResult](#measureresult10+) | 子组件测量后的尺寸信息。 | +| layout | ([Position](ts-types.md#position)) => void | 调用此方法对子组件的位置信息进行限制。 | + +## Measurable10+ + +子组件位置信息。 + +从API version 10开始支持，该接口支持在ArkTS卡片中使用。 + +| 参数 | 参数类型 | 描述 | +|------------|----------------------------------------------------------------------------------|---------------------------------------| +| measure | (childConstraint:) => [MeasureResult](#measureresult10+) | 调用此方法对子组件的尺寸范围进行限制。
返回值：子组件测量后的尺寸。 | + +## MeasureResult10+ + +测量后的组件布局信息。 + +从API version 10开始，该接口支持在ArkTS卡片中使用。 + +| 参数 | 参数类型 | 描述 | +|--------|--------|-------| +| width | Number | 测量后的宽。 | +| height | Number | 测量后的高。 | + + +## SizeResult10+ + +组件尺寸信息。 + +从API version 10开始，该接口支持在ArkTS卡片中使用。 + +| 参数 | 参数类型 | 描述 | +|--------|--------|-------| +| width | Number | 测量后的宽。 | +| height | Number | 测量后的高。 | + +> **说明：** +> +>- 自定义布局暂不支持LazyForEach写法 +>- 使用builder形式的自定义布局创建，自定义组件的build()方法内只允许存在this.builder()，即示例的推荐用法 +>- 子组件设置的位置信息和尺寸信息，优先级小于onMeasureSize设置的尺寸信息和onPlaceChildren设置的位置信息 +>- onPlaceChildren和onMeasureSize使用自定义组件写法时，暂不支持尾随闭包式写法，建议使用示例内写法 + +``` +// xxx.ets +@Entry +@Component +struct Index { + build() { + Column() { + CustomLayout({ builder: ColumnChildren }) + } + } +} + +@Builder +function ColumnChildren() { + ForEach([1, 2, 3], (index) => { //暂不支持lazyForEach的写法 + Text('S' + index) + .fontSize(30) + .width(100) + .height(100) + .borderWidth(2) + .offset({ x: 10, y: 20 }) + }) +} + +@Component +struct CustomLayout { + @BuilderParam builder: () => void; + @State startSize: number = 100; + + onPlaceChildren(selfLayoutInfo: GeometryInfo, children: Array, constraint: ConstraintSizeOptions) { + let startPos = 400; + children.forEach((child) => { + let pos = startPos - child.measureResult.height; + child.layout({ x: pos, y: pos }) + }) + } + + onMeasureSize(selfLayoutInfo: GeometryInfo, children: Array, constraint: ConstraintSizeOptions) { + let size = 100; + children.forEach((child) => { + let result: MeasureResult = child.measure({ minHeight: size, minWidth: size, maxWidth: size, maxHeight: size }) + size += result.width / 2 + ; + }) + return { width: 100, height: 400 }; + } + + build() { + this.builder() + } +} +``` + +![custom_layout10.png](figures/custom_layout10.png) \ No newline at end of file