@beppla/tapas-ui 1.5.2 → 1.5.6

package/commonjs/NumericInput/README.md

@@ -0,0 +1,95 @@
+# NumericInput
+
+数字输入组件，包含加减按钮和文本输入框，适用于数量选择场景。
+
+## 功能特性
+
+- ✅ 加减按钮控制数值增减
+- ✅ 支持手动键盘输入数字
+- ✅ 可设置最大值和最小值限制
+- ✅ 到达边界时自动禁用对应按钮
+- ✅ 支持整体禁用状态
+- ✅ 加号按钮使用主题色填充背景
+- ✅ 支持 onReduce 和 onAdd 额外回调
+- ✅ 兼容 RN 0.77 Bridgeless 模式（Android 焦点管理修复）
+- ✅ 支持自定义输入框样式
+- ✅ 支持 testID 属性用于测试
+
+## 安装使用
+
+```tsx
+import NumericInput from '@beppla/tapas-ui/components/NumericInput/NumericInput';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| value | `number` | - | 当前数值 |
+| max | `number` | - | 最大值 |
+| min | `number` | - | 最小值 |
+| onChange | `(value: number) => void` | - | 数值变化回调 |
+| onReduce | `() => void` | - | 减少按钮点击回调（在数值变化前触发） |
+| onAdd | `() => void` | - | 增加按钮点击回调（在数值变化前触发） |
+| disabled | `boolean` | - | 是否禁用整个组件 |
+| inputStyle | `StyleProp<ViewStyle>` | - | 输入框自定义样式 |
+| testID | `string` | - | 测试标识 |
+| enableBridgelessFix | `boolean` | `true` | 是否启用 RN 0.77 Bridgeless 模式兼容修复 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<NumericInput
+  value={0}
+  min={0}
+  max={99}
+  onChange={(value) => console.log('数量:', value)}
+/>
+```
+
+### 设置范围
+
+```tsx
+<NumericInput
+  value={5}
+  min={1}
+  max={10}
+  onChange={(value) => setQuantity(value)}
+/>
+```
+
+### 禁用状态
+
+```tsx
+<NumericInput
+  value={3}
+  min={0}
+  max={99}
+  disabled
+  onChange={() => {}}
+/>
+```
+
+### 带额外回调
+
+```tsx
+<NumericInput
+  value={count}
+  min={0}
+  max={99}
+  onChange={(value) => setCount(value)}
+  onAdd={() => console.log('点击了增加')}
+  onReduce={() => console.log('点击了减少')}
+/>
+```
+
+## 注意事项
+
+- `onReduce` 和 `onAdd` 在按钮点击时立即触发，即使数值已到边界也会触发
+- `onChange` 只在数值实际变化时触发（边界处不触发）
+- 手动输入时，超过 `max` 的值会被忽略
+- 失焦时会触发 `onChange` 回调，Android 上有延迟处理以兼容 Bridgeless 模式
+- 组件最小宽度 136px，高度 40px
+- 如果 Android 上遇到焦点问题，可设置 `enableBridgelessFix={false}` 尝试

package/commonjs/Overlay/README.md

@@ -0,0 +1,84 @@
+# Overlay
+
+覆盖层组件，基于 `@rneui/themed` 的 Overlay 封装，用于显示底部弹出的模态内容面板。预设从底部弹出、占屏幕 80% 高度的样式，适合底部 Sheet 和弹出菜单场景。
+
+## 功能特性
+
+- ✅ 继承 @rneui/themed OverlayProps 的全部能力
+- ✅ 预设底部弹出样式（absolute + bottom: 0）
+- ✅ 半透明遮罩背景（backdropStyle）
+- ✅ 支持点击遮罩关闭（onBackdropPress）
+- ✅ 自定义 overlayStyle 和 backdropStyle 覆盖默认样式
+- ✅ 主题色适配
+
+## 安装使用
+
+```tsx
+import { Overlay } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| isVisible | `boolean` | - | 是否显示覆盖层（必填） |
+| onBackdropPress | `() => void` | - | 点击遮罩回调 |
+| overlayStyle | `StyleProp<ViewStyle>` | 底部弹出，宽100%，高80% | 覆盖层样式 |
+| backdropStyle | `StyleProp<ViewStyle>` | 半透明灰色 | 遮罩样式 |
+| children | `React.ReactNode` | - | 覆盖层内容 |
+
+> 继承 `@rneui/themed` OverlayProps 的所有属性
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const [isVisible, setIsVisible] = useState(false);
+
+<Button onPress={() => setIsVisible(true)}>Open Overlay</Button>
+<Overlay
+  isVisible={isVisible}
+  onBackdropPress={() => setIsVisible(false)}
+>
+  <View>
+    <Text>Overlay Content</Text>
+  </View>
+</Overlay>
+```
+
+### 自定义高度
+
+```tsx
+<Overlay
+  isVisible={isVisible}
+  onBackdropPress={() => setIsVisible(false)}
+  overlayStyle={{ height: '50%' }}
+>
+  <Text>Half screen overlay</Text>
+</Overlay>
+```
+
+### 居中弹出
+
+```tsx
+<Overlay
+  isVisible={isVisible}
+  onBackdropPress={() => setIsVisible(false)}
+  overlayStyle={{
+    width: '80%',
+    height: 'auto',
+    position: 'relative',
+    borderRadius: 12,
+  }}
+>
+  <Text>Centered modal content</Text>
+</Overlay>
+```
+
+## 注意事项
+
+- 默认样式为底部弹出面板（`position: absolute, bottom: 0, width: 100%, height: 80%`）
+- 传入 `overlayStyle` 会与默认样式合并（数组形式），后者优先级更高
+- 组件需在 `ThemeProvider` 内使用
+- 遮罩背景色使用主题的 `grey4` 颜色

package/commonjs/Pagination/README.md

@@ -0,0 +1,106 @@
+# Pagination
+
+分页组件，用于大数据列表的分页导航。支持页码选择、每页条数切换、分组翻页和总数展示，适配桌面和移动端。
+
+## 功能特性
+
+- ✅ 页码分组展示（每组 5 页），前后翻组
+- ✅ 当前页高亮（圆形选中样式）
+- ✅ 每页条数下拉选择（Dropdown 集成）
+- ✅ 总数显示（可选隐藏）
+- ✅ 移动端自适应：默认隐藏总数和每页条数选择
+- ✅ 自定义每页条数选项（pageSizeOptions）
+- ✅ 自定义容器样式和背景色
+- ✅ 下拉框位置和宽度可配置
+- ✅ 无障碍支持（accessibilityRole / accessibilityLabel）
+
+## 安装使用
+
+```tsx
+import { Pagination } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| totalCount | `string` | - | 总数显示文本（必填） |
+| pageParams | `TPageParams` | `{ page: 1, pageSize: 10, totalItems: 0, totalPage: 1 }` | 分页参数 |
+| pageSizeOptions | `ItemProps[]` | `[1, 5, 10, 20, 50, 100]/Page` | 每页条数选项 |
+| visibleTotalCount | `boolean` | 桌面端 `true`，移动端 `false` | 是否显示总数 |
+| visiblePageSizeOptions | `boolean` | 桌面端 `true`，移动端 `false` | 是否显示每页条数选择 |
+| onPageChange | `(page: TPageParams) => void` | - | 页码变化回调 |
+| onPageSizeChange | `(item: ItemProps) => void` | - | 每页条数变化回调 |
+| paginationContainerStyle | `StyleProp<ViewStyle>` | - | 容器样式 |
+| pageSizePosition | `TDropdownPosition` | `'auto'` | 下拉框弹出位置 |
+| backgroundColor | `string` | - | 背景色 |
+| pageSizeDropdownWidth | `number` | 自动计算 | 下拉框宽度 |
+
+### TPageParams
+
+```tsx
+type TPageParams = {
+  page: number;       // 当前页码
+  pageSize: number;   // 每页条数
+  totalItems: number; // 总条数
+  totalPage: number;  // 总页数
+}
+```
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<Pagination
+  totalCount="100 items"
+  pageParams={{
+    page: 1,
+    pageSize: 10,
+    totalItems: 100,
+    totalPage: 10,
+  }}
+  onPageChange={(params) => {
+    fetchData(params.page, params.pageSize);
+  }}
+/>
+```
+
+### 自定义每页条数
+
+```tsx
+<Pagination
+  totalCount="500 records"
+  pageParams={pageParams}
+  pageSizeOptions={[
+    { name: '25/Page', value: 25 },
+    { name: '50/Page', value: 50 },
+    { name: '100/Page', value: 100 },
+  ]}
+  onPageChange={handlePageChange}
+  onPageSizeChange={(item) => {
+    setPageSize(item.value);
+  }}
+/>
+```
+
+### 隐藏总数和条数选择
+
+```tsx
+<Pagination
+  totalCount=""
+  pageParams={pageParams}
+  visibleTotalCount={false}
+  visiblePageSizeOptions={false}
+  onPageChange={handlePageChange}
+/>
+```
+
+## 注意事项
+
+- 页码分组为每组 5 页，通过左右箭头翻组
+- `pageParams` 变化会自动同步内部状态
+- 移动端自动隐藏总数和每页条数选择器
+- 下拉框宽度默认根据最长选项文本自动计算（最小 140px，最大 200px）
+- 组件使用 `React.memo` 优化渲染
+- 下拉框基于 Dropdown 组件实现

package/commonjs/PieChart/README.md

@@ -0,0 +1,212 @@
+# PieChart / NestedPieChart
+
+饼图组件，包含基础饼图（PieChart）和嵌套饼图（NestedPieChart）两个组件。支持饼图、环形图（Donut）、多层级嵌套等展示方式。采用**双平台渲染**策略：Web 端使用 recharts，Native 端使用 react-native-svg-charts。
+
+## 功能特性
+
+### PieChart
+- ✅ **双平台渲染**：Web 使用 recharts，Native 使用 react-native-svg-charts
+- ✅ 支持饼图和环形图（通过 innerRadius 控制）
+- ✅ 图例支持 top / bottom / left / right 四个位置
+- ✅ 图例可显示数值，支持 left / right 对齐
+- ✅ 自定义图例间距：行间距（legendItemGap）、Label-Value 间距（legendLabelValueGap）
+- ✅ Label 最小宽度控制（legendLabelMinWidth），确保数值列对齐
+- ✅ 饼图与图例间距可调（legendChartGap，左右位置时生效）
+- ✅ 自定义外圆/内圆半径，支持数字（像素）和字符串（百分比）
+- ✅ 支持扇区标签显示和中心文字
+- ✅ 长图例列表自动滚动（Native 端 ScrollView）
+
+### NestedPieChart
+- ✅ 支持多层级嵌套饼图（仅 Web 平台）
+- ✅ 树形数据结构和扁平数据结构，支持自动推断
+- ✅ 分组图例（grouped legend），可折叠展开
+- ✅ 自动配色策略（渐变色阶，baseColors 映射）
+- ✅ 扇区点击/悬停、图例点击事件
+- ✅ 图例过滤（enableLegendFilter）
+- ✅ 自定义 Tooltip
+- ✅ 格式化函数（数值 / 百分比）
+
+## 安装使用
+
+```tsx
+import { PieChart } from '@beppla/tapas-ui/components/PieChart';
+import { NestedPieChart } from '@beppla/tapas-ui/components/PieChart';
+```
+
+## PieChart Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| data | `PieChartData[]` | (必填) | 饼图数据 |
+| width | `number` | - | 图表宽度 |
+| height | `number` | `300` | 图表高度 |
+| colors | `string[]` | 默认 6 色 | 颜色方案 |
+| outerRadius | `number \| string` | 自动计算 | 外圆半径，支持像素和百分比（如 `'80%'`） |
+| innerRadius | `number \| string` | `0` | 内圆半径，设置后变为环形图 |
+| padAngle | `number` | `0.02` | 扇区间隔角度 |
+| showLabels | `boolean` | `false` | 是否在扇区上显示标签 |
+| showLegend | `boolean` | `true` | 是否显示图例 |
+| legendPosition | `'top' \| 'bottom' \| 'left' \| 'right'` | `'right'` | 图例位置 |
+| showLegendValues | `boolean` | `true` | 图例是否显示数值 |
+| legendValueAlign | `'left' \| 'right'` | `'right'` | 图例数值对齐方式 |
+| legendItemGap | `number` | `8` | 图例行间距（px） |
+| legendLabelValueGap | `number` | `12` | Label 与 Value 间距（px） |
+| legendLabelMinWidth | `number` | - | Label 最小宽度，确保对齐 |
+| legendChartGap | `number` | `30` | 饼图与图例间距（左右位置时生效） |
+| centerText | `string` | - | 中心文字（环形图） |
+| style | `any` | - | 容器样式 |
+| testID | `string` | - | 测试标识 |
+
+### PieChartData
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| value | `number` | 数值（必填） |
+| label | `string` | 标签 |
+| color | `string` | 自定义颜色（优先级高于 colors 数组） |
+| key | `string \| number` | 唯一标识 |
+
+## NestedPieChart Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| data | `NestedPieChartNode[] \| NestedPieChartFlatData[]` | (必填) | 嵌套数据 |
+| dataType | `'tree' \| 'flat'` | 自动推断 | 数据类型 |
+| levels | `number` | 自动计算 | 显示层数 |
+| width | `number` | - | 图表宽度 |
+| height | `number` | - | 图表高度 |
+| outerRadius | `number \| string` | - | 外圆半径 |
+| innerRadius | `number \| string` | - | 最内层半径 |
+| radiusGap | `number` | `10` | 层间间隔 |
+| colorStrategy | `ColorStrategy` | - | 配色策略（baseColors、autoGenerate、colorSteps） |
+| colors | `string[]` | - | 默认配色数组 |
+| showLegend | `boolean` | - | 是否显示图例 |
+| legendMode | `'flat' \| 'grouped'` | - | 图例模式 |
+| legendPosition | `'top' \| 'bottom' \| 'left' \| 'right'` | - | 图例位置 |
+| legendContent | `'all' \| 'parent-only' \| 'children-only'` | - | 图例显示内容 |
+| legendCollapsible | `boolean` | - | 图例是否可折叠 |
+| legendDefaultExpanded | `boolean` | - | 图例默认展开 |
+| legendSortStrategy | `'none' \| 'value-desc' \| 'value-asc' \| 'label-asc' \| 'label-desc'` | - | 图例排序策略 |
+| legendGroupSortStrategy | `LegendSortStrategy` | - | 分组排序策略 |
+| legendShowValues | `boolean` | - | 是否显示数值 |
+| legendShowPercent | `boolean` | - | 是否显示百分比 |
+| legendItemGap | `number` | - | 图例项间距 |
+| legendGroupGap | `number` | - | 分组间距 |
+| legendLabelMinWidth | `number` | - | Label 最小宽度 |
+| legendChartGap | `number` | - | 饼图与图例间距 |
+| showLabels | `boolean` | - | 是否显示扇区标签 |
+| labelLevel | `'all' \| number` | - | 显示标签的层级 |
+| formatValue | `(value: number) => string` | - | 数值格式化 |
+| formatPercent | `(percent: number) => string` | - | 百分比格式化 |
+| onSliceClick | `(event: SliceClickEvent) => void` | - | 扇区点击 |
+| onSliceHover | `(event: SliceClickEvent \| null) => void` | - | 扇区悬停 |
+| onLegendClick | `(event: LegendClickEvent) => void` | - | 图例点击 |
+| enableLegendFilter | `boolean` | - | 点击图例过滤扇区 |
+| showTooltip | `boolean` | - | 是否显示 Tooltip |
+| customTooltip | `(event: SliceClickEvent) => ReactNode` | - | 自定义 Tooltip |
+| padAngle | `number` | - | 扇区间隔角度 |
+| centerText | `string` | - | 中心文字 |
+| centerTextStyle | `React.CSSProperties` | - | 中心文字样式 |
+| emptyText | `string` | - | 空数据文本 |
+| style | `any` | - | 容器样式 |
+| testID | `string` | - | 测试标识 |
+
+## 使用示例
+
+### 基础饼图
+
+```tsx
+<PieChart
+  data={[
+    { value: 40, label: 'Category A', color: '#FF6B00' },
+    { value: 30, label: 'Category B', color: '#0066CC' },
+    { value: 20, label: 'Category C', color: '#00B894' },
+    { value: 10, label: 'Category D', color: '#6C5CE7' },
+  ]}
+  height={300}
+/>
+```
+
+### 环形图（Donut Chart）
+
+```tsx
+<PieChart
+  data={sampleData}
+  innerRadius="50%"
+  centerText="Total"
+/>
+```
+
+### 自定义饼图大小
+
+```tsx
+<PieChart data={sampleData} outerRadius={100} height={300} />
+<PieChart data={sampleData} outerRadius="80%" height={350} />
+```
+
+### 图例配置
+
+```tsx
+<PieChart
+  data={sampleData}
+  legendPosition="right"
+  showLegendValues
+  legendValueAlign="right"
+  legendItemGap={12}
+  legendLabelValueGap={20}
+  legendLabelMinWidth={200}
+  legendChartGap={48}
+/>
+```
+
+### NestedPieChart 嵌套饼图
+
+```tsx
+<NestedPieChart
+  data={[
+    {
+      key: 'food',
+      label: 'Food',
+      children: [
+        { key: 'rice', label: 'Rice', value: 30 },
+        { key: 'noodle', label: 'Noodle', value: 20 },
+      ],
+    },
+    {
+      key: 'drink',
+      label: 'Drink',
+      children: [
+        { key: 'coffee', label: 'Coffee', value: 25 },
+        { key: 'tea', label: 'Tea', value: 15 },
+      ],
+    },
+  ]}
+  showLegend
+  legendMode="grouped"
+  legendCollapsible
+/>
+```
+
+### 自定义配色
+
+```tsx
+<NestedPieChart
+  data={nestedData}
+  colorStrategy={{
+    baseColors: { cash: '#00B894', card: '#FF6B00' },
+    autoGenerate: true,
+  }}
+  height={450}
+/>
+```
+
+## 注意事项
+
+- **PieChart 双平台渲染**：Web 端使用 recharts（功能完整），Native 端使用 react-native-svg-charts（功能受限）
+- **NestedPieChart 仅支持 Web 平台**，Native 端会显示降级提示
+- `innerRadius` 设置为大于 0 的值即变为环形图
+- `outerRadius` 支持数字（像素）和字符串（百分比如 `'80%'`）
+- `legendChartGap` 仅在图例位于 left / right 时生效
+- `legendLabelMinWidth` 可确保不同长度标签的数值列对齐
+- Native 端图例使用 ScrollView 实现长列表滚动
+- 需安装对应平台依赖：Web 需要 `recharts`，Native 需要 `react-native-svg-charts` + `react-native-svg`

package/commonjs/Popover/README.md

@@ -0,0 +1,82 @@
+# Popover
+
+气泡弹出层组件，用于显示与触发元素相对定位的内容面板。支持四个方向（top/bottom/left/right）和三种箭头位置（start/center/end），适合工具提示、操作菜单等场景。
+
+## 功能特性
+
+- ✅ 四个弹出方向：top、bottom、left、right
+- ✅ 三种箭头位置：start、center、end
+- ✅ 自定义宽高尺寸
+- ✅ 带阴影的浮层效果（elevation: 8）
+- ✅ 箭头自动跟随方向和位置调整
+- ✅ 通过 isVisible 控制显隐
+- ✅ 支持自定义容器和内容区样式
+- ✅ 主题色适配（withTheme HOC）
+
+## 安装使用
+
+```tsx
+import { Popover } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| isVisible | `boolean` | - | 是否显示（必填） |
+| children | `React.ReactNode` | - | 弹出层内容 |
+| position | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | 弹出方向 |
+| arrowPosition | `'start' \| 'center' \| 'end'` | `'center'` | 箭头在边上的位置 |
+| width | `number` | `392` | 弹出层宽度 |
+| height | `number` | `696` | 弹出层高度 |
+| containerStyle | `StyleProp<ViewStyle>` | - | 外层容器样式 |
+| contentStyle | `StyleProp<ViewStyle>` | - | 内容区域样式 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const [isVisible, setIsVisible] = useState(false);
+
+<Button onPress={() => setIsVisible(true)}>Show Popover</Button>
+<Popover isVisible={isVisible} position="bottom">
+  <Text>Popover content here</Text>
+</Popover>
+```
+
+### 左侧弹出 + 箭头末端
+
+```tsx
+<Popover
+  isVisible={isVisible}
+  position="left"
+  arrowPosition="end"
+  width={392}
+  height={396}
+>
+  <Text>Left popover with end arrow</Text>
+</Popover>
+```
+
+### 自定义尺寸
+
+```tsx
+<Popover
+  isVisible={isVisible}
+  position="top"
+  arrowPosition="start"
+  width={280}
+  height={200}
+>
+  <Text>Compact popover</Text>
+</Popover>
+```
+
+## 注意事项
+
+- 组件使用 `position: absolute` 定位，需要父容器提供合适的定位上下文
+- `isVisible` 为 `false` 时组件返回 `null`，不占据布局空间
+- 箭头使用 TapasIcon 的 `left_arrow` 图标，通过旋转适配不同方向
+- `arrowPosition` 的 `center` 值根据 `width` 或 `height` 自动计算居中位置
+- 需在 `ThemeProvider` 内使用

package/commonjs/Progress/README.md

@@ -0,0 +1,106 @@
+# Progress
+
+进度条组件，用于显示文件上传或图片处理等任务的进度状态。支持 image 和 file 两种布局类型，可展示进行中（progress）、完成（done）和失败（failed）三种状态。
+
+## 功能特性
+
+- ✅ 两种展示类型：image（图片进度条）和 file（文件进度条）
+- ✅ 三种状态：progress（进行中）、done（完成）、failed（失败）
+- ✅ 状态自动匹配图标和颜色（success / error）
+- ✅ 自定义起始和结束内容区域（支持 ReactNode）
+- ✅ 进度百分比展示
+- ✅ file 类型支持文件名展示
+- ✅ 主题色适配
+- ✅ React.memo 优化渲染性能
+
+## 安装使用
+
+```tsx
+import { Progress } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| type | `'image' \| 'file'` | - | 展示类型（必填） |
+| data | `ProgressData` | - | 进度数据（必填） |
+| testID | `string` | - | 测试标识 |
+
+### ProgressData
+
+```tsx
+interface ProgressData {
+  start: React.ReactNode | string;   // 左侧内容（如缩略图、图标）
+  end?: React.ReactNode | string;    // 右侧内容（状态文本）
+  status: 'progress' | 'done' | 'failed';  // 当前状态
+  progress?: number;                  // 进度值（0-100）
+  file?: string;                      // 文件名（file 类型使用）
+}
+```
+
+## 使用示例
+
+### 图片上传进度
+
+```tsx
+<Progress
+  type="image"
+  data={{
+    start: <Image source={{ uri: thumbnail }} style={{ width: 40, height: 40 }} />,
+    status: 'progress',
+    progress: 65,
+  }}
+/>
+```
+
+### 上传完成
+
+```tsx
+<Progress
+  type="image"
+  data={{
+    start: <Image source={{ uri: thumbnail }} style={{ width: 40, height: 40 }} />,
+    status: 'done',
+    end: 'Uploaded',
+  }}
+/>
+```
+
+### 文件上传
+
+```tsx
+<Progress
+  type="file"
+  data={{
+    start: <TapasIcon name="file" size={20} />,
+    file: 'document.pdf',
+    status: 'progress',
+    progress: 42,
+  }}
+/>
+```
+
+### 上传失败
+
+```tsx
+<Progress
+  type="file"
+  data={{
+    start: <TapasIcon name="file" size={20} />,
+    file: 'report.xlsx',
+    status: 'failed',
+    end: 'Upload failed',
+  }}
+/>
+```
+
+## 注意事项
+
+- `data` 为 null 或 undefined 时组件返回 null
+- `image` 类型为左右布局，进度条位于中间
+- `file` 类型为上下布局，文件名在上方，进度条在下方
+- `end` 属性不存在时，默认显示 `progress%` 文本
+- 进度条宽度通过 CSS `width: ${progress}%` 实现
+- 使用 `withTheme` + `React.memo` 双重优化
+- 需在 `ThemeProvider` 内使用