MUI X v9 树视图与日期选择器深度解读：默认虚拟化、键盘优先日历与 v8 迁移要点

本文基于当前仓库 docs/pages/blog/introducing-mui-x-tree-view-and-pickers-v9.md（MUI X v9 官方发布博客，发布于 2026-04-08）撰写，系统拆解 v9 中 Date and Time Pickers 与 Tree View 两条组件线的核心变化：Rich Tree View Pro 的默认虚拟化、日期时间选择器的键盘优先与焦点管理改进、新增 locale/adapter，以及伴随破坏性变更出现的迁移与 codemod 生态。读完本文，你将清楚 v9 升级时哪些 API 被移除或替换、哪些行为默认值发生变化，以及如何在升级前用最小成本完成自查与改造。

文档定位与背景：一篇"组件级 v9 发布说明"

该文档位于本仓库的官方博客区，同时存在两个配套文件：

• Markdown 正文：docs/pages/blog/introducing-mui-x-tree-view-and-pickers-v9.md
• Next.js 页面包装：由 docs/pages/blog/introducing-mui-x-tree-view-and-pickers-v9.js 通过 ?muiMarkdown 加载同一份 Markdown 渲染成博客页。

从文件 frontmatter（第 1~9 行）可以看出它的发布属性：date: 2026-04-08，作者为 josefreitas，标签为 MUI X 与 Product。它是 MUI X v9 大版本发布系列文章中的一员，与 Introducing Material UI and MUI X v9、MUI X Data Grid v9.0、MUI X Charts v9.0 等共同构成完整的 v9 发布矩阵。

需要先说明的是：本仓库承载的是 Material UI / MUI 的文档与发布说明，Tree View、Date and Time Pickers 等 X 组件的实现源码与完整 API 文档位于 MUI X 自己的仓库（博客原文也分别把 [Date and Time Pickers 文档] 与 [Tree View 文档] 称作"API 变更的权威来源"）。因此本文以发布说明为准绳提炼可操作结论，遇到需要核对 API 细节的场景会明确指向迁移指南，避免越界推断。

为什么这篇发布说明值得细读

文档在第 11~15 行点明了 v9 的两条主线，这也是升级时最需要感知的行为层面变化：

1. 大而可预测的树：面向"海量节点、又大又快、行为可预期"的大树场景；
2. 对外部世界友好的选择器：键盘、表单、邻近控件、locale 与日期适配器（adapter）覆盖面都要与生态里其他组件保持一致。

而这一次大版本又是 MUI 全产品线的"版本对齐"动作的一部分。参考同仓库的 Introducing Material UI and MUI X v9 可以看到完整背景：MUI X 曾在 v6（2023 年）把主版本号从 Material UI 解耦，但多年实践下来独立的版本号反而加重了 peer dependency 与升级沟通成本；因此在 v9 中两者重新对齐——Material UI 直接从 v7 跳到 v9（没有 v8，正如没有 v2），与 MUI X v9 共享同一个主版本号。理解这个大背景有助于你在升级树视图与选择器时，把它放进"整个技术栈同时升主版本"的窗口里统筹规划。

Date and Time Pickers v9：把键盘体验当作一等公民

原文档将其概括为 keyboard-first calendar（键盘优先的日历）。这一方向的本质是：在日/月/年三个视图间移动、选值，不应把"必须用指针点击"当作前置条件。v9 延续了这条工作线，把它打磨成可依赖的默认行为。

fieldRef 稳定化与 clearValue

长表单、筛选区以及任何需要"可靠地把该字段重置掉"的地方，都会依赖编程式清空字段。v9 明确 fieldRef 会稳定下来并提供 clearValue。这意味着你可以把"重置此字段"当作一个稳定的命令式契约来使用，而不用再担心不同版本间 API 形状漂移。

关闭弹出层时的焦点回收

文档提到 v9 平滑了"收起 popover 时的焦点行为"（focus when dismissing the popover）。在真实场景里，点击外部关闭（click-away）若处理不当，焦点会被"搁浅"在错误的控件上——尤其是在对话框、抽屉（drawer）以及内嵌在 Data Grid 里的筛选器附近最容易出现。v9 的目标是让焦点回到符合用户预期的下一个控件，而不是游离在原控件与 popover 之间。

更多 locale 与日期适配器

文档给出两个具体新增，均以"与 Data Grid 保持同步、覆盖非公历场景"为特征：

• thTH（泰语）locale：与 Data Grid 的 locale 列表同步新增；
• AdapterDayjsBuddhist（佛历适配器）：面向非公历（佛历）纪年场景。

由此引出一个明确的升级自查项：如果你在用范围选择器（range pickers）且数据跨时区/跨纪年体系，升级后要重新校验边界场景。文档原文是"if you use range pickers across zones, re-validate edge cases after upgrading"，说明新增 locale/adapter 虽然覆盖面扩大，但边界行为仍需各业务自行回归。

两项破坏性清理：从"双轨"走向"单轨"

v9 移除了两个过渡期产物：

变更	含义	对升级的影响
移除 enableAccessibleFieldDOMStructure	可访问字段 DOM（accessible field DOM）从"可选项"变为唯一受支持模式	需要将旧结构迁移到新结构，官方提供 codemod 支持
移除 PickersDay，PickersDay2 晋升为默认日组件 API	日单元组件 API 收敛到单一形态	自定义过日渲染（如高亮某几天）的代码需改用 PickersDay2

这两条在原文中分别对应 mui-x 的 PR #21966 与 #21739。它们体现的工程取向值得注意：v9 不再维护新旧两套 DOM 结构或新旧两套日组件并存的兼容层，凡是上一个大版本留的过渡双轨，在这一版统一收口。

Tree View v9：Rich Tree View Pro 默认开启虚拟化

树视图部分是本文档技术含量最高的一段（原文档第 38~47 行）。核心信息必须拆成四层来理解。

1. 虚拟化成为默认，而非可选项

v9 的 Rich Tree View Pro 将虚拟化（virtualization）默认开启，同时提供**显式退出（opt-out）**入口，以便需要非虚拟化布局（例如节点高度不规律、需要整体测量）的场景能够关闭。这是数据量级上的判断：对于大节点树，虚拟化只渲染可视窗口内的行，保证滚动流畅；对小型树，默认开启的额外复杂度也可以随时退避。

2. 行高默认值收紧：固定行高 + itemHeight

虚拟化要高效工作，通常依赖"可预估的行位置"，因此 v9 的行高默认固定；当你的内容高度不一致时，通过设置 itemHeight 告诉渲染器每行的实际高度。这既是性能前提，也是自定义富内容（多行文本、图文混合节点）时需要记住的新配置点。

3. 事件形状从"嵌套树"改为"扁平列表"

v9 把 Rich Tree View Pro 的事件（events）从嵌套树结构改为扁平列表。文档明确这是"为了支撑虚拟化"的必要改动：虚拟化的行是动态挂载/卸载的，扁平事件流比嵌套树事件更容易按行关联与批量处理。任何基于旧事件回调写展开/收起、选中联动逻辑的代码，升级时都要改成消费扁平事件。

4. API 与样式卫生：hooks、模型形状、样式 token 三处收紧

• ref/model hooks 换新：旧版 model 与 ref 相关 hooks 被更丰富的变体取代，v9 文档点名的是 useRichTreeViewApiRef、useSimpleTreeViewApiRef、useRichTreeViewProApiRef——分别对应 Rich Tree View、Simple Tree View、Rich Tree View Pro 三个产品面。
• TreeViewBaseItem 被移除：取而代之的是"有文档的模型形状"（documented model shapes）。也就是说，给树传入的数据结构不再依赖一个隐式的 Base Item 类型，而是使用官方文档明确记录的数据模型，类型契约更透明。
• treeItemClasses 状态 token 去除：原来用 class 编码"展开/选中"这类状态的 token 被拿掉，改为暴露 data-* 属性，让你直接在 CSS 里用属性选择器定位展开态/选中态。

对"维护自定义主题或对树写命令式代码"的团队，文档在第 45 行给了明确的预算建议：升级时留出时间重新审视三件事——refs 的用法、对虚拟化的假设、以及依赖旧 class 的选择器。

补充：原文档的 Tree View 标题带 Pro plan 标识，即这些改动主要落在商业授权的 Rich Tree View Pro 之上；升级前请结合你的许可证范围核对哪些能力对你生效。

迁移指南与 codemod 生态：升级不是"改版本号"而是"跑迁移"

原文档第 49~54 行给出两个官方迁移指南入口，分别覆盖 v8→v9 的完整破坏性变更清单与 codemod 步骤：

• Date and Time Pickers：v8 → v9 迁移指南
• Tree View：v8 → v9 迁移指南

文档还反复强调"Date and Time Pickers 文档（含迁移说明）是 API 变化的权威来源"，"Tree View 文档收录完整 API 说明"——也就是说，具体属性级差异请以迁移指南与组件文档为准，本发布说明负责勾勒升级地图与意图。

值得注意的是，X 组件 v9 的 codemod 本体随 MUI X 发布，并不在本仓库内；但本仓库的 mui-codemod 包保留着同一套迁移工程思路的历史样本，可以帮我们理解"跨包迁移"到底做了什么。以 v5.0.0 阶段 Tree View 与 Date Pickers 从 @mui/lab 移入 MUI X 的 codemod 为例：

• packages/mui-codemod/src/v5.0.0/tree-view-moved-to-x.js：把 @mui/lab/TreeView、@mui/lab/TreeItem 等导入改写为 @mui/x-tree-view/...。从源码第 1~27 行可以看到，它维护着一张"导出名 → 目标入口"的映射表（TreeView、treeViewClasses、useTreeItem、treeItemClasses 等都被纳入）；第 52~112 行的转换逻辑同时处理两类导入：子路径导入（@mui/lab/TreeView）直接替换源路径，并把默认导入转成命名导入；根导入（import { TreeView } from '@mui/lab'）则把 TreeView 相关 specifier 筛进新增的 @mui/x-tree-view 导入声明、其余留在 @mui/lab。
• packages/mui-codemod/src/v5.0.0/date-pickers-moved-to-x.js：采用同样的"导出名查表"模式，覆盖 AdapterDateFns、AdapterDayjs、AdapterLuxon、AdapterMoment 以及 CalendarPicker、ClockPicker 等历史导出；其配套测试 packages/mui-codemod/src/v5.0.0/date-pickers-moved-to-x.test.js 与 tree-view-moved-to-x 的测试夹具（actual/expected 成对文件）保证了改写结果的可验证性。

这个历史样本说明了一条 MUI 迁移工程的通用规律：跨包/跨大版本的组件移动从不鼓励手工改 import，而是通过 jscodeshift 风格的 codemod 做确定性改写，再配合"before/after"夹具做回归校验。v8→v9 的树视图与选择器迁移（尤其是 enableAccessibleFieldDOMStructure 的移除、TreeViewBaseItem 的删除）大概率也会遵循同一套路：先跑 codemod 收敛机械性改动，再手动处理样式与行为层。

一套可直接落地的 v8 → v9 升级自查清单

综合本发布说明，把升级动作整理成以下顺序化清单，方便排进迭代：

1. 先读权威文档再动手：核对 Date and Time Pickers 与 Tree View 的 v8→v9 迁移指南中与本业务相关的条目（涉及移除项务必逐条对照）。
2. 跑 codemod 处理机械变更：包括可访问字段 DOM 结构的收口（enableAccessibleFieldDOMStructure 移除有 codemod 支持）与组件/类型导入的改写；有疑问时参考本仓库 packages/mui-codemod/src/v5.0.0/tree-view-moved-to-x.js 展示的"导出名查表 + 导入改写"模式来理解 codemod 的边界。
3. 替换已移除的组件 API：把自定义日渲染从 PickersDay 迁到 PickersDay2，放弃 TreeViewBaseItem，改用有文档的数据模型形状。
4. 核对树视图的 ref 与命令式代码：确认 API ref 已切到 useRichTreeViewApiRef / useSimpleTreeViewApiRef / useRichTreeViewProApiRef 对应的变体，并重新过一遍所有 apiRef 调用。
5. 重写树样式选择器：把依赖 treeItemClasses 中展开/选中状态 token 的样式，改为基于 data-* 属性的 CSS 选择器，并实测暗色主题/自定义主题下的表现。
6. 审视虚拟化假设：Rich Tree View Pro 默认虚拟化后，确认业务没有依赖"整树都挂在 DOM 上"的假设；内容高度不一致的节点设置 itemHeight，确实需要非虚拟化布局时再显式退出。
7. 改造树事件消费逻辑：把基于嵌套树形状的事件处理改为扁平列表语义。
8. 回归选择器周边行为：重点验证长表单里 fieldRef.clearValue() 的重置可靠性和稳定性；在对话框、抽屉、内嵌表格筛选等场景下验证点击外部关闭后焦点是否落在预期控件。
9. 同步 locale 与 adapter 验证：需要使用泰语时接入 thTH，需要佛历纪年时引入 AdapterDayjsBuddhist；跨时区/跨纪年的 range pickers 补跑边界用例。

仓库内的延伸阅读路径

围绕本文档，仓库内可直接跳转的关联材料如下（均为本仓库已确认存在的文件）：

• 本篇的姊妹篇总览：Introducing Material UI and MUI X v9（版本对齐、v9 生态全景）；Introducing Material UI v9（设计系统侧变化）。
• 同期发布的其他 X 组件：MUI X Data Grid v9.0、MUI X Charts v9.0、MUI X Scheduler v9 alpha、MUI X Chat v9 alpha。
• 树视图与选择器进入 MUI X 的历史沿革：lab-tree-view-to-mui-x、lab-date-pickers-to-mui-x（v5 的 lab → X 迁移），以及 date-pickers-stable-v5（选择器稳定版说明）。
• codemod 迁移工程样本：packages/mui-codemod/src/v5.0.0/tree-view-moved-to-x.js 与 packages/mui-codemod/src/v5.0.0/date-pickers-moved-to-x.js。

结语

MUI X v9 的这份发布说明虽然篇幅精炼，信息密度却很高：选择器一侧围绕"键盘优先、焦点可靠、locale 全对齐"持续收口双轨 API；树视图一侧则以 Rich Tree View Pro 默认虚拟化为锚点，连带把行高模型、事件形状、ref hooks、样式 token 全部重排了一遍。对升级者而言，最重要的不是记住每个新 API，而是抓住三条主线——默认值变了（虚拟化、固定行高）、事件形态变了（嵌套 → 扁平）、旧的双轨 API 被单轨取代（可访问字段 DOM、PickersDay → PickersDay2、TreeViewBaseItem 移除），再配合官方 v8→v9 迁移指南逐条核对。把这些意图层的变化理解透，迁移清单里的每一项就都有了"为什么"的依据。