Refine项目中ThemedSiderV2组件持久化折叠状态的技术实现

背景介绍

在Refine项目的UI组件开发中，ThemedSiderV2作为侧边栏导航组件，其折叠状态的管理对于用户体验至关重要。开发者提出了一个常见的需求：希望能够持久化保存侧边栏的折叠状态，避免用户在刷新页面后需要重新调整布局。

技术方案设计

项目维护团队经过讨论，决定采用一种灵活且非侵入式的解决方案。核心思路是在ThemedLayoutV2组件中新增一个onSiderCollapsed回调函数，该函数会在侧边栏折叠状态改变时被触发。

这个设计具有以下优点：

1. 将状态持久化的控制权完全交给使用者
2. 不强制任何特定的持久化实现方式
3. 保持了组件的高度可配置性

实现细节

技术实现主要分为三个关键部分：

1. 接口扩展：在RefineThemedLayoutV2Props接口中新增onSiderCollapsed属性，类型为(collapsed: boolean) => void的可选函数。

2. 上下文传递：通过ThemedLayoutContextProvider将回调函数传递给子组件，确保整个组件树都能访问到这个功能。

3. 状态管理封装：在上下文提供者中，将原有的setSiderCollapsed状态更新函数封装为一个包装器，在执行状态更新后调用用户提供的回调函数。

多框架适配

由于Refine支持多种UI框架，这一功能需要在以下框架中同步实现：

• Ant Design
• Material UI
• Mantine
• Chakra UI

各框架的实现保持高度一致性，确保了开发者体验的统一性。

使用示例

开发者可以这样使用这个功能来实现本地存储持久化：

const [collapsed, setCollapsed] = useState(
  localStorage.getItem('sider-collapsed') === 'true'
);

<ThemedLayoutV2
  initialSiderCollapsed={collapsed}
  onSiderCollapsed={(collapsed) => {
    localStorage.setItem('sider-collapsed', String(collapsed));
  }}
>
  {/* 子组件 */}
</ThemedLayoutV2>

开发注意事项

在实现过程中，开发者需要注意：

1. 类型定义位于单独的@refinedev/ui-types包中，修改后需要重新构建
2. 各UI框架的实现要保持一致性
3. 回调函数应该是可选的，不影响现有功能

总结

Refine项目通过这种设计，既解决了侧边栏状态持久化的常见需求，又保持了组件的灵活性和可扩展性。这种模式也可以作为其他类似功能实现的参考，展示了如何在框架设计中平衡开箱即用和高度可定制的关系。