@ticatec/topside-elements 1.0.0

package/dist/general/button/IconButton_README_CN.md

@@ -0,0 +1,522 @@
+# IconButton 图标按钮组件
+
+专为基于图标的操作设计的按钮组件，为工具栏操作、导航控件和交互元素提供简洁紧凑的界面。
+
+## 功能特性
+
+- **图标优先设计**: 专为显示图标作为主要内容而优化
+- **多种类型**: 默认、主要、次要、第三级和第四级按钮样式
+- **尺寸选项**: 大、中、小三种尺寸
+- **工具提示支持**: 通过 `data-tip` 属性内置工具提示，支持 Markdown 格式
+- **键盘导航**: 默认 `tabindex={-1}`，取消 Tab 键停留，不影响表单等场景的顺序 Tab 聚焦；支持显式传入 `tabindex` 覆盖
+- **事件处理**: 支持点击事件
+- **无障碍访问**: 使用语义化按钮元素，支持禁用状态
+- **自定义样式**: 灵活的样式定制
+- **Snippet 支持**: 通过 children 属性支持自定义图标内容
+
+## 基本用法
+
+```svelte
+<script>
+import IconButton from '@ticatec/topside-elements/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' \| 'small'` | `'medium'` | 按钮尺寸 |
+| `style` | `string` | `''` | 自定义CSS样式 |
+| `icon` | `string` | `''` | 图标类名（如FontAwesome类） |
+| `theme` | `string` | - | 主题变体 |
+| `tooltip` | `string` | - | 工具提示文本（支持Markdown，使用 `\n` 换行） |
+| `onclick` | `(event: MouseEvent) => void` | - | 点击事件处理器 |
+| `children` | `Snippet` | - | 自定义图标内容片段 |
+| `tabindex` | `number` | `-1` | Tab 键导航顺序（默认为 -1，取消 Tab 键停留） |
+| `outer` | `boolean` | `true` | focused / active 状态时是否带外框（默认为 true，设为 false 时去除聚焦/激活外框） |
+
+## 按钮类型
+
+```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} />
+```
+
+## 工具提示支持
+
+IconButton 组件内置了工具提示功能。当鼠标悬停在按钮上时，会自动显示提示文字。
+
+```svelte
+<!-- 带工具提示的图标按钮 -->
+<IconButton icon="fas fa-save" tooltip="保存文档" type="primary" onclick={handleSave} />
+<IconButton icon="fas fa-download" tooltip="下载文件" onclick={handleDownload} />
+<IconButton icon="fas fa-trash" tooltip="删除项目" type="secondary" onclick={handleDelete} />
+
+<!-- 多行提示带 Markdown -->
+<IconButton
+  icon="fas fa-warning"
+  type="secondary"
+  tooltip="> **警告**：\n> 此操作无法撤销"
+  onclick={handleDangerousAction}
+/>
+
+<!-- 禁用状态的按钮不会显示提示 -->
+<IconButton icon="fas fa-print" tooltip="打印文档" disabled={true} />
+```
+
+**注意**：需要在应用中挂载 `Tooltip` 组件才能显示工具提示：
+
+```svelte
+<script>
+  import Tooltip from '@ticatec/topside-elements/Tooltip';
+</script>
+
+<Tooltip />
+<!-- 你的应用内容 -->
+```
+
+## 按钮尺寸
+
+```svelte
+<!-- 小型图标按钮 -->
+<IconButton icon="fas fa-search" size="small" 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}
+/>
+```
+
+## Snippet 用法
+
+使用 `children` 属性提供自定义图标内容：
+
+```svelte
+<!-- 自定义图标内容 -->
+<IconButton onclick={handleCustomAction}>
+  {#snippet children()}
+    <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>
+  {/snippet}
+</IconButton>
+
+<!-- 多个图标或复杂内容 -->
+<IconButton onclick={handleMultiAction}>
+  {#snippet children()}
+    <div class="multi-icon">
+      <i class="fas fa-plus"></i>
+      <i class="fas fa-file"></i>
+    </div>
+  {/snippet}
+</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>` 元素
+- 默认设置 `tabindex={-1}`，不接收 Tab 键聚焦，避免在工具栏或表格中产生大量无谓的 Tab 停顿
+- 支持按需显式指定 `tabindex`（例如 `tabindex={0}`）
+- 正确的禁用状态处理（禁用时始终不可聚焦）
+- 聚焦时显示可见的焦点指示器
+
+### 键盘导航
+
+- **Tab** - 默认跳过（`tabindex={-1}`）；若显式指定为 `0` 则可将焦点移入/移出按钮
+- **Enter / Space** - 焦点在按钮上时激活
+- **焦点可见** - 聚焦时显示外边框（4px），与按钮之间有 3px 透明间隙。外框颜色与按钮底色一致（primary 为蓝色、secondary 为红色等）
+
+### 添加 ARIA 标签
+
+```svelte
+<!-- 为屏幕阅读器添加 aria-label，当仅使用图标时 -->
+<IconButton
+  icon="fas fa-search"
+  tooltip="搜索产品"
+  onclick={handleSearch}
+  aria-label="搜索"
+/>
+
+<!-- 或使用 tooltip 也可以提供上下文 -->
+<IconButton
+  icon="fas fa-print"
+  tooltip="打印文档"
+  onclick={handlePrint}
+/>
+```
+
+## 样式定制
+
+组件使用以下 CSS 类：
+
+- `.topside-button` - 基础按钮类
+- `.icon-button` - 图标按钮特定样式
+- `.{size}` - 尺寸特定样式（big、medium、small）
+- `.{type}` - 类型特定样式（default、primary 等）
+- `.disabled` - 禁用状态样式
+
+### CSS 变量
+
+```css
+:root {
+  /* 图标按钮颜色 */
+  --icon-btn-bg: #ffffff;
+  --icon-btn-text: #374151;
+  --icon-btn-hover-bg: #f5f5f5;
+  --icon-btn-disabled-bg: #F1F5F9;
+  --icon-btn-disabled-text: #B3BCCA;
+}
+```
+
+### 嵌入式 CSS
+
+组件使用嵌入式 CSS（无需外部 SCSS 导入）。
+
+### 焦点状态
+
+键盘焦点使用 `:focus-visible` 伪类处理，仅在使用键盘（Tab）聚焦时显示焦点指示器。聚焦时显示与悬停状态相同的背景色。
+
+## 最佳实践
+
+1. **一致的图标库**: 在应用程序中使用一致的图标库（如 FontAwesome）
+2. **适当的尺寸**: 根据上下文选择适当的尺寸（工具栏=small/medium，主要操作=big）
+3. **无障碍访问**: 始终为屏幕阅读器提供 tooltip 或 aria-label
+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(.topside-button) {
+    border-radius: 0;
+    border-left: none;
+  }
+  
+  .icon-button-group :global(.topside-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);
+  "
+/>
+```
+
+## 浏览器支持
+
+IconButton组件在支持以下特性的所有现代浏览器中工作：
+- ES6+ JavaScript
+- CSS Flexbox
+- 语义化按钮元素
+
+## 性能
+
+- 轻量级图标优先设计
+- 内置点击防抖
+- 高效的事件处理
+- 最小化DOM占用