CrossBridge 单页使用指南
本文档详细介绍如何在单个 HTML 页面 (如 index.html) 中直接使用 CrossBridge 插件，无需复杂的构建流程。特别适合简单的功能页面作为 iframe 被内嵌使用的场景。
📋 适用场景
- 独立功能页：一个只包含特定功能的 HTML 文件。
- 被 iframe 内嵌：作为子页面被主应用加载。
- 微前端模块：作为微应用独立部署。
🚀 快速开始
1. 基础 HTML 示例
创建一个简单的 index.html，直接引入 UMD 构建产物：
html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>CrossBridge 单页示例</title>
</head>
<body>
<div id="app">
<h1>功能子页面</h1>
<p>状态: <span id="status">未连接</span></p>
<button id="sendBtn">发送消息给父页面</button>
</div>
<!-- 引入 CrossBridge -->
<!-- 实际路径请根据部署情况调整，可以使用 CDN -->
<script src="./dist/cross-bridge.umd.js"></script>
<script>
// 1. 初始化
const bridge = new CrossBridge({
pageId: 'feature-page-1',
role: 'child', // 明确指定为子页面
adapters: ['postMessage'], // iframe 通信主要用 postMessage
debug: true
});
const statusEl = document.getElementById('status');
// 2. 连接
async function init() {
try {
await bridge.connect();
statusEl.textContent = '已连接';
statusEl.style.color = 'green';
// 通知父页面我已经准备好了
bridge.emit('child-ready', {
version: '1.0.0',
features: ['export', 'print']
});
} catch (err) {
statusEl.textContent = '连接失败';
statusEl.style.color = 'red';
console.error(err);
}
}
init();
// 3. 监听消息
bridge.on('parent-command', (data) => {
console.log('收到父页面指令:', data);
if (data.action === 'export') {
alert('正在执行导出...');
}
});
// 4. 发送消息
document.getElementById('sendBtn').onclick = () => {
bridge.emit('data-update', {
value: Math.random(),
timestamp: Date.now()
});
};
</script>
</body>
</html>2. 智能角色检测
让页面根据运行环境自动判断自己是独立运行还是被嵌入运行：
javascript
function detectConfig() {
// 检测是否在 iframe 中
const isInIframe = window !== window.parent;
// 或者从 URL 参数读取
const urlParams = new URLSearchParams(window.location.search);
const roleParam = urlParams.get('role');
if (roleParam) return roleParam;
return isInIframe ? 'child' : 'standalone';
}
const bridge = new CrossBridge({
pageId: 'auto-page-' + Date.now(),
role: detectConfig(),
adapters: ['postMessage', 'sharedWorker']
});🛠️ 进阶使用技巧
1. URL 参数控制
可以通过 URL 参数来动态控制页面的行为，使其更灵活：
URL 示例: http://example.com/page.html?role=child&debug=true&target=parent
javascript
const params = new URLSearchParams(location.search);
const bridge = new CrossBridge({
pageId: params.get('pageId') || 'default-page',
role: params.get('role') || 'standalone',
debug: params.get('debug') === 'true',
adapters: ['postMessage', 'sharedWorker']
});2. 资源清理
在单页应用中，注意在页面卸载时断开连接，避免内存泄漏：
javascript
window.addEventListener('beforeunload', () => {
bridge.disconnect();
});❓ 常见问题 (FAQ)
Q: 单页应用如何选择适配器？
- 被 iframe 内嵌: 必选
postMessage。 - 独立标签页: 推荐
sharedWorker(高效) 或broadcastChannel(兼容性好)。 - 混合场景: 同时配置
['postMessage', 'sharedWorker']，CrossBridge 会自动选择最优方案。
Q: 如何处理跨域？
CrossBridge 内部封装了跨域处理逻辑：
- 同域: 自动使用 SharedWorker 或 BroadcastChannel。
- 跨域: 如果配置了
websocket-relay或iframe-bridge，会自动切换到这些跨域适配器。
Q: 需要构建工具吗？
不需要。你可以直接使用 UMD 版本的 JS 文件 (dist/cross-bridge.umd.js)，就像引用 jQuery 一样简单。当然，如果你在使用 Vue/React，也可以通过 NPM 包导入使用。
📖 更多详细配置请参考 README.md 和 USGAE_EXAMPLES.md。