鸿蒙5.0开发进阶：ArkTS组件-自定义组件的自定义布局

最新推荐文章于 2025-12-02 00:52:42 发布
原创 最新推荐文章于 2025-12-02 00:52:42 发布 · 1k 阅读 · 19 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#harmonyos #华为 #android #前端 #鸿蒙系统 #ArkUI #ArkTS

往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

自定义组件的自定义布局

自定义组件的自定义布局用于通过数据计算的方式布局自定义组件内的子组件。

说明

本模块首批接口从API version 9开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。

onPlaceChildren10+

onPlaceChildren?(selfLayoutInfo: GeometryInfo, children: Array<Layoutable>, constraint: ConstraintSizeOptions):void

ArkUI框架会在自定义组件布局时，将该自定义组件的子节点自身的尺寸范围通过onPlaceChildren传递给该自定义组件。不允许在onPlaceChildren函数中改变状态变量。

系统能力： SystemCapability.ArkUI.ArkUI.Full

元服务API： 从API version 11开始，该接口支持在元服务中使用。

参数：

参数名类型说明
selfLayoutInfoGeometryInfo父组件布局信息。
childrenArray<Layoutable>子组件布局信息。
constraintConstraintSizeOptions父组件constraint信息。

示例：

示例请参考自定义布局代码示例。

onMeasureSize10+

onMeasureSize?(selfLayoutInfo: GeometryInfo, children: Array<Measurable>, constraint: ConstraintSizeOptions): SizeResult

ArkUI框架会在自定义组件确定尺寸时，将该自定义组件的节点信息和尺寸范围通过onMeasureSize传递给该开发者。不允许在onMeasureSize函数中改变状态变量。

系统能力： SystemCapability.ArkUI.ArkUI.Full

元服务API： 从API version 11开始，该接口支持在元服务中使用。

参数：

参数名类型说明
selfLayoutInfoGeometryInfo父组件布局信息。
childrenArray<Measurable>

子组件布局信息。

说明：

如果没有设置子组件的布局信息，子组件会维持上一次的布局信息，当子组件从来没有设置过尺寸时，尺寸默认为0。

constraintConstraintSizeOptions父组件constraint信息。

返回值：

类型描述
SizeResult组件尺寸信息。

示例一：

自定义布局代码示例。

// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Column() {
      CustomLayout({ builder: ColumnChildren })
    }
  }
}

@Builder
function ColumnChildren() {
  ForEach([1, 2, 3], (index: number) => { //暂不支持lazyForEach的写法
    Text('S' + index)
      .fontSize(30)
      .width(100)
      .height(100)
      .borderWidth(2)
      .offset({ x: 10, y: 20 })
  })
}

@Component
struct CustomLayout {
  @Builder
  doNothingBuilder() {
  };

  @BuilderParam builder: () => void = this.doNothingBuilder;
  @State startSize: number = 100;
  result: SizeResult = {
    width: 0,
    height: 0
  };

  onPlaceChildren(selfLayoutInfo: GeometryInfo, children: Array<Layoutable>, constraint: ConstraintSizeOptions) {
    let startPos = 300;
    children.forEach((child) => {
      let pos = startPos - child.measureResult.height;
      child.layout({ x: pos, y: pos })
    })
  }

  onMeasureSize(selfLayoutInfo: GeometryInfo, children: Array<Measurable>, 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
      ;
    })
    this.result.width = 100;
    this.result.height = 400;
    return this.result;
  }

  build() {
    this.builder()
  }
}

示例二：

通过组件的位置灵活判断是否参与布局计算。

// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Column() {
      CustomLayout({ builder: ColumnChildren })
    }
    .justifyContent(FlexAlign.Center)
    .width("100%")
    .height("100%")
  }
}

@Builder
function ColumnChildren() {
  ForEach([1, 2, 3], (item: number, index: number) => { //暂不支持lazyForEach的写法
    Text('S' + item)
      .fontSize(20)
      .width(60 + 10 * index)
      .height(100)
      .borderWidth(2)
      .margin({ left:10 })
      .padding(10)
  })
}

@Component
struct CustomLayout {
  // 只布局一行，如果布局空间不够的子组件不显示的demo
  @Builder
  doNothingBuilder() {
  };

  @BuilderParam builder: () => void = this.doNothingBuilder;
  result: SizeResult = {
    width: 0,
    height: 0
  };
  overFlowIndex: number = -1;

  onPlaceChildren(selfLayoutInfo: GeometryInfo, children: Array<Layoutable>, constraint: ConstraintSizeOptions) {
    let currentX = 0;
    let infinity = 100000;
    if (this.overFlowIndex == -1) {
      this.overFlowIndex = children.length;
    }
    for (let index = 0; index < children.length; ++index) {
      let child = children[index];
      if (index >= this.overFlowIndex) {
        // 如果子组件超出父组件范围，将它布局到较偏的位置，达到不显示的目的
        child.layout({x: infinity, y: 0});
        continue;
      }
      child.layout({ x: currentX, y: 0 })
      let margin = child.getMargin();
      currentX += child.measureResult.width + margin.start + margin.end;
    }
  }

  onMeasureSize(selfLayoutInfo: GeometryInfo, children: Array<Measurable>, constraint: ConstraintSizeOptions) {
    let width = 0;
    let height = 0;
    this.overFlowIndex = -1;
    // 假定该组件的宽度不能超过200vp，也不能超过最大约束
    let maxWidth = Math.min(200, constraint.maxWidth as number);
    for (let index = 0; index < children.length; ++index) {
      let child = children[index];
      let childResult: MeasureResult = child.measure({
          minHeight: constraint.minHeight,
          minWidth: constraint.minWidth,
          maxWidth: constraint.maxWidth,
          maxHeight: constraint.maxHeight
      })
      let margin = child.getMargin();
      let newWidth = width + childResult.width + margin.start + margin.end;
      if (newWidth > maxWidth) {
        // 记录不该布局的组件的下标
        this.overFlowIndex = index;
        break;
      }
      // 累积父组件的宽度和高度
      width = newWidth;
      height = Math.max(height, childResult.height + margin.top + margin.bottom);
    }
    this.result.width = width;
    this.result.height = height;
    return this.result;
  }

  build() {
    this.builder()
  }
}

GeometryInfo10+

父组件布局信息，继承自SizeResult。

系统能力： SystemCapability.ArkUI.ArkUI.Full

元服务API： 从API version 11开始，该接口支持在元服务中使用。

属性类型说明
borderWidthEdgeWidth

父组件边框宽度。

单位：vp

marginMargin

父组件margin信息。

单位：vp

paddingPadding

父组件padding信息。

单位：vp

widthnumber

测量后的宽。

单位：vp

说明：

若值为空时，则返回组件的百分比宽。

heightnumber

测量后的高。

单位：vp

说明：

若值为空时，则返回组件的百分比高。

Layoutable10+

子组件布局信息。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性

属性类型必填说明
measureResultMeasureResult是

子组件测量后的尺寸信息,继承自SizeResult

元服务API： 从API version 11开始，该接口支持在元服务中使用。

单位：vp

layout

layout(position: Position)

调用此方法对子组件的位置信息进行限制。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
positionPosition是位置。

getMargin12+

getMargin() : DirectionalEdgesT<number>

调用此方法获得子组件的margin信息。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

返回值：

类型说明
DirectionalEdgesT<number>子组件的margin信息。

getPadding12+

getPadding() : DirectionalEdgesT<number>

调用此方法获得子组件的padding信息。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

返回值：

类型说明
DirectionalEdgesT<number>子组件的padding信息。

getBorderWidth12+

getBorderWidth() : DirectionalEdgesT<number>

调用此方法获得子组件的borderWidth信息。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

返回值：

类型说明
DirectionalEdgesT<number>子组件的borderWidth信息。

Measurable10+

子组件位置信息。

系统能力： SystemCapability.ArkUI.ArkUI.Full

元服务API： 从API version 11开始，该接口支持在元服务中使用。

measure

measure(constraint: ConstraintSizeOptions) : MeasureResult

调用此方法对子组件的尺寸范围进行限制。

系统能力： SystemCapability.ArkUI.ArkUI.Full

元服务API： 从API version 11开始，该接口支持在元服务中使用。

参数：

参数名类型必填说明
constraintConstraintSizeOptions是约束尺寸。

返回值：

类型说明
MeasureResult测量后的组件布局信息。

getMargin12+

getMargin() : DirectionalEdgesT<number>

获取子组件的margin信息。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

返回值：

类型说明
DirectionalEdgesT<number>子组件的margin信息。

getPadding12+

getPadding() : DirectionalEdgesT<number>

获取子组件的padding信息。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

返回值：

类型说明
DirectionalEdgesT<number>子组件的padding信息。

getBorderWidth12+

getBorderWidth() : DirectionalEdgesT<number>

获取子组件的borderWidth信息。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

返回值：

类型说明
DirectionalEdgesT<number>子组件的borderWidth信息。

MeasureResult10+

测量后的组件布局信息。

系统能力： SystemCapability.ArkUI.ArkUI.Full

元服务API： 从API version 11开始，该接口支持在元服务中使用。

属性类型说明
widthnumber

测量后的宽。

单位：vp

heightnumber

测量后的高。

单位：vp

SizeResult10+

组件尺寸信息。

系统能力： SystemCapability.ArkUI.ArkUI.Full

元服务API： 从API version 11开始，该接口支持在元服务中使用。

属性类型说明
widthnumber

测量后的宽。

单位：vp

heightnumber

测量后的高。

单位：vp

DirectionalEdgesT<T>12+

全球化的边缘属性。

系统能力： SystemCapability.ArkUI.ArkUI.Full

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

属性类型说明
startT起始边缘的属性。在LTR的方向下，为左边缘，在RTL的方向下，为右边缘。
endT终止边缘的属性。在LTR的方向下，为右边缘，在RTL的方向下，为左边缘。
topT顶部边缘的属性。
bottomT底部边缘的属性。

说明

  • 自定义布局暂不支持LazyForEach写法。
  • 使用builder形式的自定义布局创建，自定义组件的build()方法内只允许存在this.builder()，即示例的推荐用法。
  • 父容器（自定义组件）上设置的尺寸信息，除aspectRatio之外，优先级小于onMeasureSize设置的尺寸信息。
  • 子组件设置的位置信息，offset、position、markAnchor优先级大于onPlaceChildren设置的位置信息，其他位置设置属性不生效。
  • 使用自定义布局方法时，需要同时调用onMeasureSize和onPlaceChildren方法，否则可能出现布局异常。

onLayout(deprecated)

onLayout?(children: Array<LayoutChild>, constraint: ConstraintSizeOptions): void

ArkUI框架会在自定义组件布局时，将该自定义组件的子节点信息和自身的尺寸范围通过onLayout传递给该自定义组件。不允许在onLayout函数中改变状态变量。

该接口从API version 9开始支持，从API version 10开始废弃，推荐使用onPlaceChildren替代。

参数：

参数名类型说明
childrenArray<LayoutChild>子组件布局信息。
constraintConstraintSizeOptions父组件constraint信息。

onMeasure(deprecated)

onMeasure?(children: Array<LayoutChild>, constraint: ConstraintSizeOptions): void

ArkUI框架会在自定义组件确定尺寸时，将该自定义组件的子节点信息和自身的尺寸范围通过onMeasure传递给该自定义组件。不允许在onMeasure函数中改变状态变量。

该接口从API version 9开始支持，从API version 10开始废弃，推荐使用onMeasureSize替代。

参数：

参数名类型说明
childrenArray<LayoutChild>子组件布局信息。
constraintConstraintSizeOptions父组件constraint信息。

LayoutChild(deprecated)

子组件布局信息。

从API version 9开始，从API version 10开始废弃，该接口支持在ArkTS卡片中使用。

属性类型说明
namestring子组件名称。
idstring子组件id。
constraintConstraintSizeOptions子组件约束尺寸。
borderInfoLayoutBorderInfo子组件border信息。
positionPosition子组件位置坐标。
measure(childConstraint: ConstraintSizeOptions) => void调用此方法对子组件的尺寸范围进行限制。
layout(LayoutInfo: LayoutInfo) => void调用此方法对子组件的位置信息进行限制。

LayoutBorderInfo(deprecated)

子组件border信息。

从API version 9开始，从API version 10开始废弃，该接口支持在ArkTS卡片中使用。

属性类型描述
borderWidthEdgeWidths边框宽度类型，用于描述组件边框不同方向的宽度。
marginMargin外边距类型，用于描述组件不同方向的外边距。
paddingPadding内边距类型，用于描述组件不同方向的内边距。

LayoutInfo(deprecated)

子组件layout信息。

从API version 9开始，从API version 10开始废弃，该接口支持在ArkTS卡片中使用。

属性类型说明
positionPosition子组件位置坐标。
constraintConstraintSizeOptions子组件约束尺寸。

通过layout修改布局。

// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Column() {
      CustomLayout() {
        ForEach([1, 2, 3], (index: number) => {
          Text('Sub' + index)
            .fontSize(30)
            .borderWidth(2)
        })
      }
    }
  }
}



@Component
struct CustomLayout {
  @Builder
  doNothingBuilder() {
  };

  @BuilderParam builder: () => void = this.doNothingBuilder;

  onLayout(children: Array<LayoutChild>, constraint: ConstraintSizeOptions) {
    let pos = 0;
    children.forEach((child) => {
      child.layout({ position: { x: pos, y: pos }, constraint: constraint })
      pos += 70;
    })
  }

  onMeasure(children: Array<LayoutChild>, constraint: ConstraintSizeOptions) {
    let size = 100;
    children.forEach((child) => {
      child.measure({ minHeight: size, minWidth: size, maxWidth: size, maxHeight: size })
      size += 50;
    })
  }

  build() {
    this.builder()
  }
}

鸿蒙Harmony应用开发—ArkTS声明式开发（通用属性：Flex布局）
m0_64420071的博客
03-01 1554
ArkTS声明式开发（通用属性：Flex布局）
HarmonyOS学习路之方舟开发框架—学习ArkTS语言（基本语法 三）
爱吃土豆丝的打工人的博客
07-17 3716
自定义组件的创建：自定义组件的实例由ArkUI框架创建。初始化自定义组件的成员变量：通过本地默认值或者构造方法传递参数来初始化自定义组件的成员变量，初始化顺序为成员变量的定义顺序。如果开发者定义了aboutToAppear，则执行aboutToAppear方法。在首次渲染的时候，执行build方法渲染系统组件，如果有自定义子组件，则创建自定义组件的实例。在执行build()函数的过程中，框架会观察每个状态变量的读取状态，将保存两个map：状态变量 -> UI组件（包括ForEach和if）
HarmonyOS ArkTS 构建布局
帅次的博客
03-18 3555
一、线性布局（Row、Column） 二、层叠布局（StackLayout） 三、弹性布局（Flex） 四、相对布局(RelativeContainer) 五、列表 (List) 六、网格布局 (Grid) 七、轮播 (Swiper)
《跟我一起学“Harmony-ArkTS”》——常用布局
Cool_foolisher的博客
12-06 1257
本章言简意赅的为大家介绍了常用布局，线性布局、层叠布局、弹性布局、列表布局和定位的内容。
鸿蒙5.0版开发：ArkTS基础组件（TextArea）
m0_69424697的博客
09-21 1822
多行文本输入框组件，当输入的文本内容超过组件宽度时会自动换行显示。
【鸿蒙next开发】ArkUI框架：ArkTS组件-无障碍属性
m0_73088370的博客
05-15 971
本文介绍了鸿蒙5.0开发中的无障碍功能，包括无障碍组、无障碍文本、无障碍说明和无障碍重要性等核心概念。
鸿蒙5.0开发进阶：ArkTS组件-自定义组件的生命周期
Androidbye的博客
02-16 892
自定义组件的生命周期回调函数用于通知用户该自定义组件的生命周期...........
鸿蒙5.0进阶开发：UI开发-构建自定义组件
AyomQAQ的博客
12-30 1023
ArkUI开发框架在NDK接口提供了自定义UI组件的能力，这些能力包括自定义测算，自定义布局和自定义绘制。
鸿蒙5.0进阶开发：UI开发-自定义渲染 (XComponent)
AyomQAQ的博客
12-19 1130
XComponent组件作为一种渲染组件，可用于EGL/OpenGLES和媒体数据写入..........
鸿蒙5.0开发进阶：自定义安全键盘实现案例
HSMMQAQ的博客
10-17 1012
本示例介绍如何使用TextInput组件实现自定义安全键盘场景.....
鸿蒙5.0进阶开发：UI开发-自定义组件节点 (FrameNode)
AyomQAQ的博客
12-28 1184
对于拥有自定义前端的第三方框架（如JSON、XML、DOM树等），需将特定的DSL转换为ArkUI的声明式描述。
鸿蒙5.0进阶开发：UI开发-构建布局（创建网格 (Grid/GridItem)）
AyomQAQ的博客
12-17 1243
网格布局是由“行”和“列”分割的单元格所组成，通过指定“项目”所在的单元格做出各种各样的布局。
【鸿蒙】HarmonyOS NEXT星河入门到实战4-ArkTS界面布局深入
春天的波菜
09-10 2434
Entry@Component@State message: string = '春天的菠菜';return;});build() {Column(){Row(){// 左侧Text('左侧')// 右侧Text('右侧固定').width(80)// LayoutWeight 多个对象Row(){// 老大Text('老大')// 老二Text('老二').width(80)// 老三Text('老三').width(80)
在OpenHarmony的ArkUI开发框架中实现自适应布局的探索
qq_14863717的博客
05-30 1461
作为一名开发者，我最近在处理一个关于OpenHarmony的ArkUI开发框架的布局问题。这个问题要求在父控件的左下角和右下角分别放置高度和宽度自适应的控件，同时我并不想使用。在此，我将分享我的思考过程和解决方案。
东南亚小微商户支付云喇叭市场现状与九联物联Cat.1鸿蒙模组UMA223-H技术价值分析
通信行业老兵、物联网从业者，做一个有趣的普通人。
12-01 1083
东南亚小微商户正经历数字化支付转型，支付云喇叭成为关键工具。搭载九联物联Cat.1鸿蒙模组UMA223-H的收款设备，凭借离线语音播报、多语言支持和弱网适应能力，在街头摊贩、零售店、跨境旅游等场景广泛应用。市场呈现国际支付巨头、本土服务商和中国出海企业多元竞争格局，其中中国企业的技术优势明显。该技术通过离线TTS引擎、硬件级音频输出等创新，降低商户成本，提升运营效率。随着东南亚电商增长和政策支持，支付云喇叭市场前景广阔，未来将向智能化、多功能化发展，成为小微商户数字化转型的核心枢纽。
Electron for 鸿蒙PC项目开发之模态框组件
风中追风
12-02 431
这是一个基于Electron开发的模态框组件示例，展示了如何在Electron应用中实现各种类型的模态对话框。该组件适用于需要用户交互确认、信息展示、表单填写等场景的桌面应用，如文件操作确认、设置面板、通知提醒等。
Electron for 鸿蒙PC项目实战案例之记忆卡片游戏
最新发布
风中追风
12-02 451
这是一个基于Electron for 鸿蒙PC的记忆翻牌游戏实现，专为初学者设计。玩家需要翻转卡片，找到匹配的一对，锻炼记忆力和专注力。游戏支持不同难度级别和多种卡片主题。
鸿蒙——首选项
2303_77656826的博客
12-01 575
获取当前页面所属的UIAbility上下文在当前index组件得到上下文确保获取的类型是UIAbilityContext类型cpntext：这个是具体的上下文名称，可改变UIAbility ：是鸿蒙应用的核心组件，管理页面生命周期、资源等。
Electron for 鸿蒙PC项目实战之拖拽组件示例
风中追风
12-02 347
这是一个基于Electron开发的拖拽组件示例，展示了如何在Electron应用中实现文件拖拽上传、文件选择以及文件预览功能。该组件适用于需要文件上传功能的桌面应用场景，如文档管理系统、媒体编辑工具等。
鸿蒙5.0版开发：ArkTS组件通用属性（触摸热区设置）
08-21
在 HarmonyOS 5.0 的 ArkTS 组件中，设置触摸热区（Touch Area）属性可以通过组件的 `touchable` 和 `hitTestBehavior` 等属性来实现。这些属性允许开发者定义组件响应触摸事件的区域和行为。 ### 配置触摸热区属性...
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
红包 添加红包
表情包 插入表情
表情包 代码片
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值