图片 Image
一、功能描述
RemoteImage 是用于显示图片的组件,对应 ViewType.IMAGE_VIEW。它支持设置图片文件名、填充模式(ScaleType)、图片染色(tint),并可结合通用属性实现圆角、圆形、描边、半透明等样式,适合展示图标、示意图、照片缩略图等。
图片资源需先通过文件传输上传到 Pilot,再用文件名引用。通过 RemoteViewHelper.createImage() 创建:
val image = helper.createImage()
二、通用属性
以下属性通过对应的 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 | 背景形状:填充色 / 描边 / 圆角(圆形用 SHAPE_OVAL) |
图片属性
| 方法 | 参数 | 说明 |
|---|---|---|
setImageFileName | String | 图片文件名(需先通过 helper.pushImageFile(...) 上传到 Pilot) |
setScaleType | ScaleType | 填充模式:MATRIX / FIT_XY / FIT_START / FIT_CENTER / FIT_END / CENTER / CENTER_CROP / CENTER_INSIDE |
setImageTint | Int | 图片染色(ARGB Int),在图片上叠加一层颜色蒙版 |
三、Tips
- 图片必须先上传到 Pilot 才能引用。先调用
helper.pushImageFile(filePath, callback)上传本地图片,在上传成功回调(onSuccess)之后再对组件调用setImageFileName(...),否则 Server 端找不到文件,图片无法显示。 - 文件名大小写敏感。
setImageFileName传入的名字须与上传文件名完全一致(含扩展名,如sea_view.webp),大小写不同会导致引用失败。 - 染色与背景颜色只能传 ARGB Int。
setImageTint/setBackground接收 Int 颜色值(如0x4DFFCC00.toInt()),不要传"#RRGGBB"、"0xAARRGGBB"或R.color.xxx。 - 圆形图片用
ShapeDescriptor的SHAPE_OVAL,并把宽高设为相等;圆角用cornerRadius(...),描边用stroke(width, color)。 - 修改已挂载组件的属性后要
syncToRemote()。setXxx只更新本地缓存,调用syncToRemote()才会批量同步到 Pilot;挂载前配置好属性则无需额外调用。 ImageView不支持文字叠加(渲染层会静默忽略文字属性),如需图片上叠文字,请在ConstraintLayout中同时放置 Image 与 Text 并设置约束。
四、示例代码
下方每组左侧为示例代码,右侧为对应的 Pilot 端渲染预览效果。
01 组件类型(方形 / 圆角 / 圆形)
// 图片需先上传到 Pilot,成功回调后再引用文件名
helper.pushImageFile(localImagePath, object : CommonCallbacks.CompletionCallbackWithProgress<Double> {
override fun onProgressUpdate(progress: Double) {}
override fun onSuccess() {
// 上传成功后再创建并设置图片
buildImages()
}
override fun onFailure(error: IDJIError) {}
})
fun buildImages() {
val imageFileName = "sea_view.webp" // 大小写须与上传文件一致
// 方形图片
val square = helper.createImage().apply {
setWidth(RemoteView.MATCH_PARENT); setHeight(80)
setImageFileName(imageFileName)
setScaleType(ScaleType.CENTER_CROP)
}
// 圆角图片
val rounded = helper.createImage().apply {
setWidth(RemoteView.MATCH_PARENT); setHeight(80)
setImageFileName(imageFileName)
setScaleType(ScaleType.CENTER_CROP)
setBackgroundShape(ShapeDescriptor.Builder().cornerRadius(12f).build())
}
// 圆形图片:宽高相等 + SHAPE_OVAL
val circle = helper.createImage().apply {
setWidth(80); setHeight(80)
setImageFileName(imageFileName)
setScaleType(ScaleType.CENTER_CROP)
setBackgroundShape(
ShapeDescriptor.Builder()
.shape(ShapeDescriptor.SHAPE_OVAL)
.fillColor(Color.RED)
.build()
)
}
}
02 组件样式(半透明 / 颜色填充 / 颜色描边)
val imageFileName = "sea_view.webp"
// 基础图片
val basic = helper.createImage().apply {
setWidth(RemoteView.MATCH_PARENT); setHeight(80)
setImageFileName(imageFileName)
setScaleType(ScaleType.CENTER_CROP)
setBackgroundShape(ShapeDescriptor.Builder().cornerRadius(8f).build())
}
// 半透明图片:降低透明度
val semiTransparent = helper.createImage().apply {
setWidth(RemoteView.MATCH_PARENT); setHeight(80)
setImageFileName(imageFileName)
setScaleType(ScaleType.CENTER_CROP)
setAlpha(0.4f)
setBackgroundShape(ShapeDescriptor.Builder().cornerRadius(8f).build())
}
// 颜色填充图片:叠加 50% 透明黄色蒙版
val tinted = helper.createImage().apply {
setWidth(RemoteView.MATCH_PARENT); setHeight(80)
setImageFileName(imageFileName)
setScaleType(ScaleType.CENTER_CROP)
setImageTint(0x4DFFCC00.toInt())
setBackgroundShape(ShapeDescriptor.Builder().cornerRadius(8f).build())
}
// 颜色描边图片:3dp 黄色描边 + 圆角
val stroked = helper.createImage().apply {
setWidth(RemoteView.MATCH_PARENT); setHeight(80)
setImageFileName(imageFileName)
setScaleType(ScaleType.CENTER_CROP)
setBackgroundShape(
ShapeDescriptor.Builder()
.cornerRadius(8f)
.stroke(3, 0xFFFFCC00.toInt())
.build()
)
}
完整可运行示例见官方 Sample
open-pilot-plugin-sample的 drawing/ImageViewDrawer.kt。