企业官网建设流程全解析

深入解析 Polymeriron-iconset-svg：定义可复用 SVG 图标集并动态注入图标

【免费下载链接】todomvcHelping you select a JavaScript framework - Todo apps for React.js, Angular, Vue and many more项目地址: https://gitcode.com/gh_mirrors/to/todomvc

导读

iron-iconset-svg是 Polymer（1.x）Iron 元素家族中负责管理 SVG 图标集合的核心组件：它允许开发者把一组矢量图标以<svg>/<defs>子节点的形式声明在iron-iconset-svg内部，并将其自动注册到全局 iconset 数据库，随后在任意元素中通过applyIcon/iron-icon按名称取出并注入使用。本文以仓库内 iron-iconset-svg 官方 README 为骨架，结合 iron-iconset-svg.html 源码实现、demo 与 测试用例，系统讲解图标集的定义方式、注册机制、克隆注入原理、viewBox与size的取值优先级，以及如何配合iron-icon完成主题化、着色与动画，帮助你在 Web Components / Polymer 应用中落地一整套自建矢量图标体系。

一、iron-iconset-svg是什么：为什么用 SVG 做图标

在开始写代码前，先明确这个组件的定位。根据 README 的说明，iron-iconset-svg允许用户定义包含 SVG 图标的专属图标集；SVG 图标元素应当是iron-iconset-svg元素的子节点，多个图标必须使用互不相同的id进行区分。

相比传统 JPG / PNG 位图，SVG 图标有三大天然优势（README 中明确列出，源码注释亦有相同描述，见 iron-iconset-svg.html）：

1. 矢量无损、分辨率无关：SVG 基于矢量描述，不依赖像素密度，在任何屏幕（含 Retina / HiDPI）上都保持清晰；
2. CSS 可样式化：图标颜色、描边等可被 CSS 覆盖；
3. 可主题化、可着色、甚至可动画：配合 CSS 变量与 transition 可做出丰富的视觉交互。

正因如此，它被用于构建一套“声明式、可检索、可复用”的图标注册表：定义一次，全局取用。

二、快速上手：定义一个自己的 SVG 图标集

2.1 引入组件

iron-iconset-svg的依赖声明在 bower.json 中：运行时依赖polymer（^1.0.0）与iron-meta（^1.0.0），开发依赖包括iron-icon、webcomponentsjs、web-component-tester等。使用前需通过 HTML Import 引入：

<link rel="import" href="../bower_components/iron-iconset-svg/iron-iconset-svg.html">

2.2 最小定义示例

README 给出的经典示例是将图标绘制在<svg><defs>内部的<g>上，并为其指定唯一id：

<iron-iconset-svg name="my-svg-icons" size="24"> <svg> <defs> <g id="shape"> <rect x="50" y="50" width="50" height="50" /> <circle cx="50" cy="50" r="50" /> </g> </defs> </svg> </iron-iconset-svg>

两个关键属性：

• name：图标集名称，随后会被注册进全局 iconset 数据库，其他元素通过"my-svg-icons:shape"这样的iconset:icon格式引用；
• size：单个图标的尺寸（逻辑单位），图标必须是正方形（源码注释明确："The size of an individual icon. Note that icons must be square."，见 iron-iconset-svg.html），默认值为24。

2.3 真实仓库 Demo：社交图标集

仓库的 demo/svg-sample-icons.html 展示了更真实的用法：一个size="100"、名为svg-sample-icons的图标集内含codepen、twitter、youtube三个图标，同时还有一个size="24"、名为inline的图标集定义shape图标：

<link rel="import" href="../../iron-icon/iron-icon.html"> <link rel="import" href="../iron-iconset-svg.html"> <iron-iconset-svg name="svg-sample-icons" size="100"> <svg> <defs> <g id="codepen"> <path class="outer-ring" d="M50,0C22.385,0,..."></path> <path class="inner-logo" d="M80.893,40.234,..."></path> </g> <path id="twitter" d="M100.001,17.942,..."></path> <g id="youtube"> <path class="youtube" d="M98.77,27.492,..."></path> </g> </defs> </svg> </iron-iconset-svg>

注意这里展示了两种合法形态：图标既可以包在<g id="...">里（内部还可按需要加class，方便后续对子路径分别着色），也可以直接是带id的<path>（如twitter）。_createIconMap的实现会对[id]选择器命中的所有子元素建索引，两种写法都会被收录。

对应的 demo/index.html 用iron-icon消费这些图标：

<iron-icon icon="svg-sample-icons:codepen"></iron-icon> <iron-icon icon="svg-sample-icons:twitter"></iron-icon> <iron-icon icon="svg-sample-icons:youtube"></iron-icon> <iron-icon icon="inline:shape"></iron-icon>

三、注册机制：iron-meta数据库与iron-iconset-added事件

定义好name后，图标集是如何做到“全局可用”的？核心在_nameChanged观察器中（iron-iconset-svg.html）：

_nameChanged: function() { new Polymer.IronMeta({type: 'iconset', key: this.name, value: this}); this.async(function() { this.fire('iron-iconset-added', this, {node: window}); }); }

这两行做了两件事：

1. 注册：以type: 'iconset'、key: 图标集名创建Polymer.IronMeta，把“名称 → iconset 实例”写入全局元数据库。iron-meta采用单态（monostate）模式，所有同type的元数据共享同一份存储（见 iron-meta.html 源码中的metaDatas单例）；
2. 广播：异步在window上触发iron-iconset-added事件，通知那些“先渲染、后等到图标集”的消费者（例如iron-icon在 iconset 尚未加载时会listen(window, 'iron-iconset-added', '_updateIcon')，收到事件后重试取图标）。

测试 test/iron-iconset-svg.html 正好验证了这两点：

test('it can be accessed via iron-meta', function () { expect(meta.byKey('foo')).to.be.equal(iconset); }); test('it fires an iron-iconset-added event on the window', function() { return loadedPromise; // 监听 window 上的 iron-iconset-added });

另外，attached回调会把自身display设为none（iron-iconset-svg.html），确保这个“纯定义型”元素不会在页面上渲染出任何可见盒子——测试同样断言getBoundingClientRect()的宽高均为 0。

四、按名称取用图标：applyIcon与removeIcon

README 描述了两步取用流程：先取得 iconset 实例，再调用applyIcon把指定图标应用到某个元素上，示例为iconset.applyIcon(iconNode, 'car')。

4.1 获取 iconset 实例

• 声明式：在页面中放一个<iron-meta type="iconset"></iron-meta>，随后调用meta.byKey('my-svg-icons')拿到 iconset（测试正是用meta.byKey('foo')断言注册结果）；
• 命令式：直接new Polymer.IronMeta({type: 'iconset'}).byKey('my-svg-icons')。

注：README 中提到的byId为早期 API 名称，当前仓库实现统一通过iron-meta的byKey检索；iron-icon内部也是走this._meta.byKey(this._iconsetName)（见 iron-icon.html）。

4.2applyIcon(element, iconName)做了什么

源码实现（iron-iconset-svg.html）：

applyIcon: function(element, iconName) { // 若元素有 shadowRoot，则把图标插入 shadowRoot，否则插入元素自身 element = element.root || element; // 先移除旧的 svg 图标，保证重复调用不叠加 this.removeIcon(element); // 克隆并安装新的 svg 图标 var svg = this._cloneIcon(iconName); if (svg) { var pde = Polymer.dom(element); pde.insertBefore(svg, pde.childNodes[0]); return element._svgIcon = svg; } return null; }

要点：

• 插入目标是元素的 shadow root（若存在）否则元素本身，且始终插到第一个子节点位置；
• 调用前会先removeIcon清理旧图标（element._svgIcon），因此同一元素反复applyIcon切换图标不会残留多个 SVG；
• 返回新安装的 SVG 元素，便于调用方继续操作；找不到匹配id时返回null。

4.3removeIcon(element)：撤销注入

removeIcon: function(element) { if (element._svgIcon) { Polymer.dom(element).removeChild(element._svgIcon); element._svgIcon = null; } }

applyIcon会把克隆体挂在element._svgIcon上，removeIcon据此精准移除并清空引用。测试 test/iron-iconset-svg.html 验证了applyIcon(div, 'circle')后div.firstElementChild变为可用节点。

4.4 枚举图标集内全部图标：getIconNames()

getIconNames: function() { this._icons = this._createIconMap(); return Object.keys(this._icons).map(function(n) { return this.name + ':' + n; }, this); }

返回形如['my-icons:circle', 'my-icons:square', 'my-icons:rect']的完整名称数组（测试 test/iron-iconset-svg.html 精确断言了这一结果），适合用于遍历、展示或调试图标资源清单。

五、图标如何被“注入”：克隆、viewBox与size的优先级

5.1 惰性建索引：_createIconMap

_cloneIcon使用“按需创建”策略：this._icons = this._icons || this._createIconMap();，因为图标集本身没有明确信号感知子节点何时解析完成（源码注释明确说明这一点）。索引表用Object.create(null)构建，避免继承Object.prototype上的成员（如 Firefox 的watch）干扰图标名查找（iron-iconset-svg.html）。

5.2_prepareSvgClone：从“定义”到“实例”

_prepareSvgClone: function(sourceSvg, size) { if (sourceSvg) { var content = sourceSvg.cloneNode(true), svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg'), viewBox = content.getAttribute('viewBox') || '0 0 ' + size + ' ' + size; svg.setAttribute('viewBox', viewBox); svg.setAttribute('preserveAspectRatio', 'xMidYMid meet'); svg.style.cssText = 'pointer-events: none; display: block; width: 100%; height: 100%;'; svg.appendChild(content).removeAttribute('id'); return svg; } return null; }

这里揭示了两个关键行为：

1. viewBox 优先于 size：若源图标自带viewBox（例如测试中的<symbol id="rect" viewBox="0 0 50 25">），则沿用源viewBox；否则按size生成'0 0 <size> <size>'。测试用两条用例精确锁定该优先级（test/iron-iconset-svg.html）：

test('prefers a viewBox attribute over the iconset size', function () { iconset.applyIcon(div, 'rect'); expect(div.firstElementChild.getAttribute('viewBox')).to.be.equal('0 0 50 25'); }); test('uses the iconset size when viewBox is not defined on the element', function () { iconset.applyIcon(div, 'circle'); expect(div.firstElementChild.getAttribute('viewBox')).to.be.equal('0 0 20 20'); });

2. 深克隆 + 去 id：cloneNode(true)复制原始定义（避免直接移动共享定义节点），克隆体的id被移除，防止同一id在 DOM 中重复出现；同时设置preserveAspectRatio="xMidYMid meet"保证缩放不失真。内联样式中的pointer-events: none是绕开 Chromium bug（注释指向 crbug.com/370136）的兼容处理。

六、与iron-icon组合：主题化、着色与动画

iron-iconset-svg定义资源，iron-icon负责展示。iron-icon通过icon="iconset:iconName"引用图标（iron-icon.html 中按:拆分出_iconsetName与_iconName，缺省 iconset 名时回退到'icons'），并通过 CSS 自定义属性完成外观控制：

仓库 demo/index.html 完整示范了“同一图标集、多种视觉”的玩法：

iron-icon { height: 64px; width: 64px; margin: auto 1em; transition: all 0.5s; -webkit-transition: all 0.5s; } iron-icon:nth-of-type(1) { fill: orange; } iron-icon:nth-of-type(2) { fill: green; } iron-icon:nth-of-type(3) { fill: navy; } iron-icon:nth-of-type(4) { fill: red; } iron-icon:hover { -webkit-filter: drop-shadow(2px 2px 2px var(--google-grey-700)); filter: drop-shadow(2px 2px 2px var(--google-grey-700)); }

配合fill直接给同一批codepen/twitter/youtube/shape图标分别着上橙、绿、藏青、红四色，并借助transition与悬停drop-shadow做出 0.5s 的平滑过渡动画——这正是 README 所说“icons can be themed, colorized, and even animated”的落地示范。

七、完整实战模板与常见问题

7.1 一个可运行的完整示例

把“定义 + 声明式消费 + 命令式消费”串起来：

<!doctype html> <html> <head> <meta charset="utf-8"> <script src="../bower_components/webcomponentsjs/webcomponents-lite.js"></script> <link rel="import" href="../bower_components/iron-iconset-svg/iron-iconset-svg.html"> <link rel="import" href="../bower_components/iron-icon/iron-icon.html"> <link rel="import" href="../bower_components/iron-meta/iron-meta.html"> </head> <body> <!-- 1. 定义图标集 --> <iron-iconset-svg name="my-svg-icons" size="24"> <svg> <defs> <g id="shape"> <rect x="12" y="0" width="12" height="24" /> <circle cx="12" cy="12" r="12" /> </g> </defs> </svg> </iron-iconset-svg> <!-- 2. 声明式消费 --> <iron-icon icon="my-svg-icons:shape"></iron-icon> <!-- 3. 命令式消费 --> <iron-meta type="iconset"></iron-meta> <div id="target"></div> <script> var meta = document.querySelector('iron-meta'); var iconset = meta.byKey('my-svg-icons'); var target = document.getElementById('target'); iconset.applyIcon(target, 'shape'); // 注入到 #target console.log(iconset.getIconNames()); // ["my-svg-icons:shape"] // iconset.removeIcon(target); // 需要时再移除 </script> </body> </html>

7.2 常见问题排查

• 图标不显示：确认<g>/<path>的id唯一且未被其他元素占用；iron-icon的icon属性必须是iconset名:icon名格式；确认iron-iconset-svg已通过 HTML Import 引入。
• 图标尺寸异常：图标必须是正方形；若个别图标自带viewBox，其优先于size（见第五节），不一致时会出现缩放差异。
• 图标集加载顺序问题：iron-icon会在window上监听iron-iconset-added事件，图标集异步到达后会自动重试更新，无需手动干预。
• 重复切换图标残留：不要绕过applyIcon手动插入 SVG，否则无法被removeIcon追踪；反复调用applyIcon本身是幂等安全的。

八、小结

iron-iconset-svg用一套极简声明式 API 完成了 SVG 图标资源从“定义 → 注册 → 检索 → 克隆注入 → 样式化”的完整闭环：name+size定义集合，iron-meta的iconset类型元数据库实现全局注册，iron-iconset-added事件解决异步加载竞态，applyIcon/removeIcon/getIconNames提供编程式操作接口，_prepareSvgClone以“viewBox 优先、size 兜底”的策略产出可直接挂载的 SVG 实例，最终由iron-icon借助 CSS 变量完成主题化与动画。无论你是为 Polymer 应用搭建统一的图标规范，还是想理解 Web Components 中“共享资源 + 动态注入”的设计范式，iron-iconset-svg 源码 与其 测试套件 都是极佳的学习样本。

【免费下载链接】todomvcHelping you select a JavaScript framework - Todo apps for React.js, Angular, Vue and many more项目地址: https://gitcode.com/gh_mirrors/to/todomvc