布局容器 Layout
一、功能描述
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 端生效。
尺寸与布局
| 方法 | 参数 | 说明 |
|---|---|---|
setWidth | Int | 宽度(dp);特殊值 RemoteView.MATCH_PARENT(-1) / WRAP_CONTENT(-2) |
setHeight | Int | 高度(dp);同上支持特殊值 |
setMinSize | minWidth: Int, minHeight: Int | 最小尺寸(dp) |
setPadding | left, top, right, bottom: Int | 内边距(dp) |
setVisibility | VisibilityType | 可见性:VISIBLE / INVISIBLE / GONE |
setAlpha | Float | 透明度,0.0 ~ 1.0 |
setEnabled | Boolean | 是否可用 |
背景与形状
| 方法 | 参数 | 说明 |
|---|---|---|
setBackground | Int | 背景纯色(ARGB Int) |
setBackgroundShape | ShapeDescriptor | 背景形状:填充色 / 描边 / 圆角 |
容器属性
| 方法 | 参数 | 说明 |
|---|---|---|
setGravity | GravityType | 设置容器内子 View 的整体对齐方式 |
addToRoot | params: WidgetLayoutParam? | 挂载容器到根布局(可选布局参数) |
addToRemote | child: RemoteViewProvider, params: WidgetLayoutParam? | 添加子 View 到容器(可选布局参数),并自动同步子 View 初始属性 |
WidgetLayoutParam(子 View 布局参数)常用项:
| 方法 / 字段 | 参数 | 说明 |
|---|---|---|
weight | Float | 权重;配合线性布局,对应方向尺寸需设为 0 |
setMargin | left, top, right, bottom: Int | 四周外边距(dp) |
marginLeft / marginTop / marginRight / marginBottom | Int | 单边外边距(dp) |
setLayoutGravity | GravityType | 子 View 自身在父容器中的对齐方式 |
约束定位(通过 RemoteViewHelper)
| 方法 | 参数 | 说明 |
|---|---|---|
setConstraints | layoutId, viewId, targetId: String, viewDirection: ViewSide, targetDirection: ViewSide, margin: Int = 0 | 将 viewId 的 viewDirection 边约束到 targetId 的 targetDirection 边;targetId 可为父布局自身 id。返回 OperationResult |
ViewSide 取值:START / END / TOP / BOTTOM(UNKNOWN 为无效值)。
三、Tips
- weight 必须配合对应方向尺寸为 0。水平线性布局按
weight均分时,子 View 需setWidth(0);垂直方向则setHeight(0)。否则子 View 会先占满自身内容尺寸,weight失效。 setConstraints前必须先 addToRemote。若约束的viewId或targetId尚未添加到布局,返回OperationResult.NO_SUCH_VIEW_ID/NO_SUCH_PARENT_VIEW_ID。请先addToRemote所有子 View,再建立约束。- 约束的 targetId 可为父布局自身 id。将子 View 的某条边约束到容器的
id(约束布局自身 id),即可实现相对父容器的四角、居中定位。 - 居中需要双向约束。约束布局中让子 View 居中,需同时约束其
START↔父 START、END↔父 END(水平居中)与TOP↔父 TOP、BOTTOM↔父 BOTTOM(垂直居中)。 - 颜色只能传 ARGB Int。容器
setBackground/setBackgroundShape的颜色是 Int 值(如0xFF1A8BFF.toInt()),不要传"#RRGGBB"或R.color.xxx。 - 修改已挂载容器的属性后要
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.kt。