ow

uniapp/youjiala/src/md/custom-icon.md

@@ -0,0 +1,93 @@
+# 自定义图标：内联 SVG 字形与 iconfont 字体两条路线
+
+适用范围：`src/utils/transferGlyph.ts`、`selectGlyph.ts`、`folderGlyph.ts`、`sortGlyph.ts`（自绘字形四件套），`src/components/page-navbar`、`file-tab-filter`、`float-add-btn` 及文件页胶囊等使用处。
+uview-pro 组件接线通则见 [theme.md](./theme.md) 开头的 CSS 变量说明；路由见 [page-routing.md](./page-routing.md)。
+
+---
+
+## 1. 为什么需要自定义图标
+
+uview-pro 自带 `u-icon` 字体库（`custom-prefix="uicon"`）覆盖常见语义，但「传输列表、新建文件夹、降序排序、多选开关」这类云盘专属语义，内置库里要么没有、要么形不似（如用 `clock` 顶替传输被用户否掉）。项目现采用**内联 SVG 字形**方案：图标从 iconfont.cn 人工挑选，SVG path 提取进代码，`<image>` 渲染，零字体文件、零网络依赖。
+
+## 2. 字形文件的标准写法（四件套同一模板）
+
+每个字形一个 `src/utils/xxxGlyph.ts`，固定三段结构：
+
+```text
+/**
+ * XX 自定义字形（内联 SVG，不依赖 iconfont 字体文件）。
+ * 字形为用户从 iconfont.cn 挑选的「……」图标，原 fill 色改为按参数注入。
+ */
+/* 字形分段存（每个元素一条子路径）：单行超长拼接会撞 operator-linebreak/Prettier 对撞 */
+const XXX_SEGMENTS = [
+  "M860.761163 ...",   // 每条 <path> 的 d 一个数组元素
+  "M553.757495 ...",
+];
+
+export function xxxGlyph(color: string): string {
+  const d = XXX_SEGMENTS.join("");
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="${color}" d="${d}" /></svg>`;
+  return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+}
+```
+
+要点（都是踩过的坑）：
+
+- **fill 参数化**：iconfont 下载的 SVG 色值是写死的（`#1A98FF`/`#999999` 等），一律改成 `${color}` 注入——同一份 path 服务点亮/置灰/反白多态，不用 CSS mask（兼容性最好）；
+- **多 path 合并**：原图多条 `<path>` 的 `d` 拼成一条（本项目挑选的图标 fill 同色，可直接合并）；若真有双色图标则需保留多个 path 标签，暂未有需求；
+- **分段存数组**：`d` 串动辄上千字符，若写成 `const X = "..." + "..."` 多行拼接会触发 ESLint `operator-linebreak` 与编辑器 Prettier 重排的对撞，数组元素逐行存放两者都不动；
+- **viewBox 原样保留**：不要统一改成 1024 方形（sortGlyph 是 `0 0 1178 1024`），改了图形会变形。
+
+## 3. 调用点接线
+
+```text
+<script setup lang="ts">
+import { sortGlyph } from "@/utils/sortGlyph";
+/* 颜色固定，模块级生成一次（computed 仅在颜色随状态变化时用，如 page-navbar 的蓝灰切换） */
+const sortIconDark = sortGlyph("#1f2329");
+</script>
+
+<template>
+  <image class="xxx__tool-img" :src="sortIconDark" mode="aspectFit" />
+</template>
+```
+
+- 颜色**固定** → 模块级 `const`；颜色**随状态** → `computed`（见 `page-navbar` 的 `transferIcon`：有任务 `TRANSFER_ACTIVE_COLOR`，闲置 `#8f959e`）；
+- 组件顶层 `defineProps/defineEmits` 之前不许插业务语句（`vue/define-macros-order`），字形常量一律放 `defineEmits` 之后；
+- 尺寸按**视觉重量**给，不是按标称值：
+  - 图形撑满 viewBox 的（selectGlyph/sortGlyph）→ 与同行 `u-icon size=36` 同框（36×36rpx；sort 因 1.15:1 非方形给 38×33rpx）；
+  - 图形四周留白多的（folderGlyph 内容只占约 78%）→ 放大框到 46×46rpx 补偿，否则肉眼显小（用户已反馈过一次）。
+
+## 4. 现有字形清单
+
+| 文件 | 字形 | 使用处 | 色态 |
+| --- | --- | --- | --- |
+| `utils/transferGlyph.ts` | 文档+上下传输箭头 | navbar 传输入口、文件页悬浮胶囊 | 点亮 `#1A98FF`（导出 `TRANSFER_ACTIVE_COLOR`）/ 置灰 / 白 |
+| `utils/selectGlyph.ts` | 方框+右上箭头 | 工具栏多选开关（未进入态） | 深 `#1f2329`；进入后仍用 `u-icon close-circle` 蓝 |
+| `utils/folderGlyph.ts` | 文件夹+加号 | 工具栏新建文件夹 | 深 `#1f2329` |
+| `utils/sortGlyph.ts` | 三横线+下箭头 | 工具栏排序 | 深 `#1f2329` |
+
+## 5. 换/加一个图标的固定步骤
+
+1. 从 iconfont.cn 挑图，复制 SVG（含 `<path d>` 与 `viewBox`）；
+2. 按第 2 节模板新建（或替换）`src/utils/xxxGlyph.ts`；
+3. 调用点把 `<u-icon>` 换成 `<image :src mode="aspectFit">`，接字形常量；
+4. 对照第 3 节做尺寸视觉校正（留意原图留白比例与 viewBox 是否方形）；
+5. 验证：`npx vue-tsc --noEmit -p tsconfig.json` 退出码 0 + 浏览器 F5 目验同行图标大小一致。
+
+## 6. 备选路线：uview-pro 官方 customPrefix 字体方案
+
+官方文档 `uviewpro.cn/zh/guide/customIcon.html`。适合**一次引入大批图标且需要小程序端**的场景（小程序 `<image>` 不认 svg data URI，字体方案全端通吃）：
+
+1. 登录 iconfont.cn → 选图标加入项目 → 下载字体包（`iconfont.css` + `woff/ttf`）；
+2. 放 `src/static/font/`，改 `iconfont.css` 里 `@font-face` 的 `src` 路径（H5 建议 base64 内嵌，App/小程序指相对路径）；
+3. `App.vue` 里 `@import` 该 css（相对路径）；
+4. 使用：`<u-icon custom-prefix="my-icon" name="传输" />`——类名规则是 `custom-prefix + '-' + name`，非 `uicon` 前缀时组件直接挂 prefix 类。
+
+当前项目图标量少（4 个）且主战场 H5/App，未引入字体包；图标超过 ~10 个或要上微信/支付宝小程序时再迁，迁移只动调用点标签，`xxxGlyph.ts` 里的 path 可留作 css 生成源。
+
+## 7. 相关坑位备忘
+
+- `u-icon` 的 `name` 只认 uview-pro 字体库类名，写陌生名字**静默空白无告警**——新语义先翻 `node_modules/uview-pro/iconfont.css` 搜 `uicon-` 确认存在，没有就走本教程；
+- 组件 prop 名以 `node_modules` 内 `types.ts` 为准（如 `u-line-progress` 是 `percent` 不是 `percentage`），写错同样静默失效；
+- 字形改动后 H5 需 F5：data URI 在模块级常量里，HMR 不一定重跑 setup。