@beppla/tapas-ui 1.5.10 → 1.5.12

package/package/module/Loading/README.md

@@ -0,0 +1,160 @@
+# Loading 组件
+
+一个全屏加载组件，提供优雅的加载动画效果。
+
+## 功能特性
+
+- 全屏模态展示
+- 淡入淡出动画效果
+- 可自定义Logo和背景色
+- 支持自定义默认Logo和尺寸
+- 自动循环动画
+- 支持透明背景
+
+## 基本用法
+
+```tsx
+import Loading from '@beppla/tapas-ui/components/Loading';
+
+// 基础用法
+<Loading visible={isLoading} />
+
+// 自定义背景色
+<Loading 
+  visible={isLoading} 
+  backgroundColor="rgba(0, 0, 0, 0.8)" 
+/>
+
+// 自定义Logo
+<Loading 
+  visible={isLoading} 
+  logo={require('./custom-logo.png')} 
+/>
+```
+
+## 避免硬编码图片引用问题
+
+### 问题描述
+之前的版本中，Loading 组件内部硬编码了 `require("../../assets/logo.png")`，这会导致在使用组件库时出现模块解析错误。
+
+### 解决方案
+现在提供了多种方式来解决这个问题：
+
+#### 1. 使用 `defaultLogo` 属性（推荐）
+```tsx
+import Loading from '@beppla/tapas-ui/components/Loading';
+import customLogo from './assets/custom-logo.png';
+
+<Loading 
+  visible={isLoading} 
+  defaultLogo={customLogo}
+/>
+```
+
+#### 2. 使用 `logo` 属性
+```tsx
+import Loading from '@beppla/tapas-ui/components/Loading';
+import customLogo from './assets/custom-logo.png';
+
+<Loading 
+  visible={isLoading} 
+  logo={customLogo}
+/>
+```
+
+#### 3. 在应用初始化时设置全局默认Logo
+```tsx
+// 在应用入口处
+import { initTapasUI } from '@beppla/tapas-ui';
+import defaultLogo from './assets/default-logo.png';
+
+initTapasUI({
+  defaultLoadingLogo: defaultLogo
+});
+
+// 在组件中使用
+<Loading visible={isLoading} />
+```
+
+## API 参考
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `visible` | `boolean` | `false` | 是否显示加载状态 |
+| `logo` | `ImageSourcePropType` | `undefined` | 自定义Logo图片（最高优先级） |
+| `defaultLogo` | `ImageSourcePropType` | `undefined` | 默认Logo图片（优先级高于内置默认） |
+| `backgroundColor` | `string` | `theme.colors.grey1` | 背景颜色 |
+| `size` | `number` | `200` | Logo尺寸（像素） |
+
+### 图片优先级说明
+
+1. **`logo`** - 最高优先级，直接使用传入的图片
+2. **`defaultLogo`** - 中等优先级，使用传入的默认图片
+3. **内置默认图片** - 最低优先级，作为最后的回退选项
+
+## 使用场景
+
+- 应用启动加载
+- 数据请求等待
+- 页面切换过渡
+- 长时间操作提示
+
+## 注意事项
+
+1. **避免硬编码引用**：不要依赖组件内部的默认图片，建议使用 `defaultLogo` 属性
+2. **图片格式支持**：支持 PNG、JPG、SVG 等常见图片格式
+3. **性能考虑**：Logo 图片建议使用适当尺寸，避免过大的图片文件
+4. **主题适配**：背景色会自动适配主题，也可以手动覆盖
+
+## 迁移指南
+
+### 从旧版本迁移
+
+**旧版本（有问题）：**
+```tsx
+// 直接使用，可能报错
+<Loading visible={isLoading} />
+```
+
+**新版本（推荐）：**
+```tsx
+// 设置自定义默认Logo
+<Loading 
+  visible={isLoading} 
+  defaultLogo={require('./assets/logo.png')}
+/>
+
+// 或者使用自定义Logo
+<Loading 
+  visible={isLoading} 
+  logo={require('./assets/logo.png')}
+/>
+```
+
+### 批量替换示例
+
+如果您的项目中有多个地方使用了 Loading 组件，可以创建一个包装组件：
+
+```tsx
+// components/AppLoading.tsx
+import Loading from '@beppla/tapas-ui/components/Loading';
+import appLogo from '../assets/app-logo.png';
+
+export const AppLoading = (props) => (
+  <Loading 
+    {...props} 
+    defaultLogo={appLogo}
+  />
+);
+
+// 在项目中使用
+import { AppLoading } from './components/AppLoading';
+
+<AppLoading visible={isLoading} />
+```
+
+## 示例代码
+
+完整的示例项目可以参考 Storybook 中的演示，或者查看 `stories/Loading/Loading.stories.tsx` 文件。

package/package/module/MessageBox/README.md

@@ -0,0 +1,120 @@
+# MessageBox
+
+模态对话框组件，用于显示重要信息和获取用户确认。支持 success、warning、error 三种状态，提供灵活的按钮配置（隐藏确认/取消按钮、隐藏整个底部栏），适合操作确认、错误提示、成功反馈等场景。
+
+## 功能特性
+
+- ✅ 支持 success、warning、error 三种状态
+- ✅ 状态自动匹配图标（check_circle / warning / error）
+- ✅ 可自定义图标名称覆盖默认状态图标
+- ✅ 灵活的按钮配置：隐藏确认按钮、隐藏取消按钮、隐藏整个底部栏
+- ✅ 自定义确认和取消按钮文本
+- ✅ 描述文本行数限制（descNumberOfLines）
+- ✅ 淡入淡出动画（animationType="fade"）
+- ✅ 透明遮罩背景
+- ✅ 支持 onVisibilityChange 双向绑定控制
+
+## 安装使用
+
+```tsx
+import { MessageBox } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| visible | `boolean` | - | 是否显示对话框 |
+| state | `'success' \| 'warning' \| 'error'` | - | 状态类型 |
+| icon | `string` | 根据 state 自动选择 | 自定义图标名称 |
+| title | `string` | - | 标题文本 |
+| text | `string` | - | 描述内容 |
+| hideFooter | `boolean` | `false` | 是否隐藏整个底部按钮栏 |
+| hideCloseBtn | `boolean` | `false` | 是否隐藏取消按钮 |
+| hideConfirmBtn | `boolean` | `false` | 是否隐藏确认按钮 |
+| confirmBtnText | `string` | `'Confirm'` | 确认按钮文本 |
+| closeBtnText | `string` | `'Close'` | 取消按钮文本 |
+| descNumberOfLines | `number` | `3` | 描述文本最大行数 |
+| onVisibilityChange | `(val: boolean) => void` | - | 可见状态变化回调 |
+| onConfirm | `() => void` | - | 确认按钮点击回调 |
+| onClose | `() => void` | - | 取消按钮点击回调 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const [visible, setVisible] = useState(false);
+
+<MessageBox
+  visible={visible}
+  title="Confirm"
+  text="Are you sure you want to proceed?"
+  confirmBtnText="OK"
+  closeBtnText="Cancel"
+  onVisibilityChange={setVisible}
+  onConfirm={() => {
+    handleConfirm();
+    setVisible(false);
+  }}
+  onClose={() => setVisible(false)}
+/>
+```
+
+### 不同状态
+
+```tsx
+<MessageBox
+  visible={visible}
+  state="success"
+  title="Success"
+  text="Operation completed!"
+  hideCloseBtn
+  confirmBtnText="OK"
+  onConfirm={() => setVisible(false)}
+/>
+
+<MessageBox
+  visible={visible}
+  state="error"
+  title="Error"
+  text="Operation failed, please retry."
+  confirmBtnText="Retry"
+  closeBtnText="Close"
+  onConfirm={() => handleRetry()}
+  onClose={() => setVisible(false)}
+/>
+```
+
+### 仅确认按钮
+
+```tsx
+<MessageBox
+  visible={visible}
+  title="Notice"
+  text="This is a notification."
+  hideCloseBtn={true}
+  confirmBtnText="Got it"
+  onConfirm={() => setVisible(false)}
+/>
+```
+
+### 无按钮（点击遮罩关闭）
+
+```tsx
+<MessageBox
+  visible={visible}
+  title="Info"
+  text="Click backdrop to close."
+  hideFooter={true}
+  onVisibilityChange={setVisible}
+/>
+```
+
+## 注意事项
+
+- 组件内部维护 `modalVisible` 状态，与外部 `visible` 同步
+- 关闭优先级：`onClose` > `onVisibilityChange` > 内部 `setModalVisible(false)`
+- 对话框固定宽度 392px，居中显示
+- 需在 `ThemeProvider` 内使用
+- 确认按钮使用主题 `primary` 色，取消按钮无背景色

package/package/module/MultiSelector/README.md

@@ -0,0 +1,246 @@
+# TapasMultiSelector
+
+一个功能完整的多选下拉组件，支持搜索、验证、动画标签和丰富的自定义选项。
+
+## 功能特性
+
+- ✅ 多选支持：可以选择多个选项
+- ✅ 搜索功能：内置搜索栏，支持过滤选项
+- ✅ 动画标签：平滑的标签动画效果
+- ✅ 状态管理：支持正常和错误状态
+- ✅ 验证支持：必填字段验证和状态消息
+- ✅ 动态定位：智能计算弹出位置和方向
+- ✅ 自定义样式：支持多种样式类型和尺寸
+- ✅ 操作按钮：清除和确认按钮
+- ✅ 响应式设计：适配不同屏幕尺寸
+- ✅ 无障碍支持：完整的可访问性支持
+
+## 安装使用
+
+```tsx
+import { TapasMultiSelector } from '@beppla/tapas-ui';
+
+// 基础用法
+<TapasMultiSelector
+  label="选择水果"
+  dropdownItems={fruitOptions}
+  onSelect={(keys) => console.log('选中:', keys)}
+/>
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `label` | `string` | - | 标签文本 |
+| `title` | `string` | - | 弹出框标题 |
+| `dropdownItems` | `TapasMultiSelectorItem[]` | `[]` | 选项列表 |
+| `selected` | `number[]` | `[]` | 当前选中的选项键值数组 |
+| `onSelect` | `(keys: number[]) => void` | - | 选择变化回调 |
+| `placeholder` | `string` | - | 占位符文本 |
+| `required` | `boolean` | `false` | 是否必填 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `state` | `"normal" \| "error"` | `"normal"` | 状态类型 |
+| `stateMsg` | `string` | - | 状态消息 |
+| `showStateMsg` | `boolean` | `false` | 是否显示状态消息 |
+| `showSelectedValue` | `boolean` | `false` | 是否显示选中值 |
+| `showSearchBar` | `boolean` | `false` | 是否显示搜索栏 |
+| `type` | `"clear" \| "solid"` | `"clear"` | 按钮类型 |
+| `width` | `number` | - | 组件宽度 |
+| `height` | `number` | - | 组件高度 |
+| `radius` | `number` | `12` | 圆角半径 |
+| `icon` | `string` | `"arrow_drop_down"` | 图标名称 |
+| `iconStyle` | `ViewStyle \| TextStyle` | - | 图标样式 |
+| `backgroundColor` | `string` | - | 背景颜色 |
+| `noLabelAnim` | `boolean` | `false` | 是否禁用标签动画 |
+| `offsetWidth` | `number` | `0` | 位置偏移宽度 |
+| `dropdownSubWidth` | `number` | `151` | 弹出框宽度 |
+| `dropdownSubHeight` | `number` | - | 弹出框最大高度 |
+| `visible` | `boolean` | - | 控制弹出框可见性 |
+| `setVisible` | `(val: boolean) => void` | - | 设置弹出框可见性 |
+| `searchPlaceholder` | `string` | `"Search"` | 搜索框占位符 |
+| `clearButtonText` | `string` | `"Clear"` | 清除按钮文本 |
+| `confirmButtonText` | `string` | `"Done"` | 确认按钮文本 |
+
+## TapasMultiSelectorItem 接口
+
+```tsx
+interface TapasMultiSelectorItem {
+  key: number;           // 唯一标识
+  value: string;         // 显示文本
+  secondaryValue?: string; // 次要文本（可选）
+}
+```
+
+## 使用示例
+
+### 基础多选
+
+```tsx
+import React, { useState } from 'react';
+import { TapasMultiSelector, TapasMultiSelectorItem } from '@beppla/tapas-ui';
+
+const MultiSelectDemo = () => {
+  const [selectedFruits, setSelectedFruits] = useState<number[]>([]);
+
+  const fruitOptions: TapasMultiSelectorItem[] = [
+    { key: 1, value: '苹果' },
+    { key: 2, value: '香蕉' },
+    { key: 3, value: '橙子' },
+    { key: 4, value: '葡萄' },
+  ];
+
+  const handleSelection = (keys: number[]) => {
+    setSelectedFruits(keys);
+    console.log('选中的水果:', keys);
+  };
+
+  return (
+    <TapasMultiSelector
+      label="选择水果"
+      dropdownItems={fruitOptions}
+      selected={selectedFruits}
+      onSelect={handleSelection}
+      placeholder="请选择您喜欢的水果"
+      showSelectedValue={true}
+    />
+  );
+};
+```
+
+### 带搜索和验证
+
+```tsx
+import React, { useState } from 'react';
+import { TapasMultiSelector } from '@beppla/tapas-ui';
+
+const ValidatedMultiSelect = () => {
+  const [selectedTags, setSelectedTags] = useState<number[]>([]);
+  const [isValid, setIsValid] = useState(true);
+
+  const tagOptions = [
+    { key: 1, value: '新上市', secondaryValue: '最近添加的产品' },
+    { key: 2, value: '热销', secondaryValue: '销量最高的产品' },
+    { key: 3, value: '促销', secondaryValue: '打折产品' },
+    { key: 4, value: '推荐', secondaryValue: '精选产品' },
+  ];
+
+  const handleSelection = (keys: number[]) => {
+    setSelectedTags(keys);
+    setIsValid(keys.length > 0);
+  };
+
+  return (
+    <TapasMultiSelector
+      label="产品标签"
+      title="选择产品标签"
+      dropdownItems={tagOptions}
+      selected={selectedTags}
+      onSelect={handleSelection}
+      required={true}
+      showSearchBar={true}
+      showStateMsg={true}
+      state={isValid ? 'normal' : 'error'}
+      stateMsg={isValid ? '已选择标签' : '请至少选择一个标签'}
+      searchPlaceholder="搜索标签..."
+      placeholder="选择产品标签"
+      clearButtonText="清除所有"
+      confirmButtonText="应用标签"
+    />
+  );
+};
+```
+
+### 自定义样式
+
+```tsx
+import React from 'react';
+import { TapasMultiSelector } from '@beppla/tapas-ui';
+
+const CustomStyledMultiSelect = () => {
+  const categoryOptions = [
+    { key: 1, value: '电子产品' },
+    { key: 2, value: '服装' },
+    { key: 3, value: '图书' },
+    { key: 4, value: '运动' },
+  ];
+
+  return (
+    <TapasMultiSelector
+      label="产品分类"
+      dropdownItems={categoryOptions}
+      type="solid"
+      radius={20}
+      width={350}
+      height={70}
+      backgroundColor="#f8f9fa"
+      iconStyle={{ color: '#007bff' }}
+      clearButtonText="重置"
+      confirmButtonText="确认选择"
+    />
+  );
+};
+```
+
+### 带次要文本的选项
+
+```tsx
+import React from 'react';
+import { TapasMultiSelector } from '@beppla/tapas-ui';
+
+const SecondaryValueDemo = () => {
+  const departmentOptions = [
+    { key: 1, value: '技术部', secondaryValue: '负责产品开发和维护' },
+    { key: 2, value: '市场部', secondaryValue: '负责品牌推广和销售' },
+    { key: 3, value: '人事部', secondaryValue: '负责人员招聘和管理' },
+    { key: 4, value: '财务部', secondaryValue: '负责财务核算和预算' },
+  ];
+
+  return (
+    <TapasMultiSelector
+      label="选择部门"
+      title="部门选择"
+      dropdownItems={departmentOptions}
+      showSearchBar={true}
+      searchPlaceholder="搜索部门..."
+      placeholder="请选择您感兴趣的部门"
+    />
+  );
+};
+```
+
+## 最佳实践
+
+1. **合理的选项数量**：建议选项数量控制在 5-20 个之间，过多选项考虑分页
+2. **清晰的标签文案**：标签和选项文案应该简洁明确，避免歧义
+3. **适当的验证**：对于重要选择，使用 `required` 和状态消息
+4. **搜索功能**：当选项较多时，启用搜索功能提升用户体验
+5. **自定义按钮文案**：根据业务场景自定义清除和确认按钮文案
+
+## 使用场景
+
+- 产品分类选择
+- 用户权限配置
+- 标签管理系统
+- 兴趣爱好选择
+- 技能评估表单
+- 多选问卷调查
+- 文件类型过滤
+- 用户分组管理
+
+## 注意事项
+
+1. `dropdownItems` 数组为空时，组件仍会正常渲染，但不会显示任何选项
+2. 当 `required` 为 `true` 且没有选择任何选项时，建议显示错误状态
+3. 组件会自动计算弹出位置，确保在屏幕边界内显示
+4. 支持 React Native 和 React Native Web 环境
+5. 动画效果在测试环境中可能需要特殊处理
+
+## 技术实现
+
+- 使用 `Modal` 实现弹出效果
+- 动态计算弹出位置和方向
+- 支持标签动画效果
+- 集成搜索和过滤功能
+- 完整的键盘导航支持
+- 响应式布局设计