初始化

2026-03-03 09:53:54 +08:00
commit 3f349a35a4
437 changed files with 65639 additions and 0 deletions
--- a/saiadmin-artd/src/directives/business/highlight.ts
+++ b/saiadmin-artd/src/directives/business/highlight.ts
@@ -0,0 +1,248 @@
+/**
+ * v-highlight 代码高亮指令
+ *
+ * 为代码块提供语法高亮、行号显示和一键复制功能。
+ * 基于 highlight.js 实现，支持多种编程语言的语法高亮。
+ *
+ * ## 主要功能
+ *
+ * - 语法高亮 - 使用 highlight.js 自动识别并高亮代码
+ * - 行号显示 - 自动为每行代码添加行号
+ * - 一键复制 - 提供复制按钮，点击即可复制代码（自动过滤行号）
+ * - 性能优化 - 批量处理代码块，避免阻塞渲染
+ * - 动态监听 - 使用 MutationObserver 监听新增代码块
+ * - 防重复处理 - 自动标记已处理的代码块，避免重复处理
+ *
+ * ## 使用示例
+ *
+ * ```vue
+ * <template>
+ *   <!-- 基础用法 -->
+ *   <div v-highlight v-html="codeContent"></div>
+ *
+ *   <!-- 配合 Markdown 渲染 -->
+ *   <div v-highlight>
+ *     <pre><code class="language-javascript">
+ *       const hello = 'world';
+ *       console.log(hello);
+ *     </code></pre>
+ *   </div>
+ * </template>
+ * ```
+ *
+ * ## 性能优化
+ *
+ * - 批量处理：每次处理 10 个代码块，避免长时间阻塞
+ * - 延迟处理：使用 requestAnimationFrame 分批处理
+ * - 重试机制：自动重试处理失败的代码块
+ * - 智能监听：只在有新代码块时才触发处理
+ *
+ * @module directives/highlight
+ * @author Art Design Pro Team
+ */
+
+import { App, Directive } from 'vue'
+import hljs from 'highlight.js'
+
+// 高亮代码
+function highlightCode(block: HTMLElement) {
+  hljs.highlightElement(block)
+}
+
+// 插入行号
+function insertLineNumbers(block: HTMLElement) {
+  const lines = block.innerHTML.split('\n')
+  const numberedLines = lines
+    .map((line, index) => {
+      return `<span class="line-number">${index + 1}</span> ${line}`
+    })
+    .join('\n')
+  block.innerHTML = numberedLines
+}
+
+// 添加复制按钮：调整 DOM 结构，将代码部分包裹在 .code-wrapper 内
+function addCopyButton(block: HTMLElement) {
+  const copyButton = document.createElement('i')
+  copyButton.className = 'copy-button'
+  copyButton.innerHTML =
+    '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24"><path fill="currentColor" d="M7 6V3a1 1 0 0 1 1-1h12a1 1 0 0 1 1 1v14a1 1 0 0 1-1 1h-3v3c0 .552-.45 1-1.007 1H4.007A1 1 0 0 1 3 21l.003-14c0-.552.45-1 1.006-1zM5.002 8L5 20h10V8zM9 6h8v10h2V4H9z"/></svg>'
+  copyButton.onclick = () => {
+    // 过滤掉行号，只复制代码内容
+    const codeContent = block.innerText.replace(/^\d+\s+/gm, '')
+    navigator.clipboard.writeText(codeContent).then(() => {
+      ElMessage.success('复制成功')
+    })
+  }
+
+  const preElement = block.parentElement
+  if (preElement) {
+    let codeWrapper: HTMLElement
+    // 如果代码块还没有被包裹，则创建包裹容器
+    if (!block.parentElement.classList.contains('code-wrapper')) {
+      codeWrapper = document.createElement('div')
+      codeWrapper.className = 'code-wrapper'
+      preElement.replaceChild(codeWrapper, block)
+      codeWrapper.appendChild(block)
+    } else {
+      codeWrapper = block.parentElement
+    }
+    // 将复制按钮添加到 pre 元素（而非 codeWrapper 内），这样它不会随滚动条滚动
+    preElement.appendChild(copyButton)
+  }
+}
+
+// 检查代码块是否已经被处理过
+function isBlockProcessed(block: HTMLElement): boolean {
+  return (
+    block.hasAttribute('data-highlighted') ||
+    !!block.querySelector('.line-number') ||
+    !!block.parentElement?.querySelector('.copy-button')
+  )
+}
+
+// 标记代码块为已处理
+function markBlockAsProcessed(block: HTMLElement) {
+  block.setAttribute('data-highlighted', 'true')
+}
+
+// 处理单个代码块
+function processBlock(block: HTMLElement) {
+  if (isBlockProcessed(block)) {
+    return
+  }
+
+  try {
+    highlightCode(block)
+    insertLineNumbers(block)
+    addCopyButton(block)
+    markBlockAsProcessed(block)
+  } catch (error) {
+    console.warn('处理代码块时出错:', error)
+  }
+}
+
+// 查找并处理所有代码块
+function processAllCodeBlocks(el: HTMLElement) {
+  const blocks = Array.from(el.querySelectorAll<HTMLElement>('pre code'))
+  const unprocessedBlocks = blocks.filter((block) => !isBlockProcessed(block))
+
+  if (unprocessedBlocks.length === 0) {
+    return
+  }
+
+  if (unprocessedBlocks.length <= 10) {
+    // 如果代码块数量少于等于10，直接处理所有代码块
+    unprocessedBlocks.forEach((block) => processBlock(block))
+  } else {
+    // 定义每次处理的代码块数
+    const batchSize = 10
+    let currentIndex = 0
+
+    const processBatch = () => {
+      const batch = unprocessedBlocks.slice(currentIndex, currentIndex + batchSize)
+
+      batch.forEach((block) => {
+        processBlock(block)
+      })
+
+      // 更新索引并继续处理下一批
+      currentIndex += batchSize
+      if (currentIndex < unprocessedBlocks.length) {
+        // 使用 requestAnimationFrame 确保下一帧再处理
+        requestAnimationFrame(processBatch)
+      }
+    }
+
+    // 开始处理第一批代码块
+    processBatch()
+  }
+}
+
+// 重试处理函数
+function retryProcessing(el: HTMLElement, maxRetries: number = 3, delay: number = 200) {
+  let retryCount = 0
+
+  const tryProcess = () => {
+    processAllCodeBlocks(el)
+
+    // 检查是否还有未处理的代码块
+    const remainingBlocks = Array.from(el.querySelectorAll<HTMLElement>('pre code')).filter(
+      (block) => !isBlockProcessed(block)
+    )
+
+    if (remainingBlocks.length > 0 && retryCount < maxRetries) {
+      retryCount++
+      setTimeout(tryProcess, delay * retryCount) // 递增延迟
+    }
+  }
+
+  tryProcess()
+}
+
+// 代码高亮、插入行号、复制按钮
+const highlightDirective: Directive<HTMLElement> = {
+  mounted(el: HTMLElement) {
+    // 立即尝试处理一次
+    processAllCodeBlocks(el)
+
+    // 延迟处理，确保 v-html 内容已经渲染
+    setTimeout(() => {
+      retryProcessing(el)
+    }, 100)
+
+    // 使用 MutationObserver 监听 DOM 变化
+    const observer = new MutationObserver((mutations) => {
+      let hasNewCodeBlocks = false
+
+      mutations.forEach((mutation) => {
+        if (mutation.type === 'childList') {
+          mutation.addedNodes.forEach((node) => {
+            if (node.nodeType === Node.ELEMENT_NODE) {
+              const element = node as HTMLElement
+              // 检查新添加的节点是否包含代码块
+              if (element.tagName === 'PRE' || element.querySelector('pre code')) {
+                hasNewCodeBlocks = true
+              }
+            }
+          })
+        }
+      })
+
+      if (hasNewCodeBlocks) {
+        // 延迟处理新添加的代码块
+        setTimeout(() => {
+          processAllCodeBlocks(el)
+        }, 50)
+      }
+    })
+
+    // 开始观察
+    observer.observe(el, {
+      childList: true,
+      subtree: true
+    })
+
+    // 将 observer 存储到元素上，以便在 unmounted 时清理
+    ;(el as any)._highlightObserver = observer
+  },
+
+  updated(el: HTMLElement) {
+    // 当组件更新时，重新处理代码块
+    setTimeout(() => {
+      processAllCodeBlocks(el)
+    }, 50)
+  },
+
+  unmounted(el: HTMLElement) {
+    // 清理 MutationObserver
+    const observer = (el as any)._highlightObserver
+    if (observer) {
+      observer.disconnect()
+      delete (el as any)._highlightObserver
+    }
+  }
+}
+
+export function setupHighlightDirective(app: App) {
+  app.directive('highlight', highlightDirective)
+}
--- a/saiadmin-artd/src/directives/business/ripple.ts
+++ b/saiadmin-artd/src/directives/business/ripple.ts
@@ -0,0 +1,114 @@
+/**
+ * v-ripple 水波纹效果指令
+ *
+ * 为元素添加 Material Design 风格的水波纹点击效果。
+ * 点击时从点击位置扩散出圆形水波纹动画，提升交互体验。
+ *
+ * ## 主要功能
+ *
+ * - 水波纹动画 - 点击时从点击位置扩散圆形波纹
+ * - 自适应大小 - 根据元素尺寸自动调整波纹大小和动画时长
+ * - 智能配色 - 自动识别按钮类型，使用合适的波纹颜色
+ * - 自定义颜色 - 支持通过参数自定义波纹颜色
+ * - 性能优化 - 使用 requestAnimationFrame 和自动清理机制
+ *
+ * ## 使用示例
+ *
+ * ```vue
+ * <template>
+ *   <!-- 基础用法 - 使用默认颜色 -->
+ *   <el-button v-ripple>点击我</el-button>
+ *
+ *   <!-- 自定义颜色 -->
+ *   <el-button v-ripple="{ color: 'rgba(255, 0, 0, 0.3)' }">自定义颜色</el-button>
+ *
+ *   <!-- 应用到任意元素 -->
+ *   <div v-ripple class="custom-card">卡片内容</div>
+ * </template>
+ * ```
+ *
+ * ## 颜色规则
+ *
+ * - 有色按钮（primary、success、warning 等）：使用白色半透明波纹
+ * - 默认按钮：使用主题色半透明波纹
+ * - 自定义：通过 color 参数指定任意颜色
+ *
+ * @module directives/ripple
+ * @author Art Design Pro Team
+ */
+
+import type { App, Directive, DirectiveBinding } from 'vue'
+
+export interface RippleOptions {
+  /** 水波纹颜色 */
+  color?: string
+}
+
+export const vRipple: Directive = {
+  mounted(el: HTMLElement, binding: DirectiveBinding) {
+    // 获取指令的配置参数
+    const options: RippleOptions = binding.value || {}
+
+    // 设置元素为相对定位，并隐藏溢出部分
+    el.style.position = 'relative'
+    el.style.overflow = 'hidden'
+
+    // 点击事件处理
+    el.addEventListener('mousedown', (e: MouseEvent) => {
+      const rect = el.getBoundingClientRect()
+      const left = e.clientX - rect.left
+      const top = e.clientY - rect.top
+
+      // 创建水波纹元素
+      const ripple = document.createElement('div')
+      const diameter = Math.max(el.clientWidth, el.clientHeight)
+      const radius = diameter / 2
+
+      // 根据直径计算动画时间（直径越大，动画时间越长）
+      const baseTime = 600 // 基础动画时间（毫秒）
+      const scaleFactor = 0.5 // 缩放因子
+      const animationDuration = baseTime + diameter * scaleFactor
+
+      // 设置水波纹的尺寸和位置
+      ripple.style.width = ripple.style.height = `${diameter}px`
+      ripple.style.left = `${left - radius}px`
+      ripple.style.top = `${top - radius}px`
+      ripple.style.position = 'absolute'
+      ripple.style.borderRadius = '50%'
+      ripple.style.pointerEvents = 'none'
+
+      // 判断是否为有色按钮（Element Plus 按钮类型）
+      const buttonTypes = ['primary', 'info', 'warning', 'danger', 'success'].map(
+        (type) => `el-button--${type}`
+      )
+      const isColoredButton = buttonTypes.some((type) => el.classList.contains(type))
+      const defaultColor = isColoredButton
+        ? 'rgba(255, 255, 255, 0.25)' // 有色按钮使用白色水波纹
+        : 'var(--el-color-primary-light-7)' // 默认按钮使用主题色水波纹
+
+      // 设置水波纹颜色、初始状态和过渡效果
+      ripple.style.backgroundColor = options.color || defaultColor
+      ripple.style.transform = 'scale(0)'
+      ripple.style.transition = `transform ${animationDuration}ms cubic-bezier(0.3, 0, 0.2, 1), opacity ${animationDuration}ms cubic-bezier(0.3, 0, 0.5, 1)`
+      ripple.style.zIndex = '1'
+
+      // 添加水波纹元素到DOM中
+      el.appendChild(ripple)
+
+      // 触发动画
+      requestAnimationFrame(() => {
+        ripple.style.transform = 'scale(2)'
+        ripple.style.opacity = '0'
+      })
+
+      // 动画结束后移除水波纹元素
+      setTimeout(() => {
+        ripple.remove()
+      }, animationDuration + 500) // 增加500ms缓冲时间
+    })
+  }
+}
+
+export function setupRippleDirective(app: App) {
+  app.directive('ripple', vRipple)
+}