@ticatec/uniface-element 0.1.71 → 0.2.1

package/docs/buttons/cn/ActionBar.md

@@ -0,0 +1,459 @@
+# ActionBar 组件
+
+`ActionBar` 组件提供了一个容器，用于组织多个按钮操作，确保一致的间距和布局。
+
+## 基础用法
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import type { ButtonActions } from '@ticatec/uniface-element';
+  
+  const actions: ButtonActions = [
+    {
+      label: "保存",
+      type: "primary",
+      icon: "icon_google_save",
+      handler: async () => {
+        await saveChanges();
+      }
+    },
+    {
+      label: "取消",
+      type: "secondary",
+      handler: async () => {
+        closeDialog();
+      }
+    }
+  ];
+</script>
+
+<ActionBar buttons={actions} />
+```
+
+## 高级用法
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import type { ButtonActions } from '@ticatec/uniface-element';
+  
+  let isProcessing = false;
+  
+  const formActions: ButtonActions = [
+    {
+      label: "重置",
+      type: "default",
+      icon: "icon_google_undo",
+      handler: async () => {
+        resetForm();
+      }
+    },
+    null, // 分隔符
+    {
+      label: "预览",
+      type: "secondary",
+      icon: "icon_google_visibility",
+      handler: async () => {
+        showPreview();
+      }
+    },
+    {
+      label: isProcessing ? "处理中..." : "提交",
+      type: "primary",
+      icon: "icon_google_send",
+      disabled: isProcessing,
+      handler: async () => {
+        isProcessing = true;
+        try {
+          await submitForm();
+        } finally {
+          isProcessing = false;
+        }
+      }
+    }
+  ];
+</script>
+
+<ActionBar 
+  buttons={formActions} 
+  gap={12}
+  style="padding: 16px; justify-content: flex-end;"
+/>
+```
+
+## 带自定义内容的 ActionBar
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import Button from '@ticatec/uniface-element/Button';
+</script>
+
+<!-- 当没有提供 buttons 属性时，使用插槽内容 -->
+<ActionBar gap={16} style="padding: 20px;">
+  <Button label="自定义操作 1" type="primary" onClick={action1} />
+  <Button label="自定义操作 2" type="secondary" onClick={action2} />
+  <Button label="自定义操作 3" type="default" onClick={action3} />
+</ActionBar>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `buttons` | `ButtonActions` | `[]` | 按钮配置数组 |
+| `style` | `string` | `''` | 自定义 CSS 样式 |
+| `gap` | `number` | `8` | 按钮间距，单位像素 |
+
+## API 参考
+
+### ButtonAction 接口
+
+```typescript
+interface ButtonAction {
+  /** 按钮标签文本 */
+  label: string;
+  
+  /** 按钮是否禁用 */
+  disabled?: boolean;
+  
+  /** 图标类（如 Google Material Icons） */
+  icon?: string;
+  
+  /** 按钮类型用于样式设置 */
+  type?: ButtonType;
+  
+  /** 点击事件处理器 */
+  handler?: MouseClickHandler;
+}
+
+type ButtonActions = Array<ButtonAction | null>;
+```
+
+### MouseClickHandler 类型
+
+```typescript
+type MouseClickHandler = (event: MouseEvent) => Promise<void>;
+```
+
+## 使用示例
+
+### 对话框操作
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import type { ButtonActions } from '@ticatec/uniface-element';
+  
+  export let onSave: () => Promise<void>;
+  export let onCancel: () => void;
+  
+  const dialogActions: ButtonActions = [
+    {
+      label: "取消",
+      type: "secondary",
+      handler: async () => {
+        onCancel();
+      }
+    },
+    {
+      label: "保存更改",
+      type: "primary",
+      icon: "icon_google_save",
+      handler: async () => {
+        await onSave();
+      }
+    }
+  ];
+</script>
+
+<div class="dialog-footer">
+  <ActionBar buttons={dialogActions} style="justify-content: flex-end;" />
+</div>
+```
+
+### 表单操作栏
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import type { ButtonActions } from '@ticatec/uniface-element';
+  
+  let formData = {};
+  let isSubmitting = false;
+  let isDraft = false;
+  
+  const formActions: ButtonActions = [
+    {
+      label: "重置",
+      type: "default",
+      handler: async () => {
+        formData = {};
+      }
+    },
+    null, // 分隔符
+    {
+      label: isDraft ? "保存中..." : "保存草稿",
+      type: "secondary",
+      icon: "icon_google_save",
+      disabled: isDraft,
+      handler: async () => {
+        isDraft = true;
+        try {
+          await saveDraft(formData);
+        } finally {
+          isDraft = false;
+        }
+      }
+    },
+    {
+      label: isSubmitting ? "提交中..." : "提交",
+      type: "primary",
+      icon: "icon_google_send",
+      disabled: isSubmitting,
+      handler: async () => {
+        isSubmitting = true;
+        try {
+          await submitForm(formData);
+        } finally {
+          isSubmitting = false;
+        }
+      }
+    }
+  ];
+</script>
+
+<form>
+  <!-- 表单字段在此 -->
+  
+  <div class="form-footer">
+    <ActionBar 
+      buttons={formActions} 
+      gap={12}
+      style="justify-content: flex-end; margin-top: 24px;"
+    />
+  </div>
+</form>
+```
+
+### 工具栏实现
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import type { ButtonActions } from '@ticatec/uniface-element';
+  
+  let selectedItems = [];
+  
+  const toolbarActions: ButtonActions = [
+    {
+      label: "全选",
+      icon: "icon_google_check_box",
+      type: "default",
+      handler: async () => {
+        selectAll();
+      }
+    },
+    null, // 分隔符
+    {
+      label: "导出",
+      icon: "icon_google_download",
+      type: "secondary",
+      disabled: selectedItems.length === 0,
+      handler: async () => {
+        await exportItems(selectedItems);
+      }
+    },
+    {
+      label: "删除选中",
+      icon: "icon_google_delete",
+      type: "third",
+      disabled: selectedItems.length === 0,
+      handler: async () => {
+        if (confirm(`删除 ${selectedItems.length} 个项目?`)) {
+          await deleteItems(selectedItems);
+        }
+      }
+    }
+  ];
+</script>
+
+<div class="toolbar">
+  <div class="toolbar-info">
+    已选择 {selectedItems.length} 个项目
+  </div>
+  <ActionBar buttons={toolbarActions} />
+</div>
+
+<style>
+  .toolbar {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 12px;
+    border-bottom: 1px solid #eee;
+  }
+  
+  .toolbar-info {
+    color: #666;
+    font-size: 14px;
+  }
+</style>
+```
+
+### 卡片操作栏
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import type { ButtonActions } from '@ticatec/uniface-element';
+  
+  export let item: any;
+  export let onEdit: (item: any) => Promise<void>;
+  export let onShare: (item: any) => Promise<void>;
+  export let onDelete: (item: any) => Promise<void>;
+  
+  const cardActions: ButtonActions = [
+    {
+      label: "编辑",
+      icon: "icon_google_edit",
+      type: "primary",
+      handler: async () => {
+        await onEdit(item);
+      }
+    },
+    {
+      label: "分享",
+      icon: "icon_google_share",
+      type: "secondary",
+      handler: async () => {
+        await onShare(item);
+      }
+    },
+    {
+      label: "删除",
+      icon: "icon_google_delete",
+      type: "third",
+      handler: async () => {
+        if (confirm("确定要删除此项目吗？")) {
+          await onDelete(item);
+        }
+      }
+    }
+  ];
+</script>
+
+<div class="card">
+  <div class="card-content">
+    <!-- 卡片内容 -->
+  </div>
+  
+  <div class="card-actions">
+    <ActionBar buttons={cardActions} gap={8} />
+  </div>
+</div>
+
+<style>
+  .card {
+    border: 1px solid #e0e0e0;
+    border-radius: 8px;
+    overflow: hidden;
+  }
+  
+  .card-content {
+    padding: 16px;
+  }
+  
+  .card-actions {
+    padding: 12px 16px;
+    background: #f8f9fa;
+    border-top: 1px solid #e0e0e0;
+  }
+</style>
+```
+
+## 最佳实践
+
+### 使用分隔符组织操作
+
+使用 `null` 值作为分隔符来组织相关操作：
+
+```svelte
+<script lang="ts">
+  const editorActions: ButtonActions = [
+    // 文件操作组
+    { label: "新建", icon: "icon_google_add", handler: newFile },
+    { label: "打开", icon: "icon_google_folder_open", handler: openFile },
+    { label: "保存", icon: "icon_google_save", handler: saveFile },
+    
+    null, // 分隔符
+    
+    // 编辑操作组
+    { label: "撤销", icon: "icon_google_undo", handler: undo },
+    { label: "重做", icon: "icon_google_redo", handler: redo },
+    
+    null, // 分隔符
+    
+    // 主要操作
+    { label: "发布", type: "primary", icon: "icon_google_publish", handler: publish }
+  ];
+</script>
+```
+
+### 使用合适的间距
+
+根据界面密度调整按钮间距：
+
+```svelte
+<!-- 紧凑界面 -->
+<ActionBar buttons={actions} gap={4} />
+
+<!-- 标准界面 -->
+<ActionBar buttons={actions} gap={8} />
+
+<!-- 宽松界面 -->
+<ActionBar buttons={actions} gap={16} />
+```
+
+### 响应式设计
+
+考虑在小屏幕上隐藏或简化操作：
+
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte';
+  
+  let isMobile = false;
+  
+  onMount(() => {
+    const checkMobile = () => {
+      isMobile = window.innerWidth < 768;
+    };
+    
+    checkMobile();
+    window.addEventListener('resize', checkMobile);
+    
+    return () => window.removeEventListener('resize', checkMobile);
+  });
+  
+  $: responsiveActions = isMobile 
+    ? [
+        { label: "保存", type: "primary", handler: save },
+        { label: "取消", type: "secondary", handler: cancel }
+      ]
+    : [
+        { label: "重置", type: "default", handler: reset },
+        null,
+        { label: "预览", type: "secondary", handler: preview },
+        { label: "保存", type: "primary", handler: save },
+        { label: "取消", type: "secondary", handler: cancel }
+      ];
+</script>
+
+<ActionBar buttons={responsiveActions} />
+```
+
+## 点击节流
+
+ActionBar 中的所有按钮都实现了自动点击节流，具有 500ms 冷却时间，以防止意外的双击并确保正确的异步操作处理。

package/docs/buttons/cn/Button.md

@@ -0,0 +1,228 @@
+# Button 组件
+
+主要的 `Button` 组件提供了支持图标和标签的全面按钮功能。
+
+## 基础用法
+
+```svelte
+<script lang="ts">
+  import Button from '@ticatec/uniface-element/Button';
+  
+  const handleClick = async (event: MouseEvent) => {
+    console.log('按钮被点击!');
+    // 执行异步操作
+  };
+</script>
+
+<Button 
+  label="保存更改"
+  type="primary"
+  icon="icon_google_save"
+  onClick={handleClick}
+/>
+```
+
+## 高级配置
+
+```svelte
+<script lang="ts">
+  import Button from '@ticatec/uniface-element/Button';
+  import type { ButtonType } from '@ticatec/uniface-element';
+  
+  let isSubmitting = false;
+  
+  const handleSubmit = async (event: MouseEvent) => {
+    isSubmitting = true;
+    try {
+      await submitForm();
+    } finally {
+      isSubmitting = false;
+    }
+  };
+</script>
+
+<Button 
+  label={isSubmitting ? "提交中..." : "提交表单"}
+  type="primary"
+  size="big"
+  variant="round"
+  icon="icon_google_send"
+  disabled={isSubmitting}
+  style="margin: 16px;"
+  onClick={handleSubmit}
+/>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `label` | `string` | `''` | 按钮文本标签 |
+| `type` | `ButtonType` | `'default'` | 视觉样式变体 |
+| `size` | `'big' \| 'medium' \| 'mini'` | `'medium'` | 按钮大小 |
+| `variant` | `'plain' \| 'round' \| ''` | `''` | 附加样式变体 |
+| `icon` | `string \| null` | `null` | 图标类（如 Google Material Icons） |
+| `disabled` | `boolean` | `false` | 禁用按钮交互 |
+| `style` | `string` | `''` | 自定义 CSS 样式 |
+| `onClick` | `(event: MouseEvent) => void` | - | 点击事件处理器 |
+
+## 带插槽内容的按钮
+
+```svelte
+<Button type="secondary" onClick={handleAction}>
+  <i class="icon_google_star"></i>
+  <span>自定义内容</span>
+  <span class="badge">3</span>
+</Button>
+```
+
+## 样式变体
+
+### ButtonType 选项
+
+```typescript
+type ButtonType = 'default' | 'primary' | 'secondary' | 'third' | 'forth';
+```
+
+### 视觉外观
+
+- **default**: 标准中性按钮外观
+- **primary**: 强调主要操作的按钮（通常为蓝色）
+- **secondary**: 次要操作按钮（通常为灰色）
+- **third**: 替代样式（通常用于警告/注意）
+- **forth**: 附加样式变体
+
+### 大小变体
+
+- **big**: 大按钮尺寸，用于突出操作
+- **medium**: 标准按钮尺寸，适用于大多数使用场景
+- **mini**: 小按钮尺寸，用于紧凑界面
+
+### 样式变体
+
+- **plain**: 最小化样式变体
+- **round**: 圆角变体
+- **'' (空字符串)**: 标准样式
+
+## 图标使用
+
+组件使用 `@ticatec/uniface-google-material-icons` 作为图标库。只需传入图标类名：
+
+```svelte
+<!-- 常用 Material Icons -->
+<Button icon="icon_google_save" label="保存" />
+<Button icon="icon_google_edit" label="编辑" />
+<Button icon="icon_google_delete" label="删除" />
+<Button icon="icon_google_add" label="添加" />
+<Button icon="icon_google_remove" label="移除" />
+<Button icon="icon_google_search" label="搜索" />
+<Button icon="icon_google_settings" label="设置" />
+<Button icon="icon_google_home" label="主页" />
+<Button icon="icon_google_check" label="确认" />
+<Button icon="icon_google_arrow_back" label="返回" />
+```
+
+## 最佳实践
+
+### 使用合适的按钮类型
+
+根据操作重要性选择正确的按钮类型：
+
+```svelte
+<!-- 主要操作 -->
+<Button label="保存" type="primary" />
+<Button label="提交" type="primary" />
+
+<!-- 次要操作 -->
+<Button label="取消" type="secondary" />
+<Button label="预览" type="secondary" />
+
+<!-- 危险操作 -->
+<Button label="删除" type="third" />
+<Button label="移除" type="third" />
+```
+
+### 正确处理异步操作
+
+始终处理加载状态和错误：
+
+```svelte
+<script lang="ts">
+  let isLoading = false;
+  let error = null;
+  
+  const handleAction = async () => {
+    isLoading = true;
+    error = null;
+    
+    try {
+      await performAction();
+    } catch (err) {
+      error = err.message;
+    } finally {
+      isLoading = false;
+    }
+  };
+</script>
+
+<Button 
+  label={isLoading ? "处理中..." : "开始处理"}
+  type="primary"
+  disabled={isLoading}
+  onClick={handleAction}
+/>
+
+{#if error}
+  <div class="error">{error}</div>
+{/if}
+```
+
+### 提供视觉反馈
+
+使用图标和适当的样式：
+
+```svelte
+<!-- 成功操作 -->
+<Button label="保存" icon="icon_google_save" type="primary" />
+
+<!-- 危险操作 -->
+<Button label="删除" icon="icon_google_delete" type="third" />
+
+<!-- 导航操作 -->
+<Button label="返回" icon="icon_google_arrow_back" type="secondary" />
+```
+
+### 考虑移动端响应式
+
+为不同屏幕尺寸使用合适的大小：
+
+```svelte
+<div class="responsive-buttons">
+  <!-- 桌面端: 普通大小，移动端: 更大以适应触摸 -->
+  <Button label="操作" size="big" class="mobile-friendly" />
+</div>
+
+<style>
+  .responsive-buttons .mobile-friendly {
+    /* 响应式样式 */
+  }
+  
+  @media (max-width: 768px) {
+    .responsive-buttons .mobile-friendly {
+      min-height: 44px; /* iOS 推荐的触摸目标大小 */
+    }
+  }
+</style>
+```
+
+## 无障碍性注意事项
+
+**⚠️ 重要提示**：当前的按钮组件存在以下无障碍性限制：
+
+- **非语义化元素**：所有按钮都使用 `<div>` 元素而不是 `<button>`
+- **对屏幕阅读器隐藏**：所有按钮默认都有 `aria-hidden="true"`
+- **无键盘导航**：组件不支持 Tab 导航或 Enter/Space 激活
+- **无焦点管理**：组件不提供 focus 方法或支持 `bind:this`
+- **无 ARIA 属性支持**：自定义 aria-* 属性无法传递
+
+如需完全的无障碍性支持，请考虑使用正确的语义化元素包装组件。