按钮 Button
一、功能描述
RemoteButton 是可点击的按钮组件,对应 ViewType.BUTTON。它支持文字样式(字号、颜色、粗体/斜体、对齐、装饰)、背景形状(填充、描边、圆角)、禁用态与点击事件,可用来实现填充按钮、描边按钮、文字按钮、TabLayout 等常见交互。
通过 RemoteViewHelper.createButton() 创建:
val button = helper.createButton()
二、通用属性
以下属性通过对应的 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 | 背景形状:填充色 / 描边 / 圆角,见下方 ShapeDescriptor |
ShapeDescriptor.Builder 可组合项:
| Builder 方法 | 参数 | 说明 |
|---|---|---|
fillColor | Int | 填充色(ARGB) |
stroke | widthDp: Int, color: Int | 描边宽度与颜色 |
cornerRadius | dp: Float | 统一圆角 |
cornerRadii | FloatArray(8) | 四角独立圆角(上左xy、上右xy、下右xy、下左xy) |
shape | SHAPE_RECTANGLE / SHAPE_OVAL | 矩形或椭圆 |
文字属性
| 方法 | 参数 | 说明 |
|---|---|---|
setText | String | 按钮文字 |
setTextSize | Float | 字号(内部取整为 sp) |
setTextColor | Int | 文字颜色(ARGB Int) |
setFontStyle | FontStyleType | 字形:NORMAL / BOLD / ITALIC / BOLD_ITALIC |
setGravity | GravityType | 对齐:CENTER / START / END / LEFT / RIGHT / TOP / BOTTOM 等 |
setMaxLines | Int | 最大行数 |
setSingleLine | Boolean | 是否单行 |
setEllipsize | EllipsizeType | 省略位置:START / MIDDLE / END / MARQUEE |
setTextDecoration | TextDecorationType | 装饰:NONE / UNDERLINE / STRIKE_THROUGH / UNDERLINE_AND_STRIKE_THROUGH |
setLetterSpacing | Float | 字间距 |
setLineSpacing | extra: Float, multiplier: Float | 行间距(额外值 + 倍数) |
事件
| 方法 | 说明 |
|---|---|
setOnClickListener | 点击回调。回调在 Binder 线程池执行,更新 UI / 业务需自行切主线程 |
三、Tips
- 颜色只能传 ARGB Int。
setTextColor/setBackground接收的是 Int 颜色值(如0xFF2D8CF0.toInt()或Color.RED),底层updateView会转为十进制字符串。不要传"#RRGGBB"、"0xAARRGGBB"或R.color.xxx。 - 点击回调不在主线程。
setOnClickListener的回调运行在 AIDL 的 Binder 线程池,若要更新 App 自身 View 或做主线程相关操作,需Handler(Looper.getMainLooper()).post { ... }切回主线程。 - 修改已挂载组件的属性后要
syncToRemote()。setXxx只更新本地缓存,调用syncToRemote()才会批量同步到 Pilot。挂载前配置好属性则无需额外调用。 - 禁用态需手动降透明度。
setEnabled(false)只是不响应点击,视觉上建议同时setAlpha(0.6f)以表达禁用观感。 - 描边按钮 = 无填充。只调用
stroke(...)而不设fillColor即得到镂空描边效果;文字按钮则不调用setBackgroundShape。 - 宽度设为
0并配合父容器weight可实现等分/按比例分配(见 TabLayout 示例)。
四、示例代码
下方每组左侧为示例代码,右侧为对应的 Pilot 端渲染预览效果。
01 组件类型(基础按钮 / 组合按钮)
// 基础按钮:填充 / 描边 / 文字
val filled = helper.createButton().apply {
setText("填充按钮")
setWidth(RemoteView.MATCH_PARENT); setHeight(32); setTextSize(14f)
setTextColor(RemoteViewColors.WHITE); setFontStyle(FontStyleType.BOLD)
setBackgroundShape(
ShapeDescriptor.Builder().fillColor(RemoteViewColors.BLUE_PRIMARY).cornerRadius(4f).build()
)
}
val stroke = helper.createButton().apply {
setText("描边按钮")
setWidth(RemoteView.MATCH_PARENT); setHeight(32); setTextSize(14f)
setTextColor(RemoteViewColors.BLUE_PRIMARY)
setBackgroundShape(
ShapeDescriptor.Builder().stroke(1, RemoteViewColors.BLUE_PRIMARY).cornerRadius(4f).build()
)
}
val text = helper.createButton().apply {
setText("文字按钮")
setWidth(RemoteView.MATCH_PARENT); setHeight(32); setTextSize(14f)
setTextColor(RemoteViewColors.BLUE_PRIMARY); setFontStyle(FontStyleType.BOLD)
}
// 组合按钮(TabLayout 效果):外圆角内直角 + weight 均分
val leftCorner = floatArrayOf(4f, 4f, 0f, 0f, 0f, 0f, 4f, 4f)
val rightCorner = floatArrayOf(0f, 0f, 4f, 4f, 4f, 4f, 0f, 0f)
val tab = helper.createLinearLayoutHorizontal().apply {
setWidth(RemoteView.MATCH_PARENT); setHeight(RemoteView.WRAP_CONTENT)
}
val tabL = helper.createButton().apply {
setText("主要按钮"); setWidth(0); setHeight(32)
setTextColor(RemoteViewColors.WHITE); setFontStyle(FontStyleType.BOLD)
setBackgroundShape(ShapeDescriptor.Builder().fillColor(RemoteViewColors.BLUE_PRIMARY).cornerRadii(leftCorner).build())
}
val tabR = helper.createButton().apply {
setText("次要按钮"); setWidth(0); setHeight(32)
setBackgroundShape(ShapeDescriptor.Builder().fillColor(RemoteViewColors.NEAR_WHITE_20).cornerRadii(rightCorner).build())
}
tab.addToRemote(tabL, WidgetLayoutParam().apply { weight = 1f })
tab.addToRemote(tabR, WidgetLayoutParam().apply { weight = 1f; marginLeft = 1 })
02 组件状态(禁用态)
// 创建按钮
val disabledFilled = helper.createButton().apply {
setText("填充按钮"); setWidth(0); setHeight(32)
setTextColor(RemoteViewColors.WHITE); setFontStyle(FontStyleType.BOLD)
setBackgroundShape(ShapeDescriptor.Builder().fillColor(RemoteViewColors.BLUE_PRIMARY).cornerRadius(4f).build())
}
val disabledStroke = helper.createButton().apply {
setText("描边按钮"); setWidth(0); setHeight(32); setTextColor(RemoteViewColors.BLUE_PRIMARY)
setBackgroundShape(ShapeDescriptor.Builder().stroke(1, RemoteViewColors.BLUE_PRIMARY).cornerRadius(4f).build())
}
val disabledText = helper.createButton().apply {
setText("文字按钮"); setWidth(0); setHeight(32)
setTextColor(RemoteViewColors.BLUE_PRIMARY); setFontStyle(FontStyleType.BOLD)
}
// 禁用态:不响应点击 + 降透明度
listOf(disabledFilled, disabledStroke, disabledText).forEach { btn ->
btn.setEnabled(false) // 不响应点击
btn.setAlpha(0.4f) // 视觉上表达禁用
}
03 组件样式(尺寸 / 形状 / 自定义颜色)
// 按钮尺寸:大 32 / 中 26 / 小 20(dp)
listOf(32, 26, 20).forEach { h ->
helper.createButton().apply {
setText("$h PX"); setWidth(0); setHeight(h)
setTextColor(RemoteViewColors.WHITE)
setBackgroundShape(ShapeDescriptor.Builder().fillColor(RemoteViewColors.BLUE_PRIMARY).cornerRadius(4f).build())
}
}
// 按钮形状:方形(0) / 圆角矩形(4) / 胶囊(24)
listOf(0f, 4f, 24f).forEach { radius ->
helper.createButton().apply {
setText("形状"); setWidth(0); setHeight(32)
setTextColor(RemoteViewColors.WHITE)
setBackgroundShape(ShapeDescriptor.Builder().fillColor(RemoteViewColors.BLUE_PRIMARY).cornerRadius(radius).build())
}
}
// 自定义颜色:绿色填充 / 蓝色 2dp 描边 / 红色文字
val green = helper.createButton().apply {
setText("填充按钮"); setWidth(0); setHeight(32); setTextColor(RemoteViewColors.WHITE)
setBackgroundShape(ShapeDescriptor.Builder().fillColor(0xFF00C774.toInt()).cornerRadius(4f).build())
}
val blueStroke = helper.createButton().apply {
setText("描边按钮"); setWidth(0); setHeight(32); setTextColor(RemoteViewColors.BLUE_PRIMARY)
setBackgroundShape(ShapeDescriptor.Builder().stroke(2, RemoteViewColors.BLUE_PRIMARY).cornerRadius(4f).build())
}
val redText = helper.createButton().apply {
setText("文字按钮"); setWidth(0); setHeight(32)
setTextColor(0xFFFF4D4F.toInt()); setFontStyle(FontStyleType.BOLD)
}
说明: 完整可运行示例见官方 Sample
open-pilot-plugin-sample的 drawing/ButtonDrawer.kt。