图片 Image

2026-11-03评分加载中…

一、功能描述

RemoteImage 是用于显示图片的组件,对应 ViewType.IMAGE_VIEW。它支持设置图片文件名、填充模式(ScaleType)、图片染色(tint),并可结合通用属性实现圆角、圆形、描边、半透明等样式,适合展示图标、示意图、照片缩略图等。

图片资源需先通过文件传输上传到 Pilot,再用文件名引用。通过 RemoteViewHelper.createImage() 创建:

val image = helper.createImage()

二、通用属性

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

图片属性

方法参数说明
setImageFileNameString图片文件名(需先通过 helper.pushImageFile(...) 上传到 Pilot)
setScaleTypeScaleType填充模式:MATRIX / FIT_XY / FIT_START / FIT_CENTER / FIT_END / CENTER / CENTER_CROP / CENTER_INSIDE
setImageTintInt图片染色(ARGB Int),在图片上叠加一层颜色蒙版

三、Tips

  1. 图片必须先上传到 Pilot 才能引用。先调用 helper.pushImageFile(filePath, callback) 上传本地图片,在上传成功回调(onSuccess)之后再对组件调用 setImageFileName(...),否则 Server 端找不到文件,图片无法显示。
  2. 文件名大小写敏感。setImageFileName 传入的名字须与上传文件名完全一致(含扩展名,如 sea_view.webp),大小写不同会导致引用失败。
  3. 染色与背景颜色只能传 ARGB Int。setImageTint / setBackground 接收 Int 颜色值(如 0x4DFFCC00.toInt()),不要传 "#RRGGBB"、"0xAARRGGBB" 或 R.color.xxx。
  4. 圆形图片用 ShapeDescriptor 的 SHAPE_OVAL,并把宽高设为相等;圆角用 cornerRadius(...),描边用 stroke(width, color)。
  5. 修改已挂载组件的属性后要 syncToRemote()。setXxx 只更新本地缓存,调用 syncToRemote() 才会批量同步到 Pilot;挂载前配置好属性则无需额外调用。
  6. 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.ktopen in new window。

最近修改: