@ticatec/uniface-element 0.2.0 → 0.2.1

package/docs/navigation/cn/navigatormenu.md

@@ -0,0 +1,512 @@
+# NavigatorMenu 导航菜单组件
+
+NavigatorMenu 组件提供分层菜单系统，支持可展开/折叠的树形导航，具有嵌套菜单结构和流畅的动画效果。
+
+## 功能特性
+
+- **分层导航**：多级树形菜单结构
+- **可展开项目**：带有子导航的可折叠菜单项
+- **流畅动画**：展开/折叠的滑动过渡效果
+- **灵活的数据结构**：支持任何菜单项数据格式
+- **自定义文本字段**：可配置从菜单项提取文本的方式
+- **点击处理**：菜单操作的自定义点击处理器
+- **递归渲染**：自动处理嵌套菜单层级
+
+## 导入
+
+```typescript
+import { NavigatorMenu, MenuItem } from '@ticatec/uniface-element/NavigatorMenu';
+```
+
+## 基本用法
+
+### 简单菜单
+
+```svelte
+<script>
+  import { NavigatorMenu } from '@ticatec/uniface-element/NavigatorMenu';
+  
+  const menuItems = [
+    {
+      item: { name: "仪表板", route: "/dashboard" },
+      expand: false,
+      children: null
+    },
+    {
+      item: { name: "用户", route: "/users" },
+      expand: false,
+      children: [
+        {
+          item: { name: "所有用户", route: "/users/list" },
+          expand: false,
+          children: null
+        },
+        {
+          item: { name: "添加用户", route: "/users/add" },
+          expand: false,
+          children: null
+        }
+      ]
+    },
+    {
+      item: { name: "设置", route: "/settings" },
+      expand: false,
+      children: null
+    }
+  ];
+  
+  const handleMenuClick = (menuItem) => {
+    console.log('菜单点击:', menuItem.item.name);
+    console.log('导航到:', menuItem.item.route);
+  };
+</script>
+
+<NavigatorMenu 
+  menuItems={menuItems}
+  textField="name"
+  onItemClick={handleMenuClick}
+/>
+```
+
+### 自定义文本提取的菜单
+
+```svelte
+<script>
+  import { NavigatorMenu } from '@ticatec/uniface-element/NavigatorMenu';
+  
+  const navigationMenu = [
+    {
+      item: { title: "首页", icon: "home", path: "/" },
+      expand: false,
+      children: null
+    },
+    {
+      item: { title: "产品", icon: "products", path: "/products" },
+      expand: true, // 初始展开
+      children: [
+        {
+          item: { title: "电子产品", path: "/products/electronics" },
+          expand: false,
+          children: [
+            {
+              item: { title: "电脑", path: "/products/electronics/computers" },
+              expand: false,
+              children: null
+            },
+            {
+              item: { title: "手机", path: "/products/electronics/phones" },
+              expand: false,
+              children: null
+            }
+          ]
+        },
+        {
+          item: { title: "服装", path: "/products/clothing" },
+          expand: false,
+          children: null
+        }
+      ]
+    }
+  ];
+  
+  // 从菜单项提取文本的自定义函数
+  const getMenuText = (item) => {
+    return `${item.icon ? '📁 ' : '📄 '}${item.title}`;
+  };
+  
+  const handleItemClick = (menuItem) => {
+    console.log('点击:', menuItem.item.title);
+  };
+</script>
+
+<NavigatorMenu 
+  menuItems={navigationMenu}
+  textField={getMenuText}
+  onItemClick={handleItemClick}
+  style="width: 300px; border: 1px solid #e0e0e0; border-radius: 4px;"
+/>
+```
+
+## API 参考
+
+### 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `menuItems` | `Array<MenuItem>` | 必需 | 菜单项对象数组 |
+| `style` | `string` | `''` | 附加CSS样式 |
+| `textField` | `string \| GetText<MenuItem>` | 必需 | 提取文本的字段名或函数 |
+| `onItemClick` | `OnMenuClick` | 必需 | 菜单项的点击处理器 |
+
+### MenuItem 接口
+
+```typescript
+interface MenuItem {
+  [key: string]: any;  // 灵活的项目数据结构
+}
+
+interface MenuNode extends TreeNode<MenuItem> {
+  item: MenuItem;      // 实际的菜单数据
+  expand: boolean;     // 此节点是否展开
+  children: MenuNode[] | null; // 子菜单项
+}
+```
+
+### 类型定义
+
+```typescript
+type OnMenuClick = (item: MenuItem) => void;
+type GetText<T> = (item: T) => string;
+```
+
+## 高级示例
+
+### 带图标的应用导航
+
+```svelte
+<script>
+  import { NavigatorMenu } from '@ticatec/uniface-element/NavigatorMenu';
+  
+  let appNavigation = [
+    {
+      item: { 
+        id: 'dashboard',
+        label: "仪表板", 
+        icon: "📊",
+        route: "/dashboard",
+        permissions: ["read"]
+      },
+      expand: false,
+      children: null
+    },
+    {
+      item: { 
+        id: 'admin',
+        label: "管理", 
+        icon: "⚙️",
+        permissions: ["admin"]
+      },
+      expand: false,
+      children: [
+        {
+          item: { 
+            id: 'users',
+            label: "用户管理", 
+            route: "/admin/users",
+            permissions: ["admin", "user_management"]
+          },
+          expand: false,
+          children: [
+            {
+              item: { 
+                id: 'user_list',
+                label: "查看用户", 
+                route: "/admin/users/list" 
+              },
+              expand: false,
+              children: null
+            },
+            {
+              item: { 
+                id: 'user_create',
+                label: "创建用户", 
+                route: "/admin/users/create" 
+              },
+              expand: false,
+              children: null
+            },
+            {
+              item: { 
+                id: 'user_roles',
+                label: "管理角色", 
+                route: "/admin/users/roles" 
+              },
+              expand: false,
+              children: null
+            }
+          ]
+        },
+        {
+          item: { 
+            id: 'system',
+            label: "系统设置", 
+            route: "/admin/system" 
+          },
+          expand: false,
+          children: null
+        }
+      ]
+    },
+    {
+      item: { 
+        id: 'reports',
+        label: "报告", 
+        icon: "📈",
+        route: "/reports" 
+      },
+      expand: false,
+      children: [
+        {
+          item: { 
+            id: 'sales_reports',
+            label: "销售报告", 
+            route: "/reports/sales" 
+          },
+          expand: false,
+          children: null
+        },
+        {
+          item: { 
+            id: 'user_reports',
+            label: "用户报告", 
+            route: "/reports/users" 
+          },
+          expand: false,
+          children: null
+        }
+      ]
+    }
+  ];
+  
+  const formatMenuText = (item) => {
+    return `${item.icon || '📄'} ${item.label}`;
+  };
+  
+  const handleNavigation = (menuNode) => {
+    const item = menuNode.item;
+    
+    if (item.route) {
+      console.log(`导航到: ${item.route}`);
+      // 在这里处理实际导航
+    } else {
+      console.log(`菜单部分: ${item.label}`);
+    }
+  };
+</script>
+
+<div class="app-navigation">
+  <h3>应用菜单</h3>
+  <NavigatorMenu 
+    menuItems={appNavigation}
+    textField={formatMenuText}
+    onItemClick={handleNavigation}
+    style="background: #f8f9fa; border-radius: 8px; padding: 10px;"
+  />
+</div>
+```
+
+### 文件系统资源管理器菜单
+
+```svelte
+<script>
+  import { NavigatorMenu } from '@ticatec/uniface-element/NavigatorMenu';
+  
+  let fileSystemMenu = [
+    {
+      item: { 
+        name: "文档",
+        type: "folder",
+        path: "/documents",
+        size: null
+      },
+      expand: true,
+      children: [
+        {
+          item: { 
+            name: "项目",
+            type: "folder",
+            path: "/documents/projects"
+          },
+          expand: false,
+          children: [
+            {
+              item: { 
+                name: "webapp",
+                type: "folder",
+                path: "/documents/projects/webapp"
+              },
+              expand: false,
+              children: [
+                {
+                  item: { 
+                    name: "src",
+                    type: "folder",
+                    path: "/documents/projects/webapp/src"
+                  },
+                  expand: false,
+                  children: null
+                },
+                {
+                  item: { 
+                    name: "package.json",
+                    type: "file",
+                    path: "/documents/projects/webapp/package.json",
+                    size: "2.1 KB"
+                  },
+                  expand: false,
+                  children: null
+                }
+              ]
+            }
+          ]
+        },
+        {
+          item: { 
+            name: "简历.pdf",
+            type: "file",
+            path: "/documents/resume.pdf",
+            size: "145 KB"
+          },
+          expand: false,
+          children: null
+        }
+      ]
+    },
+    {
+      item: { 
+        name: "下载",
+        type: "folder",
+        path: "/downloads"
+      },
+      expand: false,
+      children: [
+        {
+          item: { 
+            name: "安装程序.exe",
+            type: "file",
+            path: "/downloads/installer.exe",
+            size: "12.3 MB"
+          },
+          expand: false,
+          children: null
+        }
+      ]
+    }
+  ];
+  
+  const getFileDisplayText = (item) => {
+    const icon = item.type === 'folder' ? '📁' : '📄';
+    const sizeText = item.size ? ` (${item.size})` : '';
+    return `${icon} ${item.name}${sizeText}`;
+  };
+  
+  const handleFileClick = (menuNode) => {
+    const file = menuNode.item;
+    
+    if (file.type === 'file') {
+      console.log(`打开文件: ${file.path}`);
+    } else {
+      console.log(`访问文件夹: ${file.path}`);
+    }
+  };
+</script>
+
+<div class="file-explorer">
+  <h3>文件资源管理器</h3>
+  <NavigatorMenu 
+    menuItems={fileSystemMenu}
+    textField={getFileDisplayText}
+    onItemClick={handleFileClick}
+    style="font-family: 'Courier New', monospace; border: 1px solid #ccc; max-height: 400px; overflow-y: auto;"
+  />
+</div>
+```
+
+### 带状态管理的动态菜单
+
+```svelte
+<script>
+  import { NavigatorMenu } from '@ticatec/uniface-element/NavigatorMenu';
+  
+  let dynamicMenu = [
+    {
+      item: { id: 1, title: "主要部分", active: false },
+      expand: false,
+      children: [
+        {
+          item: { id: 11, title: "子部分 A", active: false },
+          expand: false,
+          children: null
+        },
+        {
+          item: { id: 12, title: "子部分 B", active: true },
+          expand: false,
+          children: null
+        }
+      ]
+    },
+    {
+      item: { id: 2, title: "次要部分", active: false },
+      expand: false,
+      children: null
+    }
+  ];
+  
+  let activeItemId = 12;
+  
+  const getMenuText = (item) => {
+    const activeIndicator = item.id === activeItemId ? '▶ ' : '';
+    return `${activeIndicator}${item.title}`;
+  };
+  
+  const handleMenuSelection = (menuNode) => {
+    const item = menuNode.item;
+    
+    // 更新激活状态
+    activeItemId = item.id;
+    console.log(`选择: ${item.title} (ID: ${item.id})`);
+    
+    // 通过触发响应式更新强制菜单刷新
+    dynamicMenu = [...dynamicMenu];
+  };
+  
+  const addMenuItem = () => {
+    const newId = Date.now();
+    dynamicMenu[0].children.push({
+      item: { id: newId, title: `新项目 ${newId}`, active: false },
+      expand: false,
+      children: null
+    });
+    
+    dynamicMenu = [...dynamicMenu]; // 触发响应式更新
+  };
+</script>
+
+<div class="dynamic-menu">
+  <NavigatorMenu 
+    menuItems={dynamicMenu}
+    textField={getMenuText}
+    onItemClick={handleMenuSelection}
+    style="border: 2px solid #007acc; border-radius: 6px; padding: 8px;"
+  />
+  
+  <button on:click={addMenuItem} style="margin-top: 10px;">
+    添加新菜单项
+  </button>
+</div>
+```
+
+## 最佳实践
+
+1. **清晰的层次结构**：设计反映应用程序组织的菜单结构
+2. **适当的嵌套**：避免过多嵌套层级（最多3-4级）
+3. **一致的文本**：在菜单项中使用一致的命名约定
+4. **性能优化**：对于非常大的菜单结构考虑延迟加载
+5. **状态管理**：适当地跟踪展开/折叠状态
+6. **无障碍访问**：确保菜单项的键盘导航支持
+7. **视觉反馈**：为可展开项目和当前选择提供清晰的指示器
+
+## 样式说明
+
+- 组件使用`<ul>`和`<li>`元素构建语义化菜单结构
+- 可展开项目有独特的样式类
+- 滑动过渡提供流畅的展开/折叠动画
+- 自定义CSS可以通过`style`属性应用
+
+## 集成提示
+
+- 与路由库结合使用进行导航处理
+- 考虑菜单展开状态的状态持久化
+- 为大型菜单实现搜索/筛选功能
+- 为常见菜单操作添加键盘快捷键
+- 使用各种数据结构进行测试以确保灵活性

package/docs/navigation/cn/progressbar.md

@@ -0,0 +1,199 @@
+# ProgressBar 进度条组件
+
+ProgressBar 组件提供可视化进度指示，支持圆形和线性显示模式，以及各种状态指示。
+
+## 功能特性
+
+- **多种显示类型**：圆形和线性进度条
+- **状态指示器**：成功、失败、取消和进行中状态
+- **可定制外观**：可配置尺寸、颜色和文本显示
+- **视觉反馈**：不同状态的图标和颜色编码
+- **CSS 自定义属性**：通过 CSS 变量支持主题
+
+## 导入
+
+```typescript
+import { ProgressBar, ProgressStatus } from '@ticatec/uniface-element/ProgressBar';
+```
+
+## 基本用法
+
+### 圆形进度条
+
+```svelte
+<script>
+  import { ProgressBar, ProgressStatus } from '@ticatec/uniface-element/ProgressBar';
+  
+  let progress = 65;
+  let status = ProgressStatus.progressing;
+</script>
+
+<ProgressBar 
+  {progress} 
+  {status}
+  type="circular" 
+  size={120} 
+/>
+```
+
+### 线性进度条
+
+```svelte
+<script>
+  import { ProgressBar, ProgressStatus } from '@ticatec/uniface-element/ProgressBar';
+  
+  let progress = 45;
+</script>
+
+<ProgressBar 
+  {progress}
+  type="liner" 
+  height={8}
+  showText={true}
+/>
+```
+
+## API 参考
+
+### 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `progress` | `number` | `0` | 进度值 (0-100) |
+| `size` | `number` | `100` | 圆形进度条的大小 |
+| `type` | `'circular' \| 'liner'` | `'circular'` | 进度条类型 |
+| `height` | `number` | `5` | 进度条高度/厚度 |
+| `showText` | `boolean` | `true` | 是否显示进度文本 |
+| `status` | `ProgressStatus` | `ProgressStatus.progressing` | 进度状态 |
+
+### ProgressStatus 枚举
+
+```typescript
+enum ProgressStatus {
+  progressing = 'progressing',  // 进行中
+  successful = 'successful',    // 成功
+  failure = 'failure',         // 失败
+  canceled = 'canceled'        // 已取消
+}
+```
+
+## 状态示例
+
+### 成功状态
+
+```svelte
+<ProgressBar 
+  progress={100} 
+  status={ProgressStatus.successful}
+  type="circular"
+/>
+```
+
+### 失败状态
+
+```svelte
+<ProgressBar 
+  progress={50} 
+  status={ProgressStatus.failure}
+  type="liner"
+/>
+```
+
+### 取消状态
+
+```svelte
+<ProgressBar 
+  progress={30} 
+  status={ProgressStatus.canceled}
+  type="circular"
+/>
+```
+
+## 样式定制
+
+组件使用 CSS 自定义属性进行主题配置：
+
+```css
+:root {
+  --uniface-progress-bar-color: #22BDFF;         /* 默认进度颜色 */
+  --uniface-progress-bar-success-color: #2DC071; /* 成功状态颜色 */
+  --uniface-progress-bar-failure-color: #FF685B; /* 失败状态颜色 */
+  --uniface-progress-bar-canceled-color: #FFC533; /* 取消状态颜色 */
+  --uniface-progress-bar-bg: #E2E8F0;            /* 背景颜色 */
+}
+```
+
+## 高级示例
+
+### 动态进度与状态更新
+
+```svelte
+<script>
+  import { ProgressBar, ProgressStatus } from '@ticatec/uniface-element/ProgressBar';
+  
+  let progress = 0;
+  let status = ProgressStatus.progressing;
+  
+  const simulate = () => {
+    const timer = setInterval(() => {
+      progress += 10;
+      if (progress >= 100) {
+        clearInterval(timer);
+        status = ProgressStatus.successful;
+      }
+    }, 500);
+  };
+</script>
+
+<ProgressBar {progress} {status} type="circular" size={100} />
+<button on:click={simulate}>开始进度</button>
+```
+
+### 文件上传进度指示器
+
+```svelte
+<script>
+  import { ProgressBar, ProgressStatus } from '@ticatec/uniface-element/ProgressBar';
+  
+  let uploadProgress = 0;
+  let uploadStatus = ProgressStatus.progressing;
+  
+  const handleUpload = async (file) => {
+    uploadStatus = ProgressStatus.progressing;
+    
+    // 模拟上传进度
+    for (let i = 0; i <= 100; i += 10) {
+      uploadProgress = i;
+      await new Promise(resolve => setTimeout(resolve, 200));
+    }
+    
+    uploadStatus = ProgressStatus.successful;
+  };
+</script>
+
+<div class="upload-container">
+  <ProgressBar 
+    progress={uploadProgress} 
+    status={uploadStatus}
+    type="liner" 
+    height={6}
+  />
+  <input type="file" on:change={handleUpload} />
+</div>
+```
+
+## 最佳实践
+
+1. **选择合适的类型**：在紧凑空间使用圆形，在宽布局中使用线性
+2. **状态指示**：始终更新状态以反映操作的实际状态
+3. **用户反馈**：提供关于正在发生的事情的清晰文本或视觉提示
+4. **无障碍访问**：确保足够的颜色对比度并考虑屏幕阅读器
+5. **性能优化**：避免过度的进度更新；限制到合理的间隔
+6. **错误处理**：使用失败状态并在适当时提供重试机制
+
+## 无障碍访问说明
+
+- 进度条通过视觉指示器传达完成状态
+- 状态特定的图标（✔、✗、!）提供额外的上下文
+- 颜色编码支持不同的进度状态
+- 可以切换文本显示以满足不同的无障碍访问需求