@coffic/cosy-ui 0.3.39 → 0.3.45

package/dist/components/navigation/TableOfContents.astro

@@ -1,12 +1,12 @@
 ---
 /**
  * @component TableOfContents
- * 
+ *
  * @description
  * TableOfContents 组件是一个目录导航组件，用于显示页面内容的标题结构。
  * 它会自动检测页面中的标题元素，生成目录列表，并在用户滚动页面时高亮当前可见的标题。
  * 当页面只有一个标题或没有足够的标题结构时，组件会自动隐藏。
- * 
+ *
  * @design
  * 设计理念：
  * 1. 导航辅助 - 帮助用户快速了解页面结构和导航到特定内容
@@ -15,37 +15,37 @@
  * 4. 响应式设计 - 在小屏幕设备上自动隐藏，优化空间利用
  * 5. 智能显示 - 当页面结构不需要目录时自动隐藏
  * 6. 多语言支持 - 支持多种语言显示，自动检测当前语言环境
- * 
+ *
  * @usage
  * 基本用法：
  * ```astro
  * <TableOfContents />
  * ```
- * 
+ *
  * 自定义标题和选择器：
  * ```astro
- * <TableOfContents 
- *   title="章节导航" 
- *   selector="h2, h3, h4" 
- *   maxDepth={4} 
+ * <TableOfContents
+ *   title="章节导航"
+ *   selector="h2, h3, h4"
+ *   maxDepth={4}
  * />
  * ```
- * 
+ *
  * 非固定位置：
  * ```astro
  * <TableOfContents fixed={false} />
  * ```
- * 
+ *
  * 指定内容容器：
  * ```astro
  * <TableOfContents containerSelector=".article-content" />
  * ```
- * 
+ *
  * 指定语言：
  * ```astro
  * <TableOfContents lang="zh-cn" />
  * ```
- * 
+ *
  * 启用日志：
  * ```astro
  * <TableOfContents enableLogging={true} />
@@ -58,56 +58,56 @@ import { getCurrentLanguage } from '../../utils/language';
 import { createTextGetter } from '../../utils/i18n';
 
 interface Props {
-  /**
-   * 是否固定在右侧
-   * @default true
-   */
-  fixed?: boolean;
-  /**
-   * 自定义类名
-   */
-  class?: string;
-  /**
-   * 标题选择器
-   * @default "h2, h3"
-   */
-  selector?: string;
-  /**
-   * 最大深度
-   * @default 3
-   */
-  maxDepth?: number;
-  /**
-   * 标题文本
-   * @default 根据语言自动选择
-   */
-  title?: string;
-  /**
-   * 内容容器选择器，用于限制标题搜索范围
-   * @default "main"
-   */
-  containerSelector?: string;
-  /**
-   * 显示目录所需的最少标题数量
-   * @default 2
-   */
-  minHeadings?: number;
-  /**
-   * 语言
-   * @default 自动检测
-   */
-  lang?: string;
+	/**
+	 * 是否固定在右侧
+	 * @default true
+	 */
+	fixed?: boolean;
+	/**
+	 * 自定义类名
+	 */
+	class?: string;
+	/**
+	 * 标题选择器
+	 * @default "h2, h3"
+	 */
+	selector?: string;
+	/**
+	 * 最大深度
+	 * @default 3
+	 */
+	maxDepth?: number;
+	/**
+	 * 标题文本
+	 * @default 根据语言自动选择
+	 */
+	title?: string;
+	/**
+	 * 内容容器选择器，用于限制标题搜索范围
+	 * @default "main"
+	 */
+	containerSelector?: string;
+	/**
+	 * 显示目录所需的最少标题数量
+	 * @default 2
+	 */
+	minHeadings?: number;
+	/**
+	 * 语言
+	 * @default 自动检测
+	 */
+	lang?: string;
 }
 
 const {
-  fixed = true,
-  class: className = '',
-  selector = 'h2, h3',
-  maxDepth = 3,
-  containerSelector = 'main',
-  minHeadings = 2,
-  lang: userLang,
-  title,
+	fixed = true,
+	class: className = '',
+	selector = 'h2, h3',
+	maxDepth = 3,
+	containerSelector = 'main',
+	minHeadings = 2,
+	lang: userLang,
+	title,
 } = Astro.props;
 
 // 获取当前语言
@@ -121,268 +121,281 @@ const titleText = title || t('title');
 const tocId = `toc-${Math.random().toString(36).substring(2, 9)}`;
 ---
 
-<aside class:list={[
-  'cosy:hidden cosy:xl:block cosy:w-64 cosy:shrink-0',
-  className
-]}>
-  <div class="cosy:top-16 cosy:sticky">
-    <div class={`toc-container ${fixed ? 'cosy:w-64' : 'cosy:w-full cosy:max-w-xs'}`} id={`${tocId}-container`} style="display: none;">
-      <div class="cosy:bg-base-100 cosy:shadow-xl cosy:card">
-        <div class="cosy:p-4 cosy:card-body">
-          <div class="cosy:mb-2 cosy:font-bold cosy:text-lg cosy:card-title">{titleText}</div>
-          <ul class="cosy:menu cosy:menu-sm" id={tocId}>
-            <!-- 目录项将通过 JavaScript 动态生成 -->
-            <li class="cosy:text-base-content/60">{t('loading')}</li>
-          </ul>
-        </div>
-      </div>
-    </div>
-  </div>
+<aside class:list={['cosy:hidden cosy:xl:block cosy:w-64 cosy:shrink-0', className]}>
+	<div class="cosy:top-18 cosy:sticky">
+		<div
+			class={`toc-container toc-scroll-container ${fixed ? 'cosy:w-64' : 'cosy:w-full cosy:max-w-xs'}`}
+			id={`${tocId}-container`}
+			style="display: none;">
+			<div class="cosy:bg-base-100 cosy:shadow-inner cosy:card">
+				<div class="cosy:p-4 cosy:card-body">
+					<div class="cosy:mb-2 cosy:font-bold cosy:text-lg cosy:card-title">{titleText}</div>
+					<ul class="cosy:menu cosy:menu-sm" id={tocId}>
+						<!-- 目录项将通过 JavaScript 动态生成 -->
+						<li class="cosy:text-base-content/60">{t('loading')}</li>
+					</ul>
+				</div>
+			</div>
+		</div>
+	</div>
 </aside>
 
 <script define:vars={{ selector, maxDepth, tocId, containerSelector, minHeadings, langInfo }}>
-  // 在页面加载完成后生成目录
-  function generateTOC() {
-    // 使用指定的容器选择器查找内容容器
-    const container = document.querySelector(containerSelector);
-    if (!container) return;
-    
-    // 排除 CodeExample 组件中的标题
-    const headings = Array.from(container.querySelectorAll(selector)).filter(heading => {
-      // 检查标题是否在 CodeExample 组件内
-      const isInCodeExample = heading.closest('.code-example') !== null;
-      return !isInCodeExample;
-    });
-    
-    const tocList = document.getElementById(tocId);
-    const tocContainer = document.getElementById(`${tocId}-container`);
-    
-    if (!tocList || !tocContainer) return;
-    
-    // 如果标题数量少于最小要求，保持隐藏状态并退出
-    if (headings.length < minHeadings) {
-      tocContainer.style.display = 'none';
-      return;
-    }
-    
-    // 显示目录容器
-    tocContainer.style.display = 'block';
-    
-    // 清空占位符
-    tocList.innerHTML = '';
-    
-    // 用于存储已使用的 ID，确保唯一性
-    const usedIds = new Set();
-    
-    // 为每个标题创建目录项
-    headings.forEach((heading) => {
-      // 如果标题没有 ID 或 ID 为空，则生成一个
-      if (!heading.id || heading.id.trim() === '') {
-        // 从标题文本生成 ID
-        let newId = generateIdFromText(heading.textContent || '');
-        
-        // 确保 ID 唯一
-        let counter = 0;
-        let uniqueId = newId;
-        while (usedIds.has(uniqueId) || document.getElementById(uniqueId)) {
-          counter++;
-          uniqueId = `${newId}-${counter}`;
-        }
-        
-        // 设置标题的 ID
-        heading.id = uniqueId;
-      }
-      
-      // 记录已使用的 ID
-      usedIds.add(heading.id);
-      
-      const level = parseInt(heading.tagName.substring(1));
-      if (level > maxDepth) return;
-      
-      const listItem = document.createElement('li');
-      listItem.className = `toc-level-${level}`;
-      listItem.dataset.headingId = heading.id;
-      
-      const link = document.createElement('a');
-      link.href = `#${heading.id}`;
-      link.textContent = heading.textContent;
-      link.className = 'cosy:text-base-content/80 cosy:hover:text-primary cosy:transition-colors';
-      
-      // 添加缩进
-      if (level === 3) {
-        link.style.paddingLeft = '1.5rem';
-      }
-      
-      listItem.appendChild(link);
-      tocList.appendChild(listItem);
-      
-      // 添加点击事件，平滑滚动到目标位置
-      link.addEventListener('click', (e) => {
-        e.preventDefault();
-        const targetId = link.getAttribute('href').substring(1);
-        const targetElement = document.getElementById(targetId);
-        
-        if (targetElement) {
-          // 滚动到目标位置，并添加一些偏移以避免被固定导航遮挡
-          const offset = 80; // 可根据实际情况调整
-          const targetPosition = targetElement.getBoundingClientRect().top + window.scrollY - offset;
-          
-          window.scrollTo({
-            top: targetPosition,
-            behavior: 'smooth'
-          });
-          
-          // 更新 URL，但不跳转
-          history.pushState(null, null, `#${targetId}`);
-          
-          // 添加高亮效果
-          setTimeout(() => {
-            highlightActiveHeading();
-          }, 500);
-        }
-      });
-    });
-    
-    // 如果没有找到标题或标题数量不足，隐藏目录
-    if (tocList.children.length < minHeadings) {
-      tocContainer.style.display = 'none';
-      return;
-    }
-    
-    // 添加活动标题高亮
-    highlightActiveHeading();
-    
-    // 使用节流函数优化滚动事件
-    window.addEventListener('scroll', throttle(highlightActiveHeading, 100));
-  }
-  
-  // 从文本生成有效的 ID
-  function generateIdFromText(text) {
-    return text
-      .trim()
-      .toLowerCase()
-      .replace(/[\s\n]+/g, '-') // 将空格和换行替换为连字符
-      .replace(/[^\w\u4e00-\u9fa5-]/g, '') // 只保留字母、数字、中文和连字符
-      .replace(/^-+|-+$/g, '') // 移除开头和结尾的连字符
-      .replace(/-{2,}/g, '-') // 将多个连字符替换为单个
-      || 'heading'; // 如果结果为空，则使用默认值
-  }
-  
-  // 节流函数，限制函数调用频率
-  function throttle(func, delay) {
-    let lastCall = 0;
-    return function(...args) {
-      const now = new Date().getTime();
-      if (now - lastCall < delay) {
-        return;
-      }
-      lastCall = now;
-      return func(...args);
-    };
-  }
-  
-  // 高亮当前可见的标题
-  function highlightActiveHeading() {
-    const tocContainer = document.getElementById(`${tocId}-container`);
-    if (!tocContainer || tocContainer.style.display === 'none') return;
-    
-    const container = document.querySelector(containerSelector);
-    if (!container) return;
-    
-    const headings = Array.from(container.querySelectorAll(selector));
-    if (headings.length < minHeadings) return;
-    
-    // 获取视口高度和滚动位置
-    const viewportHeight = window.innerHeight;
-    const scrollTop = window.scrollY;
-    
-    // 计算视口中心位置
-    const viewportMiddle = scrollTop + viewportHeight / 3;
-    
-    let activeHeadingId = null;
-    let closestHeading = null;
-    let closestDistance = Infinity;
-    
-    // 找到最接近视口中心的标题
-    for (const heading of headings) {
-      const headingTop = heading.getBoundingClientRect().top + scrollTop;
-      const distance = Math.abs(headingTop - viewportMiddle);
-      
-      if (distance < closestDistance) {
-        closestDistance = distance;
-        closestHeading = heading;
-      }
-    }
-    
-    // 如果找到了最接近的标题，使用它的ID
-    if (closestHeading) {
-      activeHeadingId = closestHeading.id;
-    } else if (headings.length > 0) {
-      // 如果没有找到，使用第一个标题
-      activeHeadingId = headings[0].id;
-    }
-    
-    // 更新活动链接样式
-    const tocLinks = document.querySelectorAll(`#${tocId} a`);
-    let hasActiveLink = false;
-    
-    tocLinks.forEach(link => {
-      const href = link.getAttribute('href').substring(1);
-      
-      // 清除所有高亮
-      link.classList.remove('cosy:text-primary', 'cosy:font-medium');
-      
-      // 添加当前活动标题的高亮
-      if (href === activeHeadingId) {
-        link.classList.add('cosy:text-primary', 'cosy:font-medium');
-        hasActiveLink = true;
-        
-        // 添加一个动画效果，使高亮更明显
-        link.animate([
-          { transform: 'translateX(-5px)' },
-          { transform: 'translateX(0)' }
-        ], {
-          duration: 300,
-          easing: 'ease-out'
-        });
-      }
-    });
-    
-    // 如果没有找到活动链接，尝试高亮第一个标题
-    if (!hasActiveLink && tocLinks.length > 0) {
-      tocLinks[0].classList.add('cosy:text-primary', 'cosy:font-medium');
-    }
-    
-    // 确保活动链接在视图中可见
-    const activeLink = document.querySelector(`#${tocId} a.cosy:text-primary`);
-    if (activeLink && tocList) {
-      const tocScrollContainer = document.querySelector('.cosy:fixed');
-      if (tocScrollContainer) {
-        const linkTop = activeLink.offsetTop;
-        const containerScrollTop = tocScrollContainer.scrollTop;
-        const containerHeight = tocScrollContainer.clientHeight;
-        
-        // 如果链接不在可视区域内，滚动到可见位置
-        if (linkTop < containerScrollTop || linkTop > containerScrollTop + containerHeight) {
-          tocScrollContainer.scrollTop = linkTop - containerHeight / 2;
-        }
-      }
-    }
-  }
-  
-  // 页面加载时初始化
-  document.addEventListener('astro:page-load', generateTOC);
-  // 初始加载时也初始化
-  generateTOC();
-  
-  // 添加resize事件监听，在窗口大小变化时重新计算高亮
-  window.addEventListener('resize', throttle(() => {
-    generateTOC(); // 重新生成TOC，以防窗口大小变化导致标题可见性变化
-    highlightActiveHeading();
-  }, 100));
-  
-  // 立即触发一次高亮计算
-  setTimeout(generateTOC, 100);
-  setTimeout(highlightActiveHeading, 500);
-</script>
+	// 在页面加载完成后生成目录
+	function generateTOC() {
+		// 使用指定的容器选择器查找内容容器
+		const container = document.querySelector(containerSelector);
+		if (!container) return;
+
+		// 排除 CodeExample 组件中的标题
+		const headings = Array.from(container.querySelectorAll(selector)).filter((heading) => {
+			// 检查标题是否在 CodeExample 组件内
+			const isInCodeExample = heading.closest('.code-example') !== null;
+			return !isInCodeExample;
+		});
+
+		const tocList = document.getElementById(tocId);
+		const tocContainer = document.getElementById(`${tocId}-container`);
+
+		if (!tocList || !tocContainer) return;
+
+		// 如果标题数量少于最小要求，保持隐藏状态并退出
+		if (headings.length < minHeadings) {
+			tocContainer.style.display = 'none';
+			return;
+		}
+
+		// 显示目录容器
+		tocContainer.style.display = 'block';
+
+		// 清空占位符
+		tocList.innerHTML = '';
+
+		// 用于存储已使用的 ID，确保唯一性
+		const usedIds = new Set();
+
+		// 为每个标题创建目录项
+		headings.forEach((heading) => {
+			// 如果标题没有 ID 或 ID 为空，则生成一个
+			if (!heading.id || heading.id.trim() === '') {
+				// 从标题文本生成 ID
+				let newId = generateIdFromText(heading.textContent || '');
+
+				// 确保 ID 唯一
+				let counter = 0;
+				let uniqueId = newId;
+				while (usedIds.has(uniqueId) || document.getElementById(uniqueId)) {
+					counter++;
+					uniqueId = `${newId}-${counter}`;
+				}
+
+				// 设置标题的 ID
+				heading.id = uniqueId;
+			}
+
+			// 记录已使用的 ID
+			usedIds.add(heading.id);
+
+			const level = parseInt(heading.tagName.substring(1));
+			if (level > maxDepth) return;
+
+			const listItem = document.createElement('li');
+			listItem.className = `toc-level-${level}`;
+			listItem.dataset.headingId = heading.id;
+
+			const link = document.createElement('a');
+			link.href = `#${heading.id}`;
+			link.textContent = heading.textContent;
+			link.className = 'cosy:text-base-content/80 cosy:hover:text-primary cosy:transition-colors';
+
+			// 添加缩进
+			if (level === 3) {
+				link.style.paddingLeft = '1.5rem';
+			}
+
+			listItem.appendChild(link);
+			tocList.appendChild(listItem);
+
+			// 添加点击事件，平滑滚动到目标位置
+			link.addEventListener('click', (e) => {
+				e.preventDefault();
+				const targetId = link.getAttribute('href').substring(1);
+				const targetElement = document.getElementById(targetId);
+
+				if (targetElement) {
+					// 滚动到目标位置，并添加一些偏移以避免被固定导航遮挡
+					const offset = 80; // 可根据实际情况调整
+					const targetPosition =
+						targetElement.getBoundingClientRect().top + window.scrollY - offset;
+
+					window.scrollTo({
+						top: targetPosition,
+						behavior: 'smooth',
+					});
+
+					// 更新 URL，但不跳转
+					history.pushState(null, null, `#${targetId}`);
+
+					// 添加高亮效果
+					setTimeout(() => {
+						highlightActiveHeading();
+					}, 500);
+				}
+			});
+		});
+
+		// 如果没有找到标题或标题数量不足，隐藏目录
+		if (tocList.children.length < minHeadings) {
+			tocContainer.style.display = 'none';
+			return;
+		}
+
+		// 添加活动标题高亮
+		highlightActiveHeading();
+
+		// 使用节流函数优化滚动事件
+		window.addEventListener('scroll', throttle(highlightActiveHeading, 200));
+	}
 
+	// 从文本生成有效的 ID
+	function generateIdFromText(text) {
+		return (
+			text
+				.trim()
+				.toLowerCase()
+				.replace(/[\s\n]+/g, '-') // 将空格和换行替换为连字符
+				.replace(/[^\w\u4e00-\u9fa5-]/g, '') // 只保留字母、数字、中文和连字符
+				.replace(/^-+|-+$/g, '') // 移除开头和结尾的连字符
+				.replace(/-{2,}/g, '-') || // 将多个连字符替换为单个
+			'heading'
+		); // 如果结果为空，则使用默认值
+	}
+
+	// 高亮当前可见的标题
+	function highlightActiveHeading() {
+		const tocContainer = document.getElementById(`${tocId}-container`);
+		if (!tocContainer || tocContainer.style.display === 'none') return;
+
+		const container = document.querySelector(containerSelector);
+		if (!container) return;
+
+		const headings = Array.from(container.querySelectorAll(selector));
+		if (headings.length < minHeadings) return;
+
+		// 获取视口高度和滚动位置
+		const viewportHeight = window.innerHeight;
+		const scrollTop = window.scrollY;
+
+		// 计算视口中心位置
+		const viewportMiddle = scrollTop + viewportHeight / 3;
+
+		let activeHeadingId = null;
+		let closestHeading = null;
+		let closestDistance = Infinity;
+
+		// 找到最接近视口中心的标题
+		for (const heading of headings) {
+			const headingTop = heading.getBoundingClientRect().top + scrollTop;
+			const distance = Math.abs(headingTop - viewportMiddle);
+
+			if (distance < closestDistance) {
+				closestDistance = distance;
+				closestHeading = heading;
+			}
+		}
+
+		// 如果找到了最接近的标题，使用它的ID
+		if (closestHeading) {
+			activeHeadingId = closestHeading.id;
+		} else if (headings.length > 0) {
+			// 如果没有找到，使用第一个标题
+			activeHeadingId = headings[0].id;
+		}
+
+		// 更新活动链接样式
+		const tocLinks = document.querySelectorAll(`#${tocId} a`);
+		let activeLink = document.querySelector(`#${tocId} a.active-toc-link`);
+		let currentActiveId = activeLink ? activeLink.getAttribute('href').substring(1) : null;
+
+		// 如果当前活动标题没有变化，避免不必要的样式更新
+		if (currentActiveId === activeHeadingId) {
+			return;
+		}
+
+		let hasActiveLink = false;
+
+		tocLinks.forEach((link) => {
+			const href = link.getAttribute('href').substring(1);
+
+			// 清除所有高亮
+			link.classList.remove('cosy:text-primary', 'cosy:font-medium', 'active-toc-link');
+
+			// 添加当前活动标题的高亮
+			if (href === activeHeadingId) {
+				link.classList.add('cosy:text-primary', 'cosy:font-medium', 'active-toc-link');
+				hasActiveLink = true;
+
+				// 只在首次高亮时添加一个轻微的过渡效果，而不是每次滚动都动画
+				if (href !== currentActiveId) {
+					link.style.transition = 'color 0.3s ease';
+				}
+			}
+		});
+
+		// 如果没有找到活动链接，尝试高亮第一个标题
+		if (!hasActiveLink && tocLinks.length > 0) {
+			tocLinks[0].classList.add('cosy:text-primary', 'cosy:font-medium', 'active-toc-link');
+		}
+
+		// 确保活动链接在视图中可见
+		const newActiveLink = document.querySelector(`#${tocId} a.active-toc-link`);
+		const tocList = document.getElementById(tocId);
+		if (newActiveLink && tocList) {
+			const tocScrollContainer = document.querySelector('.toc-scroll-container');
+			if (tocScrollContainer) {
+				const linkTop = newActiveLink.offsetTop;
+				const containerScrollTop = tocScrollContainer.scrollTop;
+				const containerHeight = tocScrollContainer.clientHeight;
+
+				// 如果链接不在可视区域内，平滑滚动到可见位置
+				if (linkTop < containerScrollTop || linkTop > containerScrollTop + containerHeight) {
+					tocScrollContainer.scrollTo({
+						top: linkTop - containerHeight / 2,
+						behavior: 'smooth',
+					});
+				}
+			}
+		}
+	}
+
+	// 节流函数，限制函数调用频率
+	function throttle(func, delay) {
+		let lastCall = 0;
+		return function (...args) {
+			const now = new Date().getTime();
+			if (now - lastCall < delay) {
+				return;
+			}
+			lastCall = now;
+			return func(...args);
+		};
+	}
+
+	// 页面加载时初始化
+	document.addEventListener('astro:page-load', generateTOC);
+	// 初始加载时也初始化
+	generateTOC();
+
+	// 添加resize事件监听，在窗口大小变化时重新计算高亮
+	window.addEventListener(
+		'resize',
+		throttle(() => {
+			generateTOC(); // 重新生成TOC，以防窗口大小变化导致标题可见性变化
+			highlightActiveHeading();
+		}, 200)
+	);
+
+	// 立即触发一次高亮计算
+	setTimeout(generateTOC, 100);
+	setTimeout(highlightActiveHeading, 500);
+</script>