WinUI 3 TableView 控件功能规格解读面向 Windows Shell 场景的只读优先轻量级表格控件【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xamlTableView 是 WinUI 3microsoft-ui-xaml 仓库中面向 Windows Shell 现代化改造DUI → WinUI 3而设计的轻量级、生产级表格控件核心目标是实现与任务管理器Task Manager、文件资源管理器File Explorer详情视图相媲美的呈现能力。本文基于仓库内 TableView-functional-spec.md 展开结合配套的 TableView-dev-spec.md、TableView API 规格 以及 TableView 源码目录 中的真实实现完整梳理它的设计目标、功能需求矩阵、交付节奏与底层实现机制帮助读者理解这个控件能做什么、怎么交付、底层如何工作。TableView 是什么轻量级表格而非 DataGrid 替代品从功能规格的 Purpose 章节可以明确控件的定位TableView是一个面向 WinUI 3 的轻量级、生产级表格控件用于现代化 Windows Shell 界面DUI → WinUI 3目标是实现与任务管理器和文件资源管理器详情视图的对等能力。它是一个只读优先的呈现控件——不是完整的DataGrid替代品。这一定位贯穿整个功能设计控件以稳定、高效地呈现大量行数据为第一优先交互能力编辑、选择、排序、分组以可插拔、增量式的方式逐步叠加。与之呼应的工程描述在 TableView-dev-spec.md 中进一步明确TableView是Microsoft.UI.Xaml.Controls.Tabular.dll中最小的、仅用于显示的基础表格控件将ItemsSource渲染为虚拟化行并用Columns为每个已实现的行/列交叉点生成一个单元格。设计目标Goals功能规格列出了四条核心目标它们决定了后续所有需求条目的优先级目标内容数据模型与布局在ObservableCollection支撑的模型上实现行/列布局支持实时、增量更新增/删/改无需整体重渲染行虚拟化与滚动行虚拟化 平滑滚动约 500 行时达到≥30 FPS低输入延迟无障碍UIA Grid/Table/Selection 模式 Narrator 支持键盘操作对等主题支持 Light / Dark / High Contrast 主题其中≥30 FPS 滚动、低延迟、高频更新直接对应任务管理器场景的实时指标刷新需求——这是性能需求条目的来源。四阶段交付路线4-PR stackTableView 的能力不是一次性交付而是通过 4 个 PR 分阶段落地功能规格给出了清晰的交付矩阵PR交付内容PR 1空的Microsoft.UI.Xaml.Controls.Tabular.dll脚手架PR 2本文档对应阶段仅显示基线列/单元格/表头、网格线、密度、行虚拟化、前导冻结列、键盘行焦点导航、只读 UIA peersPR 3选择、单列排序、分组、2 级层次结构、列宽调整/重排、导航状态主题化渲染PR 4测试 TableViewSamples端到端示例应用这种拆分让显示基线可以独立验证后续交互能力选择/排序/分组在稳定基础上增量叠加。仓库现状印证了这一演进controls/dev/TableView目录下已经出现TableView_Selection.cpp、TableView_Sort.cpp、TableView_Grouping.cpp、TableViewGroupHeader.cpp、TableViewSource.cpp等文件说明 PR3 的交互能力已在源码中落地而 TableView-spec.md 中TableViewSortCycle、ITableViewSortComparer、SortByColumn、TableViewGroupInfo、ExpandAllGroups()等 API 已进入 IDL属于仍属 v1、但随后续变更增量交付的范畴。功能需求全景功能规格按主题将需求分类每一条都标注了 MLP/v1 还是延后状态以及由哪个 PR 交付。以下逐类展开。核心控件与数据模型显式列模型无自动生成——PR2。列由开发者通过Columns集合显式声明见 TableView-spec.md 中Columns为内容属性contentproperty(Columns)的声明。ObservableCollection支撑的ItemsSource支持增量增/删/改——PR2 渲染、PR3 塑形排序/分组。默认只读IsReadOnlytrue——PR2。自定义单元格模板TableViewTemplateColumn——PR2。GroupedItemsSource用于分组/带状分段——PR3。仓库中已对应TableViewSource与分组相关源码controls/dev/TableView/TableViewSource.cpp、TableView_Grouping.cpp。列能力Column capabilities宽度 MinWidth/MaxWidthv1 支持像素宽度Auto/*回退到默认宽度——PR2UI 拖拽调整在 PR3。需要说明API 规格文档TableView-spec.md与功能规格在 v1 宽度能力上存在演进差异——API 规格中的Width表注明 v1 只实现显式像素宽度Auto/*回退默认宽度、真正的 Auto/Star 尺寸调整延后而配套的 dev-spec 与当前TableView_Layout.cpp源码已实现四步宽度解析管线见下文列宽解析引擎即 Pixel/Auto/Star 三种模式在仓库当前代码中均已解析落地。列重排拖拽 MoveColumn——PR3。显示/隐藏通过Visibility——PR2。注意无障碍语义UIA 网格/表格提供程序只统计并暴露可见列折叠列不进入 UIA 列模型详见后文无障碍节。吸顶表头Sticky header始终可见——PR2。单列排序SortByColumn/ 表头点击——PR3。网格线通过GridLinesVisibility控制由主题资源驱动——PR2。前导前缀冻结列Leading-prefix frozen尾随冻结列延后——PR2前导尾随延后。多列排序——延后P2 / vNext。行与层次Row hierarchy单选 多选Ctrl/Shift——PR3。每行/单元格上下文菜单复选框选择文件资源管理器特有——PR3 / 表面层。2 级嵌套行v1 硬上限 分组——PR3。2 级层次、行拖拽、marquee框选选择——超出范围。编辑Editing编辑是 TableView 交互能力中最关键的一部分功能规格描述得最为详尽可选单元格编辑在控件上设置IsReadOnly false每列可单独设置IsReadOnly。编辑器由列提供TableViewTextColumn生成TextBoxTableViewTemplateColumn使用CellEditingTemplate。手势双击/双指轻触和F2开始编辑Enter提交Esc取消焦点移出单元格即提交。编程 APIBeginEdit、CommitEdit、CancelEdit、IsEditing、CurrentItem/CurrentColumn/SetCurrentCell。可否决的生命周期事件BeginningEdit、CellEditEnding、RowEditEnding外加EditEnded两个*EditEnding事件的参数暴露GetDeferral()允许处理程序异步校验或保存而不阻塞 UI 线程。回滚数据项实现ITableViewEditableItem时由应用拥有事务否则控件对编辑值做快照取消时恢复。校验数据项实现INotifyDataErrorInfo作用域限定为该列编辑的属性校验失败阻止提交。多单元格行事务CancelEdit(Row)回滚已提交的兄弟单元格——延后。编辑无障碍播报开始/提交/取消时的 live-region/UIA 通知——延后需本地化字符串。仓库当前实现以单元格级编辑为范围TableView-spec.md 的 Appendix 明确说明CommitEdit()/CancelEdit()只关闭打开的单元格编辑没有行级提交/取消 API也没有RowEditEnding行事务与行编辑一起到来。这与功能规格中延后的条目相互印证。编辑状态机与手势策略被刻意拆分为两个文件TableView_Editing.cpp 拥有编辑状态机TableView_EditingInput.cpp 拥有手势策略这样未来的键盘/选择层改变手势路由时无需重开状态机且状态机无需合成输入即可测试。TableViewTextColumn的编辑TextBox会复用列的BindingPath、Converter、ConverterParameter、ConverterLanguage、TargetNullValue、FallbackValue 与源选择器全部继承但强制ModeTwoWayUpdateSourceTriggerExplicit。Explicit是关键它让控件决定值何时落到数据项上——取消可丢弃编辑器而不改源校验失败可保持编辑打开若用PropertyChanged每次按键都会改数据项。虚拟化与性能Virtualization performance行虚拟化只实现可见行 缓存——PR2。实现依赖ItemsRepeater的垂直StackLayoutTableView.xaml中PART_RowsRepeater的VerticalCacheLength2.0。平滑滚动400–500 行 ≥30 FPS支持高频更新任务管理器指标场景低延迟——PR2/PR3。列虚拟化刻意省略因为典型表格只有约 5–50 列。每行渲染每个非空列的一个单元格包装器折叠列渲染隐藏单元格因此 TableView 面向约 5–50 列的典型应用表不面向 100 列的表格式规模。这也被列为 v1 非目标之一。样式与主题Styling themingLight / Dark / High Contrast 主题令牌 内联回退如深色网格线#29FFFFFF——PR2完整自主题 Theme-XBF 发射延后。实际样式资源集中在 TableView_themeresources.xaml而 TableView.xaml 提供默认样式与最后手段的回退画刷并对齐说明TabularSurfaces资源是规范来源见其中TabularSurfaceGridLineBrush等键。单元格级样式通过TableViewTemplateColumn实现自定义单元格 内置文本单元格默认样式左对齐、垂直居中。公开的按列对齐/字重 API——延后PR3。默认模板为两带布局圆角BorderControlCornerRadius卡片边缘 双行Grid行 0Auto表头带、行 1*主体带圆角仅影响渲染、不缩小主体视口因此不影响行虚拟化。行模板TableViewRow的PART_RootBorder提供 40px 最小行高、1px 底部网格线和CommonStates视觉状态Normal/PointerOver/Pressed/Disabled。工具提示Tooltips功能规格对工具提示给出了非常细致的规定这也是其与常见实现差异最大的部分之一单元格工具提示通过TableViewColumn.CellToolTipBinding选择启用绑定针对每行数据项求值其值即工具提示内容。无绑定则无工具提示、也无每单元格成本。之所以必要是因为文本单元格以CharacterEllipsis渲染且不换行超宽值无法阅读——PR3。作者优先级在单元格自身内容模板内设置的工具提示在该内容上方打开控件的工具提示覆盖单元格其余部分控件从不触碰它未附加的工具提示。内容字符串或任何ToolTip可承载的内容。UIElement会被该单元格的ToolTip作为父级因此转换器每次求值需返回新元素。计算内容用IValueConverter编写。无障碍字符串工具提示文本以单元格的AutomationProperties.HelpText发布TableViewCellAutomationPeer在 UIA 查询时若发现其仅重复单元格自身文本则抑制避免值被播报两次。抑制以所有权记录为门控应用设置的文本永不被丢弃。回收被回收的行绝不显示上一项的单元格工具提示。无需失效 API——绑定跟踪行的DataContext被回收的行通过刷新单元格文本的同一继承链重新解析源PropertyChanged会原地更新活动的工具提示。因为控件在实现单元格时从不调用应用代码所以没有重入面、没有 drain 预算、也没有合并机制。列表头工具提示通过TableViewColumn.HeaderToolTip选择启用值即内容覆盖整个表头单元格含内边距与排序指示。表头单元格是重建而非回收因此在表头构建时读取值、变化时原地重应用——无绑定、无失效。字符串内容由TableViewColumnHeaderAutomationPeer作为表头的 UIA 帮助文本上报有排序状态时与之拼接表头 peer 是虚拟的因此元素上的AutomationProperties.HelpText永远到不了客户端——PR4。组表头工具提示——延后至分组启用。值得强调的结论性规定工具提示不以文本截断为门控——没有 WinUI 控件依据IsTextTrimmed开关工具提示已发布的模式是以廉价内容谓词非空字符串或显式选择启用。无障碍Accessibility / UIAGrid/Table peersRow peerSelectionItemGridItemColumnHeader peerInvoke→ 排序——PR2 只读 Grid/TablePR3 选择 排序 invoke。Narrator、键盘导航对等、排序播报——PR2 导航PR3 排序。源码中的实现TableViewAutomationPeer.cpp 等给出四个 peerTableViewAutomationPeerIGridProvider、ITableProvider、ISelectionProvider、IItemContainerProvider、TableViewRowAutomationPeerISelectionItemProvider、TableViewColumnHeaderAutomationPeer、TableViewCellAutomationPeerIGridItemProvider、ITableItemProvider、IValueProvider。API 规格补充了细节Selection/SelectionItem仅在SelectionMode允许选择时公布GetSelection()返回已实现选中行的 provider滚出实现窗口的选中行通过IItemContainerProvider.FindItemByProperty访问。可靠性与服务Reliability servicing确定性行为、单元测试覆盖PR4、SFI/安全合规、采用后的 API 稳定性。源码级佐证布局与虚拟化的底层实现功能规格的需求条目在仓库源码中都能找到对应实现这里给出最有代表性的三处1. 列宽解析引擎TableView_Layout.cpp——注释明确说明列宽策略完全由 TableView 拥有行和表头只是薄管道。每个布局周期运行四步管线将每列写入只读的ActualWidth测量 缓存——TableView::MeasureOverride测量模板子树每个已实现的TableViewCellsPanel表头 行无约束地测量其单元格并按列缓存测量宽度。解析一次——ResolveColumnWidths拉取表头宿主与已实现行中各列的最大测量宽度将Width/MinWidth/MaxWidth与主体视口解析为ActualWidthPixel→ 给定像素Auto→ 拉取的最大值数据集内只增不减*→ 固定列之后视口的比例份额带 min/max 钳制与再分配WPFComputeStarColumnWidths形态。共享——每个表头/行TableViewCellsPanel排列时读取解析后的ActualWidth宽度变化时TableView直接使这些面板失效原子性地重排。排列——ArrangeOverride将单元格按这些宽度从左到右放置前导冻结单元格随后固定到水平滚动偏移。宽度解析是表级单点决策每次布局周期只计算一次单元格与行只测量和缓存从不决定或推送宽度。源码还包含两个已知的 v1 布局限制*列需要有限视口宽度到内容的主机中保持临时默认宽度固定列PixelAuto已超过视口时*列坍缩到MinWidth并横向滚动与 WPF DataGrid 行为一致。2. 单元格面板TableViewCellsPanel.cpp——MeasureOverride将每个单元格测量两次先无约束测量学习 Auto 尺寸所需的测量宽度再以列解析宽度约束测量第二遍。第二遍至关重要若内容宽于列而未被约束DesiredSize大于列宽XAML 排列会把单元格的渲染尺寸扩张到该期望宽度并被剪裁到列槽——这会裁掉单元格右边框垂直网格线。约束测量让省略号内容与边框都留在列内边界网格线得以正确渲染。3. 默认模板TableView.xaml——表头带PART_HeaderRow→PART_HeaderScroller仅水平滚动条隐藏→TableViewCellsPanelPART_HeaderHost主体带PART_BodyScroller→PART_BodyContent→ItemsRepeaterPART_RowsRepeater垂直StackLayout、VerticalCacheLength2.0 空状态PART_EmptyStatePresenter。吸顶表头由 C 控件在PART_BodyScroller.ViewChanged时驱动PART_HeaderScroller的水平偏移实现单向同步仅处理主体的ViewChanged表头永不作为源并跳过 0.5px 的近似相等偏移以避免ViewChanged乒乓。4. 冻结前导列——前导冻结的表头与主体单元格对水平滚动偏移做反向平移counter-translate。仅列 0 开始的连续前导前缀被固定后续的Leading列按非冻结处理。这依赖ElementCompositionPreview.SetIsTranslationEnabled否则UIElement.Translation的 X/Y 变化是空操作非冻结单元格从固定带中裁剪出去使水平滚动内容不会画到冻结单元格下方。5. 行虚拟化与回收——行由ItemsRepeater在垂直轴虚拟化只有实现矩形与主体视口相交的行外加两侧各两个视口的缓存被物化为TableViewRow实例离屏行回到回收池。回收时ItemsRepeater把池中行的DataContext重新指向新项单元格数据通过DataContext继承 绑定响应式更新——单元格不会被命令式重贴在 repeater 测量期间变更活动单元格会重入框架布局并快速失败。因此RebuildCells只用于结构性变化列/模板/密度纯回收只刷新依赖索引的视觉交替行条纹与冻结列固定。dev-spec 特别强调自定义列重写GenerateElementCore必须响应式绑定继承的DataContext不得设置本地DataContext否则回收后会显示陈旧数据——TableView.idl 中GenerateElementCore的注释明确记载了这一要求。排序的所有权与对账Sort ownershipdev-spec 补充了功能规格中单列排序的底层规则它是理解后续排序 API 的关键排序有两条前端且任何时刻只有一条轴生效二者对账而非叠加TableView.SortByColumn以及表头点击声明控件自身的轴并发布TableViewColumn.SortDirection——这是表头箭头chevron绘制的依据。TableViewSource.Sort在源上声明轴。路径重载Sort(sortMemberPath, direction)命名属性控件可将其与列的SortMemberPath匹配并点亮该列的箭头委托重载Sort(keySelector, direction)是不透明的键可能根本不对应任何列计算键、多字段、自定义比较器因此不显示箭头。对账规则通过控件排序清除应用在源上声明的轴在源上声明排序清除控件的轴路径声明的轴匹配到列则点亮该列并带列抛出Sorted否则清除所有SortDirection且Sorted携带空列ClearSort()清除所有轴包括应用声明的。这样避免了早期声明的轴静默压过晚期声明的轴、而箭头却展示失败方的情况——WPF 的拆分方式相同SortDescriptions携带属性名DataGrid据此匹配列并点亮箭头。风格模型分层可增长Styling model样式分层设计显示基线保持最小、更丰富的表面可增量生长v1当前基线RowBackground/AlternatingRowBackground——可选行带两者皆空 无带WPFDataGrid对等AlternatingRowBackground仅在设置时覆盖奇数行。GridLinesVisibility——行/单元格网格线边框。Density——行最小高度 内置单元格/表头内边距预设。TabularSurfaces主题资源——主题感知light/dark/high-contrast默认画刷的来源主题与高对比度变化时重新解析。丰富样式后续以逐元素Style依赖属性交付对齐 WPFDataGrid的RowStyle/CellStyle/ColumnHeaderStyle不是单一的整体TableStyle。RowStyle作用于已实现的TableViewRowCellStyle作用于每单元格容器单元格包装Border单元格内容通过列模板/GenerateElementCore定制ColumnHeaderStyle作用于生成的表头单元格。它们作为一个连贯集合一起落地——单独发布一个会造成不对称的样式表面。选择这种方案的理由是逐元素Style与标准 WinUIStyle/Setter/ControlTemplate机制组合可扩展到任意属性而不引发依赖属性爆炸主题感知由TabularSurfaces资源字典拥有在应用/页面作用域覆盖TabularSurface*键即可按主题重新解析单一可切换的表格外观可用目标为TableView的Style 一组TabularSurface覆盖的ResourceDictionary表达。优先级规则v1 便捷画刷RowBackground/AlternatingRowBackground作为 WPF 迁移捷径保留并增补Style依赖属性——显式设置的便捷画刷优先于对应的RowStylesetter。交付边界v1 内延后 vs 非目标功能规格明确区分了延后但仍属 v1与v1 非目标理解这一边界对规划使用场景很重要延后但仍属 v1增量交付行选择多选/扩展选择、单列排序与过滤、分组与 2 级层次、列宽调整与重排。v1 非目标替换 DataGrid、marquee框选选择、多列排序、列虚拟化、行表头、超过 2 级的层次结构、行拖拽、表格电子表格式交互、100 列的表格式规模TableView每可见列每行实现一个单元格目标约 5–50 列。此外 dev-spec 补充Auto自动收缩v1 宽度单调增长、尾随冻结列、剪贴板、增量加载、多单元格行编辑事务、编辑无障碍播报为 v1 之外/后续工作。相关文档导航功能规格原文TableView-functional-spec.md本文所依据的主文档布局与实现设计TableView-dev-spec.mdAPI 表面与示例docs/api-specs/TableView/TableView-spec.md源码控件实现位于 controls/dev/TableView列宽引擎见 TableView_Layout.cpp默认模板见 TableView.xaml公开 API 定义见 TableView.idl 与 TableViewSource.idl需要说明的是功能规格面向内部工程需求总结其正文标注为 Internalmirror-excluded商业/竞争分析内容未包含本文严格基于规格正文与仓库实现梳理技术事实不涉及外部业务资料。【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xaml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/17 0:06:54 · 阅读 1.2k WinUI 3 TableView 控件功能规格解读：面向 Windows Shell 场景的只读优先轻量级表格控件
WinUI 3 TableView 控件功能规格解读面向 Windows Shell 场景的只读优先轻量级表格控件【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xamlTableView 是 WinUI 3microsoft-ui-xaml 仓库中面向 Windows Shell 现代化改造DUI → WinUI 3而设计的轻量级、生产级表格控件核心目标是实现与任务管理器Task Manager、文件资源管理器File Explorer详情视图相媲美的呈现能力。本文基于仓库内 TableView-functional-spec.md 展开结合配套的 TableView-dev-spec.md、TableView API 规格 以及 TableView 源码目录 中的真实实现完整梳理它的设计目标、功能需求矩阵、交付节奏与底层实现机制帮助读者理解这个控件能做什么、怎么交付、底层如何工作。TableView 是什么轻量级表格而非 DataGrid 替代品从功能规格的 Purpose 章节可以明确控件的定位TableView是一个面向 WinUI 3 的轻量级、生产级表格控件用于现代化 Windows Shell 界面DUI → WinUI 3目标是实现与任务管理器和文件资源管理器详情视图的对等能力。它是一个只读优先的呈现控件——不是完整的DataGrid替代品。这一定位贯穿整个功能设计控件以稳定、高效地呈现大量行数据为第一优先交互能力编辑、选择、排序、分组以可插拔、增量式的方式逐步叠加。与之呼应的工程描述在 TableView-dev-spec.md 中进一步明确TableView是Microsoft.UI.Xaml.Controls.Tabular.dll中最小的、仅用于显示的基础表格控件将ItemsSource渲染为虚拟化行并用Columns为每个已实现的行/列交叉点生成一个单元格。设计目标Goals功能规格列出了四条核心目标它们决定了后续所有需求条目的优先级目标内容数据模型与布局在ObservableCollection支撑的模型上实现行/列布局支持实时、增量更新增/删/改无需整体重渲染行虚拟化与滚动行虚拟化 平滑滚动约 500 行时达到≥30 FPS低输入延迟无障碍UIA Grid/Table/Selection 模式 Narrator 支持键盘操作对等主题支持 Light / Dark / High Contrast 主题其中≥30 FPS 滚动、低延迟、高频更新直接对应任务管理器场景的实时指标刷新需求——这是性能需求条目的来源。四阶段交付路线4-PR stackTableView 的能力不是一次性交付而是通过 4 个 PR 分阶段落地功能规格给出了清晰的交付矩阵PR交付内容PR 1空的Microsoft.UI.Xaml.Controls.Tabular.dll脚手架PR 2本文档对应阶段仅显示基线列/单元格/表头、网格线、密度、行虚拟化、前导冻结列、键盘行焦点导航、只读 UIA peersPR 3选择、单列排序、分组、2 级层次结构、列宽调整/重排、导航状态主题化渲染PR 4测试 TableViewSamples端到端示例应用这种拆分让显示基线可以独立验证后续交互能力选择/排序/分组在稳定基础上增量叠加。仓库现状印证了这一演进controls/dev/TableView目录下已经出现TableView_Selection.cpp、TableView_Sort.cpp、TableView_Grouping.cpp、TableViewGroupHeader.cpp、TableViewSource.cpp等文件说明 PR3 的交互能力已在源码中落地而 TableView-spec.md 中TableViewSortCycle、ITableViewSortComparer、SortByColumn、TableViewGroupInfo、ExpandAllGroups()等 API 已进入 IDL属于仍属 v1、但随后续变更增量交付的范畴。功能需求全景功能规格按主题将需求分类每一条都标注了 MLP/v1 还是延后状态以及由哪个 PR 交付。以下逐类展开。核心控件与数据模型显式列模型无自动生成——PR2。列由开发者通过Columns集合显式声明见 TableView-spec.md 中Columns为内容属性contentproperty(Columns)的声明。ObservableCollection支撑的ItemsSource支持增量增/删/改——PR2 渲染、PR3 塑形排序/分组。默认只读IsReadOnlytrue——PR2。自定义单元格模板TableViewTemplateColumn——PR2。GroupedItemsSource用于分组/带状分段——PR3。仓库中已对应TableViewSource与分组相关源码controls/dev/TableView/TableViewSource.cpp、TableView_Grouping.cpp。列能力Column capabilities宽度 MinWidth/MaxWidthv1 支持像素宽度Auto/*回退到默认宽度——PR2UI 拖拽调整在 PR3。需要说明API 规格文档TableView-spec.md与功能规格在 v1 宽度能力上存在演进差异——API 规格中的Width表注明 v1 只实现显式像素宽度Auto/*回退默认宽度、真正的 Auto/Star 尺寸调整延后而配套的 dev-spec 与当前TableView_Layout.cpp源码已实现四步宽度解析管线见下文列宽解析引擎即 Pixel/Auto/Star 三种模式在仓库当前代码中均已解析落地。列重排拖拽 MoveColumn——PR3。显示/隐藏通过Visibility——PR2。注意无障碍语义UIA 网格/表格提供程序只统计并暴露可见列折叠列不进入 UIA 列模型详见后文无障碍节。吸顶表头Sticky header始终可见——PR2。单列排序SortByColumn/ 表头点击——PR3。网格线通过GridLinesVisibility控制由主题资源驱动——PR2。前导前缀冻结列Leading-prefix frozen尾随冻结列延后——PR2前导尾随延后。多列排序——延后P2 / vNext。行与层次Row hierarchy单选 多选Ctrl/Shift——PR3。每行/单元格上下文菜单复选框选择文件资源管理器特有——PR3 / 表面层。2 级嵌套行v1 硬上限 分组——PR3。2 级层次、行拖拽、marquee框选选择——超出范围。编辑Editing编辑是 TableView 交互能力中最关键的一部分功能规格描述得最为详尽可选单元格编辑在控件上设置IsReadOnly false每列可单独设置IsReadOnly。编辑器由列提供TableViewTextColumn生成TextBoxTableViewTemplateColumn使用CellEditingTemplate。手势双击/双指轻触和F2开始编辑Enter提交Esc取消焦点移出单元格即提交。编程 APIBeginEdit、CommitEdit、CancelEdit、IsEditing、CurrentItem/CurrentColumn/SetCurrentCell。可否决的生命周期事件BeginningEdit、CellEditEnding、RowEditEnding外加EditEnded两个*EditEnding事件的参数暴露GetDeferral()允许处理程序异步校验或保存而不阻塞 UI 线程。回滚数据项实现ITableViewEditableItem时由应用拥有事务否则控件对编辑值做快照取消时恢复。校验数据项实现INotifyDataErrorInfo作用域限定为该列编辑的属性校验失败阻止提交。多单元格行事务CancelEdit(Row)回滚已提交的兄弟单元格——延后。编辑无障碍播报开始/提交/取消时的 live-region/UIA 通知——延后需本地化字符串。仓库当前实现以单元格级编辑为范围TableView-spec.md 的 Appendix 明确说明CommitEdit()/CancelEdit()只关闭打开的单元格编辑没有行级提交/取消 API也没有RowEditEnding行事务与行编辑一起到来。这与功能规格中延后的条目相互印证。编辑状态机与手势策略被刻意拆分为两个文件TableView_Editing.cpp 拥有编辑状态机TableView_EditingInput.cpp 拥有手势策略这样未来的键盘/选择层改变手势路由时无需重开状态机且状态机无需合成输入即可测试。TableViewTextColumn的编辑TextBox会复用列的BindingPath、Converter、ConverterParameter、ConverterLanguage、TargetNullValue、FallbackValue 与源选择器全部继承但强制ModeTwoWayUpdateSourceTriggerExplicit。Explicit是关键它让控件决定值何时落到数据项上——取消可丢弃编辑器而不改源校验失败可保持编辑打开若用PropertyChanged每次按键都会改数据项。虚拟化与性能Virtualization performance行虚拟化只实现可见行 缓存——PR2。实现依赖ItemsRepeater的垂直StackLayoutTableView.xaml中PART_RowsRepeater的VerticalCacheLength2.0。平滑滚动400–500 行 ≥30 FPS支持高频更新任务管理器指标场景低延迟——PR2/PR3。列虚拟化刻意省略因为典型表格只有约 5–50 列。每行渲染每个非空列的一个单元格包装器折叠列渲染隐藏单元格因此 TableView 面向约 5–50 列的典型应用表不面向 100 列的表格式规模。这也被列为 v1 非目标之一。样式与主题Styling themingLight / Dark / High Contrast 主题令牌 内联回退如深色网格线#29FFFFFF——PR2完整自主题 Theme-XBF 发射延后。实际样式资源集中在 TableView_themeresources.xaml而 TableView.xaml 提供默认样式与最后手段的回退画刷并对齐说明TabularSurfaces资源是规范来源见其中TabularSurfaceGridLineBrush等键。单元格级样式通过TableViewTemplateColumn实现自定义单元格 内置文本单元格默认样式左对齐、垂直居中。公开的按列对齐/字重 API——延后PR3。默认模板为两带布局圆角BorderControlCornerRadius卡片边缘 双行Grid行 0Auto表头带、行 1*主体带圆角仅影响渲染、不缩小主体视口因此不影响行虚拟化。行模板TableViewRow的PART_RootBorder提供 40px 最小行高、1px 底部网格线和CommonStates视觉状态Normal/PointerOver/Pressed/Disabled。工具提示Tooltips功能规格对工具提示给出了非常细致的规定这也是其与常见实现差异最大的部分之一单元格工具提示通过TableViewColumn.CellToolTipBinding选择启用绑定针对每行数据项求值其值即工具提示内容。无绑定则无工具提示、也无每单元格成本。之所以必要是因为文本单元格以CharacterEllipsis渲染且不换行超宽值无法阅读——PR3。作者优先级在单元格自身内容模板内设置的工具提示在该内容上方打开控件的工具提示覆盖单元格其余部分控件从不触碰它未附加的工具提示。内容字符串或任何ToolTip可承载的内容。UIElement会被该单元格的ToolTip作为父级因此转换器每次求值需返回新元素。计算内容用IValueConverter编写。无障碍字符串工具提示文本以单元格的AutomationProperties.HelpText发布TableViewCellAutomationPeer在 UIA 查询时若发现其仅重复单元格自身文本则抑制避免值被播报两次。抑制以所有权记录为门控应用设置的文本永不被丢弃。回收被回收的行绝不显示上一项的单元格工具提示。无需失效 API——绑定跟踪行的DataContext被回收的行通过刷新单元格文本的同一继承链重新解析源PropertyChanged会原地更新活动的工具提示。因为控件在实现单元格时从不调用应用代码所以没有重入面、没有 drain 预算、也没有合并机制。列表头工具提示通过TableViewColumn.HeaderToolTip选择启用值即内容覆盖整个表头单元格含内边距与排序指示。表头单元格是重建而非回收因此在表头构建时读取值、变化时原地重应用——无绑定、无失效。字符串内容由TableViewColumnHeaderAutomationPeer作为表头的 UIA 帮助文本上报有排序状态时与之拼接表头 peer 是虚拟的因此元素上的AutomationProperties.HelpText永远到不了客户端——PR4。组表头工具提示——延后至分组启用。值得强调的结论性规定工具提示不以文本截断为门控——没有 WinUI 控件依据IsTextTrimmed开关工具提示已发布的模式是以廉价内容谓词非空字符串或显式选择启用。无障碍Accessibility / UIAGrid/Table peersRow peerSelectionItemGridItemColumnHeader peerInvoke→ 排序——PR2 只读 Grid/TablePR3 选择 排序 invoke。Narrator、键盘导航对等、排序播报——PR2 导航PR3 排序。源码中的实现TableViewAutomationPeer.cpp 等给出四个 peerTableViewAutomationPeerIGridProvider、ITableProvider、ISelectionProvider、IItemContainerProvider、TableViewRowAutomationPeerISelectionItemProvider、TableViewColumnHeaderAutomationPeer、TableViewCellAutomationPeerIGridItemProvider、ITableItemProvider、IValueProvider。API 规格补充了细节Selection/SelectionItem仅在SelectionMode允许选择时公布GetSelection()返回已实现选中行的 provider滚出实现窗口的选中行通过IItemContainerProvider.FindItemByProperty访问。可靠性与服务Reliability servicing确定性行为、单元测试覆盖PR4、SFI/安全合规、采用后的 API 稳定性。源码级佐证布局与虚拟化的底层实现功能规格的需求条目在仓库源码中都能找到对应实现这里给出最有代表性的三处1. 列宽解析引擎TableView_Layout.cpp——注释明确说明列宽策略完全由 TableView 拥有行和表头只是薄管道。每个布局周期运行四步管线将每列写入只读的ActualWidth测量 缓存——TableView::MeasureOverride测量模板子树每个已实现的TableViewCellsPanel表头 行无约束地测量其单元格并按列缓存测量宽度。解析一次——ResolveColumnWidths拉取表头宿主与已实现行中各列的最大测量宽度将Width/MinWidth/MaxWidth与主体视口解析为ActualWidthPixel→ 给定像素Auto→ 拉取的最大值数据集内只增不减*→ 固定列之后视口的比例份额带 min/max 钳制与再分配WPFComputeStarColumnWidths形态。共享——每个表头/行TableViewCellsPanel排列时读取解析后的ActualWidth宽度变化时TableView直接使这些面板失效原子性地重排。排列——ArrangeOverride将单元格按这些宽度从左到右放置前导冻结单元格随后固定到水平滚动偏移。宽度解析是表级单点决策每次布局周期只计算一次单元格与行只测量和缓存从不决定或推送宽度。源码还包含两个已知的 v1 布局限制*列需要有限视口宽度到内容的主机中保持临时默认宽度固定列PixelAuto已超过视口时*列坍缩到MinWidth并横向滚动与 WPF DataGrid 行为一致。2. 单元格面板TableViewCellsPanel.cpp——MeasureOverride将每个单元格测量两次先无约束测量学习 Auto 尺寸所需的测量宽度再以列解析宽度约束测量第二遍。第二遍至关重要若内容宽于列而未被约束DesiredSize大于列宽XAML 排列会把单元格的渲染尺寸扩张到该期望宽度并被剪裁到列槽——这会裁掉单元格右边框垂直网格线。约束测量让省略号内容与边框都留在列内边界网格线得以正确渲染。3. 默认模板TableView.xaml——表头带PART_HeaderRow→PART_HeaderScroller仅水平滚动条隐藏→TableViewCellsPanelPART_HeaderHost主体带PART_BodyScroller→PART_BodyContent→ItemsRepeaterPART_RowsRepeater垂直StackLayout、VerticalCacheLength2.0 空状态PART_EmptyStatePresenter。吸顶表头由 C 控件在PART_BodyScroller.ViewChanged时驱动PART_HeaderScroller的水平偏移实现单向同步仅处理主体的ViewChanged表头永不作为源并跳过 0.5px 的近似相等偏移以避免ViewChanged乒乓。4. 冻结前导列——前导冻结的表头与主体单元格对水平滚动偏移做反向平移counter-translate。仅列 0 开始的连续前导前缀被固定后续的Leading列按非冻结处理。这依赖ElementCompositionPreview.SetIsTranslationEnabled否则UIElement.Translation的 X/Y 变化是空操作非冻结单元格从固定带中裁剪出去使水平滚动内容不会画到冻结单元格下方。5. 行虚拟化与回收——行由ItemsRepeater在垂直轴虚拟化只有实现矩形与主体视口相交的行外加两侧各两个视口的缓存被物化为TableViewRow实例离屏行回到回收池。回收时ItemsRepeater把池中行的DataContext重新指向新项单元格数据通过DataContext继承 绑定响应式更新——单元格不会被命令式重贴在 repeater 测量期间变更活动单元格会重入框架布局并快速失败。因此RebuildCells只用于结构性变化列/模板/密度纯回收只刷新依赖索引的视觉交替行条纹与冻结列固定。dev-spec 特别强调自定义列重写GenerateElementCore必须响应式绑定继承的DataContext不得设置本地DataContext否则回收后会显示陈旧数据——TableView.idl 中GenerateElementCore的注释明确记载了这一要求。排序的所有权与对账Sort ownershipdev-spec 补充了功能规格中单列排序的底层规则它是理解后续排序 API 的关键排序有两条前端且任何时刻只有一条轴生效二者对账而非叠加TableView.SortByColumn以及表头点击声明控件自身的轴并发布TableViewColumn.SortDirection——这是表头箭头chevron绘制的依据。TableViewSource.Sort在源上声明轴。路径重载Sort(sortMemberPath, direction)命名属性控件可将其与列的SortMemberPath匹配并点亮该列的箭头委托重载Sort(keySelector, direction)是不透明的键可能根本不对应任何列计算键、多字段、自定义比较器因此不显示箭头。对账规则通过控件排序清除应用在源上声明的轴在源上声明排序清除控件的轴路径声明的轴匹配到列则点亮该列并带列抛出Sorted否则清除所有SortDirection且Sorted携带空列ClearSort()清除所有轴包括应用声明的。这样避免了早期声明的轴静默压过晚期声明的轴、而箭头却展示失败方的情况——WPF 的拆分方式相同SortDescriptions携带属性名DataGrid据此匹配列并点亮箭头。风格模型分层可增长Styling model样式分层设计显示基线保持最小、更丰富的表面可增量生长v1当前基线RowBackground/AlternatingRowBackground——可选行带两者皆空 无带WPFDataGrid对等AlternatingRowBackground仅在设置时覆盖奇数行。GridLinesVisibility——行/单元格网格线边框。Density——行最小高度 内置单元格/表头内边距预设。TabularSurfaces主题资源——主题感知light/dark/high-contrast默认画刷的来源主题与高对比度变化时重新解析。丰富样式后续以逐元素Style依赖属性交付对齐 WPFDataGrid的RowStyle/CellStyle/ColumnHeaderStyle不是单一的整体TableStyle。RowStyle作用于已实现的TableViewRowCellStyle作用于每单元格容器单元格包装Border单元格内容通过列模板/GenerateElementCore定制ColumnHeaderStyle作用于生成的表头单元格。它们作为一个连贯集合一起落地——单独发布一个会造成不对称的样式表面。选择这种方案的理由是逐元素Style与标准 WinUIStyle/Setter/ControlTemplate机制组合可扩展到任意属性而不引发依赖属性爆炸主题感知由TabularSurfaces资源字典拥有在应用/页面作用域覆盖TabularSurface*键即可按主题重新解析单一可切换的表格外观可用目标为TableView的Style 一组TabularSurface覆盖的ResourceDictionary表达。优先级规则v1 便捷画刷RowBackground/AlternatingRowBackground作为 WPF 迁移捷径保留并增补Style依赖属性——显式设置的便捷画刷优先于对应的RowStylesetter。交付边界v1 内延后 vs 非目标功能规格明确区分了延后但仍属 v1与v1 非目标理解这一边界对规划使用场景很重要延后但仍属 v1增量交付行选择多选/扩展选择、单列排序与过滤、分组与 2 级层次、列宽调整与重排。v1 非目标替换 DataGrid、marquee框选选择、多列排序、列虚拟化、行表头、超过 2 级的层次结构、行拖拽、表格电子表格式交互、100 列的表格式规模TableView每可见列每行实现一个单元格目标约 5–50 列。此外 dev-spec 补充Auto自动收缩v1 宽度单调增长、尾随冻结列、剪贴板、增量加载、多单元格行编辑事务、编辑无障碍播报为 v1 之外/后续工作。相关文档导航功能规格原文TableView-functional-spec.md本文所依据的主文档布局与实现设计TableView-dev-spec.mdAPI 表面与示例docs/api-specs/TableView/TableView-spec.md源码控件实现位于 controls/dev/TableView列宽引擎见 TableView_Layout.cpp默认模板见 TableView.xaml公开 API 定义见 TableView.idl 与 TableViewSource.idl需要说明的是功能规格面向内部工程需求总结其正文标注为 Internalmirror-excluded商业/竞争分析内容未包含本文严格基于规格正文与仓库实现梳理技术事实不涉及外部业务资料。【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xaml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考