@ticatec/uniface-element 0.2.4 → 0.3.0

package/dist/button/IconButton_README_CN.md

@@ -0,0 +1,513 @@
+# IconButton 图标按钮组件
+
+专为基于图标的操作设计的按钮组件，为工具栏操作、导航控件和交互元素提供简洁紧凑的界面。
+
+## 功能特性
+
+- **图标优先设计**: 专为显示图标作为主要内容而优化
+- **多种类型**: 默认、主要、次要、第三级和第四级按钮样式
+- **尺寸选项**: 大、中、小三种尺寸
+- **事件处理**: 支持点击、聚焦和失焦事件
+- **无障碍访问**: 使用语义化按钮元素，支持禁用状态
+- **防抖保护**: 内置点击防抖，防止快速重复触发
+- **自定义样式**: 灵活的样式定制
+- **插槽支持**: 通过插槽支持自定义图标内容
+
+## 基本用法
+
+```svelte
+<script>
+import IconButton from '@ticatec/uniface-element/IconButton';
+
+const handleClick = (event) => {
+  console.log('图标按钮被点击!', event);
+};
+</script>
+
+<IconButton 
+  icon="fas fa-heart" 
+  onclick={handleClick} 
+/>
+```
+
+## 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `type` | `'default' \| 'primary' \| 'secondary' \| 'third' \| 'forth'` | `'default'` | 按钮类型/样式 |
+| `disabled` | `boolean` | `false` | 是否禁用按钮 |
+| `size` | `'big' \| 'medium' \| 'mini'` | `'medium'` | 按钮尺寸 |
+| `style` | `string` | `''` | 自定义CSS样式 |
+| `icon` | `string` | `''` | 图标类名（如FontAwesome类） |
+| `onclick` | `(event: MouseEvent) => void` | - | 点击事件处理器 |
+| `onfocus` | `(event: FocusEvent) => void` | `() => {}` | 聚焦事件处理器 |
+| `onblur` | `(event: FocusEvent) => void` | `() => {}` | 失焦事件处理器 |
+
+## 按钮类型
+
+```svelte
+<!-- 默认图标按钮 -->
+<IconButton icon="fas fa-star" type="default" onclick={handleClick} />
+
+<!-- 主要图标按钮 -->
+<IconButton icon="fas fa-plus" type="primary" onclick={handleClick} />
+
+<!-- 次要图标按钮 -->
+<IconButton icon="fas fa-edit" type="secondary" onclick={handleClick} />
+
+<!-- 第三级图标按钮 -->
+<IconButton icon="fas fa-share" type="third" onclick={handleClick} />
+
+<!-- 第四级图标按钮 -->
+<IconButton icon="fas fa-info" type="forth" onclick={handleClick} />
+```
+
+## 按钮尺寸
+
+```svelte
+<!-- 小型图标按钮 -->
+<IconButton icon="fas fa-search" size="mini" onclick={handleClick} />
+
+<!-- 中型图标按钮（默认） -->
+<IconButton icon="fas fa-search" size="medium" onclick={handleClick} />
+
+<!-- 大型图标按钮 -->
+<IconButton icon="fas fa-search" size="big" onclick={handleClick} />
+```
+
+## 常见使用场景
+
+### 工具栏操作
+
+```svelte
+<div class="toolbar">
+  <IconButton icon="fas fa-bold" onclick={toggleBold} />
+  <IconButton icon="fas fa-italic" onclick={toggleItalic} />
+  <IconButton icon="fas fa-underline" onclick={toggleUnderline} />
+  <IconButton icon="fas fa-link" onclick={insertLink} />
+</div>
+
+<style>
+  .toolbar {
+    display: flex;
+    gap: 4px;
+    padding: 8px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+  }
+</style>
+```
+
+### 导航控件
+
+```svelte
+<div class="navigation">
+  <IconButton icon="fas fa-chevron-left" onclick={goBack} />
+  <IconButton icon="fas fa-home" onclick={goHome} />
+  <IconButton icon="fas fa-chevron-right" onclick={goForward} />
+</div>
+```
+
+### 操作按钮
+
+```svelte
+<div class="actions">
+  <IconButton icon="fas fa-heart" type="primary" onclick={toggleFavorite} />
+  <IconButton icon="fas fa-share" type="secondary" onclick={shareItem} />
+  <IconButton icon="fas fa-bookmark" onclick={bookmarkItem} />
+  <IconButton icon="fas fa-trash" type="secondary" onclick={deleteItem} />
+</div>
+```
+
+## 事件处理
+
+```svelte
+<script>
+let isLiked = false;
+
+const handleLike = (event) => {
+  isLiked = !isLiked;
+  console.log('喜欢状态切换:', isLiked);
+};
+
+const handleFocus = (event) => {
+  // 显示工具提示或高亮
+  showTooltip = true;
+};
+
+const handleBlur = (event) => {
+  // 隐藏工具提示
+  showTooltip = false;
+};
+</script>
+
+<IconButton 
+  icon={isLiked ? "fas fa-heart" : "far fa-heart"}
+  type={isLiked ? "primary" : "default"}
+  onclick={handleLike}
+  onfocus={handleFocus}
+  onblur={handleBlur}
+/>
+```
+
+## 禁用状态
+
+```svelte
+<IconButton 
+  icon="fas fa-save" 
+  disabled={true}
+  onclick={handleSave} 
+/>
+```
+
+## 自定义样式
+
+```svelte
+<IconButton 
+  icon="fas fa-star"
+  style="
+    background: linear-gradient(45deg, #ffd700, #ffed4e);
+    color: #333;
+    border: 2px solid #ffd700;
+    border-radius: 50%;
+  "
+  onclick={handleClick}
+/>
+```
+
+## 插槽用法
+
+```svelte
+<!-- 自定义图标内容 -->
+<IconButton onclick={handleCustomAction}>
+  <svg width="16" height="16" viewBox="0 0 24 24">
+    <path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/>
+  </svg>
+</IconButton>
+
+<!-- 多个图标或复杂内容 -->
+<IconButton onclick={handleMultiAction}>
+  <div class="multi-icon">
+    <i class="fas fa-plus"></i>
+    <i class="fas fa-file"></i>
+  </div>
+</IconButton>
+```
+
+## 高级示例
+
+### 切换按钮
+
+```svelte
+<script>
+let isToggled = false;
+
+const handleToggle = (event) => {
+  isToggled = !isToggled;
+};
+</script>
+
+<IconButton 
+  icon={isToggled ? "fas fa-toggle-on" : "fas fa-toggle-off"}
+  type={isToggled ? "primary" : "default"}
+  onclick={handleToggle}
+/>
+```
+
+### 加载状态
+
+```svelte
+<script>
+let isLoading = false;
+
+const handleRefresh = async (event) => {
+  isLoading = true;
+  try {
+    await refreshData();
+  } finally {
+    isLoading = false;
+  }
+};
+</script>
+
+<IconButton 
+  icon={isLoading ? "fas fa-spinner fa-spin" : "fas fa-sync"}
+  disabled={isLoading}
+  onclick={handleRefresh}
+/>
+```
+
+### 上下文操作
+
+```svelte
+<script>
+let showMenu = false;
+
+const toggleMenu = (event) => {
+  showMenu = !showMenu;
+};
+</script>
+
+<div class="menu-container">
+  <IconButton 
+    icon="fas fa-ellipsis-v"
+    type={showMenu ? "primary" : "default"}
+    onclick={toggleMenu}
+  />
+  
+  {#if showMenu}
+    <div class="dropdown-menu">
+      <button on:click={editItem}>编辑</button>
+      <button on:click={duplicateItem}>复制</button>
+      <button on:click={deleteItem}>删除</button>
+    </div>
+  {/if}
+</div>
+```
+
+### 通知按钮
+
+```svelte
+<script>
+let notificationCount = 3;
+
+const handleNotifications = (event) => {
+  // 打开通知面板
+  openNotificationsPanel();
+};
+</script>
+
+<div class="notification-button">
+  <IconButton 
+    icon="fas fa-bell"
+    type={notificationCount > 0 ? "primary" : "default"}
+    onclick={handleNotifications}
+  />
+  {#if notificationCount > 0}
+    <span class="notification-badge">{notificationCount}</span>
+  {/if}
+</div>
+
+<style>
+  .notification-button {
+    position: relative;
+    display: inline-block;
+  }
+  
+  .notification-badge {
+    position: absolute;
+    top: -8px;
+    right: -8px;
+    background: #ff4444;
+    color: white;
+    border-radius: 50%;
+    width: 20px;
+    height: 20px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 10px;
+    font-weight: bold;
+  }
+</style>
+```
+
+### 媒体控件
+
+```svelte
+<script>
+let isPlaying = false;
+
+const togglePlay = (event) => {
+  isPlaying = !isPlaying;
+  if (isPlaying) {
+    startPlayback();
+  } else {
+    pausePlayback();
+  }
+};
+</script>
+
+<div class="media-controls">
+  <IconButton icon="fas fa-step-backward" onclick={previousTrack} />
+  <IconButton 
+    icon={isPlaying ? "fas fa-pause" : "fas fa-play"}
+    type="primary"
+    size="big"
+    onclick={togglePlay}
+  />
+  <IconButton icon="fas fa-step-forward" onclick={nextTrack} />
+</div>
+```
+
+## 无障碍访问
+
+IconButton组件遵循无障碍访问最佳实践：
+
+- 使用语义化的`<button>`元素
+- 支持键盘导航（Tab、Enter、Space键）
+- 正确的禁用状态处理
+- 为屏幕阅读器提供聚焦和失焦事件
+
+### 添加ARIA标签
+
+```svelte
+<!-- 为屏幕阅读器添加aria-label，当仅使用图标时 -->
+<IconButton 
+  icon="fas fa-search"
+  onclick={handleSearch}
+  style="aria-label: 搜索"
+/>
+
+<!-- 或使用title属性作为工具提示 -->
+<IconButton 
+  icon="fas fa-print"
+  onclick={handlePrint}
+  style="title: 打印文档"
+/>
+```
+
+## 样式定制
+
+组件使用以下CSS类：
+
+- `.uniface-button` - 基础按钮类
+- `.icon-button` - 图标按钮特定样式
+- `.{size}` - 尺寸特定样式（big、medium、mini）
+- `.{type}` - 类型特定样式（default、primary等）
+- `.disabled` - 禁用状态样式
+
+### CSS示例
+
+```css
+.uniface-button.icon-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  padding: 6px;
+  border: 1px solid #ddd;
+  background: #fff;
+  color: #333;
+  border-radius: 4px;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.uniface-button.icon-button:hover:not(.disabled) {
+  background: #f5f5f5;
+}
+
+.uniface-button.icon-button:focus {
+  outline: 2px solid #007acc;
+  outline-offset: 2px;
+}
+
+.uniface-button.icon-button.big {
+  width: 48px;
+  height: 48px;
+  padding: 12px;
+}
+
+.uniface-button.icon-button.mini {
+  width: 24px;
+  height: 24px;
+  padding: 4px;
+}
+
+.uniface-button.icon-button.primary {
+  background: #007acc;
+  color: white;
+  border-color: #007acc;
+}
+
+.uniface-button.icon-button.disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+```
+
+## 最佳实践
+
+1. **一致的图标库**: 在应用程序中使用一致的图标库（如FontAwesome）
+2. **适当的尺寸**: 根据上下文选择适当的尺寸（工具栏=mini/medium，主要操作=big）
+3. **无障碍访问**: 始终为屏幕阅读器提供aria-label或title
+4. **视觉反馈**: 使用不同类型来表示状态或重要性
+5. **分组**: 将相关的图标按钮组合在一起
+6. **工具提示**: 考虑添加工具提示以获得更好的用户体验
+7. **上下文**: 确保图标易于识别且符合上下文
+
+## 常见模式
+
+### 按钮组
+
+```svelte
+<div class="icon-button-group">
+  <IconButton icon="fas fa-align-left" onclick={alignLeft} />
+  <IconButton icon="fas fa-align-center" onclick={alignCenter} />
+  <IconButton icon="fas fa-align-right" onclick={alignRight} />
+</div>
+
+<style>
+  .icon-button-group {
+    display: flex;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    overflow: hidden;
+  }
+  
+  .icon-button-group :global(.uniface-button) {
+    border-radius: 0;
+    border-left: none;
+  }
+  
+  .icon-button-group :global(.uniface-button:first-child) {
+    border-left: 1px solid #ddd;
+  }
+</style>
+```
+
+### 浮动操作按钮
+
+```svelte
+<IconButton 
+  icon="fas fa-plus"
+  type="primary"
+  size="big"
+  onclick={addNewItem}
+  style="
+    position: fixed;
+    bottom: 20px;
+    right: 20px;
+    border-radius: 50%;
+    box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+  "
+/>
+```
+
+## 与工具提示集成
+
+```svelte
+<script>
+import Tooltip from '@ticatec/uniface-element/Tooltip';
+</script>
+
+<Tooltip text="保存文档">
+  <IconButton icon="fas fa-save" onclick={handleSave} />
+</Tooltip>
+```
+
+## 浏览器支持
+
+IconButton组件在支持以下特性的所有现代浏览器中工作：
+- ES6+ JavaScript
+- CSS Flexbox
+- 语义化按钮元素
+
+## 性能
+
+- 轻量级图标优先设计
+- 内置点击防抖
+- 高效的事件处理
+- 最小化DOM占用