@beppla/tapas-ui 1.5.10 → 1.5.12

package/package/module/PieChart/NestedPieChart.README.md

@@ -0,0 +1,421 @@
+# NestedPieChart (多层级饼图)
+
+多层级饼图组件，支持双层嵌套、分组图例、交互高亮等功能。专为 Store insights / Summary 等场景设计。
+
+## 特性
+
+### 核心功能
+
+- ✅ **多层级支持**：支持 2 层嵌套（外层大类 + 内层子类），可扩展到 N 层
+- ✅ **树形数据结构**：支持 `tree` 和 `flat` 两种数据输入格式
+- ✅ **智能配色**：
+  - 大类固定基色（可自定义 mapping）
+  - 子类自动生成同色系渐变色
+  - 保证相邻颜色可辨识（可配置最小色差）
+- ✅ **分组图例**：
+  - 按大类分组显示
+  - 支持折叠/展开（可配置默认状态）
+  - 显示分组小计和子项明细
+  - 可配置排序策略（按值、按标签、保持原序）
+- ✅ **交互高亮**：
+  - Hover 扇区高亮对应图例项
+  - Hover 图例项高亮对应扇区
+  - 点击事件支持（扇区和图例）
+- ✅ **数据筛选**：点击图例可隐藏/显示对应扇区（可选）
+- ✅ **自定义 Tooltip**：支持自定义渲染和格式化
+- ✅ **数据处理**：自动去重、合并、过滤 0 值
+- ✅ **响应式布局**：自适应容器尺寸
+- ✅ **跨端支持**：Web 端完整功能，RN 端提供降级方案
+
+## 基础用法
+
+### 树形数据（推荐）
+
+```tsx
+import { NestedPieChart } from '@beppla/tapas-ui';
+
+const data = [
+  {
+    key: 'cash',
+    label: 'Cash',
+    children: [
+      { key: 'cash-19', label: '19% VAT', value: 1250.50 },
+      { key: 'cash-7', label: '7% VAT', value: 680.30 },
+    ],
+  },
+  {
+    key: 'credit-card',
+    label: 'Credit Card',
+    children: [
+      { key: 'cc-19', label: '19% VAT', value: 3420.80 },
+      { key: 'cc-7', label: '7% VAT', value: 1560.40 },
+    ],
+  },
+];
+
+const paymentMethodColors = {
+  'cash': '#00B894',
+  'credit-card': '#FF6B00',
+};
+
+<NestedPieChart
+  data={data}
+  height={450}
+  colorStrategy={{
+    baseColors: paymentMethodColors,
+    autoGenerate: true,
+  }}
+  formatValue={(value) => `€${value.toFixed(2)}`}
+/>
+```
+
+### 扁平数据
+
+```tsx
+const flatData = [
+  { key: 'cash-19', label: '19% VAT', value: 1250.50, groupKey: 'cash', groupLabel: 'Cash' },
+  { key: 'cash-7', label: '7% VAT', value: 680.30, groupKey: 'cash', groupLabel: 'Cash' },
+  { key: 'cc-19', label: '19% VAT', value: 3420.80, groupKey: 'credit-card', groupLabel: 'Credit Card' },
+];
+
+<NestedPieChart
+  data={flatData}
+  dataType="flat"
+  height={450}
+/>
+```
+
+## Props
+
+### 数据相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `NestedPieChartNode[]` \| `NestedPieChartFlatData[]` | **required** | 图表数据 |
+| `dataType` | `'tree'` \| `'flat'` | auto | 数据类型，默认自动推断 |
+| `levels` | `number` | auto | 显示层数，默认自动计算 |
+
+### 尺寸相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `width` | `number` | auto | 容器宽度 |
+| `height` | `number` | `400` | 容器高度 |
+| `outerRadius` | `number` \| `string` | auto | 外圆半径（可以是数字或百分比） |
+| `innerRadius` | `number` \| `string` | `60` | 内圆半径（形成 donut 图） |
+| `radiusGap` | `number` | `15` | 层与层之间的间隔 |
+
+### 配色相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `colorStrategy` | `ColorStrategy` | `{ autoGenerate: true }` | 配色策略 |
+| `colors` | `string[]` | `DEFAULT_COLORS` | 默认配色数组 |
+
+#### ColorStrategy
+
+```tsx
+interface ColorStrategy {
+  baseColors?: Record<string, string>; // 大类基色 mapping
+  autoGenerate?: boolean;              // 是否自动生成子类渐变色
+  colorSteps?: number;                 // 渐变色阶数
+  minColorDiff?: number;               // 相邻颜色最小色差 (0-1)
+}
+```
+
+### 图例相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showLegend` | `boolean` | `true` | 是否显示图例 |
+| `legendMode` | `'flat'` \| `'grouped'` | `'grouped'` | 图例模式 |
+| `legendPosition` | `'top'` \| `'bottom'` \| `'left'` \| `'right'` | `'right'` | 图例位置 |
+| `legendContent` | `'all'` \| `'parent-only'` \| `'children-only'` | `'all'` | 图例显示内容 |
+| `legendCollapsible` | `boolean` | `true` | 是否可折叠 |
+| `legendDefaultExpanded` | `boolean` | `true` | 默认展开状态 |
+| `legendSortStrategy` | `LegendSortStrategy` | `'none'` | 子项排序策略 |
+| `legendGroupSortStrategy` | `LegendSortStrategy` | `'none'` | 分组排序策略 |
+| `legendShowValues` | `boolean` | `true` | 是否显示数值 |
+| `legendShowPercent` | `boolean` | `true` | 是否显示百分比 |
+| `legendItemGap` | `number` | `6` | 图例项间距 |
+| `legendGroupGap` | `number` | `16` | 分组间距 |
+| `legendLabelMinWidth` | `number` | auto | 标签最小宽度 |
+| `legendChartGap` | `number` | `30` | 图例与图表间距 |
+
+#### LegendSortStrategy
+
+- `'none'`: 保持原始顺序
+- `'value-desc'`: 按值降序
+- `'value-asc'`: 按值升序
+- `'label-asc'`: 按标签升序
+- `'label-desc'`: 按标签降序
+
+### 格式化相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `formatValue` | `(value: number) => string` | Euro format | 数值格式化函数 |
+| `formatPercent` | `(percent: number) => string` | `${percent.toFixed(1)}%` | 百分比格式化函数 |
+
+### 交互相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onSliceClick` | `(event: SliceClickEvent) => void` | - | 扇区点击事件 |
+| `onSliceHover` | `(event: SliceClickEvent \| null) => void` | - | 扇区 hover 事件 |
+| `onLegendClick` | `(event: LegendClickEvent) => void` | - | 图例点击事件 |
+| `enableLegendFilter` | `boolean` | `false` | 是否启用图例筛选功能 |
+
+### Tooltip 相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showTooltip` | `boolean` | `true` | 是否显示 Tooltip |
+| `customTooltip` | `(event: SliceClickEvent) => ReactNode` | - | 自定义 Tooltip 渲染 |
+
+### 其他
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `padAngle` | `number` | `0.01` | 扇区间隔角度 |
+| `centerText` | `string` | - | 中心文本 |
+| `centerTextStyle` | `CSSProperties` | - | 中心文本样式 |
+| `emptyText` | `string` | `'No data available'` | 空数据提示文本 |
+| `style` | `any` | - | 容器样式 |
+| `testID` | `string` | - | 测试 ID |
+
+## 数据结构
+
+### NestedPieChartNode (树形)
+
+```tsx
+interface NestedPieChartNode {
+  key: string | number;           // 唯一标识
+  label: string;                  // 显示文本
+  value?: number;                 // 叶子节点必须有值
+  color?: string;                 // 自定义颜色（可选）
+  children?: NestedPieChartNode[]; // 子节点
+  metadata?: Record<string, any>; // 额外元数据
+}
+```
+
+### NestedPieChartFlatData (扁平)
+
+```tsx
+interface NestedPieChartFlatData {
+  key: string | number;
+  label: string;
+  value: number;
+  groupKey: string | number;      // 所属分组
+  groupLabel: string;             // 分组名称
+  color?: string;
+  metadata?: Record<string, any>;
+}
+```
+
+## 事件对象
+
+### SliceClickEvent
+
+```tsx
+interface SliceClickEvent {
+  key: string | number;
+  label: string;
+  value: number;
+  level: number;                  // 0=根，1=第一层子节点
+  path: Array<string | number>;   // 从根到当前节点的路径
+  parentKey?: string | number;
+  metadata?: Record<string, any>;
+}
+```
+
+### LegendClickEvent
+
+```tsx
+interface LegendClickEvent extends SliceClickEvent {
+  groupKey?: string | number;
+  isGroupHeader?: boolean;        // 是否点击的是分组标题
+}
+```
+
+## 高级用法
+
+### 自定义配色策略
+
+```tsx
+<NestedPieChart
+  data={data}
+  colorStrategy={{
+    baseColors: {
+      'cash': '#00B894',
+      'credit-card': '#FF6B00',
+      'apple-pay': '#0066CC',
+    },
+    autoGenerate: true,
+    colorSteps: 5,
+    minColorDiff: 0.12,
+  }}
+/>
+```
+
+### 交互和筛选
+
+```tsx
+function InteractiveChart() {
+  const [selectedItem, setSelectedItem] = useState<string>('');
+  
+  return (
+    <>
+      <NestedPieChart
+        data={data}
+        enableLegendFilter={true}
+        onSliceClick={(event) => {
+          setSelectedItem(event.label);
+        }}
+        onLegendClick={(event) => {
+          console.log('Legend clicked:', event);
+        }}
+      />
+      {selectedItem && <Text>Selected: {selectedItem}</Text>}
+    </>
+  );
+}
+```
+
+### 自定义 Tooltip
+
+```tsx
+<NestedPieChart
+  data={data}
+  customTooltip={(event) => (
+    <div style={{
+      backgroundColor: '#2C3E50',
+      color: 'white',
+      padding: '12px',
+      borderRadius: '8px',
+    }}>
+      <div style={{ fontWeight: 600 }}>{event.label}</div>
+      <div>Amount: €{event.value.toFixed(2)}</div>
+      <div>Level: {event.level === 0 ? 'Payment Method' : 'Tax Rate'}</div>
+    </div>
+  )}
+/>
+```
+
+### 排序策略
+
+```tsx
+<NestedPieChart
+  data={data}
+  legendGroupSortStrategy="value-desc"  // 分组按值降序
+  legendSortStrategy="value-desc"       // 子项按值降序
+/>
+```
+
+### 中心文本和样式
+
+```tsx
+<NestedPieChart
+  data={data}
+  centerText="€14,768"
+  centerTextStyle={{
+    fontSize: '28px',
+    fontWeight: 700,
+    color: '#2C3E50',
+  }}
+/>
+```
+
+## 使用场景
+
+### Store Insights / Summary
+
+```tsx
+// 支付方式 -> 税率分析
+const salesData = [
+  {
+    key: 'cash',
+    label: 'Cash',
+    children: [
+      { key: 'cash-19', label: '19% VAT', value: 1250.50 },
+      { key: 'cash-7', label: '7% VAT', value: 680.30 },
+    ],
+  },
+  // ...
+];
+
+<NestedPieChart
+  data={salesData}
+  height={450}
+  formatValue={(value) => new Intl.NumberFormat('de-DE', {
+    style: 'currency',
+    currency: 'EUR',
+  }).format(value)}
+/>
+```
+
+### 分类销售分析
+
+```tsx
+// 产品类别 -> 子类别销售
+const productData = [
+  {
+    key: 'food',
+    label: 'Food & Beverage',
+    children: [
+      { key: 'food-hot', label: 'Hot Meals', value: 5200 },
+      { key: 'food-cold', label: 'Cold Drinks', value: 3100 },
+      { key: 'food-dessert', label: 'Desserts', value: 1800 },
+    ],
+  },
+  // ...
+];
+```
+
+## 注意事项
+
+1. **数据要求**：
+   - 每个节点必须有唯一的 `key`
+   - 叶子节点必须有 `value`
+   - 0 值会被自动过滤
+
+2. **性能优化**：
+   - 自动去重和合并相同 key 的数据
+   - 建议数据量不超过 100 个节点（包括所有层级）
+
+3. **跨端支持**：
+   - Web 端：完整功能
+   - React Native：目前提供降级提示，后续版本支持
+
+4. **颜色生成**：
+   - 建议为主要分类提供 `baseColors` mapping
+   - 子类渐变色会自动生成，保证同色系且可辨识
+
+## 类型定义
+
+完整的 TypeScript 类型定义请参考：
+- `NestedPieChart.types.ts`
+
+## 工具函数
+
+组件提供了一系列工具函数，可单独导入使用：
+
+```tsx
+import {
+  isTreeData,
+  flatToTree,
+  cleanData,
+  generateColorShades,
+  generateColorMap,
+  processData,
+  buildLegendGroupData,
+  formatEuro,
+} from '@beppla/tapas-ui';
+```
+
+## 相关组件
+
+- `PieChart` - 基础饼图组件
+- `BarChart` - 柱状图组件
+- `LineChart` - 折线图组件
+- `ComboChart` - 组合图组件

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

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