WeChat Markdown 编辑器（md）微信公众号 SVG 动画设计：无 ID 冒泡编组交互的核心方法论与工程落地

WeChat Markdown 编辑器md微信公众号 SVG 动画设计无 ID 冒泡编组交互的核心方法论与工程落地【免费下载链接】md✍ WeChat Markdown Editor | 一款高度简洁的微信 Markdown 编辑器支持 Markdown 语法、自定义主题样式、内容管理、多图床、AI 助手等特性项目地址: https://gitcode.com/gh_mirrors/md10/md本文基于 mdWeChat Markdown Editor仓库内wechat-svg技能体系的核心原则文档系统讲解在微信公众号等强约束 SVG 环境中如何用纯 SVG无 JS、无块级 CSS、无id/class/defs依赖构建可靠的分层交互动画。你将掌握绝对父子链编组架构、世界层 / 遭遇层 / 触发层三分法、施加 → 抵消 → 再施加的变换串层策略以及仓库中真实工程实现微信粘贴净化管线如何验证与支撑这套方法论从而写出粘贴后不失效、可冒泡、可复用的微信 SVG 动画。背景为什么微信里的 SVG 需要一套独立方法论微信公众号后台对粘贴内容有严格的过滤策略id、class、defs、marker、foreignObject、href/url(#id)引用、块级 CSS 与 JS 动画都可能被裁剪或失效。这意味着浏览器里常见的靠 CSS 类名 JS 事件 defs复用的 SVG 动画写法在微信里几乎全部不可用。仓库在 .agents/skills/wechat-svg/SKILL.md 中明确列出了微信生态对AttributeName的白名单约束超出白名单的标签、指令或属性名可能在保存后被平台过滤元素Name说明animatex控制简单几何体 x 轴方向移动animatey控制简单几何体 y 轴方向移动animatewidth控制简单几何体宽度变化animateheight控制简单几何体高度变化animateopacity控制透明度变化数值通常为 0 到 1animated控制贝塞尔曲线补间表现可能有随机性animatepoints控制多边形补间表现可能有随机性animatestroke-width控制描边宽度animatestroke-linecap控制描边端点样式animatestroke-dashoffset控制描边偏移常用于线性遮罩/进度线animatefill控制填充色过渡变化setvisibility控制可见性visible/hidden/collapse/inheritanimateTransformtranslate控制路径和编组位移animateTransformscale控制路径和编组缩放可用于翻转animateTransformrotate控制路径和编组旋转animateTransformskewX控制 x 轴倾斜animateTransformskewY控制 y 轴倾斜animateMotionpath复杂轨迹动画可配合rotate定义朝向配套的禁用边界默认遵守不使用id、class、href/xlink:href含url(#id)引用、defs、embed、块级 CSS 与 JS 动画样式尽量以内联属性或style的最小必要形式书写。在这一强约束前提下core-principles.md 给出了一套自洽的交互设计方法论。它的核心洞察是真正有效的无 ID 冒泡交互不是看起来层很多而是一条从最外层到最深层连续不间断的父子链。下文逐条展开。一、绝对父子链原则一切方法论的基石无 ID 环境里没有选择器可用动画之间的协同只能依赖事件冒泡沿父子链传播。因此最外层到最深层之间必须是一条连续不间断的父子链透明触发器必须放在整条链的最底部任何平级断链都会让整套方法论失效。错误的示意很多g平行摆放、触发器只是在视觉上放在下面、某一层动画和触发器不是父子关系而是兄弟关系。正确目标只有一个每一层动画都在触发器的祖先链上。触发器透明矩形或透明组是最深层的接收者用户点击后事件逐级冒泡祖先链上的每一层animateTransform都因beginclick而被激活从而形成一次点击、整链响应的编组动画。从仓库工程实现可以印证这套结构的重要性apps/web/src/services/export/wechat-svg.ts 的净化管线在粘贴前会把 SVG 里所有id/class/defs全部剥除stripUnsupportedAttributes也就是说仓库自己产出的微信 SVG 也必须在无 ID 前提下自洽运行——这正是绝对父子链成为硬约束的原因。对应测试见 wechat-svg.test.ts 中 strips id, class and internal style tags 用例。二、世界层 / 遭遇层 / 触发层三分法为了让动画既宏大又可控把整条父子链按职责切分为三层世界层承担大场景运动例如背景上升、地面后退、天空密度变化。它是场景的参考系通常挂在链的上层。遭遇层承担单个事件对象例如气球、直升机、飞机、火箭、第二个 UFO。每个遭遇物是一个独立模块。触发层只负责接收事件并向上冒泡不负责视觉叙事。它位于最深层通常是一个全透明或极小不可见的元素点击命中后事件沿祖先链冒泡。分工的价值在于世界层负责镜头感遭遇层负责单个叙事对象触发层负责输入。三者各司其职任何一层都不越权动画时序才可预测。三、施加 → 抵消 → 再施加变换串层的三段式复杂变换串层时例如对象既要跟随世界层运动又要保持自身局部姿态固定采用三段式先施加外层参考系变化如世界层整体平移、背景上升在下一层抵消这段变化反向补偿让对象回到干净坐标基准再在更深层只对当前对象施加自己的局部运动旋转、摇摆、闪烁等。好处在于父层控制大结构子层拿回局部控制权更深层总能回到干净坐标系。这样后续对象不会继承前一个对象的轨迹、旋转、透明度或姿态残留——这正是每个遭遇物必须模块化闭环见下文的数学基础。仓库的静态图表净化同样体现了补偿思维wechat-svg.ts 在处理 PlantUML 超宽图时会先把 SVG 写死像素宽高、preserveAspectRatioxMidYMid meet再套上overflow-x: scroll的外层section实现微信可横向滑动wrapWidePlantUmlSvg注释标明same nested section pattern as markedSlider与 packages/core/src/extensions/slider.ts 中markedSlider渲染的横向滑动卡片是同一套补偿式布局思路。四、遭遇物必须模块化闭环每个遭遇物的最小结构是一个三段闭环g !-- 位移施加层 -- animateTransform ... / g !-- 姿态层 -- animateTransform ... / !-- 对象本体、文本卡、image -- /g g !-- 位移抵消层 -- animateTransform ... / !-- 下一个更深层模块 -- /g /g外层g施加位移世界层带来的参考系变化姿态层承载对象自身的旋转/缩放位移抵消层把坐标系还回去。这样设计后后续对象不会继承前一个对象的轨迹、旋转、透明度或姿态残留——每个遭遇物都是自包含、可独立替换的模块。这一点在image素材接入时尤其重要完整规范见 image-integration.mdimage只是视觉内容不应该自己决定时间轴时间轴、旋转、进场和冻结全部由外层g接管image必须属于某个对象模块不能脱链挂在 SVG 根部位置用x/y尺寸用width/height组级运动用外层transform不依赖外部 CSS 与响应式布局。标准结构来自 SKILL.md 与 image-integration.mdg animateTransform attributeNametransform typetranslate beginclick dur80s values... keyTimes... fillfreeze restartnever / g animateTransform attributeNametransform typerotate beginclick dur80s values... keyTimes... fillfreeze restartnever / image x0 y-800 width609 height639 href... / image x0 y-1500 width609 height634 href... / /g /g判断文本卡与image归属的标准不是看起来近不近而是是否应该共享同一轨迹和同一姿态二者都应属于同一对象的局部层级但不一定要放进同一最小组。五、交互模式必须全链统一推荐正式规范也是仓库 skill 中已验证的交互写法animateTransform beginclick dur30s fillfreeze restartnever ... /固定要求所有交互动画统一beginclick所有交互动画统一fillfreeze所有交互动画统一restartnever删除所有旧的touchend;mouseup回位链不允许主链是click、补偿层还是touchstart/touchend不允许提示文案、遮挡层、字幕层停留在旧交互语义交互模式一旦切换必须全文件统一不允许一部分层保留旧长按逻辑、一部分层改成 click-only。这条原则在工程测试里也有镜像wechat-svg.test.ts 的 does not let juice-inlined style fill override an explicit fillnone 等用例验证了净化结果里不允许新旧样式语义混存——同一份 SVG 输出必须语义自洽不能一部分属性来自 CSS、一部分来自内联而互相打架。六、局部效果必须就地收口以下效果只能包裹在最小局部范围里红灯闪烁尾焰呼吸发光小幅摇摆局部透明度变化原因opacity、visibility这类属性会沿父子链继承。如果把它们挂在公共父层深层对象会跟着一起透明、一起闪烁误伤更深层链路。正确做法是把这些局部效果压缩到对象姿态层内部的最小子组让影响范围严格限定在当前遭遇物。同样地仓库的静态净化在剥离 CSS 时会刻意保护fillnone这类关键语义见bakePaint中对显式none的优先保留以及 keeps flowchart edge fillnone so links are not painted as blobs 测试——原理一致局部语义不能被上层规则污染。七、全局收尾层也必须在链内常见误区视觉上想让字幕固定在屏幕中央就把它直接挂到 SVG 根部最外层。这会导致字幕虽然居中却脱离了整条父子链无法参与整体时序无法在点击后按keyTimes出现、无法与世界层/遭遇层协调。正确做法把收尾字幕接在最深层内部补偿组之后让它位于已经抵消完成的视口坐标层中这样既能稳定居中又不脱离方法论——它依然在触发器祖先链上只是其参考系已经被补偿为视口坐标。image-integration.md 对收尾字幕放最外层这一典型错误给出的修法完全相同把字幕接入最深层补偿后的内部视口坐标层。判断标准是它属于故事收尾的一部分仍然应该放进最深层链内而不是它看起来像 HUD 就放最外层。八、固定实施顺序新模块的标准流水线后续新模块一律按以下顺序实现避免先写动画、后补结构导致的返工判断属于世界层还是遭遇层先画静态本体搭施加层 / 姿态层 / 抵消层骨架计算时序与keyTimes再接文本卡、image、说明层最后统一检查交互模式、补偿层、最深层触发器。这套顺序与仓库净化管线sanitizeSvgForWeChat的执行顺序如出一辙wechat-svg.ts先展开 marker、展开use、烘焙渐变结构完整性再内联呈现属性、重映射墨色、转换 baseline呈现层最后统一尺寸、剥离不支持属性收尾检查——先结构、后动画、再统一检查是两边共同遵守的工程纪律。九、静态图表适配方法论在非动画场景的延伸虽然不是交互动画第三方静态 SVG如 Mermaid、PlantUML粘贴到微信时同样受白名单约束仓库的 SKILL.md 给出了固定修法现象原因修法箭头消失defsmarkerurl(#id)被过滤将 marker 展开为内联path/polygon移除marker-end图表过大width100%或 CSSmax-width被忽略按 viewBox 1:1 渲染设置显式像素width/height不超过正文栏可用宽度保留viewBox文字错位foreignObject兼容性差转为text/tspan或外层 HTMLsection这些修法在源码中有精确实现箭头展开expandMarkers会解析defs中的marker读取refX/refY/orient/markerUnits把 marker 图形克隆到线/路径终点并沿路径切向计算旋转角getLineAngleFromAttributes、getPathAngleFromElement找不到 marker 定义时还会用appendFallbackArrow按stroke-width * 4生成兜底三角形。测试 expands marker-end into inline graphics and removes defs 验证了defs、marker、marker-end全部被移除且出现内联path/polygon。显式像素尺寸仓库以WECHAT_MAX_WIDTH_PX 677微信正文栏最大宽度为上限fixMermaidDimensions/fixSvgDimensions将width/height写死为像素并保留viewBox超出上限按比例缩到 677 内。测试 sets explicit pixel dimensions capped for WeChat 与 scales oversized viewBox down to article width 均断言结果不含%且不超过 677。文字转义flattenMermaidHtmlLabels把foreignObject里的 HTML 标签转成真实text/tspan按行拆分并设置fill、font-size、text-anchor再对重叠的双向边标签做分离separateOverlappingMermaidEdgeLabelsconvertDominantBaselineToDy把dominant-baseline换算为dy偏移避免微信基线差异导致文字错位。测试 converts mermaid html labels to SVG text without extra dy offset、separates overlapping bidirectional state edge labels 均覆盖这些路径。十、仓库中的完整净化管线与排错顺序把上述方法论落到工程上仓库在导出到剪贴板时通过 clipboard.ts 依次调用prepareDiagramSvgsForWeChat在 SVG 仍保有defs时展开use图标、烘焙url(#gradient)渐变、烘焙 HTML 标签颜色、扁平化 Mermaid 标签、转换 baselinesanitizeSvgsForWeChat展开 marker 箭头、内联呈现属性、把深灰墨色重映射为currentColor适配微信深色模式、统一像素尺寸、剥离id/class/defs/styleprepareMathFormulasForWeChat对 KaTeX/MathJax 公式 SVG 保留defs与id仅将墨色改为currentColor以跟随正文文字色测试 skips MathJax formula SVGs (preserves ids and defs)、keeps currentColor so formulas follow WeChat text color in dark mode。无论手写交互动画还是净化第三方图表官方技能都推荐按固定顺序排查问题不要跳步是否还是绝对父子链触发器是否在最深层补偿层是否成对存在坐标是否跑出视口opacity/visibility是否误伤深层keyTimes与出现窗口静态 SVG是否仍依赖defs/id/ 百分比宽度。常见错误速查表错误现象修法平级g当深层结构事件链断回到单一路径父子链只施加不抵消后续对象继承前一层轨迹每个遭遇物补上抵消层局部闪烁挂在公共父层深层对象一起透明把opacity动画缩到最小局部组文案/字幕放错逻辑层视觉居中但脱离编组绑对象局部层或放最深层补偿后的视口坐标层交互模式半新半旧部分层仍用旧长按逻辑全链统一begin/fill/restartmarker 箭头依赖 defs粘贴后箭头消失内联展开箭头移除marker-endSVG 使用 width 100%粘贴后撑满编辑器写死像素宽高并保留 viewBoximage放在 SVG 根部图片脱离编组时间轴挂回对应遭遇物的姿态层或其内部子组image跟在错误的补偿层下面位置始终不对或跟随下一对象移动确认它位于当前对象姿态层内部而非下一对象补偿层之后只调x/y不看外层 transform怎么挪都不对先定外层轨迹再微调x/y总结微信强约束 SVG 环境的本质是用结构换能力既然不能用id/class/defs/JS就把所有协同关系显式编码进一条连续的父子链里。本文的八条核心原则——绝对父子链、世界/遭遇/触发三分法、施加 → 抵消 → 再施加、遭遇物模块化闭环、交互模式全链统一、局部效果就地收口、全局收尾层入链、固定实施顺序——共同构成一套可复用的设计系统。仓库在 apps/web/src/services/export/wechat-svg.ts 中的静态净化实现与 wechat-svg.test.ts 中的几十条用例正是这套方法论在真实工程中的验证样本手写动画遵守同一套父子链与补偿纪律静态图表遵守同一套内联、像素化、去依赖的净化纪律最终目标一致——粘贴进微信公众号后动画仍可点击冒泡、静态图不失真不丢箭头。延伸阅读技能入口 .agents/skills/wechat-svg/SKILL.md含 AttributeName 白名单与静态适配要点、.agents/skills/wechat-svg/references/image-integration.mdimage接入与典型陷阱、apps/web/src/services/export/wechat-svg.ts净化管线源码、apps/web/src/services/export/wechat-svg.test.ts行为级测试、apps/web/src/services/export/clipboard.ts导出调用链。【免费下载链接】md✍ WeChat Markdown Editor | 一款高度简洁的微信 Markdown 编辑器支持 Markdown 语法、自定义主题样式、内容管理、多图床、AI 助手等特性项目地址: https://gitcode.com/gh_mirrors/md10/md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考