理解 LyteNyte Grid 的声明式架构：Props 即状态的 React 数据表格设计哲学

LyteNyte Grid 是一款由 1771 Technologies 打造的零依赖 React 数据表格（Data Grid），gzip 后仅约 40 KB，却内置 150+ 企业级功能。它最独特的设计哲学是："view is a function of state"（视图是状态的函数）——表格的一切状态都通过 props 传入，组件本身完全无状态（stateless），因此被称为"Props 即状态"的 prop-driven 架构。本文用 5 分钟带你读懂这套声明式设计。

什么是"Props 即状态"：声明式数据表格的核心

传统表格库常让你"命令式"地操作表格：拿到一个 ref，调用 gridInstance.setRowSelection()、gridInstance.sortBy()……这类 API 强，但状态藏在组件内部，和 React 生态是割裂的。

LyteNyte Grid 反其道而行：你想让表格呈现什么状态，就传什么 props。表格视图永远忠实反映你提供的 props，没有任何隐藏的同步逻辑。

一个最小例子——传什么列，就显示什么列：

const columns: Column[] = [
  { id: "Company", widthFlex: 2 },
  { id: "Country", widthFlex: 2 },
  { id: "Price", type: "number", cellRenderer: PriceCell },
];

function MyGrid() {
  return <Grid columns={columns} />;
}

这套理念带来的直接好处：

• 🎯 零同步烦恼：状态源可以是 URL 参数、服务端返回、全局 store，表格自动呈现对应视图
• 🧩 可组合：状态存哪里、怎么流转完全由你决定，表格只是"渲染器"
• 🤖 对 AI 友好：声明式 + 100% 类型安全，AI 编码助手可以静态验证代码，不需要理解命令式时序

类型定义见 index.ts，所有 props 都有完整的 TypeScript 泛型推导，写错属性名在编译期就会报错。

修改 props 值：状态更新就是"换一次 props"

声明式架构下，"改变表格状态"= "改变传给表格的 props"。

比如想动态切换行高，只需把 rowHeight 存进 React 的 useState，再传下去：

const [height, setHeight] = useState(28);
return <Grid rowHeight={height} />;

官方交互演示（拖动按钮切换行高）在 grid-reactivity-row-height 示例/row-detail-nested_x/src/demo.tsx?utm_source=gitcode_repo_files) 中，完整文档见 grid-reactivity.mdx/grid-reactivity.mdx?utm_source=gitcode_repo_files)。

受控与非受控：管理 Grid 状态的两种方式

有些操作（展开行详情、展开列分组、切换分组列）会由用户交互触发状态变更。LyteNyte Grid 支持两种管理模式，思路和 React 的 input 组件完全一致：

模式	做法	类比
非受控（默认）	只传值、不传 handler，表格内部自行管理	<input />
受控	同时传值和 onChange handler，状态完全由你掌控	<input value onChange />

例如受控的行详情展开，同时提供 rowDetailExpansions 和 onRowDetailExpansionsChange 即可：

<Grid
  rowDetailExpansions={expansions}
  onRowDetailExpansionsChange={setExpansions}
/>

一个值得记住的例外：columns 永远是受控的。你希望表格能改列（拖拽换序、调整宽度），就必须提供 onColumnsChange handler。交互示例见 grid-reactivity-controlled-state 演示/row-detail-nested_x/src/demo.tsx?utm_source=gitcode_repo_files)。

为什么 props 要"记忆化"：性能优化最快的路径

传给表格的 columns、columnBase 等是对象/数组/函数，每次渲染都新建引用会触发不必要的重渲染：

// ❌ 每次渲染都产生新对象，表格会全量重算布局
<Grid columnBase={{ width: 100 }} />

两条最快的优化路径：

1. 手动记忆化：把值定义在组件外，或用 useMemo / useCallback
2. 交给 React Compiler：编译期自动记忆化，你写"坏"代码也能得到好性能（详见 grid-react-compiler.mdx/grid-react-compiler.mdx?utm_source=gitcode_repo_files)）

声明式 + 记忆化的组合，正是 LyteNyte Grid 能渲染百万行、处理每秒 10,000 次更新的底层原因之一。

声明与命令的混合逃生舱：ref 与 API 扩展

纯声明式不意味着放弃命令式能力，只是把它放在次要位置：

• 通过 ref 拿到稳定的 Grid.API 引用，可调用 api.rowSelect()、api.scrollIntoView()、api.exportData() 等方法
• 用 apiExtension prop 给 API 追加自定义方法，且所有渲染回调都能拿到同一个 API 引用

源码里这个"混合点"就一处：root.tsx 中 useExtendedAPI 生成 API 对象后，用 useImperativeHandle 暴露给 ref。扩展细节见 grid-api-extensions.mdx/grid-api-extensions.mdx?utm_source=gitcode_repo_files)。

无头组件（Headless）：声明式组合的极致形态

Grid 还支持把整个 DOM 结构拆成声明式组件——Grid.Viewport、Grid.Header、Grid.RowsCenter、Grid.Cell 等，像搭积木一样自由组装表格，每一块都接受标准 props。这让你能在保持 props 驱动的前提下，给任意部件注入自定义逻辑：

<Grid>
  <Grid.Viewport>
    <Grid.Header />
    <Grid.RowsContainer>
      <Grid.RowsTop />
      <Grid.RowsCenter />
      <Grid.RowsBottom />
    </Grid.RowsContainer>
  </Grid.Viewport>
</Grid>

组件解剖学完整说明在 grid-headless-parts.mdx/grid-headless-parts.mdx?utm_source=gitcode_repo_files)。

这套哲学在源码中如何实现

想快速验证"props 驱动"不是口号，看三个文件即可：

1. index.ts：Grid 组件及其子组件（Grid.Header、Grid.Cell…）的导出结构
2. root.tsx：根组件把每个 prop 注入对应的 React Context Provider，props 变化 → Context 更新 → 视图重算
3. use-piece.ts：内部的 Piece 信号机制，基于 useSyncExternalStore 实现细粒度订阅——只有真正读到的状态变化才会触发对应 UI 更新，这是声明式架构下性能不打折的关键

总结：为什么这个设计哲学值得借鉴

维度	命令式表格	LyteNyte Grid 声明式
状态位置	组件内部黑盒	你的 props，完全透明
同步成本	手动双向同步	零同步，props 即视图
类型安全	运行时发现错误	编译期 100% 校验
AI 协作	时序难验证	静态可验证

一句话概括：把表格当作纯函数，把状态留在你的应用里。这套 "Props 即状态" 的设计让复杂的企业级表格（排序、分组、透视、编辑）依然保持可预测、可测试、可组合——这正是 React 社区最推崇的架构方向。