文本 Text
一、功能描述
RemoteText 是用于显示静态文本的组件,对应 ViewType.TEXT_VIEW。它支持字号、颜色、字形(粗体/斜体)、对齐、文本装饰(下划线/删除线)、单行截断、多行省略、可滚动长文本、字间距/行间距等,适合展示标题、说明、状态信息等。
通过 RemoteViewHelper.createText() 创建:
val label = helper.createText()
二、通用属性
以下属性通过对应的 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 | 背景形状:填充色 / 描边 / 圆角 |
文字属性
| 方法 | 参数 | 说明 |
|---|---|---|
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 等 |
setTextDecoration | TextDecorationType | 装饰:NONE / UNDERLINE / STRIKE_THROUGH / UNDERLINE_AND_STRIKE_THROUGH |
setMaxLines | Int | 最大行数 |
setSingleLine | Boolean | 是否单行 |
setEllipsize | EllipsizeType | 省略位置:START / MIDDLE / END / MARQUEE |
setVerticalScrollable | Boolean | 是否允许垂直滚动(长文本) |
setLetterSpacing | Float | 字间距 |
setLineSpacing | extra: Float, multiplier: Float | 行间距(额外值 + 倍数) |
三、Tips
- 颜色只能传 ARGB Int。
setTextColor/setBackground接收 Int 颜色值(如0xFF1890FF.toInt()或Color.RED),底层updateView会转为十进制字符串。不要传"#RRGGBB"、"0xAARRGGBB"或R.color.xxx。 - 修改已挂载组件的属性后要
syncToRemote()。setXxx只更新本地缓存,调用syncToRemote()才会批量同步到 Pilot。挂载前配置好属性则无需额外调用。 - 单行截断需配合
setSingleLine(true)+setEllipsize(...)。只设singleLine会截断但不显示省略号,配合EllipsizeType.END才有"…"。 - 长文本滚动需
setVerticalScrollable(true),并给一个受限的setHeight,否则文本会一直撑高而不滚动。 setMaxLines与setSingleLine(true)同时设置时,以单行为准。
四、示例代码
下方每组左侧为示例代码,右侧为对应的 Pilot 端渲染预览效果。
01 组件类型(基础文本 / 特殊类型)
// 基础文本:普通 / 下划线 / 删除线 / 加粗 / 彩色
val normal = helper.createText().apply {
setText("普通文本信息"); setWidth(RemoteView.MATCH_PARENT); setTextSize(14f)
}
val underline = helper.createText().apply {
setText("下划线文本信息"); setWidth(RemoteView.MATCH_PARENT); setTextSize(14f)
setTextDecoration(TextDecorationType.UNDERLINE)
}
val strike = helper.createText().apply {
setText("删除线文本信息"); setWidth(RemoteView.MATCH_PARENT); setTextSize(14f)
setTextDecoration(TextDecorationType.STRIKE_THROUGH)
}
val bold = helper.createText().apply {
setText("加粗文本信息"); setWidth(RemoteView.MATCH_PARENT); setTextSize(14f)
setFontStyle(FontStyleType.BOLD)
}
val colored = helper.createText().apply {
setText("色彩文本信息"); setWidth(RemoteView.MATCH_PARENT); setTextSize(14f)
setTextColor(0xFF1890FF.toInt())
}
// 特殊类型:单行 / 截断省略 / 折行 / 可滚动
val singleLine = helper.createText().apply {
setText("单行文本信息"); setWidth(RemoteView.MATCH_PARENT); setSingleLine(true)
}
val ellipsize = helper.createText().apply {
setText("文本信息内容多,截断处理不展示全部内容,截断处理不展示全部内容,截断处理不展示全部内容")
setWidth(RemoteView.MATCH_PARENT); setSingleLine(true); setEllipsize(EllipsizeType.END)
}
val wrap = helper.createText().apply {
setText("文本信息内容多,折行展示全部信息,折行展示全部信息,折行展示全部信息,折行展示全部信息")
setWidth(RemoteView.MATCH_PARENT); setMaxLines(3)
}
val scrollable = helper.createText().apply {
setText("这是一些文本信息,内容多,可滚动展示")
setWidth(RemoteView.MATCH_PARENT); setHeight(56); setVerticalScrollable(true)
}
02 组件状态(正常 / 置灰)
// 正常态
val normal = helper.createText().apply {
setText("文本正常态"); setWidth(RemoteView.MATCH_PARENT); setTextSize(14f)
}
// 置灰态:降透明度 + 灰色文字
val disabled = helper.createText().apply {
setText("文本置灰态"); setWidth(RemoteView.MATCH_PARENT); setTextSize(14f)
setTextColor(0xFF888888.toInt())
setAlpha(0.6f)
}
03 组件样式(字体尺寸 / 自定义颜色)
// 字体尺寸:大 12sp / 中 11sp / 小 9sp(配字间距、行间距)
val large = helper.createText().apply {
setText("大,字号 12sp"); setWidth(RemoteView.MATCH_PARENT)
setTextSize(12f); setLetterSpacing(0.01f)
}
val medium = helper.createText().apply {
setText("中,字号 11sp"); setWidth(RemoteView.MATCH_PARENT)
setTextSize(11f); setLetterSpacing(0.03f); setLineSpacing(1f, 1f)
}
val small = helper.createText().apply {
setText("小,字号 9sp"); setWidth(RemoteView.MATCH_PARENT)
setTextSize(9f); setLetterSpacing(0.05f); setLineSpacing(0f, 1.3f)
}
// 自定义颜色:蓝 / 红 / 橙
val blue = helper.createText().apply { setText("蓝色文本"); setTextColor(0xFF1890FF.toInt()) }
val red = helper.createText().apply { setText("红色文本"); setTextColor(0xFFE41F29.toInt()) }
val orange = helper.createText().apply { setText("橙色文本"); setTextColor(0xFFFF9F0A.toInt()) }
完整可运行示例见官方 Sample
open-pilot-plugin-sample的 drawing/TextViewDrawer.kt。