图片 basic-image

2026年7月20日大约 4 分钟

图片 `basic-image`

显示静态图片或数据驱动图片，支持滤镜与三态切换。

类型串：basic-image　默认尺寸：[320, 200]　分类：媒体

实时预览

下面渲染的是真实组件（与编辑器 / 运行时同源）。修改右侧「样式参数」，左侧预览实时更新；点击底部「全页面查看」可放大。

直填网络图片地址（image 支持 URL）+ fill-style: 'cover' 等比铺满；brightness / saturate 滤镜微调色感，通用「边框设置」组（border: true + border-radius / border-color）给图片加圆角描边。右侧面板拖动滤镜滑杆即可实时看效果。

属性

下表为本组件特有的属性；position / size / opacity / background / border / 联动选中 / 筛选等通用参数见组件手册总览。

basic

属性	名称	类型	默认	说明
`image`	图片	`file`	—
`fill-style`	填充方式	`select(radioGroup)`	`fill`	可选：`fill` / `cover` / `contain` / `none`

filter

属性	名称	类型	默认
`brightness`	亮度	`slider(min=0,max=200,step=1,unit=%)`	`100`
`contrast`	对比度	`slider(min=0,max=200,step=1,unit=%)`	`100`
`saturate`	饱和度	`slider(min=0,max=200,step=1,unit=%)`	`100`
`hue`	色相	`slider(min=0,max=360,step=1,unit=°)`	`0`

show-click

属性	名称	类型	默认	说明
`show-click`	点击状态	`boolean`	`false`
`image-click`	点击图片	`file`	—
`fill-style-click`	点击填充方式	`select(radioGroup)`	`继承`	可选：`fill` / `cover` / `contain` / `none`

show-hover

属性	名称	类型	默认	说明
`show-hover`	悬停状态	`boolean`	`false`
`image-hover`	悬停图片	`file`	—
`fill-style-hover`	悬停填充方式	`select(radioGroup)`	`继承`	可选：`fill` / `cover` / `contain` / `none`

show-selected

属性	名称	类型	默认	说明
`show-selected`	选中状态	`boolean`	`false`
`image-selected`	选中图片	`file`	—
`fill-style-selected`	选中填充方式	`select(radioGroup)`	`fill`	可选：`fill` / `cover` / `contain` / `none`

animation-display

属性	名称	类型	默认	说明
`animation-display`	播放动画	`boolean`	`false`
`animation-type`	动画类型	`select(radioGroup)`	`scroll`	可选：`scroll` / `blink`
`animation-easing`	缓动方式	`select`	`none`	可选：`none` / `Power1.easeIn` / `Power1.easeOut` / `Power1.easeInOut` / `Power2.easeIn` / `Power2.easeOut` / `Power2.easeInOut` / `Power3.easeIn` / `Power3.easeOut` / `Power3.easeInOut` / `Power4.easeIn` / `Power4.easeOut` / `Power4.easeInOut` / `Sine.easeIn` / `Sine.easeOut` / `Sine.easeInOut` / `Expo.easeIn` / `Expo.easeOut` / `Expo.easeInOut` / `Circ.easeIn` / `Circ.easeOut` / `Circ.easeInOut` / `Back.easeIn` / `Back.easeOut` / `Back.easeInOut` / `Elastic.easeIn` / `Elastic.easeOut` / `Elastic.easeInOut` / `Bounce.easeIn` / `Bounce.easeOut` / `Bounce.easeInOut` / `SlowMo.easeIn` / `SlowMo.easeOut` / `SlowMo.easeInOut`
`animation-delay`	动画延迟时长	`number<float>(step=0.1,unit=秒)`	`1`
`animation-duration`	单个动画持续时长	`number<float>(step=0.1,unit=秒)`	`1`
`animation-loop`	循环播放动画	`boolean`	`false`
`animation-interval`	循环间隔时长	`number<float>(step=0.1,unit=秒)`	`0`

binding

属性	名称	类型	默认	说明
`relationship-value`	选中判定值	`string`	—

数据绑定

字段槽	类型 / 约束	说明
`image-field`	`field(recommend=string,min=0,max=1)`	动态图片
`relationship-field`	`field(recommend=string,min=0,max=1)`	选中判定字段

事件

触发器

触发器在预览 / 播放态生效（编辑态点击 = 选中组件）。写在本组件 options.interactions 的 groups[].trigger 里。

触发器	名称	触发时机	payload（供动作公式 `{:字段}` 取值）
`itemClicked`	点击某项	点击图片时触发	绑定行数据
`click`	点击	点击本组件时触发	无
`mouseEnter`	鼠标移入	指针移入组件时触发	无
`mouseLeave`	鼠标移出	指针移出组件时触发	无
`appear`	入场	组件出现时触发（配合进场动画）	无
`disappear`	离场	组件消失时触发（配合退场动画）	无
`receiveBehaviorEvent`	接收行为事件	收到 `sendBehaviorEvent` 动作或宿主 `ctx.emit` 投递的事件时触发（按 `eventName` 匹配）	发送方携带的 data

动作

触发器命中后执行的动作。本组件既可发起动作（配在自己的交互里），也可作为其它组件动作的目标。

动作	名称	说明
`changeOption`	修改设置	把本组件（或其它组件）的某个属性改为静态值 / 公式动态值
`switchState`	切换状态	切到多状态里的某个状态（`state:""` 回默认态）
`appear / disappear`	进 / 退场动画	对目标 `opacity` 做 0↔100 插值的显隐动画

完整动作清单（switchScreen / switchWindow / openUrl / sendBehaviorEvent / transfer / executeScript / requestApi 等）与持久化写法见事件交互。

示例

{
  "type": "basic-image",
  "uid": "w_basic_image",
  "options": {
    "position": [40, 40],
    "size": [320, 200],
    "image-field": [["conn_demo", "tbl_demo", "字段名"]],
    "relationship-field": [["conn_demo", "tbl_demo", "字段名"]]
  }
}

绑定三元组 [连接uid, 表uid, 字段uid] 指向工程 connections 里的真实字段，见数据系统。

变体示例：contain 与 cover 填充对比

同一张 3:2 图片放进两个 1.28:1 的组件盒：左 fill-style: 'contain' 等比完整显示（上下留出背景色空带）、右 fill-style: 'cover' 等比铺满（左右裁掉超出部分）；开启通用「背景」组给盒子铺深色底，留白差异一目了然。

延伸阅读：组件手册总览 · 数据系统 · 事件交互。