Skip to content

以下是对 gc-qa-rag-frontend/src/common/utils.ts 文件的详细 Markdown 文档说明：

文档：utils.ts 代码详解

文件概述

本文件是前端项目中的通用工具库，包含了多个常用的实用函数，涵盖了 DOM 操作、剪贴板交互、URL 参数解析、日期格式化以及事件上报等功能。通过这些工具函数，可以极大地简化前端开发中的重复性工作，提高代码的可维护性和复用性。下面将对每个函数的实现原理、设计考虑和适用场景进行详细说明。

主要函数说明与原理分析

1. captureDivToClipboard

该异步函数的作用是将指定的 HTMLDivElement（可选地加上内外边距）渲染为图片，并复制到系统剪贴板。其实现流程如下：

  • 首先校验传入的元素是否为有效的 HTMLDivElement，防止类型错误。
  • 获取目标 div 的尺寸和位置，并根据传入的 padding 参数调整宽高，确保图片内容不会被裁剪。
  • 创建一个临时的 div 容器，将原始 div 克隆后插入其中，并设置合适的样式（如绝对定位、背景色、padding 等），以保证渲染效果和隔离性。
  • 使用 html2canvas 库将临时容器渲染为 canvas，并设置 scale 以适配高分辨率屏幕，useCORS 以支持跨域图片。
  • 渲染完成后，移除临时容器，避免污染 DOM。
  • 将 canvas 转换为 Blob，再通过 Clipboard API 复制到剪贴板，实现图片的跨应用粘贴。
  • 全流程采用 try-catch 包裹，确保异常被捕获并抛出，便于调用方处理。

设计考虑：
该函数充分考虑了跨浏览器兼容性（如 Clipboard API 的支持）、高分辨率适配、DOM 污染防护（临时节点及时移除）、异常处理等细节。适用于需要将页面局部内容以图片形式分享、保存或粘贴到其他应用的场景。

2. extractContentAfterDivider

该函数用于从文本中提取分隔符（---）之后的内容。其实现方式简单高效：

  • 查找分隔符在文本中的位置，如果存在且后面还有内容，则返回分隔符后的文本并去除首尾空白。
  • 如果未找到分隔符，则返回原始文本的去空白版本。

设计考虑：
适用于 Markdown、日志、配置等文本格式中，快速提取正文或特定分段内容。

3. copyToClipboard

该异步函数用于将文本内容复制到系统剪贴板。其实现分为两步：

  • 首先尝试使用现代浏览器的 navigator.clipboard.writeText API，若成功则直接返回。
  • 如果 API 不可用或失败，则回退到传统的 textarea + document.execCommand("copy") 方案。通过动态创建隐藏的 textarea，选中并执行复制命令，最后移除节点，保证兼容性。

设计考虑：
兼容新旧浏览器 API，确保在绝大多数环境下都能实现文本复制功能。异常处理和 DOM 清理也做得较为完善。

4. getUrlSearchArg

该函数用于获取当前页面 URL 中的查询参数值。其实现逻辑如下：

  • 优先判断 location.hash 是否存在（适配单页应用的 hash 路由），如果有则解析 hash 中的查询参数。
  • 否则解析标准的 location.search 查询参数。
  • 解析过程中使用 URLSearchParams，并通过异常捕获保证健壮性。

设计考虑：
兼容传统路由和 hash 路由两种场景，适用于前端路由参数解析、动态页面渲染等需求。

5. getDateStringByUnixTime

该函数将 Unix 时间戳（秒）转换为 [YYYY-MM-DD] 格式的日期字符串。其实现方式为：

  • 若未传入时间戳，直接返回空字符串。
  • 否则将时间戳转换为 Date 对象，提取年、月、日，并补零格式化，最终拼接为标准日期字符串。

设计考虑：
简化了时间戳到日期字符串的转换，适用于日志、消息、历史记录等场景的时间展示。

6. raise_gtag_event

该函数用于向全局 dataLayer 推送自定义事件，便于 Google Analytics（gtag.js）等埋点统计。其实现方式为：

  • 获取全局 dataLayer 数组（如不存在则新建空数组）。
  • 将事件名和参数对象推入 dataLayer，以便后续被埋点脚本采集。

设计考虑：
为埋点、统计、用户行为分析等场景提供了统一的事件上报接口，便于前端与数据分析系统对接。

总结

utils.ts 文件通过一系列高内聚、低耦合的工具函数，极大提升了前端开发的效率和代码质量。每个函数都针对实际开发中的常见需求，兼顾了易用性、兼容性和健壮性。无论是 DOM 操作、剪贴板交互，还是 URL 解析、日期格式化、埋点上报，都能在本工具库中找到高效、可靠的解决方案。建议在项目中广泛复用这些工具函数，减少重复劳动，提升开发体验。