输入框 EditText

2026-09-20评分加载中…

一、功能描述

RemoteEditText 是用于接收用户文本输入的可编辑组件,对应 ViewType.EDIT_TEXT。它支持提示文案(hint)、字号、颜色、字形、对齐、键盘输入类型、最大长度、自动分组、光标定位、字数限制、多行/单行、文本变化监听等,适合表单、搜索框、数值录入等场景。

通过 RemoteViewHelper.createEditText() 创建:

val input = helper.createEditText()

二、通用属性

以下属性通过对应的 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)
setGravityGravityType对齐:CENTER / START / END / LEFT / RIGHT / TOP / BOTTOM 等
setFontStyleFontStyleType字形:NORMAL / BOLD / ITALIC / BOLD_ITALIC
setHintString提示文案(占位符)
setHintByResIdInt通过资源 ID 设置提示文案,随服务端语言自动切换
setHintTextColorInt提示文案颜色(ARGB Int)
setInputTypeInputType键盘输入类型(见下方合法值)
setMaxLengthInt最大输入字符数
setGroupingString自动分组:按指定组长插入空格(如 "4" → 每 4 位一组)
setCursorPositionInt光标位置(从 0 开始索引)
setMaxLinesInt最大行数
setSingleLineBoolean是否单行
setEllipsizeEllipsizeType省略位置:START / MIDDLE / END / MARQUEE
setVerticalScrollableBoolean是否允许垂直滚动(多行长文本)

InputType 合法值:TEXT / TEXT_MULTI_LINE / NUMBER / NUMBER_DECIMAL / NUMBER_SIGNED / PHONE / EMAIL_ADDRESS / PASSWORD / NUMBER_PASSWORD。

事件

方法参数说明
setOnTextChangeListenerIRemoteViewTextWatcher文本变化监听,含 beforeTextChanged / onTextChanged / afterTextChanged。回调运行在 Binder 线程池

三、Tips

  1. 颜色只能传 ARGB Int。setTextColor / setHintTextColor / setBackground 接收 Int 颜色值(如 0xFF1A8BFF.toInt() 或 Color.RED)。不要传 "#RRGGBB"、"0xAARRGGBB" 或 R.color.xxx。
  2. setOnTextChangeListener 的回调运行在 Binder 线程池,不在主线程。若要在回调中更新 UI 或访问只能在主线程操作的对象,务必先切回主线程(如 Handler(Looper.getMainLooper()).post { ... })。
  3. 修改已挂载组件的属性后要 syncToRemote()。setXxx 只更新本地缓存,调用 syncToRemote() 才会批量同步到 Pilot。挂载前配置好属性则无需额外调用。
  4. 密码输入用 setInputType(InputType.PASSWORD)(纯数字密码用 NUMBER_PASSWORD),文本会以圆点遮罩显示。
  5. 限制字数用 setMaxLength(n);自动分组用 setGrouping("4")(每 4 位插入一个分隔空格,适合银行卡号、序列号等)。
  6. hint 需要随语言切换时用 setHintByResId(resId) 而非 setHint(String),服务端语言变更时会自动刷新 hint 文案。

四、示例代码

下方每组左侧为示例代码,右侧为对应的 Pilot 端渲染预览效果。

01 输入框样式(默认 / 自定义 hint 颜色 / 圆角背景)

// 填充圆角背景:黑底圆角 + 蓝字居中
val filled = helper.createEditText().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(36)
    setText("填充输入框")
    setTextColor(0xFF1A8BFF.toInt())
    setGravity(GravityType.CENTER)
    setBackgroundShape(
        ShapeDescriptor.Builder().fillColor(0x99000000.toInt()).cornerRadius(4f).build()
    )
}

// 描边圆角背景:1dp 灰边 + 白字居中
val outlined = helper.createEditText().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(36)
    setText("描边输入框")
    setTextColor(0xFFFFFFFF.toInt())
    setGravity(GravityType.CENTER)
    setBackgroundShape(
        ShapeDescriptor.Builder().stroke(1, 0xFF888888.toInt()).cornerRadius(4f).build()
    )
}

// 默认样式:无底无边 + 白字居中
val plain = helper.createEditText().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(36)
    setText("默认输入框")
    setTextColor(0xFFFFFFFF.toInt())
    setGravity(GravityType.CENTER)
}

// 自定义 hint 颜色:灰色提示 / 红色提示
val hintGrey = helper.createEditText().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(36)
    setHint("请输入内容")
    setHintTextColor(0x55FFFFFF.toInt())
    setGravity(GravityType.CENTER)
    setBackgroundShape(
        ShapeDescriptor.Builder().fillColor(0x99000000.toInt()).cornerRadius(4f).build()
    )
}
val hintRed = helper.createEditText().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(36)
    setHint("请输入内容")
    setHintTextColor(0x55D54941.toInt())
    setGravity(GravityType.CENTER)
    setBackgroundShape(
        ShapeDescriptor.Builder().fillColor(0x99000000.toInt()).cornerRadius(4f).build()
    )
}

02 输入控制(数字键盘 / 密码 / 自动分组 / 限制字数)

// 数字键盘:弹出纯数字软键盘
val number = helper.createEditText().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(36)
    setHint("数字模式")
    setInputType(InputType.NUMBER)
    setText("012345678910")
    setTextColor(0xFF1A8BFF.toInt())
    setGravity(GravityType.CENTER)
    setBackgroundShape(
        ShapeDescriptor.Builder().fillColor(0x99000000.toInt()).cornerRadius(4f).build()
    )
}

// 密码:文本以圆点遮罩显示
val password = helper.createEditText().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(36)
    setHint("密码模式")
    setInputType(InputType.PASSWORD)
    setText("012345678910")
    setTextColor(0xFF1A8BFF.toInt())
    setGravity(GravityType.CENTER)
    setBackgroundShape(
        ShapeDescriptor.Builder().fillColor(0x99000000.toInt()).cornerRadius(4f).build()
    )
}

// 自动分组:每 4 位插入一个空格(银行卡号)
val grouping = helper.createEditText().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(36)
    setHint("银行卡号")
    setGrouping("4")
    setText("0000111122223333")
    setTextColor(0xFF1A8BFF.toInt())
    setGravity(GravityType.CENTER)
    setBackgroundShape(
        ShapeDescriptor.Builder().fillColor(0x99000000.toInt()).cornerRadius(4f).build()
    )
}

// 限制字数:最多 8 个字符
val maxLength = helper.createEditText().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(36)
    setHint("最多输入 8 个字符")
    setMaxLength(8)
    setText("最多输入8个")
    setTextColor(0xFF1A8BFF.toInt())
    setGravity(GravityType.CENTER)
    setBackgroundShape(
        ShapeDescriptor.Builder().fillColor(0x99000000.toInt()).cornerRadius(4f).build()
    )
}

// 文本变化监听(回调在 Binder 线程池,更新 UI 需切主线程)
number.setOnTextChangeListener(object : IRemoteViewTextWatcher {
    override fun beforeTextChanged(s: String, start: Int, count: Int, after: Int) {}
    override fun onTextChanged(s: String, start: Int, before: Int, count: Int) {
        Handler(Looper.getMainLooper()).post {
            // 在主线程安全地更新 UI
        }
    }
    override fun afterTextChanged(s: String) {}
})

说明: 完整可运行示例见官方 Sample open-pilot-plugin-sample 的 drawing/EditTextDrawer.ktopen in new window。

最近修改: