在线调试
l2d-viewer 是一款面向 l2d 开发者的可视化调试工具，支持在浏览器中加载、预览和调试 Live2D 模型（Cubism 2 / Cubism 6）。本文档将带你完整了解每一项功能的使用方法。
点击前往：https://l2d-viewer.hacxy.cn
目录
界面概览
界面分为三个区域：
| 区域 | 说明 |
|---|---|
| 顶部栏 | 模型 URL 输入、加载状态、主题切换 |
| Canvas 画布 | Live2D 模型渲染区，支持拖拽移动 |
| 右侧边栏 | 变换控制 + 各调试面板 |
加载模型
通过 URL 输入框加载
在顶部栏的输入框中粘贴模型配置文件的 URL，支持以下格式：
- Cubism 2：
.model.json - Cubism 6：
.model3.json
- Cubism 2：
按下 Enter 键或点击 Load 按钮开始加载。
加载过程中，画布上会显示进度遮罩，顶部状态徽章会变为
loading状态。加载完成后，模型出现在画布中，状态变为
loaded，右侧各面板数据自动填充。
从历史记录加载
输入框支持下拉历史，点击输入框后会显示最近加载过的模型 URL（最多 20 条），直接点击即可重新加载，无需重新输入。
错误处理
若 URL 不可访问或格式有误，状态徽章会显示 error，并在画布区域展示错误提示。请检查 URL 是否正确、服务器是否允许跨域（CORS）。
变换控制
模型加载后，可以通过右侧边栏的变换控制区域调整模型的位置和大小。
X / Y 位置滑块
- X 轴：左右移动模型，范围
-2到2 - Y 轴：上下移动模型，范围
-2到2 - 拖动滑块时模型实时响应，代码预览也会同步更新
Scale 缩放滑块
- 调整模型的显示大小，范围
0.1到5 1为模型原始大小
鼠标拖拽移动
直接在画布上按住鼠标左键并拖动，模型会跟随鼠标移动，松手后位置锁定。右侧 X/Y 滑块数值也会同步更新。
重置按钮
点击重置按钮，将 X、Y、Scale 全部恢复为默认值（x=0, y=0, scale=1）。
表情面板
表情面板位于右侧边栏，默认收起，点击面板标题可展开。
播放表情
- 面板展开后显示模型支持的所有表情 ID
- 点击任意表情条目即可立即播放该表情
- 当前激活的表情会以绿色高亮标记
随机表情
点击面板内的 随机 按钮，工具会随机选择并播放一个表情，适合快速浏览模型支持的全部表情效果。
取消激活
再次点击已激活的表情，或等待表情动画结束，高亮状态自动消失。
动作面板
动作面板位于右侧边栏，默认展开。
动作分组
Live2D 模型的动作通常按组织分类（如 idle、tap_body 等）。面板以折叠组的形式展示，点击组名可展开该组下的所有动作文件。
播放动作
点击某个动作条目即可以最高优先级（priority=3）播放该动作。
播放进度条
动作播放期间，对应条目下方会出现一条蓝色进度条，实时展示播放进度（0% → 100%）。
自动展开
当某个动作正在播放时，其所在的分组会自动展开，方便定位当前动作。
参数面板
参数面板位于右侧边栏，默认收起，点击标题展开。
这是调试 Live2D 模型时最强大的功能之一，可以实时查看和修改所有模型参数。
实时参数值
面板通过 requestAnimationFrame 循环每帧读取模型参数，参数值会实时刷新。
搜索过滤
面板顶部有搜索框，输入参数 ID 的关键字（如 Eye、Mouth）即可过滤参数列表，快速定位目标参数。
活跃参数高亮
当某个动作正在播放时，被动作驱动的参数会以蓝色左边框标记，表示该参数当前处于活跃状态（即 value ≠ default）。这对于分析动作驱动了哪些参数非常有用。
手动调整参数
每个参数行都配有一个滑块，拖动可直接修改参数值，模型对应部位实时响应。
- 滑块范围由模型定义的
min/max决定 - 行尾的数值显示当前精确值（保留 3 位小数）
重置单个参数
每个参数行末尾有一个 ↺ 按钮，点击后将该参数值恢复为模型的 default 默认值。
Hit Area 覆盖层
Hit Area 是 Live2D 模型定义的可点击区域，用于响应用户的触摸/点击事件（如点击头部、身体触发不同动作）。
开启覆盖层
在右侧 Hit Area 面板中，点击显示覆盖层开关（或勾选框），画布上会立即出现绿色矩形边框，标注所有 Hit Area 的位置和大小。
- 矩形边框：绿色半透明填充 + 亮绿色描边
- 矩形左上角显示该区域的 名称（如
Head、Body） - 覆盖层不会遮挡鼠标事件，不影响正常交互
数据表格
Hit Area 面板展开后，下方显示一个数据表格，列出所有区域的原始坐标数据（x、y、w、h），均为相对于 canvas 尺寸的比例值（0~1）。
关闭覆盖层
再次点击开关即可隐藏覆盖层。
代码预览与复制
代码预览区块位于右侧变换控制下方，实时展示当前模型配置对应的 JavaScript 调用代码：
l2d.load({
path: 'https://example.com/model/model3.json',
position: [0.00, 0.00],
scale: 1.00,
})每当你调整 URL、位置或缩放时，代码会实时更新。
复制代码
点击代码块右上角的 复制 按钮，代码内容会复制到剪贴板，可直接粘贴到你的项目中使用。
10. 主题切换
顶部栏右侧有一个灯泡图标的主题切换按钮：
- 点击切换深色模式和浅色模式
- 主题偏好会自动保存，下次打开工具时保持上次的设置
URL 分享
l2d-viewer 支持通过 URL query string 传递模型地址，方便分享调试链接。
格式
https://your-deployment-url/viewer?model=<编码后的模型URL>使用方法
- 加载模型后，浏览器地址栏会自动更新为带
?model=参数的 URL - 直接复制浏览器地址栏中的 URL 发送给他人
- 对方访问该 URL 时，工具会自动加载对应模型，无需手动输入
使用技巧
调试动作驱动的参数
- 在动作面板中播放某个动作
- 打开参数面板
- 观察带蓝色高亮的参数——这些就是该动作正在驱动的参数
- 可以据此了解动作的实现方式，或验证参数映射是否正确
快速定位参数
模型参数可能多达数十甚至上百个。使用参数面板顶部的搜索框，输入 Eye、Mouth、Head 等关键字可快速过滤，无需手动翻滚列表。
验证 Hit Area 位置
开启 Hit Area 覆盖层后，可以直观核查各区域是否正确覆盖了模型对应部位（如点击头部区域是否确实在头部上方），避免在集成阶段才发现坐标偏差。
导出精确配置
调整好模型的位置和缩放后，使用代码预览一键复制配置代码，可以直接作为你项目中 l2d.load() 的调用参数，保证调试环境与生产环境的展示效果一致。
历史记录管理
历史下拉最多保存 20 条记录，自动去重，最新访问的地址排在最前面。如果某个测试模型不再需要，在新的模型加载后旧记录会随时间自动淘汰。