@beppla/tapas-ui 1.5.2 → 1.5.7

package/module/Dropdown/README.md

@@ -0,0 +1,230 @@
+# Dropdown / CustomDropdown / InputDropdown
+
+下拉选择组件系列。Dropdown 是主组件，支持普通下拉和 Modal 弹出两种模式；CustomDropdown 是底层下拉容器；InputDropdown 是带搜索输入框的下拉组件。
+
+## 功能特性
+
+- ✅ 两种模式：CustomDropdown 弹出模式和 Modal 弹出模式
+- ✅ 支持搜索过滤选项
+- ✅ 响应式定位，自动检测上下空间选择弹出方向
+- ✅ 移动端自动切换为 BottomSheet 样式
+- ✅ 支持自定义按钮（customButton）
+- ✅ 支持自定义弹出内容（customPopoverContent）
+- ✅ 浮动标签动画（Modal 模式）
+- ✅ 错误状态和状态消息显示
+- ✅ 支持必填标识
+- ✅ InputDropdown 支持输入搜索、清空、只读模式
+- ✅ 支持扩展按钮（extendBtn）
+- ✅ 多种定位方式：left、center、right、upLeft、upRight、upCenter、auto
+
+## 安装使用
+
+```tsx
+import Dropdown from '@beppla/tapas-ui/components/Dropdown/Dropdown';
+import CustomDropdown from '@beppla/tapas-ui/components/Dropdown/CustomDropdown';
+import InputDropdown from '@beppla/tapas-ui/components/Dropdown/InputDropdown';
+```
+
+## Props
+
+### Dropdown Props（核心属性）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| options | `ItemProps[]` | - | 选项列表 |
+| value | `ItemProps` | - | 当前选中值 |
+| onChange | `(value: ItemProps) => void` | - | 选中变化回调 |
+| prefix | `string` | `''` | 显示值前缀 |
+| width | `number` | - | 按钮宽度 |
+| subWidth | `number` | - | 弹出框宽度 |
+| subHeight | `number` | `150` | 弹出框高度 |
+| type | `'button' \| 'option'` | `'option'` | 类型，button 模式不更新选中值 |
+| onClose | `() => void` | - | 关闭回调 |
+| onPress | `() => void` | - | 按钮点击回调 |
+| onItemPress | `(value: string \| number) => void` | - | button 类型下的选项点击回调 |
+| disabled | `boolean` | - | 是否禁用 |
+| showSearchBar | `boolean` | - | 是否显示搜索栏 |
+| placeholder | `string` | - | 搜索栏占位文字 |
+| onSearchChange | `(value: string) => void` | - | 搜索内容变化回调 |
+| testID | `string` | - | 测试标识 |
+
+### Dropdown Modal 模式属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| useModal | `boolean` | `false` | 是否使用 Modal 弹出模式 |
+| dropdownItems | `TapasDropDownItem[]` | `[]` | Modal 模式下的选项列表 |
+| selected | `string` | - | 选中项的 key |
+| showSelectedValue | `boolean` | `false` | 是否显示选中值文字 |
+| dropdownType | `'clear' \| 'solid'` | `'clear'` | 下拉按钮类型 |
+| arrowIcon | `boolean` | `false` | 是否显示箭头图标 |
+| onSelect | `(item: TapasDropDownItem) => void` | - | Modal 模式选择回调 |
+| label | `string` | - | 标签文字 |
+| required | `boolean` | - | 是否必填 |
+| state | `'normal' \| 'error'` | `'normal'` | 状态 |
+| stateMsg | `string` | - | 状态消息 |
+| showStateMsg | `boolean` | `false` | 是否显示状态消息 |
+| showCheckedStatusInList | `boolean` | `false` | 列表中是否高亮选中项 |
+| noLabelAnim | `boolean` | `false` | 是否禁用标签动画 |
+| radius | `number` | `12` | 圆角半径 |
+| backgroundColor | `string` | - | 背景颜色 |
+| labelColor | `string` | - | 标签颜色 |
+| emptyText | `string` | `'No options'` | 空列表提示文字 |
+| extendBtn | `string` | - | 扩展按钮文字 |
+| extendBtnIcon | `string` | - | 扩展按钮图标 |
+| onExtendBtnPress | `() => void` | - | 扩展按钮回调 |
+| customPopoverContent | `React.ReactNode` | - | 自定义弹出内容 |
+| modalVisible | `boolean` | - | 控制 Modal 可见性 |
+| setModalVisible | `(val: boolean) => void` | - | 设置 Modal 可见性回调 |
+| iconStyle | `ViewStyle \| TextStyle` | - | 图标样式 |
+| offsetWidth | `number` | `0` | 偏移宽度 |
+
+### CustomDropdown Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| children | `React.ReactNode` | - | 弹出框内容 |
+| value | `string` | - | 按钮显示文字 |
+| onPress | `() => void` | - | 按钮点击回调 |
+| onClose | `() => void` | - | 关闭回调 |
+| isVisible | `boolean` | - | 是否展开 |
+| width | `number` | `80` | 按钮宽度 |
+| subWidth | `number` | `250` | 弹出框宽度 |
+| subHeight | `number` | `258` | 弹出框高度 |
+| icon | `any` | - | 自定义图标 |
+| subContainerPosition | `TDropdownPosition` | `'left'` | 弹出位置 |
+| subContainerTop | `number` | - | 自定义 top 值（优先级最高） |
+| subContainerLeft | `number` | - | 自定义 left 值（优先级最高） |
+| customButton | `React.ReactNode` | - | 自定义触发按钮 |
+| dropdownButtonStyle | `StyleProp<ViewStyle>` | - | 按钮样式 |
+| dropdownButtonSelectedStyle | `StyleProp<ViewStyle>` | - | 选中时按钮样式 |
+| dropdownButtonHoverStyle | `StyleProp<ViewStyle>` | - | hover 时按钮样式 |
+| sheetTitlePros | `SheetTileProps` | - | 移动端 BottomSheet 标题配置 |
+| dropdownBackgroundColor | `string` | - | 自定义弹出框背景色 |
+
+### InputDropdown Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| label | `string` | - | 输入框标签（必填） |
+| value | `ItemProps` | - | 当前选中值 |
+| options | `ItemProps[]` | - | 选项列表 |
+| onChange | `(value?: ItemProps) => void` | - | 选中变化回调 |
+| onSearch | `(value: string) => void` | - | 搜索回调 |
+| required | `boolean` | - | 是否必填 |
+| readOnly | `boolean` | - | 是否只读 |
+| clearable | `boolean` | - | 是否可清空 |
+| disabled | `boolean` | - | 是否禁用 |
+| defaultShowLabel | `boolean` | - | 默认是否显示标签 |
+| labelBg | `string` | - | 标签背景色 |
+| labelColor | `string` | - | 标签颜色 |
+| allCreate | `boolean` | - | 是否允许自定义输入值 |
+| labelPosition | `'top' \| 'middle'` | - | 标签位置 |
+| children | `React.ReactNode` | - | 自定义下拉内容 |
+
+### TapasDropDownItem 数据类型
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| key | `string \| number` | 选项唯一标识 |
+| value | `string` | 选项显示文字 |
+| secondaryValue | `string` | 次要显示文字（可选） |
+
+## 使用示例
+
+### 基础下拉
+
+```tsx
+const [isVisible, setIsVisible] = useState(false);
+const [value, setValue] = useState(options[0]);
+
+<Dropdown
+  title="Name"
+  options={options}
+  value={value}
+  width={150}
+  subWidth={150}
+  onChange={(val) => { setValue(val); setIsVisible(false); }}
+  isVisible={isVisible}
+  onClose={() => setIsVisible(false)}
+  onPress={() => setIsVisible(!isVisible)}
+/>
+```
+
+### 带搜索的下拉
+
+```tsx
+<Dropdown
+  title="Name"
+  options={options}
+  value={value}
+  showSearchBar={true}
+  subWidth={200}
+  onSearchChange={(val) => console.log(val)}
+  isVisible={isVisible}
+  onClose={() => setIsVisible(false)}
+  onPress={() => setIsVisible(!isVisible)}
+  onChange={(val) => setValue(val)}
+/>
+```
+
+### InputDropdown（可搜索输入下拉）
+
+```tsx
+<InputDropdown
+  label="选择名称"
+  options={options}
+  value={selectedValue}
+  clearable
+  labelBg="#fff"
+  isVisible={isVisible}
+  onClose={() => setIsVisible(false)}
+  onPress={() => setIsVisible(!isVisible)}
+  onChange={(val) => setValue(val)}
+/>
+```
+
+### 自定义按钮
+
+```tsx
+<Dropdown
+  options={options}
+  value={value}
+  customButton={
+    <View style={{ width: 48, height: 40, justifyContent: 'center', alignItems: 'center' }}>
+      <Icon name="more_vert" size={20} />
+    </View>
+  }
+  isVisible={isVisible}
+  onClose={() => setIsVisible(false)}
+  onPress={() => setIsVisible(!isVisible)}
+  onChange={(val) => setValue(val)}
+/>
+```
+
+### Modal 模式
+
+```tsx
+<Dropdown
+  useModal={true}
+  dropdownItems={[
+    { key: '1', value: '选项一' },
+    { key: '2', value: '选项二' },
+  ]}
+  selected="1"
+  showSelectedValue={true}
+  dropdownType="solid"
+  label="选择"
+  onSelect={(item) => console.log(item)}
+/>
+```
+
+## 注意事项
+
+- 普通模式下需要手动管理 `isVisible` 状态
+- Web 端点击外部会自动关闭弹出框（通过 document click 事件）
+- 移动端自动使用 BottomSheet 展示
+- `subContainerTop` 和 `subContainerLeft` 优先级高于 `subContainerPosition`
+- Modal 模式下弹出位置会自动检测屏幕空间，优先向下展示
+- `type="button"` 时点击选项不会更新选中值，仅触发 `onItemPress`
+- InputDropdown 在 `allCreate` 为 false 时，失焦后会恢复为选中值

package/module/ExternalLink/README.md

@@ -0,0 +1,81 @@
+# ExternalLink
+
+外部链接组件，用于打开外部 URL。自动适配 Web（window.open）和移动端（Linking.openURL）平台差异，提供统一的外链交互体验。
+
+## 功能特性
+
+- ✅ 跨平台链接打开：Web 新标签页、移动端外部浏览器
+- ✅ 移动端自动检测 URL 可用性（Linking.canOpenURL）
+- ✅ 支持自定义点击行为（onPress 覆盖默认行为）
+- ✅ 文本子元素自动包装 Text 组件
+- ✅ 自定义链接和文本样式
+- ✅ 默认下划线链接样式
+- ✅ 主题色适配（primary 色）
+
+## 安装使用
+
+```tsx
+import { ExternalLink } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| href | `string` | - | 目标 URL（必填） |
+| children | `React.ReactNode` | - | 链接内容（必填） |
+| style | `any` | - | 外层容器样式 |
+| textStyle | `any` | - | 文本样式 |
+| onPress | `() => void` | - | 自定义点击行为（覆盖默认打开链接） |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<ExternalLink href="https://beppla.com">
+  Visit BEPPLA
+</ExternalLink>
+```
+
+### 自定义样式
+
+```tsx
+<ExternalLink
+  href="https://docs.beppla.com"
+  textStyle={{ color: '#895F38', fontSize: 14 }}
+>
+  Documentation
+</ExternalLink>
+```
+
+### ReactNode 子元素
+
+```tsx
+<ExternalLink href="https://support.beppla.com">
+  <View style={{ flexDirection: 'row', alignItems: 'center' }}>
+    <TapasIcon name="help" size={16} />
+    <Text style={{ marginLeft: 4 }}>Help Center</Text>
+  </View>
+</ExternalLink>
+```
+
+### 自定义点击行为
+
+```tsx
+<ExternalLink
+  href="https://example.com"
+  onPress={() => trackLinkClick('example')}
+>
+  Custom handler
+</ExternalLink>
+```
+
+## 注意事项
+
+- 字符串类型的 children 自动包装为 Text 组件并应用 textStyle
+- 非字符串类型的 children 直接渲染，textStyle 不生效
+- 移动端打开前会检查 `Linking.canOpenURL`，不支持的 URL 会在控制台警告
+- `onPress` 存在时不会打开 href 链接
+- 默认文本样式：主题 primary 色、下划线、fontSize 16
+- 需在 `ThemeProvider` 内使用

package/module/Gantt/README.md

@@ -0,0 +1,155 @@
+# Gantt 甘特图组件
+
+功能强大的甘特图组件，用于可视化展示时间序列数据和项目/任务计划。支持多种时间粒度（年 / 月 / 周 / 天 / 小时 / 半小时），自动滚动到当前时间，并提供灵活的事件卡片渲染。基于 VariableSizeGrid 虚拟滚动引擎构建，可处理大量时间段数据。
+
+## 功能特性
+
+- ✅ 六种时间粒度：YEAR / MONTH / WEEK / DAY / HOUR / HELF（半小时）
+- ✅ 自动计算列数：根据时间范围和粒度自动生成列
+- ✅ 自动滚动到当前时间点
+- ✅ 实时时间指示线
+- ✅ 粘性列头：时间刻度固定在顶部
+- ✅ 日期切换回调（滚动时自动触发 attachSwitchDay）
+- ✅ 自定义任务卡片渲染
+- ✅ 卡片点击事件（attachPressCard）
+- ✅ GanttContext 上下文共享：子组件可访问完整网格信息
+- ✅ 基于虚拟滚动的高性能渲染
+- ✅ 主题色适配
+
+## 安装使用
+
+```tsx
+import { Gantt } from '@beppla/tapas-ui';
+```
+
+## GanttProps
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| width | `number` | - | 容器宽度（必填） |
+| height | `number` | - | 容器高度（必填） |
+| data | `any[]` | - | 任务数据数组（必填），每项包含 startTime/endTime |
+| children | `RenderComponent<any>` | - | 自定义卡片渲染组件（必填） |
+| range | `string[]` | 当天 00:00-23:59 | 时间范围 [startISO, endISO] |
+| unit | `DateUnit` | `DateUnit.HELF` | 时间粒度 |
+| columnWidth | `number` | `165` | 列宽（像素） |
+| rowHeight | `number` | `88` | 行高（像素，实际会 +8 间距） |
+| columnHeaderHeight | `number` | `24` | 列头高度 |
+| columnHeaderBackgroundColor | `string` | - | 列头背景色 |
+| columnHeaderBorder | `{ top?: boolean; left?: boolean; right?: boolean; bottom?: boolean }` | - | 列头边框配置 |
+| attachSwitchDay | `(date?: Date) => void` | - | 滚动切换日期时回调 |
+| attachPressCard | `(info: PressCardProps) => void` | - | 卡片点击回调 |
+| style | `Object` | - | 自定义样式 |
+
+### DateUnit 枚举
+
+```tsx
+enum DateUnit {
+  YEAR = 365 * 24 * 60 * 60 * 1000,
+  MONTH = 31 * 24 * 60 * 60 * 1000,
+  WEEK = 7 * 24 * 60 * 60 * 1000,
+  DAY = 24 * 60 * 60 * 1000,
+  HOUR = 60 * 60 * 1000,
+  HELF = 30 * 60 * 1000,  // 半小时
+}
+```
+
+### PressCardProps
+
+```tsx
+interface PressCardProps {
+  columnIndex?: number;
+  rowIndex?: number;
+  dataIndex: number;
+}
+```
+
+### GanttContextType
+
+通过 `GanttContext` 共享的上下文信息：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| columnCount | `number` | 列总数 |
+| rowCount | `number` | 行总数 |
+| columnWidth | `number` | 列宽 |
+| rowHeight | `number` | 行高 |
+| width / height | `number` | 容器尺寸 |
+| startDate / endDate | `Date` | 时间范围 |
+| rangeVal | `Date[]` | 原始时间范围 |
+| unit | `DateUnit` | 时间粒度 |
+| now | `Date` | 当前时间 |
+| gridDataMap | `GridDataMap` | 网格数据映射 |
+| gridRef / headerRef | `Ref` | Grid 实例引用 |
+
+## 辅助模块
+
+- **Accessories.tsx**：ColumnHeaderCon（列头渲染）、GanttCellRender（单元格渲染）、GanttItemWrapper（单元格包装器）
+- **helper.ts**：calculateRoundedColumnCount、calculateTotalRows、calculateCurrentColumnIndex、scrollToCurrentTime、getDefualtDateTimeRange
+- **GanttInnerElementType.tsx**：自定义 Grid innerElement，包含列头和时间线
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+import { Gantt, DateUnit } from '@beppla/tapas-ui';
+
+const tasks = [
+  { startTime: '2026-04-01T09:00:00', endTime: '2026-04-01T11:30:00' },
+  { startTime: '2026-04-01T13:00:00', endTime: '2026-04-01T15:00:00' },
+];
+
+<Gantt
+  width={800}
+  height={400}
+  data={tasks}
+  unit={DateUnit.HELF}
+  range={['2026-04-01T00:00:00', '2026-04-01T23:59:59']}
+  attachSwitchDay={(date) => console.log('Date:', date)}
+  attachPressCard={(info) => console.log('Card:', info)}
+>
+  {TaskCardComponent}
+</Gantt>
+```
+
+### 天级粒度（多日视图）
+
+```tsx
+<Gantt
+  width={1200}
+  height={500}
+  data={projectTasks}
+  unit={DateUnit.DAY}
+  range={['2026-04-01', '2026-04-30']}
+  columnWidth={80}
+  rowHeight={60}
+>
+  {ProjectTaskCard}
+</Gantt>
+```
+
+### 自定义列头高度和颜色
+
+```tsx
+<Gantt
+  width={800}
+  height={400}
+  data={tasks}
+  columnHeaderHeight={32}
+  columnHeaderBackgroundColor="#F5F0E6"
+>
+  {TaskCard}
+</Gantt>
+```
+
+## 注意事项
+
+- 数据项需包含 `startTime` 和 `endTime` 字段（ISO 字符串）
+- 数据项可携带 `now` 字段覆盖当前时间（服务器时间同步场景）
+- 组件会自动排序任务并计算行分配（避免重叠）
+- 滚动到当前时间使用 `requestAnimationFrame` 延迟执行
+- 日期切换回调使用 RAF 节流，避免频繁触发
+- `range` 默认为当天 00:00:00 到 23:59:59
+- 基于 Web DOM 实现，仅适用于 `Platform.OS === 'web'`
+- 需在 `ThemeProvider` 内使用

package/module/Grid/README.md

@@ -0,0 +1,197 @@
+# Grid 虚拟滚动网格组件
+
+高性能虚拟滚动网格组件，支持固定尺寸和可变尺寸的行列，可处理数千行列的大型数据集。包含三个变体：**StaticFixedSizeGrid**（粘性列 + 列头）、**FixedSizeGrid**（等宽等高）、**VariableSizeGrid**（动态行列尺寸），满足从简单表格到复杂数据面板的各种场景。
+
+## 功能特性
+
+- ✅ 虚拟滚动渲染：仅渲染可视区域内的单元格，支持数千行列
+- ✅ 三种 Grid 变体：StaticFixedSizeGrid / FixedSizeGrid / VariableSizeGrid
+- ✅ 粘性列（Sticky Columns）：指定列固定在右侧，水平滚动时不跟随
+- ✅ 粘性列头（Sticky Headers）：列头固定在顶部，垂直滚动时不跟随
+- ✅ 可变行高和列宽：VariableSizeGrid 支持通过函数动态返回尺寸
+- ✅ 滚动同步：多个 Grid 实例间的滚动联动
+- ✅ 滚动阴影指示器：左右边缘滚动时显示阴影
+- ✅ RTL（右到左）布局支持
+- ✅ Overscan 预渲染：提前渲染可视区外的行列，减少滚动白屏
+- ✅ scrollTo / scrollToItem 命令式滚动 API
+- ✅ 自定义边框和圆角控制
+- ✅ hasActions 支持：特定单元格允许 overflow visible（下拉菜单不被裁切）
+
+## 安装使用
+
+```tsx
+import {
+  StaticFixedSizeGrid,
+  FixedSizeGrid,
+  VariableSizeGrid,
+} from '@beppla/tapas-ui';
+```
+
+## StaticFixedSizeGrid Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| columnCount | `number` | - | 总列数（必填） |
+| columnWidth | `(index: number) => number` | - | 列宽函数（必填） |
+| rowCount | `number` | - | 总行数（必填） |
+| rowHeight | `(index: number) => number` | - | 行高函数（必填） |
+| width | `number` | - | 容器宽度（必填） |
+| height | `number` | - | 容器高度（必填） |
+| children | `(props: ChildrenProps) => ReactNode` | - | 单元格渲染函数（必填） |
+| headersRender | `(props: ChildrenProps) => JSX.Element` | - | 列头渲染函数 |
+| columnHeaderHeight | `number` | `40` | 列头高度 |
+| columnHeaderBackgroundColor | `string` | 主题 grey4 | 列头背景色 |
+| stickyColumnIndices | `number[]` | - | 粘性列索引数组 |
+| border | `boolean` | `false` | 是否显示边框 |
+| onScroll | `(event) => void` | - | 滚动回调 |
+| hideBorder | `string[]` | - | 隐藏指定方向边框（top/bottom/left/right） |
+| hideborderRadius | `string[]` | - | 隐藏指定角的圆角（topLeft/topRight） |
+| hasActions | `(columnIndex, rowIndex) => boolean` | - | 判断单元格是否有下拉操作菜单 |
+| gridRef | `React.MutableRefObject<any>` | - | Grid 实例引用 |
+| style | `Object` | - | 自定义容器样式 |
+
+### ChildrenProps
+
+```tsx
+interface ChildrenProps {
+  columnIndex: number;
+  rowIndex: number;
+  style: CSSProperties;
+}
+```
+
+## FixedSizeGrid Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| columnCount | `number` | - | 总列数（必填） |
+| columnWidth | `number` | - | 固定列宽（必填） |
+| rowCount | `number` | - | 总行数（必填） |
+| rowHeight | `number` | - | 固定行高（必填） |
+| width | `number` | - | 容器宽度（必填） |
+| height | `number` | - | 容器高度（必填） |
+| children | `RenderComponent<T>` | - | 单元格渲染组件（必填） |
+| itemData | `T` | - | 传递给子组件的数据 |
+| direction | `'ltr' \| 'rtl'` | `'ltr'` | 文本方向 |
+| overscanColumnCount | `number` | `1` | 列预渲染数量 |
+| overscanRowCount | `number` | `1` | 行预渲染数量 |
+| onScroll | `OnScrollCallback` | - | 滚动回调 |
+| onItemsRendered | `OnItemsRenderedCallback` | - | 可见区域变化回调 |
+
+## VariableSizeGrid Props
+
+与 FixedSizeGrid 相同，但 `columnWidth` 和 `rowHeight` 为函数类型：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| columnWidth | `(index: number) => number` | 根据索引返回列宽 |
+| rowHeight | `(index: number) => number` | 根据索引返回行高 |
+
+## 使用示例
+
+### StaticFixedSizeGrid（粘性列 + 列头）
+
+```tsx
+const columnWidths = [100, 150, 200, 120, 80];
+
+const Cell = ({ columnIndex, rowIndex, style }: ChildrenProps) => (
+  <div style={style}>
+    Item {rowIndex},{columnIndex}
+  </div>
+);
+
+const ColumnHeaders = ({ columnIndex, style }: ChildrenProps) => (
+  <div style={style}>Header {columnIndex}</div>
+);
+
+<StaticFixedSizeGrid
+  columnCount={5}
+  columnWidth={(index) => columnWidths[index]}
+  rowCount={1000}
+  rowHeight={() => 56}
+  width={650}
+  height={400}
+  border={true}
+  headersRender={ColumnHeaders}
+  stickyColumnIndices={[4]}
+>
+  {Cell}
+</StaticFixedSizeGrid>
+```
+
+### FixedSizeGrid（等宽等高）
+
+```tsx
+<FixedSizeGrid
+  columnCount={1000}
+  columnWidth={75}
+  rowCount={1000}
+  rowHeight={40}
+  width={300}
+  height={300}
+>
+  {Cell}
+</FixedSizeGrid>
+```
+
+### VariableSizeGrid（动态尺寸）
+
+```tsx
+<VariableSizeGrid
+  columnCount={1000}
+  columnWidth={(index) => 75 + Math.round(Math.random() * 50)}
+  rowCount={1000}
+  rowHeight={(index) => (index % 2 === 0 ? 40 : 56)}
+  width={300}
+  height={300}
+>
+  {Cell}
+</VariableSizeGrid>
+```
+
+### 多 Grid 滚动联动
+
+```tsx
+const gridRef = useRef(null);
+
+<StaticFixedSizeGrid
+  columnCount={20}
+  columnWidth={(i) => widths[i]}
+  rowCount={100}
+  rowHeight={() => 56}
+  width={650}
+  height={400}
+  onScroll={(event) => {
+    gridRef.current?.scrollTo({
+      ...event,
+      scrollTop: gridRef.current.state.scrollTop,
+    });
+  }}
+  headersRender={Headers}
+>
+  {Cell}
+</StaticFixedSizeGrid>
+
+<StaticFixedSizeGrid
+  gridRef={gridRef}
+  columnCount={20}
+  columnWidth={(i) => widths[i]}
+  rowCount={50}
+  rowHeight={() => 56}
+  width={650}
+  height={300}
+>
+  {Cell}
+</StaticFixedSizeGrid>
+```
+
+## 注意事项
+
+- StaticFixedSizeGrid 内部基于 VariableSizeGrid + StickyListContext 实现
+- 粘性列通过独立的 VariableSizeGrid 实例渲染，使用 `position: sticky` 固定
+- 滚动同步使用 RAF（requestAnimationFrame）节流优化性能
+- `hasActions` 为 true 的单元格设置 `overflow: visible` 允许下拉菜单溢出
+- 列头同步滚动通过 `headerRef.scrollTo()` 实现
+- FixedSizeGrid 的 `columnWidth` 和 `rowHeight` 必须是 number 类型
+- VariableSizeGrid 的 `columnWidth` 和 `rowHeight` 必须是函数类型
+- 组件基于 Web DOM（div），仅适用于 `Platform.OS === 'web'`