wired-mat-icon 图标集生成指南：iconset-full.ts 的构建原理、not_converted.svg 的由来与维护实践

UI组件前端【免费下载链接】wired-elementsCollection of custom elements that appear hand drawn. Great for wireframes or a fun look.项目地址https://gitcode.com/gh_mirrors/wi/wired-elements点击查看免费下载本篇指南围绕 wired-elements 仓库中 experimental/wired-mat-icon/CONTRIBUTING.md 展开系统讲解 Material 手绘图标组件 wired-mat-icon 的内置图标集iconset-full.ts是如何从官方 SVG 雪碧图一键生成的深入剖析生成脚本的底层实现并解释not_converted.svg中那些无法转换的图标背后的技术原因与兼容性边界。读完你不仅能独立完成图标集的重新生成与更新还能理解 roughjs 路径渲染对 SVG 结构的硬性要求为后续扩展或二次开发打好基础。一、为什么需要维护 iconset-full.tswired-mat-icon是一个把 Material Icons 渲染成手绘hand drawn风格的 Web Component。它本身并不包含 SVG 源码而是把成百上千个图标各自的path数据集中存放在一个 TypeScript 文件里供组件在运行时按名称查找。这个文件就是 src/iconset/iconset-full.ts。打开它可以直观看到它的形态——一个名为ICON_SET的常量对象key 是图标名如adb、android、autorenewvalue 是对应 SVGpath元素的d属性值例如{adb:M5 16c0 3.87 ...,android:M6 18c0 .55 ..., ...}其类型定义在 src/iconset/index.ts 中export type SvgIconSet { [key: string]: string };同时该文件导出一个iconsetLoader工具函数它接收ICON_SET后返回一个按名字取 path的查询函数export const iconsetLoader (ICON_SET: SvgIconSet) (iconName?: string): string { if (iconName) { return ICON_SET[iconName]; } return ; }组件 src/WiredMatIcon.ts 正是这样消费它的const findSvgPath iconsetLoader(ICON_SET); set icon(value: string) { this._icon value; this._path findSvgPath(this.icon); // 运行时查表得到 d 属性 }每次icon属性变化组件都会用iconsetLoader从ICON_SET中查出对应的路径字符串再放进模板里的path d${this._path}/交给wired-icon渲染成手绘风格。因此iconset-full.ts就是整个组件的图标数据库它是否完整、格式是否正确直接决定了wired-mat-icon能用哪些图标。二、如何生成 iconset-full.ts一键脚本流程根据 CONTRIBUTING.md 的说明生成iconset-full.ts的完整流程如下。2.1 进入 generate 目录并运行生成命令npm run generate该命令实际执行的是 package.json 中定义的脚本scripts: { generate: serve ./generate }即用serve这个静态文件服务器把experimental/wired-mat-icon/generate目录作为站点根目录启动。由于该仓库目录本身就是一个独立的 npm 包有自己的 package.json在experimental/wired-mat-icon目录下直接执行即可。首次运行前需要先安装依赖serve位于 devDependencies 中。2.2 通过本地端口访问生成页面脚本启动后会监听5000 端口。在浏览器打开http://localhost:5000页面上会看到一个textarea文本域其中已经填充了iconset-full.ts的完整内容——这就是脚本实时生成的成果。2.3 把内容写入目标文件按文档中的做法把textarea里的内容复制出来写入文件iconset-full.ts即仓库中的 src/iconset/iconset-full.ts就完成了整个图标集的更新。这也是维护 FAQ给出的标准答案不需要手工编辑成千上万条 path 数据一切由生成页面代劳。三、生成脚本的底层原理源码级剖析npm run generate之所以能凭空产出iconset-full.ts靠的是 generate/index.html 中一段精悍的浏览器脚本。理解它有助于判断什么时候该重新生成、什么时候需要手工介入。3.1 数据来源官方 SVG 雪碧图generate目录下存放着从 Material Icons 官方下载的 SVG 雪碧图文件包括actions.svg、alert.svg、av.svg、communication.svg、content.svg、device.svg、editor.svg、file.svg、hardware.svg、image.svg、maps.svg、navigation.svg、notification.svg、places.svg、social.svg等十余个分类文件toggle.svg也出现在该目录中。以 actions.svg 为例其内部结构是把大量 24×24 的图标平铺在一张更大的画布上svg width360 height360 viewBox0 0 360 360 ... svg width24 height24 viewBox0 0 24 24 idic_3d_rotation_24px x24.../svg svg width24 height24 viewBox0 0 24 24 idic_accessibility_24px x240 y168.../svg ... /svg每个图标子节点都有形如ic_图标名_24px的id——这正是生成脚本解析的锚点。3.2 页面如何加载雪碧图index.html 用object标签把每个分类雪碧图加载进页面并隐藏它们style object { visibility: hidden; height: 0px; width: 0px; } /style object dataactions.svg typeimage/svgxml/object object dataalert.svg typeimage/svgxml/object !-- ...其余分类依次列出... --所有object加载完成后retrievePaths会在每个load事件里被回调。3.3 核心解析逻辑const retrievePaths function(object) { counter; const icons object.contentDocument.firstElementChild.getElementsByTagName(svg); const regex /ic_(.*)_24px/; // id 统一采用该格式 const result {}; for (icon of icons) { const id regex.exec(icon.getAttribute(id))[1]; // 去掉 ic_ 前缀和 _24px 后缀得到图标名 result[id] icon.lastElementChild.getAttribute(d); // 取最后一个子元素即 path的 d 属性 } let stringValue JSON.stringify(result); stringValue stringValue.substring(1, stringValue.length - 1); // 去掉首尾花括号 if (counter source.length) { stringValue };; // 最后一个分类收尾 } else { stringValue ,; // 其余分类用逗号拼接 } resultArea.value stringValue; }初始化时textarea 的初始值被设置为resultArea.value import { SvgIconSet } from ./index;export const ICON_SET: SvgIconSet {;随后各分类依次把自己的JSON片段拼接到}结尾之前最终形成完整的、可直接落盘的iconset-full.ts内容。3.4 为什么只取 pathroughjs 的输入约束脚本注释揭示了取舍逻辑viewBox几乎总是0 0 24 24因此不取宽高恒为 24因此不取x、y定位属性不感兴趣最终只需要path。这种只取d属性的做法并非偷懒而是由渲染链路决定的wired-icon组件见 experimental/wired-icon/src/WiredIcon.ts会把图标svg交给wiredSvg(svg, options)来自wired-lib来生成手绘轮廓。roughjs 的路径处理面向的是纯粹的path数据——一条d字符串就能完整描述图形。雪碧图中由circle、rect、多条 path 叠加等复杂结构构成的图标无法用单一的d属性承载也就无法走通这条渲染管线。四、not_converted.svg那些无法转换的图标这是 CONTRIBUTING.md 中第二个 FAQ 的主题也是维护者必须知道的知识点。4.1 文件是什么not_converted.svg 是生成过程的落选名单——它收集了因为结构原因无法被转换为iconset-full.ts条目的原始 SVG。它们静静地躺在那里等待有解决方案的人来处理。4.2 无法转换的两类原因根据文档说明原因主要有两类原因一SVG 结构超出单个 path的范畴。部分官方图标内部包含的不只是简单的path元素。它们可能由circle、rect、polygon或多条 path 组合而成例如 actions.svg 中的ic_accessible_24px就同时包含circle和path。生成脚本只提取icon.lastElementChild.getAttribute(d)即最后一个子元素的d属性对于这类混合结构要么提取不到完整图形要么需要编写大量额外代码才能把它们转换成 roughjs 兼容的 path——文档原话是it would have been a lot more code just to support those few icons为了支持这几个图标要付出大量额外代码。因此权衡之下它们被排除在图标集之外。原因二viewBox 尺寸不一致。部分图标使用的是0 0 26 24而非标准的0 0 24 24。由于组件渲染时把viewbox硬编码为-1 -1 24 26见 WiredMatIcon.ts 中的模板尺寸不一致的图标直接混入会导致缩放、定位错乱。文档的评价是Not worth the added code !不值得为此增加代码因此同样被放弃。4.3 对使用者的实际影响这两类弃用图标并不会在组件里报错——iconsetLoader 在查不到名字时返回空字符串图标会渲染成空白。README 的 Troubleshooting 章节中列出了一批无法渲染的图标名单如signal_wifi_statusbar_*、fiber_manual_record、pets、bubble_chart、brightness_1、pool等正是这些无法转换的图标的反映。如果你确实需要它们方向不是改组件而是改进生成脚本或手工补充转换逻辑把它们补进iconset-full.ts。五、生成产物的消费链路从 iconset-full.ts 到屏幕上的手绘图标为了让为什么这样生成更有体感这里梳理一下产物的完整消费链路查询wired-mat-icon的icon属性如android经iconsetLoader(ICON_SET)查表得到d字符串WiredMatIcon.ts。装配组件模板输出wired-icon .config${this.config}svg viewbox-1 -1 24 26 ...title${this.icon}/titlepath d${this._path}//svg/wired-icon。title同时作为无障碍标签。手绘化wired-icon在connectedCallback中调用wiredSvg(svg, {...DEFAULT_CONFIG, ...this.config})WiredIcon.ts用 roughjs 生成手绘线条。默认配置DEFAULT_CONFIG的roughness为0.1这也是 README 中默认粗糙度 0.1 在多数情况下最合适一说的出处。个性化config属性对象支持fillStyle、fill、hachureGap、fillWeight、strokeWidth等 roughjs 选项可以覆盖默认效果例如{fillStyle: zigzag, fill: #3B5998}。可以看出iconset-full.ts的质量直接决定了第 1 步能否查到正确的路径而生成脚本的正确性则决定了iconset-full.ts的质量——这就是维护这份 FAQ 的意义所在。六、维护实践与注意事项汇总什么时候重跑生成官方 Material Icons 图标库更新、需要新增图标时重跑npm run generate并按 2.3 节落盘即可。仓库是只读的此流程适用于你自己的本地副本或 fork。生成结果如何校验打开http://localhost:5000后先核对 textarea 首尾内容——应当以import { SvgIconSet } from ./index;export const ICON_SET: SvgIconSet {开头、以};结尾中间每个分类片段以逗号衔接否则说明某张雪碧图加载失败。遇到新图标没进去优先检查它是否出现在not_converted.svg中。若是说明该图标结构多元素组合或 26×24 viewBox不满足单 path约束需要额外转换逻辑而不是简单重跑。包体积提示iconset-full.ts是超大的单文件涵盖近千个图标路径README 也提醒该组件对打包体积影响很大生产环境可考虑使用更轻量的 wired-icon 按需引入。这是选择全量图标集这一设计时伴随的已知取舍。七、扩展阅读experimental/wired-mat-icon/README.md组件的安装、属性icon/config、样式与 JavaScript 用法。experimental/wired-mat-icon/src/iconset/index.tsSvgIconSet类型与iconsetLoader实现。experimental/wired-mat-icon/src/WiredMatIcon.ts组件如何消费图标集并装配 SVG。experimental/wired-icon/src/WiredIcon.ts底层手绘渲染入口与默认 roughness 配置。experimental/wired-mat-icon/package.jsongenerate脚本与依赖定义。赞分享UI组件前端【免费下载链接】wired-elementsCollection of custom elements that appear hand drawn. Great for wireframes or a fun look.项目地址https://gitcode.com/gh_mirrors/wi/wired-elements点击查看免费下载相关推荐Thorium macOS 图标构建指南从 PNG IconSet 到 .icns 的生成与品牌化落地Thorium macOS 图标构建指南从 PNG IconSet 到 .icns 的生成与品牌化落地 本篇围绕 logos/NEW/mac/gen/READ桌面应用跨平台Polymer iron-icon 图标组件完全指南src 属性、内置图标集与自定义 iconset 实战Polymer iron icon 图标组件完全指南src 属性、内置图标集与自定义 iconset 实战 iron icon 是 Polymer Iron示例工程前端Angular Material 图标组件mat-icon完全指南字体图标、SVG 图标与无障碍实践Angular Material 图标组件mat icon完全指南字体图标、SVG 图标与无障碍实践 mat icon 是 Angular Materia前端UI组件设计系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考