完善功能

src/utils/helper.ts

@@ -25,12 +25,21 @@ export const isMac = userAgent.includes("Macintosh");
 export const isLinux = userAgent.includes("Linux");
 export const isElectron = userAgent.includes("Electron");
 
-// 链接跳转
+/**
+ * 打开链接
+ * @param url 链接地址
+ * @param target 打开方式（_self 或 _blank）
+ */
 export const openLink = (url: string, target: "_self" | "_blank" = "_blank") => {
   window.open(url, target);
 };
 
-// 图标渲染
+/**
+ * 渲染图标
+ * @param iconName 图标名称
+ * @param option 图标选项（大小和样式）
+ * @returns 图标组件
+ */
 export const renderIcon = (
   iconName: string,
   option: {
@@ -52,7 +61,11 @@ export const sleep = (ms: number): Promise<void> => {
   return new Promise((resolve) => setTimeout(resolve, ms));
 };
 
-// 选项渲染
+/**
+ * 渲染选项
+ * @param param0 包含节点和选项的对象
+ * @returns 包含工具提示的节点
+ */
 export const renderOption = ({ node, option }: { node: VNode; option: SelectOption }) =>
   h(
     NTooltip,
@@ -63,7 +76,12 @@ export const renderOption = ({ node, option }: { node: VNode; option: SelectOpti
     },
   );
 
-// 模糊搜索
+/**
+ * 模糊搜索
+ * @param keyword 搜索关键词
+ * @param data 要搜索的数据数组
+ * @returns 包含匹配项的数组
+ */
 export const fuzzySearch = (keyword: string, data: SongType[]): SongType[] => {
   try {
     const result: SongType[] = [];
@@ -131,7 +149,10 @@ export const argbToRgb = (x: number): number[] => {
   return [r, g, b];
 };
 
-// 封面加载完成
+/**
+ * 封面加载完成时，设置透明度为 1
+ * @param e 事件对象
+ */
 export const coverLoaded = (e: Event) => {
   const target = e.target as HTMLElement | null;
   if (target && target.nodeType === Node.ELEMENT_NODE) {
@@ -139,7 +160,11 @@ export const coverLoaded = (e: Event) => {
   }
 };
 
-// 数字处理
+/**
+ * 格式化数字
+ * @param num 要格式化的数字
+ * @returns 格式化后的数字字符串
+ */
 export const formatNumber = (num: number): string => {
   if (num < 10000) {
     return num.toString();
@@ -150,7 +175,11 @@ export const formatNumber = (num: number): string => {
   }
 };
 
-// 文件大小处理
+/**
+ * 格式化文件大小
+ * @param bytes 文件大小（字节）
+ * @returns 格式化后的文件大小字符串
+ */
 export const formatFileSize = (bytes: number): string => {
   if (bytes < 1024) {
     return `${bytes} B`;
@@ -163,7 +192,11 @@ export const formatFileSize = (bytes: number): string => {
   }
 };
 
-// 将图片链接转为 BlobUrl
+/**
+ * 将图片链接转为 BlobUrl
+ * @param imageUrl 图片链接
+ * @returns BlobUrl
+ */
 export const convertImageUrlToBlobUrl = async (imageUrl: string) => {
   const response = await fetch(imageUrl);
   if (!response.ok) {
@@ -178,7 +211,12 @@ export const convertImageUrlToBlobUrl = async (imageUrl: string) => {
   return imageBlobURL;
 };
 
-// 复制文本
+/**
+ * 复制数据到剪贴板
+ * @param text 要复制的数据
+ * @param message 复制成功提示消息（可选）
+ * @returns 无
+ */
 export const copyData = async (text: any, message?: string) => {
   const { copy, copied, isSupported } = useClipboard({ legacy: true });
   if (!isSupported.value) {
@@ -201,7 +239,10 @@ export const copyData = async (text: any, message?: string) => {
   }
 };
 
-// 获取剪贴板内容
+/*
+ * 获取剪贴板内容
+ * @returns 剪贴板内容字符串或 null
+ */
 export const getClipboardData = async (): Promise<string | null> => {
   try {
     const text = await navigator.clipboard.readText();
@@ -241,7 +282,10 @@ export const formatForGlobalShortcut = (shortcut: string): string => {
     .join("+");
 };
 
-// 获取更新日志
+/**
+ * 获取更新日志
+ * @returns 更新日志数组
+ */
 export const getUpdateLog = async (): Promise<UpdateLogType[]> => {
   const result = await getCacheData(updateLog, { key: "updateLog", time: 10 });
   if (!result || isEmpty(result)) return [];
@@ -289,3 +333,15 @@ export const changeLocalPath = async (delIndex?: number) => {
     window.$message.error("更改本地歌曲文件夹出错，请重试");
   }
 };
+
+/**
+ * 洗牌数组（Fisher-Yates）
+ */
+export const shuffleArray = <T>(arr: T[]): T[] => {
+  const copy = arr.slice();
+  for (let i = copy.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [copy[i], copy[j]] = [copy[j], copy[i]];
+  }
+  return copy;
+};