@beppla/tapas-ui 1.5.2 → 1.5.7

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

package/commonjs/Header/README.md

@@ -0,0 +1,109 @@
+# Header
+
+应用页眉组件，提供顶部导航栏功能，包含标题显示、左侧菜单/返回按钮、搜索框和用户头像。自动适配桌面端和移动端的不同展示形式。
+
+## 功能特性
+
+- 自适应响应式设计（桌面端和移动端标题字号、搜索框形态自动切换）
+- 支持左侧菜单按钮（`showLeftIcon`）和返回按钮（`hasBack`）
+- 桌面端搜索框为完整输入框（168px），移动端为圆形搜索图标
+- 用户头像显示（圆形 Avatar）并支持点击事件
+- 标题长文本自动省略号处理（桌面端 `text-overflow: ellipsis`）
+- 搜索文本变化实时回调
+- 可自定义左侧图标名称
+- 固定高度 72px
+
+## 安装使用
+
+```tsx
+import { Header } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | `string` | - | 页眉标题文本 |
+| hasBack | `boolean` | `false` | 是否显示返回按钮 |
+| showLeftIcon | `boolean` | `false` | 是否显示左侧菜单按钮 |
+| leftIcon | `string` | `'menu'` | 左侧图标名称 |
+| onLeftIconPress | `() => void` | - | 左侧按钮/返回按钮点击回调 |
+| backIconStyle | `any` | - | 返回按钮图标自定义样式 |
+| isShowSearch | `boolean` | `false` | 是否显示搜索框 |
+| searchPlaceholderText | `string` | - | 搜索框占位符文本 |
+| searchOnChangeText | `(text: string) => void` | - | 搜索文本变化回调 |
+| avatarSource | `string` | - | 头像图片 URI |
+| avatarOnPress | `() => void` | - | 头像点击回调 |
+| headerContainerStyle | `StyleProp<ViewStyle>` | - | 容器自定义样式 |
+| theme | `any` | - | 主题对象（自动注入） |
+
+> Header 继承 `@rneui/themed` 的 `HeaderProps`，支持所有 RNE Header 原生属性。
+
+## 使用示例
+
+### 基础标题
+
+```tsx
+<Header title="Home" />
+```
+
+### 带返回按钮
+
+```tsx
+<Header
+  title="Order Details"
+  hasBack={true}
+  onLeftIconPress={() => navigation.goBack()}
+/>
+```
+
+### 带菜单按钮
+
+```tsx
+<Header
+  title="Dashboard"
+  showLeftIcon={true}
+  leftIcon="menu"
+  onLeftIconPress={() => toggleNav()}
+/>
+```
+
+### 完整功能（搜索 + 头像）
+
+```tsx
+<Header
+  title="Products"
+  showLeftIcon={true}
+  isShowSearch={true}
+  searchPlaceholderText="Search products..."
+  searchOnChangeText={(text) => handleSearch(text)}
+  avatarSource="https://randomuser.me/api/portraits/men/36.jpg"
+  avatarOnPress={() => alert('Avatar clicked')}
+  onLeftIconPress={() => alert('Menu clicked')}
+/>
+```
+
+### 自定义容器样式
+
+```tsx
+<Header
+  title="Custom Styled Header"
+  hasBack={true}
+  onLeftIconPress={() => goBack()}
+  headerContainerStyle={{
+    backgroundColor: '#1a1a1a',
+    paddingHorizontal: 20,
+  }}
+/>
+```
+
+## 注意事项
+
+- 页眉高度固定为 72px，背景色跟随主题 `theme.colors.background`
+- 标题在桌面端使用 `h2` 字号和 `weightL` 字重，移动端使用 `h3` 字号
+- `hasBack` 和 `showLeftIcon` 可同时设置，但通常二选一使用
+- 桌面端标题占据整行（`flexGrow: 1`），自动省略号处理长文本
+- 搜索框仅在 `isShowSearch=true` 时显示；桌面端为输入框，移动端为图标
+- 搜索文本变化通过 `useEffect` 延迟触发 `searchOnChangeText` 回调
+- 头像使用 `Avatar` 组件，大小为 `small`，圆形显示
+- 左侧图标大小为 20px，颜色使用主题 `grey1`

package/commonjs/HelloWave/README.md

@@ -0,0 +1,28 @@
+# HelloWave
+
+挥手动画组件，使用 Animated API 实现简单的摆动效果，默认展示挥手 emoji。
+
+## 安装使用
+
+```tsx
+import { HelloWave } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| emoji | `string` | `'👋'` | 显示的 emoji |
+| duration | `number` | `150` | 单次摆动时长（毫秒） |
+| repeatCount | `number` | `4` | 重复次数 |
+| style | `any` | - | 容器样式 |
+| textStyle | `any` | - | 文本样式 |
+| testID | `string` | - | 测试标识 |
+
+## 使用示例
+
+```tsx
+<HelloWave />
+
+<HelloWave emoji="🎉" duration={200} repeatCount={6} />
+```

package/commonjs/Hoverable/Hoverable.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","_interopRequireWildcard","require","_reactNative","_jsxRuntime","e","t","WeakMap","r","n","__esModule","o","i","f","__proto__","default","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","Hoverable","children","onHoverIn","onHoverOut","style","testID","isHovered","setIsHovered","useState","handleHoverIn","handleHoverOut","renderChildren","isValidElement","cloneElement","Platform","OS","jsx","onMouseEnter","onMouseLeave","View","_default","exports"],"sourceRoot":"../../../components","sources":["Hoverable/Hoverable.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,uBAAA,CAAAC,OAAA;AACA,IAAAC,YAAA,GAAAD,OAAA;AAA8C,IAAAE,WAAA,GAAAF,OAAA;AAAA,SAAAD,wBAAAI,CAAA,EAAAC,CAAA,6BAAAC,OAAA,MAAAC,CAAA,OAAAD,OAAA,IAAAE,CAAA,OAAAF,OAAA,YAAAN,uBAAA,YAAAA,CAAAI,CAAA,EAAAC,CAAA,SAAAA,CAAA,IAAAD,CAAA,IAAAA,CAAA,CAAAK,UAAA,SAAAL,CAAA,MAAAM,CAAA,EAAAC,CAAA,EAAAC,CAAA,KAAAC,SAAA,QAAAC,OAAA,EAAAV,CAAA,iBAAAA,CAAA,uBAAAA,CAAA,yBAAAA,CAAA,SAAAQ,CAAA,MAAAF,CAAA,GAAAL,CAAA,GAAAG,CAAA,GAAAD,CAAA,QAAAG,CAAA,CAAAK,GAAA,CAAAX,CAAA,UAAAM,CAAA,CAAAM,GAAA,CAAAZ,CAAA,GAAAM,CAAA,CAAAO,GAAA,CAAAb,CAAA,EAAAQ,CAAA,gBAAAP,CAAA,IAAAD,CAAA,gBAAAC,CAAA,OAAAa,cAAA,CAAAC,IAAA,CAAAf,CAAA,EAAAC,CAAA,OAAAM,CAAA,IAAAD,CAAA,GAAAU,MAAA,CAAAC,cAAA,KAAAD,MAAA,CAAAE,wBAAA,CAAAlB,CAAA,EAAAC,CAAA,OAAAM,CAAA,CAAAK,GAAA,IAAAL,CAAA,CAAAM,GAAA,IAAAP,CAAA,CAAAE,CAAA,EAAAP,CAAA,EAAAM,CAAA,IAAAC,CAAA,CAAAP,CAAA,IAAAD,CAAA,CAAAC,CAAA,WAAAO,CAAA,KAAAR,CAAA,EAAAC,CAAA;AAU9C,MAAMkB,SAAmC,GAAGA,CAAC;EAC3CC,QAAQ;EACRC,SAAS;EACTC,UAAU;EACVC,KAAK;EACLC;AACF,CAAC,KAAK;EACJ,MAAM,CAACC,SAAS,EAAEC,YAAY,CAAC,GAAG,IAAAC,eAAQ,EAAC,KAAK,CAAC;EAEjD,MAAMC,aAAa,GAAGA,CAAA,KAAM;IAC1BF,YAAY,CAAC,IAAI,CAAC;IAClBL,SAAS,GAAG,CAAC;EACf,CAAC;EAED,MAAMQ,cAAc,GAAGA,CAAA,KAAM;IAC3BH,YAAY,CAAC,KAAK,CAAC;IACnBJ,UAAU,GAAG,CAAC;EAChB,CAAC;EAED,MAAMQ,cAAc,GAAGA,CAAA,KAAM;IAC3B,IAAI,OAAOV,QAAQ,KAAK,UAAU,EAAE;MAClC,OAAOA,QAAQ,CAACK,SAAS,CAAC;IAC5B;IAEA,iBAAI,IAAAM,qBAAc,EAACX,QAAQ,CAAC,EAAE;MAC5B,oBAAO,IAAAY,mBAAY,EAACZ,QAAQ,EAAE;QAAEK;MAAU,CAAC,CAAC;IAC9C;IAEA,OAAOL,QAAQ;EACjB,CAAC;;EAED;EACA,IAAIa,qBAAQ,CAACC,EAAE,KAAK,KAAK,EAAE;IACzB,oBACE,IAAAnC,WAAA,CAAAoC,GAAA;MACEZ,KAAK,EAAEA,KAAM;MACba,YAAY,EAAER,aAAc;MAC5BS,YAAY,EAAER,cAAe;MAC7B,eAAaL,MAAO;MAAAJ,QAAA,EAEnBU,cAAc,CAAC;IAAC,CACd,CAAC;EAEV;;EAEA;EACA,oBACE,IAAA/B,WAAA,CAAAoC,GAAA,EAACrC,YAAA,CAAAwC,IAAI;IAACf,KAAK,EAAEA,KAAM;IAACC,MAAM,EAAEA,MAAO;IAAAJ,QAAA,EAChCU,cAAc,CAAC;EAAC,CACb,CAAC;AAEX,CAAC;AAAC,IAAAS,QAAA,GAAAC,OAAA,CAAA9B,OAAA,GAEaS,SAAS","ignoreList":[]}
+{"version":3,"names":["_react","_interopRequireWildcard","require","_reactNative","_jsxRuntime","e","t","WeakMap","r","n","__esModule","o","i","f","__proto__","default","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","Hoverable","children","onHoverIn","onHoverOut","style","testID","isHovered","setIsHovered","useState","handleHoverIn","handleHoverOut","renderChildren","isValidElement","cloneElement","Platform","OS","jsx","onMouseEnter","onMouseLeave","View","_default","exports"],"sourceRoot":"../../../components","sources":["Hoverable/Hoverable.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,uBAAA,CAAAC,OAAA;AACA,IAAAC,YAAA,GAAAD,OAAA;AAA8C,IAAAE,WAAA,GAAAF,OAAA;AAAA,SAAAD,wBAAAI,CAAA,EAAAC,CAAA,6BAAAC,OAAA,MAAAC,CAAA,OAAAD,OAAA,IAAAE,CAAA,OAAAF,OAAA,YAAAN,uBAAA,YAAAA,CAAAI,CAAA,EAAAC,CAAA,SAAAA,CAAA,IAAAD,CAAA,IAAAA,CAAA,CAAAK,UAAA,SAAAL,CAAA,MAAAM,CAAA,EAAAC,CAAA,EAAAC,CAAA,KAAAC,SAAA,QAAAC,OAAA,EAAAV,CAAA,iBAAAA,CAAA,uBAAAA,CAAA,yBAAAA,CAAA,SAAAQ,CAAA,MAAAF,CAAA,GAAAL,CAAA,GAAAG,CAAA,GAAAD,CAAA,QAAAG,CAAA,CAAAK,GAAA,CAAAX,CAAA,UAAAM,CAAA,CAAAM,GAAA,CAAAZ,CAAA,GAAAM,CAAA,CAAAO,GAAA,CAAAb,CAAA,EAAAQ,CAAA,gBAAAP,CAAA,IAAAD,CAAA,gBAAAC,CAAA,OAAAa,cAAA,CAAAC,IAAA,CAAAf,CAAA,EAAAC,CAAA,OAAAM,CAAA,IAAAD,CAAA,GAAAU,MAAA,CAAAC,cAAA,KAAAD,MAAA,CAAAE,wBAAA,CAAAlB,CAAA,EAAAC,CAAA,OAAAM,CAAA,CAAAK,GAAA,IAAAL,CAAA,CAAAM,GAAA,IAAAP,CAAA,CAAAE,CAAA,EAAAP,CAAA,EAAAM,CAAA,IAAAC,CAAA,CAAAP,CAAA,IAAAD,CAAA,CAAAC,CAAA,WAAAO,CAAA,KAAAR,CAAA,EAAAC,CAAA;AAU9C,MAAMkB,SAAmC,GAAGA,CAAC;EAC3CC,QAAQ;EACRC,SAAS;EACTC,UAAU;EACVC,KAAK;EACLC;AACF,CAAC,KAAK;EACJ,MAAM,CAACC,SAAS,EAAEC,YAAY,CAAC,GAAG,IAAAC,eAAQ,EAAC,KAAK,CAAC;EAEjD,MAAMC,aAAa,GAAGA,CAAA,KAAM;IAC1BF,YAAY,CAAC,IAAI,CAAC;IAClBL,SAAS,GAAG,CAAC;EACf,CAAC;EAED,MAAMQ,cAAc,GAAGA,CAAA,KAAM;IAC3BH,YAAY,CAAC,KAAK,CAAC;IACnBJ,UAAU,GAAG,CAAC;EAChB,CAAC;EAED,MAAMQ,cAAc,GAAGA,CAAA,KAAM;IAC3B,IAAI,OAAOV,QAAQ,KAAK,UAAU,EAAE;MAClC,OAAOA,QAAQ,CAACK,SAAS,CAAC;IAC5B;IAEA,iBAAI,IAAAM,qBAAc,EAACX,QAAQ,CAAC,EAAE;MAC5B,oBAAO,IAAAY,mBAAY,EAACZ,QAAQ,EAA6B;QAAEK;MAAU,CAAC,CAAC;IACzE;IAEA,OAAOL,QAAQ;EACjB,CAAC;;EAED;EACA,IAAIa,qBAAQ,CAACC,EAAE,KAAK,KAAK,EAAE;IACzB,oBACE,IAAAnC,WAAA,CAAAoC,GAAA;MACEZ,KAAK,EAAEA,KAAM;MACba,YAAY,EAAER,aAAc;MAC5BS,YAAY,EAAER,cAAe;MAC7B,eAAaL,MAAO;MAAAJ,QAAA,EAEnBU,cAAc,CAAC;IAAC,CACd,CAAC;EAEV;;EAEA;EACA,oBACE,IAAA/B,WAAA,CAAAoC,GAAA,EAACrC,YAAA,CAAAwC,IAAI;IAACf,KAAK,EAAEA,KAAM;IAACC,MAAM,EAAEA,MAAO;IAAAJ,QAAA,EAChCU,cAAc,CAAC;EAAC,CACb,CAAC;AAEX,CAAC;AAAC,IAAAS,QAAA,GAAAC,OAAA,CAAA9B,OAAA,GAEaS,SAAS","ignoreList":[]}

package/commonjs/IconText/README.md

@@ -0,0 +1,99 @@
+# IconText
+
+图标文本组合组件，支持图标与文本的水平排列展示，可作为标签或可点击元素使用。
+
+## 功能特性
+
+- ✅ 图标 + 文本水平排列
+- ✅ 两种类型：text（纯展示，外层 View）和 label（可点击，外层 TouchableOpacity）
+- ✅ 三种尺寸：small (12px) / medium (14px) / large (16px)
+- ✅ 自定义图标颜色（iconColor）
+- ✅ 自定义背景颜色（backgroundColor）
+- ✅ 文本截断控制（numberOfLines / ellipsizeMode）
+- ✅ 自定义最大宽度（maxWidth）
+- ✅ 支持 onLayout 事件回调
+- ✅ 基于 @rneui/themed 主题系统
+
+## 安装使用
+
+```tsx
+import IconText from '@beppla/tapas-ui/components/IconText/IconText';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | `string` | (必填) | 文本内容 |
+| icon | `string` | - | 图标名称（TapasIcon） |
+| index | `number` | - | 索引值，作为 key |
+| type | `'text' \| 'label'` | `'text'` | 类型：text 纯展示，label 可点击 |
+| size | `'small' \| 'medium' \| 'large'` | `'medium'` | 尺寸 |
+| style | `StyleProp<ViewStyle>` | - | 自定义容器样式 |
+| titleStyle | `StyleProp<TextStyle>` | - | 自定义文本样式 |
+| maxWidth | `number` | - | 最大宽度 |
+| numberOfLines | `number` | - | 文本最大行数 |
+| ellipsizeMode | `'head' \| 'middle' \| 'tail' \| 'clip'` | - | 文本截断模式 |
+| onPress | `() => void` | - | 点击回调（仅 label 类型生效） |
+| onLayout | `(e: any) => void` | - | 布局事件回调 |
+| iconColor | `string` | 主题 secondary 色 | 图标颜色 |
+| backgroundColor | `string` | 主题 grey5 色 | 背景颜色 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<IconText title="示例文本" icon="home" />
+```
+
+### 不同尺寸
+
+```tsx
+<IconText title="小号" icon="info" size="small" />
+<IconText title="中号" icon="info" size="medium" />
+<IconText title="大号" icon="info" size="large" />
+```
+
+### 可点击标签
+
+```tsx
+<IconText
+  title="点击我"
+  icon="star"
+  type="label"
+  onPress={() => console.log('Clicked')}
+/>
+```
+
+### 自定义颜色
+
+```tsx
+<IconText
+  title="自定义颜色"
+  icon="warning"
+  iconColor="#FF6B00"
+  backgroundColor="#FFF3E0"
+/>
+```
+
+### 文本截断
+
+```tsx
+<IconText
+  title="这是一个很长的文本需要截断处理"
+  icon="info"
+  maxWidth={150}
+  numberOfLines={1}
+  ellipsizeMode="tail"
+/>
+```
+
+## 注意事项
+
+- `type='text'` 时外层包裹 View 容器（带 grey5 背景），不可点击
+- `type='label'` 时外层包裹 TouchableOpacity，可触发 onPress
+- 不同尺寸对应不同的字号和图标大小：small (12px/12px)、medium (14px/16px)、large (16px/20px)
+- 图标固定在文本左侧，间距为 4px
+- 不传 `icon` 时只渲染文本部分
+- 组件使用 `@rneui/themed` 主题系统，需在 ThemeProvider 内使用

package/commonjs/Image/PreviewImg/README.md

@@ -0,0 +1,100 @@
+# PreviewImg
+
+图片预览覆盖层组件，用于全屏展示图片集合，支持缩略图导航和前后切换。
+
+## 功能特性
+
+- ✅ 全屏图片预览
+- ✅ 缩略图导航
+- ✅ 前后切换功能
+- ✅ 点击缩略图快速跳转
+- ✅ 背景蒙层支持
+- ✅ 响应式尺寸
+
+## 安装使用
+
+```tsx
+import PreviewImg from '@beppla/tapas-ui/components/Image/PreviewImg';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| isVisible | boolean | false | 是否显示预览层 |
+| data | IFileState[] | - | 图片数据数组 |
+| defaultIndex | number | 0 | 默认显示的图片索引 |
+| onClose | () => void | - | 关闭预览时的回调 |
+| onSelect | (index: number) => void | - | 选择图片时的回调 |
+
+## IFileState 结构
+
+```tsx
+interface IFileState {
+  fileId?: string;
+  fileName?: string;
+  fileUrl?: string;
+}
+```
+
+## 使用示例
+
+### 基础用法
+```tsx
+import PreviewImg from '@beppla/tapas-ui/components/Image/PreviewImg';
+import { useState } from 'react';
+
+export default function App() {
+  const [visible, setVisible] = useState(false);
+
+  const images = [
+    { fileUrl: "https://example.com/image1.jpg", fileName: "Image 1" },
+    { fileUrl: "https://example.com/image2.jpg", fileName: "Image 2" },
+  ];
+
+  return (
+    <PreviewImg
+      isVisible={visible}
+      data={images}
+      onClose={() => setVisible(false)}
+    />
+  );
+}
+```
+
+### 带选择回调
+```tsx
+<PreviewImg
+  isVisible={visible}
+  data={images}
+  defaultIndex={0}
+  onClose={() => setVisible(false)}
+  onSelect={(index) => {
+    console.log(`Selected image at index: ${index}`);
+  }}
+/>
+```
+
+### 多张图片预览
+```tsx
+const images = [
+  { fileId: "1", fileUrl: "https://example.com/photo1.jpg", fileName: "Photo 1" },
+  { fileId: "2", fileUrl: "https://example.com/photo2.jpg", fileName: "Photo 2" },
+  { fileId: "3", fileUrl: "https://example.com/photo3.jpg", fileName: "Photo 3" },
+];
+
+<PreviewImg
+  isVisible={visible}
+  data={images}
+  defaultIndex={1}
+  onClose={() => setVisible(false)}
+/>
+```
+
+## 注意事项
+
+- 单张图片时不显示前后导航按钮
+- 点击背景蒙层会关闭预览
+- 点击关闭按钮（X 图标）会关闭预览
+- 缩略图边框颜色为橙色（#F55523）表示当前选中
+- 仅支持 web 平台的 HTML img 标签

package/commonjs/Image/README.md

@@ -0,0 +1,88 @@
+# PreviewImg
+
+图片预览组件，支持全屏遮罩层展示图片，提供缩略图列表导航和左右切换功能。适合商品图片、订单附件等多图预览场景。
+
+## 功能特性
+
+- ✅ 全屏遮罩层预览（Overlay）
+- ✅ 多图浏览：底部缩略图列表导航
+- ✅ 左右切换按钮（chevron_left / chevron_right）
+- ✅ 首张/末张图片自动禁用对应切换按钮
+- ✅ 点击缩略图快速跳转
+- ✅ 当前选中缩略图高亮边框
+- ✅ 点击遮罩或关闭按钮关闭预览
+- ✅ 自定义默认展示图片索引（defaultIndex）
+
+## 安装使用
+
+```tsx
+import { PreviewImg } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| isVisible | `boolean` | `false` | 是否显示预览 |
+| data | `IFileState[]` | - | 图片数据数组（必填） |
+| defaultIndex | `number` | `0` | 默认展示的图片索引 |
+| onClose | `() => void` | - | 关闭回调（必填） |
+| onSelect | `(index: number) => void` | - | 图片选择回调（预留） |
+
+### IFileState
+
+```tsx
+interface IFileState {
+  fileId?: string;
+  fileName?: string;
+  fileUrl?: string;
+}
+```
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const [visible, setVisible] = useState(false);
+const images = [
+  { fileId: '1', fileName: 'photo1.jpg', fileUrl: 'https://example.com/1.jpg' },
+  { fileId: '2', fileName: 'photo2.jpg', fileUrl: 'https://example.com/2.jpg' },
+];
+
+<PreviewImg
+  isVisible={visible}
+  data={images}
+  onClose={() => setVisible(false)}
+/>
+```
+
+### 指定默认图片
+
+```tsx
+<PreviewImg
+  isVisible={visible}
+  data={images}
+  defaultIndex={2}
+  onClose={() => setVisible(false)}
+/>
+```
+
+### 单张图片（无切换按钮）
+
+```tsx
+<PreviewImg
+  isVisible={visible}
+  data={[{ fileUrl: 'https://example.com/single.jpg' }]}
+  onClose={() => setVisible(false)}
+/>
+```
+
+## 注意事项
+
+- 组件使用 HTML `<img>` 标签渲染，仅适用于 Web 平台
+- 主图高度自适应：`window.innerHeight - 200`
+- 缩略图固定尺寸 84x84，选中态边框色 `#F55523`
+- 单张图片时不显示左右切换按钮
+- 预览层使用 `@rneui/themed` 的 Overlay 组件
+- 需在 `ThemeProvider` 内使用