@beppla/tapas-ui 1.5.2 → 1.5.7

package/module/Navigation/README.md

@@ -0,0 +1,197 @@
+# Navigation
+
+侧边导航栏组件，提供可展开/折叠的垂直导航菜单。支持导航项（navItems）和系统项（systemItems）两层分组，收起时仅显示图标，展开时显示图标和文本。
+
+## 功能特性
+
+- 可展开/折叠的侧边导航（收起 56px，展开 336px）
+- 导航项和系统项两层分组（系统项固定在底部）
+- 点击 Logo 切换展开/折叠状态
+- 选中项高亮显示（展开时背景高亮，收起时图标高亮）
+- 移动端支持背景遮罩层（点击遮罩关闭导航）
+- 可配置权限信息（`permissions` 字段）
+- 支持 `selectedIndex` 受控选中
+- 可选集成 React Navigation 自动路由导航
+- 自定义 Logo 图片
+
+## 安装使用
+
+```tsx
+import { Navigation, NavItem, NavItemType, SelectedItem } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| navItems | `NavItem[]` | - | 导航项数组 |
+| systemItems | `NavItem[]` | - | 系统项数组（显示在底部） |
+| logoImg | `ImageSourcePropType` | - | Logo 图片资源 |
+| expanded | `boolean` | `false` | 是否展开导航菜单 |
+| onItemPress | `(item: NavItem) => void` | - | 导航项点击回调 |
+| onLogoPress | `() => void` | - | Logo 点击回调 |
+| defaultSelectedItem | `SelectedItem` | - | 默认选中项 |
+| selectedIndex | `number` | - | 选中项索引（受控模式，仅匹配 navItems） |
+| visible | `boolean` | `true` | 导航栏是否可见 |
+| onMaskPress | `() => void` | - | 背景遮罩点击回调（移动端） |
+| navigation | `{ navigate: (routeName: string, params?: any) => void }` | - | React Navigation 对象（可选） |
+
+## 类型定义
+
+### NavItem
+
+```tsx
+interface NavItem {
+  name: string;              // 项目名称（展开时显示）
+  iconName: string;          // TapasIcon 图标名称
+  url?: string;              // 链接 URL（可选）
+  permissions?: Permissions[]; // 权限要求（可选）
+}
+```
+
+### Permissions
+
+```tsx
+interface Permissions {
+  resource: string;  // 资源名
+  action: string;    // 操作名
+}
+```
+
+### NavItemType / SelectedItem
+
+```tsx
+enum NavItemType {
+  Nav = 'nav',       // 导航项
+  System = 'system', // 系统项
+}
+
+interface SelectedItem {
+  type: NavItemType;         // 项目类型
+  selectedItemIndex: number; // 项目索引
+}
+```
+
+## 使用示例
+
+### 基础导航
+
+```tsx
+import { Navigation, NavItem, NavItemType } from '@beppla/tapas-ui';
+
+const navItems: NavItem[] = [
+  { name: 'Dashboard', iconName: 'home' },
+  { name: 'Analytics', iconName: 'vector' },
+  { name: 'Products', iconName: 'product_items' },
+  { name: 'Messages', iconName: 'chat' },
+];
+
+const systemItems: NavItem[] = [
+  { name: 'Settings', iconName: 'settings' },
+  { name: 'Refresh', iconName: 'refresh' },
+];
+
+export default function App() {
+  return (
+    <Navigation
+      navItems={navItems}
+      systemItems={systemItems}
+      logoImg={require('./logo.png')}
+      defaultSelectedItem={{
+        type: NavItemType.Nav,
+        selectedItemIndex: 0,
+      }}
+    />
+  );
+}
+```
+
+### 带点击回调
+
+```tsx
+<Navigation
+  navItems={navItems}
+  systemItems={systemItems}
+  logoImg={require('./logo.png')}
+  onItemPress={(item) => {
+    console.log('Selected:', item.name);
+    setCurrentPage(item.name);
+  }}
+/>
+```
+
+### 受控选中索引
+
+```tsx
+const [selectedIdx, setSelectedIdx] = useState(0);
+
+<Navigation
+  navItems={navItems}
+  systemItems={systemItems}
+  logoImg={require('./logo.png')}
+  selectedIndex={selectedIdx}
+  onItemPress={(item) => {
+    const idx = navItems.findIndex(n => n.name === item.name);
+    if (idx >= 0) setSelectedIdx(idx);
+  }}
+/>
+```
+
+### 与 React Navigation 集成
+
+```tsx
+import { useNavigation } from '@react-navigation/native';
+
+const navigation = useNavigation();
+
+<Navigation
+  navItems={[
+    { name: 'Home', iconName: 'home' },
+    { name: 'Details', iconName: 'info' },
+  ]}
+  logoImg={require('./logo.png')}
+  navigation={navigation}
+/>
+```
+
+### 完整布局示例
+
+```tsx
+import { View, Text } from 'react-native';
+import { Navigation, NavItem } from '@beppla/tapas-ui';
+import { useState } from 'react';
+
+const navItems: NavItem[] = [
+  { name: 'Dashboard', iconName: 'home' },
+  { name: 'Products', iconName: 'product_items' },
+  { name: 'Orders', iconName: 'manufacturing' },
+];
+
+export default function App() {
+  const [page, setPage] = useState('Dashboard');
+
+  return (
+    <View style={{ flexDirection: 'row', height: '100%' }}>
+      <Navigation
+        navItems={navItems}
+        logoImg={require('./logo.png')}
+        onItemPress={(item) => setPage(item.name)}
+      />
+      <View style={{ flex: 1, padding: 16 }}>
+        <Text>{page} Content</Text>
+      </View>
+    </View>
+  );
+}
+```
+
+## 注意事项
+
+- 导航栏默认收起状态（宽度 56px），点击 Logo 切换展开（336px）/折叠
+- 桌面端点击 Logo 触发 `onLogoPress` 并切换展开状态；移动端点击 Logo 触发 `onMaskPress`
+- 展开时会在导航栏外显示半透明遮罩层（`rgba(0,0,0,0.5)`），点击遮罩可关闭
+- `selectedIndex` 仅匹配 `navItems` 数组，不支持直接选中 `systemItems`
+- 设置 `navigation` 属性后，点击导航项会自动调用 `navigation.navigate(item.name)`
+- 导航项图标大小固定 20px，颜色为主题 `white`
+- 选中状态：展开时背景高亮（`secondary` 色），收起时图标容器高亮
+- `visible=false` 时整个导航栏不渲染

package/module/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/module/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/module/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/module/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`