列表 basic-list

2026年7月20日大约 3 分钟

列表 `basic-list`

数据列表，可显序号 / 数值条、自动轮播滚动。

类型串：basic-list　默认尺寸：[280, 320]　分类：控件

实时预览

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

属性

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

basic

属性	名称	类型	默认	说明
`static-items`	静态条目	`string`	`列表项一,列表项二,列表项三,列表项四`
`show-index`	显示序号	`boolean`	`false`
`row-height`	行高	`number(unit=px,min=0)`	`36`
`show-divider`	显示分割线	`boolean`	`true`
`auto-select-first`	默认选中首行	`boolean`	`false`
`carousel`	轮播	`boolean`	`false`
`carousel-type`	切换方式	`select(radioGroup)`	`scroll`	可选：`scroll` / `page`
`carousel-speed`	滚动速度	`number(min=1,unit=px/秒)`	`30`
`carousel-page-count`	每页条数	`number(min=1,unit=条)`	`4`
`carousel-dwell`	停留时长	`number(min=0.5,unit=秒)`	`3`
`carousel-loop`	循环播放	`boolean`	`true`
`show-dots`	显示翻页点	`boolean`	`true`
`dot-position`	翻页点位置	`select(radioGroup)`	`bottom`	可选：`top` / `bottom`
`dot-color`	翻页点颜色	`color`	`#B2B2B2`
`dot-active-color`	翻页点选中色	`color`	`#FFFFFF`

valueBar

属性	名称	类型	默认
`valueBar`	数值条	`boolean`	`false`
`value-bar-color`	数值条颜色	`color(gradient)`	`#2f7bff`
`value-bar-bg`	数值条背景	`color`	`rgba(47,123,255,0.12)`
`value-bar-height`	数值条高度	`number(unit=px,min=0)`	`6`

font

属性	名称	类型	默认
`title-color`	标题颜色	`color`	`#e6e8ec`
`value-color`	数值颜色	`color`	`#2f7bff`
`list-font-size`	字号	`number(unit=px,min=0)`	`14`

row

属性	名称	类型	默认
`row-bg`	行背景	`color`	`transparent`
`row-alt-bg`	隔行背景	`color`	`rgba(255,255,255,0.03)`
`hover-bg`	悬停背景	`color`	`rgba(47,123,255,0.15)`
`selected-bg`	选中背景	`color`	`rgba(47,123,255,0.3)`
`divider-color`	分割线颜色	`color`	`rgba(255,255,255,0.08)`

scrollbar

属性	名称	类型	默认
`show-scrollbar`	显示滚动条	`boolean`	`false`
`scrollbar-size`	滚动条宽度	`number(min=0,unit=px)`	`4`
`scrollbar-color`	滚动条颜色	`color`	`#a5a5a5`
`scrollbar-bg-color`	滚动条背景颜色	`color`	`transparent`
`scrollbar-border-radius`	滚动条圆角	`number(min=0,unit=px)`	`2`

数据绑定

字段槽	类型 / 约束	说明
`title-field`	`field(recommend=string,min=0,max=1)`	标题字段
`value-field`	`field(recommend=number,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-list",
  "uid": "w_basic_list",
  "options": {
    "position": [40, 40],
    "size": [280, 320],
    "title-field": [["conn_demo", "tbl_demo", "字段名"]],
    "value-field": [["conn_demo", "tbl_demo", "字段名"]]
  }
}

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

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