HandsomeDocs
    主题

事件、回调与调试

事件把用户操作连接到数据和业务能力。先在「接口与回调」定义 API 或回调，再在手动编辑器选择节点，进入「交互」配置事件与动作。

选择节点并配置触发事件
选择节点并配置触发事件点击图片放大

哪些操作能触发事件

事件按组件能力提供，交互面板中的可选列表是当前节点支持的范围。

类型常见触发
按钮、可操作节点点击、确认、取消
输入与搜索输入、变更、聚焦、失焦、回车、搜索、清空
选择与容器选择、打开、关闭、添加、移除、重排
表单提交、校验未通过
媒体加载、出错、播放、暂停、结束、进度变化
初始化打开时自动执行；点击事件也可选择打开作品时执行

不要把所有行为都写在点击中。例如输入搜索应考虑防抖，初始化取数应考虑打开事件，表单提交应处理无效输入。

一个事件可以执行多个动作

动作用途
调用已配置 API使用「接口与回调」中的定义，复用标识和响应示例
发起 HTTP 请求指定 URL、方法、查询参数、正文等
调用 JS 回调连接宿主已经实现并注册的函数
修改本地状态更新、重置或组合当前作品的数据
延迟在动作链中等待指定时长
发出自定义事件通知宿主页面发生了指定操作

动作按顺序执行，还可设置「成功后」「失败后」分支。例如搜索按钮先清空旧错误，再请求接口；成功后更新列表，失败后显示提示并提供重试。

参数从哪里来

事件参数使用 JSON。以下写法读取事件上下文，不能当作任意 JavaScript 使用：

写法代表什么
{"$state":"/keyword"}当前作品状态中的 keyword
{"$event":"/value"}触发事件携带的 value；具体字段以该事件为准
{"$result":"/"}当前动作链上一份执行结果
{"$error":"/message"}错误对象中的 message，常用于失败分支

例如将作品状态中的关键词作为接口参数：

{
  "keyword": { "$state": "/keyword" }
}

路径以 / 开头，名称大小写与响应一致。事件调试中的实际参数能帮助确认 /value 是否存在。

加载、结果、错误与重复操作

配置结果、加载与错误状态路径
配置结果、加载与错误状态路径点击图片放大

常见配置是结果 /response、加载 /loading、错误 /error。页面再根据这些值显示内容、加载提示和失败提示。

场景建议
用户快速输入进行搜索配置防抖，重复触发时采用新的执行并取消旧执行
点击提交或获取按钮执行期间显示加载，并避免重复提交
请求较慢设置合理超时；失败分支给出重试入口
多步骤请求逐步保存需要复用的结果，明确失败后如何恢复

界面会提供等待当前执行完成、采用最新执行等并发策略。取消旧执行依赖网络请求或回调对取消信号的支持；它不能撤销服务端已完成的业务操作。

JS 回调怎样才能真的执行

「接口与回调 → JS 回调」保存的是名称、用途和输入输出示例，不是函数实现。站点开发者需要在最终宿主页面注册同名函数；未接入时，工作台会显示无法调用的原因。

比如作品声明回调标识 site.notify，参数 {"message":"已完成"}。在已经放置灵构标签的主题页面中，可由站点开发者接入：

站点开发者：查看宿主回调接入示例
<lingui-component id="my-work" data-lingui="component-你的项目ID"></lingui-component>
<script>
  customElements.whenDefined('lingui-component').then(() => {
    const element = document.getElementById('my-work');
    element.interactions = {
      callbacks: {
        'site.notify': async (args, context) => {
          console.log(args.message);
          return { ok: true };
        },
      },
    };
  });
</script>

把占位项目 ID 替换为实际 ID，并由宿主实现需要的业务。回调可接收取消信号、读取和修改作品状态；本例只输出日志并返回结果。工作台预览会隔离站点业务处理器，因此请在实际接入页面验证宿主回调。

如果回调用于打开作品时自动执行，应由宿主在实例开始执行前准备好处理器。敏感业务的鉴权与权限判断仍由自己的服务端完成。

四种调试方式

展开预览下方「交互调试」，查看节点 ID、触发事件、动作、执行阶段、耗时、请求状态和状态变化。先检查输入参数，再检查接口结果是否写到了预期路径。

保存顺序

按三层保存

接口「保存配置」 → 事件「保存事件配置」 → 项目「保存项目 / 保存新版本」。

只测试接口或在预览中点过按钮，不会自动保存刚才的配置。