按钮 Button

2026-09-20评分加载中…

一、功能描述

RemoteButton 是可点击的按钮组件,对应 ViewType.BUTTON。它支持文字样式(字号、颜色、粗体/斜体、对齐、装饰)、背景形状(填充、描边、圆角)、禁用态与点击事件,可用来实现填充按钮、描边按钮、文字按钮、TabLayout 等常见交互。

通过 RemoteViewHelper.createButton() 创建:

val button = helper.createButton()

二、通用属性

以下属性通过对应的 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背景形状:填充色 / 描边 / 圆角,见下方 ShapeDescriptor

ShapeDescriptor.Builder 可组合项:

Builder 方法参数说明
fillColorInt填充色(ARGB)
strokewidthDp: Int, color: Int描边宽度与颜色
cornerRadiusdp: Float统一圆角
cornerRadiiFloatArray(8)四角独立圆角(上左xy、上右xy、下右xy、下左xy)
shapeSHAPE_RECTANGLE / SHAPE_OVAL矩形或椭圆

文字属性

方法参数说明
setTextString按钮文字
setTextSizeFloat字号(内部取整为 sp)
setTextColorInt文字颜色(ARGB Int)
setFontStyleFontStyleType字形:NORMAL / BOLD / ITALIC / BOLD_ITALIC
setGravityGravityType对齐:CENTER / START / END / LEFT / RIGHT / TOP / BOTTOM 等
setMaxLinesInt最大行数
setSingleLineBoolean是否单行
setEllipsizeEllipsizeType省略位置:START / MIDDLE / END / MARQUEE
setTextDecorationTextDecorationType装饰:NONE / UNDERLINE / STRIKE_THROUGH / UNDERLINE_AND_STRIKE_THROUGH
setLetterSpacingFloat字间距
setLineSpacingextra: Float, multiplier: Float行间距(额外值 + 倍数)

事件

方法说明
setOnClickListener点击回调。回调在 Binder 线程池执行,更新 UI / 业务需自行切主线程

三、Tips

  1. 颜色只能传 ARGB Int。setTextColor / setBackground 接收的是 Int 颜色值(如 0xFF2D8CF0.toInt() 或 Color.RED),底层 updateView 会转为十进制字符串。不要传 "#RRGGBB"、"0xAARRGGBB" 或 R.color.xxx。
  2. 点击回调不在主线程。setOnClickListener 的回调运行在 AIDL 的 Binder 线程池,若要更新 App 自身 View 或做主线程相关操作,需 Handler(Looper.getMainLooper()).post { ... } 切回主线程。
  3. 修改已挂载组件的属性后要 syncToRemote()。setXxx 只更新本地缓存,调用 syncToRemote() 才会批量同步到 Pilot。挂载前配置好属性则无需额外调用。
  4. 禁用态需手动降透明度。setEnabled(false) 只是不响应点击,视觉上建议同时 setAlpha(0.6f) 以表达禁用观感。
  5. 描边按钮 = 无填充。只调用 stroke(...) 而不设 fillColor 即得到镂空描边效果;文字按钮则不调用 setBackgroundShape。
  6. 宽度设为 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.ktopen in new window。

最近修改: