---
name: wechat-svg-hotspots
description: 制作公众号SVG多热区点击渐显组件，在同一画面中分别打开短说明并返回，适用于流程图、作品注释和知识卡片。
metadata:
  version: "0.1.0"
---

# 多热区点击与返回

读者点击某个热区，在固定画面内打开对应说明，再点“返回”回到总图。每个说明都能重复打开。导出的文章片段使用内联 SVG 与 SMIL。

## 收集材料

需要 2～4 个热区的标题和说明。用户已有总图时，同时取得图片，以及每个热区在 600×600 画布上的 `x、y、width、height`。图片可用本地 PNG、JPEG、WebP 或 HTTPS 地址。未提供总图时，脚本生成原创的编号卡片总图。

标题、提示语、强调色和底色沿用文章风格。说明控制在六行以内，标题最多两行。承载长段正文时，正文继续放在组件下方。

## 生成

复制 [examples/hotspots.json](examples/hotspots.json) 并替换文字，然后执行。

```text
python <本Skill目录>/scripts/render.py --config <本次目录>/hotspots.json --out <本次目录>/hotspots.html --preview-out <本次目录>/hotspots-preview.html
```

默认每次生成独立事件 ID，同一文章可插入多个实例。需要稳定 ID 时使用 `--id-prefix`，每个实例采用不同值。前缀中的连字符会自动转为下划线，最终事件 ID 只含英文字母、数字和下划线，避免事件时间表达式产生歧义。选择前缀时按转换后的值区分实例。已有输出需要替换时使用 `--overwrite`。

输入示例包含必需字段。可选字段为 `hint`、`accent`、`background`、`base_image`。每个 `spots` 项可增加 `rect`，例如 `[40, 150, 520, 76]`，用于定位图片上的热区。图片以完整留边方式放在画布中，热区坐标按最终留边后的画面设置。局部热区采用透明触发框，编号标题仍显示在框内。

相对图片路径以配置文件目录为起点。脚本将本地光栅图嵌入结果。使用 HTTPS 图片时，检查接收端能否加载，并按编辑器实际要求转存素材。

## 实际检查

1. 预览初始总图，逐个点击热区，核对对应标题和说明。
2. 每次点“返回”，确认总图重新可点。同一热区再打开一次，检查内容和返回动作。
3. 在一页放两个实例，确认彼此的打开、关闭互不影响。
4. 检查 320px、375px 阅读宽度，核对文字和热区边界。
5. 按实际目标插入秀米，保存重开，再核对图层、动画事件和图片。公众号同步及手机微信点击另行取得实际结果。

2026-11-12 已完成生成与输入检查、独立使用、双实例隔离及320/375px真实鼠标测试。三个热区均可打开、返回并重复打开。独立秀米测试稿保存重开后，在秀米阅读预览中重复通过上述交互。公众号同步和手机微信点击待验证。

## 实现与来源

每个说明层同时用 `visibility="hidden"` 和内联样式 `visibility:hidden` 设置初始隐藏。热区点击开始该层的可见区间，“返回”按钮结束区间，恢复隐藏状态。说明层的背景和返回按钮采用 `pointer-events="visiblePainted"`，避免隐藏层拦截总图点击。说明层覆盖总图，回到总图后才会再次命中其他热区。独立 ID 用于隔离多个组件。

本次秀米保存后的 DOM 清理了 `data-*`、`aria-*` 和 `visibility` 属性，保留了内联初始样式及 `g[id]`、`set`、`animate`。复核时用保留的事件 ID 定位说明层，再检查实际计算样式与打开、返回动作。新导入路径继续核对其保存结果。

本组件代码和示例图形独立编写。调研参考了“多热区点击渐显（返回）”教程及作者关于返回热区、底图重复、同尺寸对齐的说明。[小红书教程 05](https://www.xiaohongshu.com/explore/674d2e98000000000702a8e0)

SMIL 事件、区间结束与可见性遵循 SVG 动画机制。编辑器可能清理相关属性，保存后继续核对。[W3C SVG 动画规范](https://www.w3.org/TR/SVG11/animate.html)

## 品牌演示与GIF

[查看可操作演示](examples/brand-preview.html) · [查看GIF](examples/demo.gif) · [读取品牌样式与素材](examples/brand-style.json)

1. 先看GIF选择效果，再读取 `examples/brand-style.json` 和 `examples/brand-component.html`，确认本组件的画布、配色及素材。
2. 按本次任务采用使用者自己的头像、账号资料、正文与配图。直接修改本地品牌HTML模板和相邻素材即可复用单项包。原有生成器的参数能力以本Skill正文为准。
3. 文字保留原生编辑。图片放在对应动画组或状态组里，保留事件ID、SMIL时序与透明点击区。同篇放多个实例时，分别生成独立ID并同步事件引用。
4. 修改后检查完整动作与返回，核对文字、图片和按钮边界，再检查目标编辑器中的保存结果。

本版已有600px浏览器操作／播放采集、320／375px布局检查，GIF记录与实际文件校验一致。

品牌输出的秀米保存重开、公众号同步与真实手机微信效果待按目标环境核对。
