文本 Text

2026-09-20评分加载中…

一、功能描述

RemoteText 是用于显示静态文本的组件,对应 ViewType.TEXT_VIEW。它支持字号、颜色、字形(粗体/斜体)、对齐、文本装饰(下划线/删除线)、单行截断、多行省略、可滚动长文本、字间距/行间距等,适合展示标题、说明、状态信息等。

通过 RemoteViewHelper.createText() 创建:

val label = helper.createText()

二、通用属性

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

文字属性

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

三、Tips

  1. 颜色只能传 ARGB Int。setTextColor / setBackground 接收 Int 颜色值(如 0xFF1890FF.toInt() 或 Color.RED),底层 updateView 会转为十进制字符串。不要传 "#RRGGBB"、"0xAARRGGBB" 或 R.color.xxx。
  2. 修改已挂载组件的属性后要 syncToRemote()。setXxx 只更新本地缓存,调用 syncToRemote() 才会批量同步到 Pilot。挂载前配置好属性则无需额外调用。
  3. 单行截断需配合 setSingleLine(true) + setEllipsize(...)。只设 singleLine 会截断但不显示省略号,配合 EllipsizeType.END 才有"…"。
  4. 长文本滚动需 setVerticalScrollable(true),并给一个受限的 setHeight,否则文本会一直撑高而不滚动。
  5. 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.ktopen in new window。

最近修改: