ItemsControl 项容器

通用布局能力：RenderItemsControl 的 options 组合 RenderBoxOptions，可直接配置 width、height、min/max、margin 和槽位对齐；item 内部 padding 是 item 外观配置。详见组件通用布局属性。

DirectSurface UI 的模板项容器公共类名是 RenderItemsControl。它按业务数据数组生成一组 RenderItemContainer，每个 item 通过 itemTemplate(item, state, index) 返回一个子组件。它支持纵向/横向排列、可变尺寸 item、单选、激活、hover、键盘焦点、内部滚动条、滚动定位和虚拟化。

RenderItemsControl 是“数据项到组件树”的通用容器。标准文本列表优先用 ListView，多列表格用 GridView，树形数据用 TreeView，纯布局组合用 StackPanel、Wrap 或 Masonry。

API 总览

import {  mergeItemContainerStyle,  RenderItemsControl,  RenderText,  rgba,  type ItemContainerState,  type ItemContainerStyleOverrides,  type ItemTemplate,  type ItemsControlItemMetrics,  type ItemsControlOrientation,  type ItemsControlScrollAlign,  type ItemsControlScrollMode,  type ItemsControlSelectionChange,  type ItemsControlSelectionMode,  type ItemsControlVirtualizationOptions,} from 'ds-ui'

最小装配顺序是：准备稳定 key 的 items，提供 getKey 和 itemTemplate，再创建 RenderItemsControl<T>。模板必须为每个 item 返回新的 RenderBox 实例，不要复用同一个子组件。

何时使用

• 每一项都需要业务模板，例如患者卡片、任务卡片、消息卡片、搜索结果卡片。
• 行高或卡片尺寸可能不同。
• 需要在 item 上统一绘制 selected、hovered、focused、disabled 状态。
• 需要大数据虚拟化，但每项仍由模板组件绘制。
• 需要横向列表、横向滚动或纵向列表内部滚动。
• 需要 scrollToIndex()、scrollToKey() 和 item metrics 支持外部定位。

不适合：

• 只是简单文本行，使用 ListView。
• 有列头、排序、列宽和单元格编辑，使用 GridView。
• 数据有父子层级，使用 TreeView 或 TreeGrid。
• item 模板很重但未开启虚拟化。大数据下应开启 virtualization.enabled。

最小示例

interface TaskItem {  id: string  title: string} const taskItems: TaskItem[] = [  { id: 'task-1', title: '核对病历' },  { id: 'task-2', title: '提交审核' },] const taskList = new RenderItemsControl<TaskItem>({  items: taskItems,  getKey: item => item.id,  itemTemplate: (item, state) => new RenderText(state.selected ? `* ${item.title}` : item.title),  onSelectionChange: change => {    state.selectedTaskId = change.item.id  },})

itemTemplate 返回的是组件实例。不要在模板里复用同一个 RenderBox 实例，每个 item 都应该返回新的子组件。

ItemContainerState 字段：

构造参数

new RenderItemsControl(options) 的 options：

interface PatientCard {  id: string  name: string  bedNo: string} const patientCards: PatientCard[] = [  { id: 'p1', name: '李安然', bedNo: '12床' },  { id: 'p2', name: '王明', bedNo: '18床' },] const patients = new RenderItemsControl<PatientCard>({  items: patientCards,  getKey: item => item.id,  itemAppearance: 'row',  itemMinHeight: 36,  itemTemplate: item => new RenderText(`${item.bedNo} ${item.name}`),})

Item 容器样式覆盖

itemAppearance 选择一套主题外观，itemStyle 在单个 RenderItemsControl 实例上覆盖其中一部分 token。覆盖是按字段合并的：background、border、text 会深合并状态 token，paddingX、paddingY、minHeight、borderRadius、borderWidth、borderPlacement、accentWidth、accentColor 和 focusColor 会按传入值替换。

itemStyle: undefined 表示完全使用 itemAppearance 的主题样式。

interface MenuItem {  id: string  title: string} const lightLinkList = new RenderItemsControl<MenuItem>({  items: menus,  getKey: item => item.id,  itemAppearance: 'navigation',  itemShowAccent: false,  itemMinHeight: 26,  itemPaddingY: 0,  itemStyle: {    background: { normalBg: rgba(0, 0, 0, 0) },    borderWidth: 0,  },  itemTemplate: item => new RenderText(item.title, {    role: 'accent',    overflow: 'ellipsis',  }),  onActivate: item => openMenu(item.id),})

上例只把 normal 背景改成透明并关闭边框，hover、selected、focused、disabled 的背景和文字状态仍来自 navigation 外观。模板里只放展示内容，让 RenderItemsControl 继续统一负责 pointer、selection、activate、hover、滚动和键盘导航。

ItemTemplate

ItemTemplate<T> 的签名：

interface TaskItem {  id: string  title: string} const taskTemplate: ItemTemplate<TaskItem> = (item, itemState, index) => {  const prefix = itemState.focused ? `${index + 1}. ` : ''  return new RenderText(`${prefix}${item.title}`)}

itemState 包含：

模板会在这些情况下重新执行：

• item 数据引用变化或 index 变化。
• disabled 状态变化。
• selected、hovered、focused 状态变化。
• itemMinHeight、itemPaddingY、itemShowAccent、itemAppearance 等容器选项变化。

模板里可以返回交互子组件。RenderItemsControl 会检查 hit test path，如果事件已经命中 item 内部的交互子组件，就不会抢占 pointer down/up。

选择模型

selectionMode：

interface TaskItem {  id: string  title: string} const taskItems: TaskItem[] = [  { id: 'task-1', title: '核对病历' },  { id: 'task-2', title: '提交审核' },] const actionList = new RenderItemsControl<TaskItem>({  items: taskItems,  getKey: item => item.id,  selectionMode: 'none',  itemTemplate: item => new RenderText(item.title),  onActivate: item => {    state.lastActionId = item.id  },})

selectedItem 必须是当前 items 数组中的对象引用。只传相同 key 的新对象不会选中：

interface TaskItem {  id: string  title: string} const taskItems: TaskItem[] = [  { id: 'task-1', title: '核对病历' },  { id: 'task-2', title: '提交审核' },] const taskList = new RenderItemsControl<TaskItem>({  items: taskItems,  getKey: item => item.id,  itemTemplate: item => new RenderText(item.title),}) const selectedTask = taskList.items.find(item => item.id === 'task-2') ?? nulltaskList.selectedItem = selectedTask

程序设置 selectedItem 不触发 onSelectionChange。只有用户交互导致选中变化时才触发回调。

可选、禁用和激活

isItemDisabled(item, index) 用于禁用 item：

• 禁用项不响应选中、激活和键盘确认。
• disabled 状态会传给模板。
• 容器整体 disabled = true 时，所有 item 都视为 disabled。

isItemSelectable(item, index) 用于把某些 item 从选择模型里排除：

• 不可选项不会替换当前选中项。
• 如果提供了 onActivate，不可选项仍可以被激活。
• 适合分组标题、快捷操作行、说明行。

interface TaskItem {  id: string  title: string} const taskItems: TaskItem[] = [  { id: 'group', title: '待办任务' },  { id: 'task-1', title: '核对病历' },] const mixedList = new RenderItemsControl<TaskItem>({  items: taskItems,  getKey: item => item.id,  isItemSelectable: (_item, index) => index !== 0,  itemTemplate: item => new RenderText(item.title),  onActivate: item => {    state.activatedTaskId = item.id  },})

属性

const taskList = new RenderItemsControl({  items: [{ id: 'task-1', title: '核对病历' }],  getKey: item => item.id,  itemTemplate: item => new RenderText(item.title),}) taskList.spacing = 6taskList.itemAppearance = 'row'taskList.maxHeight = 360taskList.scrollY = 0

方法

align 类型为 ItemsControlScrollAlign，可取：

const taskList = new RenderItemsControl({  items: Array.from({ length: 10000 }, (_, index) => ({    id: `task-${index}`,    title: `任务 ${index}`,  })),  getKey: item => item.id,  height: 320,  virtualization: { enabled: true, estimatedItemMainSize: 36 },  itemTemplate: item => new RenderText(item.title),}) taskList.scrollToIndex(3000, 'start')taskList.scrollToKey('task-9000', 'center')

ItemsControlItemMetrics

纵向列表中，mainOffset/mainSize 表示 y/height；横向列表中表示 x/width。

const taskList = new RenderItemsControl({  items: [    { id: 'task-1', title: '核对病历' },    { id: 'task-2', title: '提交审核' },  ],  getKey: item => item.id,  itemTemplate: item => new RenderText(item.title),}) const taskMetric = taskList.getItemMetricsForKey('task-2')if (taskMetric) {  state.taskTop = taskMetric.mainOffset}

debugState

debugState() 返回：

const taskList = new RenderItemsControl({  items: [{ id: 'task-1', title: '核对病历' }],  getKey: item => item.id,  itemTemplate: item => new RenderText(item.title),}) const itemsState = taskList.debugState()state.materializedCount = itemsState.materializedKeys.lengthstate.itemsViewportHeight = itemsState.viewportHeight

布局和滚动

纵向布局：

• item 依次沿 y 轴排列。
• bounded width 下 item 会拉伸到可用宽度。
• 内容高度超过视口时显示垂直滚动条。
• 垂直滚动条出现后会预留 gutter，避免内容绘制到滚动条下面。

横向布局：

• item 依次沿 x 轴排列。
• maxWidth 常用于限制控件宽度，从而产生横向滚动。
• 内容宽度超过视口时显示水平滚动条。
• 横向列表里，鼠标纵向滚轮会优先转换为横向滚动。

interface TaskItem {  id: string  title: string} const taskItems: TaskItem[] = [  { id: 'task-1', title: '核对病历' },  { id: 'task-2', title: '提交审核' },] const horizontalTasks = new RenderItemsControl<TaskItem>({  items: taskItems,  getKey: item => item.id,  orientation: 'horizontal',  maxWidth: 420,  itemTemplate: item => new RenderText(item.title),})

scrollMode: 'none' 会关闭内部滚动条，并把滚动偏移夹到 0。此时如果内容超出父约束，超出的部分不会通过内部滚动查看。

虚拟化

ItemsControlVirtualizationOptions：

interface TaskItem {  id: string  title: string} const virtualTasks = new RenderItemsControl<TaskItem>({  items: Array.from({ length: 10000 }, (_, index) => ({    id: `task-${index}`,    title: `任务 ${index}`,  })),  getKey: item => item.id,  height: 320,  virtualization: {    enabled: true,    estimatedItemMainSize: 36,    overscan: 2,  },  itemTemplate: item => new RenderText(item.title),})

虚拟化行为：

• 初始只 materialize 估算视口内的 item 和 overscan。
• 滚动时根据 VariableVirtualizer 计算范围。
• 已测量 item 会把真实尺寸回写给 virtualizer。
• 如果测量后范围变化，会再次 reconcile 当前范围。
• debugState().materializedKeys 只包含实际创建的容器。
• getItemMetrics() 在虚拟化开启时可以返回全量虚拟 metrics，但大量调用仍有成本。

性能建议：

• 大数据列表必须提供稳定且唯一的 getKey。
• estimatedItemMainSize 应接近真实平均高度或宽度。
• overscan 不要过大，否则会抵消虚拟化收益。
• itemTemplate 不要创建过重组件或发起业务请求。
• 需要频繁更新 item 时，尽量保持对象和 key 稳定，减少模板重建。

鼠标行为

如果 pointer 事件已经命中 item 模板内部的交互子组件，RenderItemsControl 不会抢占该事件，也不会因为 hover 立即重建当前模板。这能避免按钮、输入框等嵌在 item 内时被父列表打断。

键盘行为

键盘只在容器 focused 且未 disabled 时生效。

键盘移动会调用内部 ensure visible。虚拟化开启时，如果目标 item 当前未 materialized，会记录 pending key，下一次 layout 会根据 metrics 再滚动到可见。

动态更新

interface TaskItem {  id: string  title: string} function replaceTasks(control: RenderItemsControl<TaskItem>, nextItems: TaskItem[]): void {  const selectedId = control.selectedItem?.id ?? ''  control.items = nextItems  control.selectedItem = nextItems.find(item => item.id === selectedId) ?? nextItems[0] ?? null}

更新 items 时：

• 重新计算 _itemKeys 和 key 到 index 的映射。
• 按 key 复用已有 RenderItemContainer。
• 数据引用或 index 改变时刷新模板。
• 不再存在的容器会 detach。
• 已无效的 selected、hovered、focused key 会被清理。
• 虚拟化开启时只 reconcile 当前 materialized 范围。

getKey 不能返回重复 key。若重复，内部 key index 只保留第一次出现的位置，选择和滚动定位会变得不可预测。

与其他组件的区别

常见问题

为什么 selectedItem 设置后没有选中？

selectedItem 必须是当前 items 数组里的同一对象引用，并且 selectionMode === 'single'，目标项不能 disabled，isItemSelectable 也不能返回 false。

为什么滚动后 debugContainers 里没有全部项？

开启虚拟化后，debugContainers() 只返回当前 materialized 的容器。需要全量位置数据时用 getItemMetrics()，需要确认当前创建了哪些容器时看 debugState().materializedKeys。

为什么 hover 时模板会重新创建？

itemTemplate 接收 state.hovered。为了让模板能根据 hover 状态改变内容，父容器会刷新模板。模板里有交互子组件时，命中该子组件的 hover 会尽量保留当前模板，避免打断子组件交互。

为什么在滚动边界外层容器没有继续滚动？

只要 ItemsControl 自己有对应方向的滚动条，它会在滚动边界继续消费 wheel，避免内嵌滚动区域把滚动传给外层，导致页面跳动。

什么时候使用 itemAppearance = 'row'？

'row' 更像数据行：底部分割线、较小圆角、浅选中背景。用于诊断列表、明细行、数据组行。'navigation' 更适合左侧导航。默认外观适合卡片式 item。

相关文档

• ListView
• GridView
• TreeView
• TreeGrid
• StackPanel
• ScrollView
• 虚拟化
• 大数据表格
• 主题与状态