Wix 的自定义 HTML/JS（例如使用 html5-qrcode 进行扫码）与 Velo 后端环境相互隔离——前者运行在浏览器客户端，后者受到安全沙箱保护。如果尝试在纯前端中直接调用 wixData.insert()，会因跨域和权限问题被拒绝。那么，如何安全地将扫描结果存入数据库？答案是使用 postMessage 桥接，让前端只负责采集和传递数据，敏感操作留在受控的后端执行。
在 Wix 开发中，这是一个非常典型的场景：你有一个自定义 HTML 组件（比如用 html5-qrcode 库实现的二维码扫描器），需要将解码后的 URL 存入数据库。但 Velo 与前端 JS 之间严格隔离——Velo 的 API 只能在 Wix 页面代码或后端文件中使用，而 Custom Code 中的 JS 只是普通浏览器脚本，两者之间没有直接的通信通道。如果强行将 wixData.insert() 塞入前端代码，几乎必然会报错。
先明确几个核心判断：第一，绝对不能在前端直接调用数据库 API，即使代码看起来再简洁也不行；第二，postMessage + $w.htmlComponent.onmessage 是官方推荐的跨上下文通信方案，既安全又可控。下面直接上步骤，代码注释已经写得很详细，但我会把每个关键点再展开说明透彻。
✅ 实现步骤
1. 在 Velo 页面代码中监听消息
建议将这部分放在页面级的 JS 中（例如 backend/page.js 或 public/js/my-page.js）。核心逻辑是绑定一个 HTML Component 的 onMessage 事件，接收到前端发来的消息后再执行数据插入。注意，这里的组件 ID 必须与编辑器中手动添加的 HTML Component ID 一致。
// 注意：必须绑定到一个已存在的 HTML Component（如名为 'qrReceiver' 的自定义 HTML 组件）
$w.onReady(function () {
// 确保该组件已添加且 ID 匹配（例如：HTML Component 的 ID 设为 'qrReceiver'）
$w('#qrReceiver').onMessage((event) => {
const { data } = event;
// ✅ 严格校验消息来源与结构（安全关键！）
if (data?.type === 'QR_SCAN_RESULT' && typeof data.url === 'string' && data.url.trim()) {
const url = data.url.trim();
// 执行数据库写入（自动继承当前用户权限，支持角色/规则校验）
wixData.insert('scanned_instructions', { URL: url })
.then((result) => {
console.log('✅ QR 数据已存入集合:', result._id);
})
.catch((err) => {
console.error('❌ 插入失败:', err);
});
}
});
});
2. 在 Custom Code 的 HTML/JS 中触发 postMessage
这部分在 Wix 后台的「Settings → Advanced → Custom Code」中添加，放在 Site Header 或 Footer 均可。关键是要找到 HTML Component 的 iframe 元素，通过 contentWindow.postMessage 发送数据。别忘了在发送前确认组件已加载完成——可以使用 MutationObserver 或简单延时实现。
⚠️ 关键注意事项
- 安全第一：postMessage 的 targetOrigin 参数在生产环境下绝对不能使用
'*'，务必替换为你的 Wix 站点具体域名（例如'https://mysite.wixsite.com'）。否则任何站点都能向你的 iframe 发送消息，后果严重。 - 组件绑定：$w('#qrReceiver') 中的 qrReceiver 必须是你在编辑器中手动拖入的一个「HTML Component」，并将其 ID 设为 qrReceiver。这个组件可以是空的
，它唯一的用途就是充当通信桥梁——没有它，消息无法传入。
- 权限控制：所有数据库操作都在 Velo 上下文中执行，这意味着 Wix 的数据库权限规则（例如“仅登录用户可写”）会自动生效，比前端直连安全得多。你无需额外编写校验逻辑，但必须确保集合权限配置正确。
- 错误处理：Velo 端的 wixData.insert() 务必进行异常捕获并记录日志，方便排查。前端不需要等待响应，但如需反馈（例如显示“保存成功”），可以设计双向通信——在 Velo 中向 $w('#qrReceiver') 发回一条消息，前端再监听 message 事件。
✅ 总结
通过 postMessage 桥接自定义前端 JS 与 Velo，既满足了动态扫码录入的需求，又严格遵循了 Wix 的安全模型——敏感逻辑留在受控后端，前端只负责采集和传递。这个方案一旦跑通，后续扩展也非常方便：例如添加手动输入 URL 的文本框，或同时处理多种类型的数据，只需统一消息格式即可。这是 Wix 生态中调用 Velo 功能的标准、可靠且可扩展的方式。
