布局容器 Layout

2026-09-20评分加载中…

一、功能描述

RemoteLayout 是所有布局容器的基类,用来组织和排布子 View。它派生出两类常用容器:

  • 线性布局 RemoteLinearLayout:子 View 沿水平或垂直方向依次排列,对应 ViewType.LINEAR_LAYOUT_HORIZONTAL / ViewType.LINEAR_LAYOUT_VERTICAL。通过 helper.createLinearLayoutHorizontal() / helper.createLinearLayoutVertical() 创建。
  • 约束布局 RemoteConstraintLayout:子 View 通过相对约束定位,对应 ViewType.CONSTRAINT_LAYOUT。通过 helper.createConstraintLayout() 创建,用 helper.setConstraints(...) 建立约束关系。

容器自身用 addToRoot() 挂载到根布局,子 View 用 addToRemote(child, params?) 添加进容器:

// 水平线性布局
val row = helper.createLinearLayoutHorizontal().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(RemoteView.WRAP_CONTENT)
}
row.addToRoot()
row.addToRemote(helper.createButton().apply { setText("按钮") })

关键概念

  • setGravity(GravityType):设置容器内子 View 的整体对齐方式,取值 CENTER / CENTER_HORIZONTAL / CENTER_VERTICAL / TOP / BOTTOM / LEFT / RIGHT / START / END 等。
  • WidgetLayoutParam:子 View 在父容器中的布局参数,可设 weight(权重,配合线性布局)、margin(外边距)、layoutGravity(自身在父容器中的对齐)。
  • weight + 尺寸置 0:线性布局中,子 View 在排列方向的尺寸设为 0 并配 weight,即可按比例分配剩余空间(水平方向置 width=0,垂直方向置 height=0)。
  • ViewSide:约束布局的方向枚举,取值 START / END / TOP / BOTTOM(另有 UNKNOWN)。

二、通用属性

以下属性通过对应的 setXxx() 方法设置。除标注外,属性修改后若容器已挂载,需调用 syncToRemote() 使其在 Pilot 端生效。

尺寸与布局

方法参数说明
setWidthInt宽度(dp);特殊值 RemoteView.MATCH_PARENT(-1) / WRAP_CONTENT(-2)
setHeightInt高度(dp);同上支持特殊值
setMinSizeminWidth: Int, minHeight: Int最小尺寸(dp)
setPaddingleft, top, right, bottom: Int内边距(dp)
setVisibilityVisibilityType可见性:VISIBLE / INVISIBLE / GONE
setAlphaFloat透明度,0.0 ~ 1.0
setEnabledBoolean是否可用

背景与形状

方法参数说明
setBackgroundInt背景纯色(ARGB Int)
setBackgroundShapeShapeDescriptor背景形状:填充色 / 描边 / 圆角

容器属性

方法参数说明
setGravityGravityType设置容器内子 View 的整体对齐方式
addToRootparams: WidgetLayoutParam?挂载容器到根布局(可选布局参数)
addToRemotechild: RemoteViewProvider, params: WidgetLayoutParam?添加子 View 到容器(可选布局参数),并自动同步子 View 初始属性

WidgetLayoutParam(子 View 布局参数)常用项:

方法 / 字段参数说明
weightFloat权重;配合线性布局,对应方向尺寸需设为 0
setMarginleft, top, right, bottom: Int四周外边距(dp)
marginLeft / marginTop / marginRight / marginBottomInt单边外边距(dp)
setLayoutGravityGravityType子 View 自身在父容器中的对齐方式

约束定位(通过 RemoteViewHelper)

方法参数说明
setConstraintslayoutId, viewId, targetId: String, viewDirection: ViewSide, targetDirection: ViewSide, margin: Int = 0将 viewId 的 viewDirection 边约束到 targetId 的 targetDirection 边;targetId 可为父布局自身 id。返回 OperationResult

ViewSide 取值:START / END / TOP / BOTTOM(UNKNOWN 为无效值)。

三、Tips

  1. weight 必须配合对应方向尺寸为 0。水平线性布局按 weight 均分时,子 View 需 setWidth(0);垂直方向则 setHeight(0)。否则子 View 会先占满自身内容尺寸,weight 失效。
  2. setConstraints 前必须先 addToRemote。若约束的 viewId 或 targetId 尚未添加到布局,返回 OperationResult.NO_SUCH_VIEW_ID / NO_SUCH_PARENT_VIEW_ID。请先 addToRemote 所有子 View,再建立约束。
  3. 约束的 targetId 可为父布局自身 id。将子 View 的某条边约束到容器的 id(约束布局自身 id),即可实现相对父容器的四角、居中定位。
  4. 居中需要双向约束。约束布局中让子 View 居中,需同时约束其 START↔父 START、END↔父 END(水平居中)与 TOP↔父 TOP、BOTTOM↔父 BOTTOM(垂直居中)。
  5. 颜色只能传 ARGB Int。容器 setBackground / setBackgroundShape 的颜色是 Int 值(如 0xFF1A8BFF.toInt()),不要传 "#RRGGBB" 或 R.color.xxx。
  6. 修改已挂载容器的属性后要 syncToRemote()。addToRemote / addToRoot 已内部同步初始属性;后续单独改属性才需 syncToRemote()。

四、示例代码

下方每组左侧为示例代码,右侧为对应的 Pilot 端渲染预览效果。

01 线性布局(权重均分 / 定宽间距 / 垂直对齐)

// 1) 水平 weight 均分 1:1:1
val rowEqual = helper.createLinearLayoutHorizontal().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(30)
}
rowEqual.addToRoot()
listOf("1", "2", "3").forEach { t ->
    val block = helper.createButton().apply {
        setText(t); setWidth(0); setHeight(30)   // width=0 配合 weight
        setBackgroundShape(ShapeDescriptor.Builder().fillColor(0xFF1A8BFF.toInt()).cornerRadius(2f).build())
    }
    rowEqual.addToRemote(block, WidgetLayoutParam().apply { weight = 1f; marginLeft = 2 })
}

// 2) 水平 weight 按比例 1:2:3
val rowRatio = helper.createLinearLayoutHorizontal().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(30)
}
rowRatio.addToRoot()
listOf(1f, 2f, 3f).forEach { w ->
    val block = helper.createButton().apply {
        setText("${w.toInt()}"); setWidth(0); setHeight(30)
        setBackgroundShape(ShapeDescriptor.Builder().fillColor(0xFF1A8BFF.toInt()).cornerRadius(2f).build())
    }
    rowRatio.addToRemote(block, WidgetLayoutParam().apply { weight = w; marginLeft = 2 })
}

// 3) 固定宽度 + 间距(不使用 weight)
val rowFixed = helper.createLinearLayoutHorizontal().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(30)
}
rowFixed.addToRoot()
listOf(30, 50, 40).forEach { wDp ->
    val block = helper.createButton().apply {
        setText("${wDp}dp"); setWidth(wDp); setHeight(30)
        setBackgroundShape(ShapeDescriptor.Builder().fillColor(0xFF1A8BFF.toInt()).cornerRadius(2f).build())
    }
    rowFixed.addToRemote(block, WidgetLayoutParam().apply { marginRight = 4 })
}

// 4) 垂直布局 + gravity 居中对齐
val colCenter = helper.createLinearLayoutVertical().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(120)
    setGravity(GravityType.CENTER_HORIZONTAL)   // 子 View 整体水平居中
}
colCenter.addToRoot()
colCenter.addToRemote(helper.createText().apply { setText("标题") })
colCenter.addToRemote(helper.createText().apply { setText("副标题") })

02 约束布局(四角 + 居中)

// 创建约束布局并挂载
val cl = helper.createConstraintLayout().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(120)
    setBackgroundShape(ShapeDescriptor.Builder().fillColor(0xFF0659D9.toInt()).cornerRadius(4f).build())
}
cl.addToRoot()

// 先把所有子 View 添加进容器(约束前必须已 addToRemote)
val tl = helper.createButton().apply { setText("左上"); setWidth(50); setHeight(28) }
val tr = helper.createButton().apply { setText("右上"); setWidth(50); setHeight(28) }
val bl = helper.createButton().apply { setText("左下"); setWidth(50); setHeight(28) }
val br = helper.createButton().apply { setText("右下"); setWidth(50); setHeight(28) }
val center = helper.createButton().apply { setText("居中"); setWidth(50); setHeight(28) }
listOf(tl, tr, bl, br, center).forEach { cl.addToRemote(it) }

val parentId = cl.remoteView.id
val m = 8

// 左上:START↔父 START,TOP↔父 TOP
helper.setConstraints(cl.remoteView.id, tl.remoteView.id, parentId, ViewSide.START, ViewSide.START, m)
helper.setConstraints(cl.remoteView.id, tl.remoteView.id, parentId, ViewSide.TOP, ViewSide.TOP, m)

// 右上:END↔父 END,TOP↔父 TOP
helper.setConstraints(cl.remoteView.id, tr.remoteView.id, parentId, ViewSide.END, ViewSide.END, m)
helper.setConstraints(cl.remoteView.id, tr.remoteView.id, parentId, ViewSide.TOP, ViewSide.TOP, m)

// 左下:START↔父 START,BOTTOM↔父 BOTTOM
helper.setConstraints(cl.remoteView.id, bl.remoteView.id, parentId, ViewSide.START, ViewSide.START, m)
helper.setConstraints(cl.remoteView.id, bl.remoteView.id, parentId, ViewSide.BOTTOM, ViewSide.BOTTOM, m)

// 右下:END↔父 END,BOTTOM↔父 BOTTOM
helper.setConstraints(cl.remoteView.id, br.remoteView.id, parentId, ViewSide.END, ViewSide.END, m)
helper.setConstraints(cl.remoteView.id, br.remoteView.id, parentId, ViewSide.BOTTOM, ViewSide.BOTTOM, m)

// 居中:四边均约束到父布局对应边(双向约束实现水平 + 垂直居中)
helper.setConstraints(cl.remoteView.id, center.remoteView.id, parentId, ViewSide.START, ViewSide.START)
helper.setConstraints(cl.remoteView.id, center.remoteView.id, parentId, ViewSide.END, ViewSide.END)
helper.setConstraints(cl.remoteView.id, center.remoteView.id, parentId, ViewSide.TOP, ViewSide.TOP)
helper.setConstraints(cl.remoteView.id, center.remoteView.id, parentId, ViewSide.BOTTOM, ViewSide.BOTTOM)

说明: 完整可运行示例见官方 Sample open-pilot-plugin-sample 的 drawing/LayoutDrawer.ktopen in new window。

最近修改: