Simple Iframe SDK

简单易用的 iframe 通信 SDK，提供六个核心 API，支持连接失败自动重试。

安装

``bash
npm install iframe-comlink-sdk
`

使用方法

$3

`javascript
import { AIAssistantSDK } from 'iframe-comlink-sdk'

const sdk = new AIAssistantSDK({
onSubmit: (data) => {
console.log('收到子页面数据:', data)
},
onSelect: (data) => {
console.log('收到子页面选择数据:', data)
// data 结构：{ customString?, businessType?, data: [{ label, value, originData? }] }
console.log('自定义回复内容:', data.customString)
console.log('业务类型:', data.businessType)
console.log('选择的项:', data.data)
},
getToken: () => {
return {
/* 商龙云token /
sly_token: 'xxx',
/* 组织ID /
orgId: 'yyy',
/* 组织类型: 0-门店, 1-集团 /
orgType: 0,
/* 账户ID /
accountId: 'zzz'
}
},
onOpenLink: (data) => {
console.log('收到子页面打开链接请求:', data)
// 处理打开链接逻辑，比如在新标签页中打开
if (data.url) {
window.open(data.url, '_blank')
}
}
})
`

OpenLinkData数据结构

SDK使用的OpenLinkData数据结构如下：

`typescript
interface OpenLinkData {
/* 必传，固定值 /
code: 'menuJump'
/* 必传 业务线跳自己菜单或者表单上时，对应着他们自己的菜单 code，sourceModule 他们肯定知道，业务线跳商龙云菜单时，需要商龙云同学告诉业务线同学对应的 menuId /
id: string
/* 非必传 业务线自己的菜单 id，打开业务线自己表单时，需要传 /
sourceId?: string
/* 必传 add:新建，edit:详情, menu:正常菜单跳转 /
type: 'add' | 'edit' | 'menu'
/* 非必传 跳转详情或者新建的时候(业务线/商龙云)，需要传此值， ---新建时为 add，详情时为 detailId /
detailId?: string
/* 非必传 跳转新建或者详情时(业务线/商龙云)，需要传 /
name?: string
/* 必传 商龙云：000， 供应链：010 新餐饮：012 老餐饮： 005 /
sourceCode: '000' | '010' | '012' | '005'
/* 非必传 新建或者详情时(业务线/商龙云)，需要传 /
url?: string
/* 非必传 跳转商龙云详情或者新建的时候，需要时传此值 /
query?: Record
/* 在业务线的新建或者编辑标签页时，点击保存或者保存并新建成功后，进行通讯时需要传此值，true:需要替换当前标签页(新建->编辑、 编辑->新建) /
replaceTab?: boolean
/* 业务线的新建或者编辑页签，离开或者关闭时，是否需要通知业务线进行更改校验，需要为 true /
formCheck?: boolean
/* 是否为报表类型的菜单 /
isReport?: boolean
}
`

SelectionData数据结构

SDK使用的SelectionData数据结构如下（用于 onSelect 方法）：

`typescript
interface SelectionItem {
/* 显示标签 /
label: string
/* 选择值（通常是id） /
value: string | number
/* 原始数据（业务方的完整数据） /
originData?: any
}

interface SelectionData {
/* 自定义字符串（用于自定义显示回复内容） /
customString?: string
/* 业务类型标识 /
businessType?: string
/* 选择的数据（支持单选和多选） /
data: SelectionItem[]
}
`

$3

#### 单选场景

`typescript
// 选择单个商品
await sdk.onSelect({
customString: '已选择商品：iPhone 15 Pro',
businessType: 'product',
data: [
{
label: 'iPhone 15 Pro',
value: 'P001',
originData: {
id: 'P001',
name: 'iPhone 15 Pro',
price: 8999,
stock: 100
}
}
]
})

// 选择单个客户
await sdk.onSelect({
customString: '已选择客户：张三',
businessType: 'customer',
data: [
{
label: '张三',
value: 'C001',
originData: {
id: 'C001',
name: '张三',
phone: '13800138000',
address: '北京市朝阳区'
}
}
]
})
`

#### 多选场景

`typescript
// 选择多个商品
await sdk.onSelect({
customString: '已选择3个商品',
businessType: 'product',
data: [
{
label: 'iPhone 15 Pro',
value: 'P001',
originData: { id: 'P001', name: 'iPhone 15 Pro', price: 8999 }
},
{
label: 'MacBook Pro',
value: 'P002',
originData: { id: 'P002', name: 'MacBook Pro', price: 12999 }
},
{
label: 'AirPods Pro',
value: 'P003',
originData: { id: 'P003', name: 'AirPods Pro', price: 1999 }
}
]
})

// 选择多个供应商
await sdk.onSelect({
customString: '已选择2个供应商',
businessType: 'supplier',
data: [
{
label: '供应商A',
value: 'S001',
originData: { id: 'S001', name: '供应商A', contact: '李四' }
},
{
label: '供应商B',
value: 'S002',
originData: { id: 'S002', name: '供应商B', contact: '王五' }
}
]
})
`

$3

`typescript
// 打开新建页面
await sdk.onOpenLink({
code: 'menuJump',
id: 'productModule',
type: 'add',
detailId: 'add',
name: '新建商品',
sourceCode: '000',
url: 'https://example.com/product/new',
formCheck: true
})

// 打开编辑页面
await sdk.onOpenLink({
code: 'menuJump',
id: 'productModule',
type: 'edit',
detailId: '12345',
name: '编辑商品',
sourceCode: '000',
url: 'https://example.com/product/edit/12345',
query: { readonly: false },
replaceTab: true,
formCheck: true
})

// 普通菜单跳转
await sdk.onOpenLink({
code: 'menuJump',
id: 'reportModule',
type: 'menu',
name: '销售报表',
sourceCode: '000',
isReport: true
})
`




$3

`javascript
import { AIAssistantSDK } from 'iframe-comlink-sdk'

const sdk = new AIAssistantSDK({
onSetToken: (tokenData) => {
console.log('收到父页面发送的token:', tokenData)
// 处理接收到的token数据
localStorage.setItem('currentTokens', JSON.stringify(tokenData))
}
})

// 🎯 智能等待：以下方法会自动等待SDK初始化完成，无需担心时序问题

// 发送数据给另一个子页面（双iframe模式）或父页面（单iframe模式）
await sdk.onSubmit({ message: 'hello' })

// 发送选择数据给另一个子页面（双iframe模式）或父页面（单iframe模式）
await sdk.onSelect({
customString: '已选择商品：iPhone 15 Pro',
businessType: 'product',
data: [{ label: 'iPhone 15 Pro', value: 'P001', originData: { id: 'P001', name: 'iPhone 15 Pro', price: 8999 } }]
})

// 请求父页面打开链接（自动等待初始化完成）
const result = await sdk.onOpenLink({
code: 'menuJump', // 必传，固定值
id: 'sourceModule', // 必传，菜单code或目标模块ID
sourceId: 'myMenuId', // 非必传，业务线自己的菜单ID
type: 'add', // 必传，操作类型：add-新建，edit-详情，menu-菜单跳转
detailId: 'add', // 非必传，新建时为'add'，详情时为具体ID
name: '新建商品', // 非必传，标签页名称
sourceCode: '000', // 必传，系统代码：000-商龙云，010-供应链，012-新餐饮，005-老餐饮
url: 'https://example.com/form', // 非必传，跳转URL
query: { productId: 123 }, // 非必传，查询参数
replaceTab: false, // 非必传，是否替换当前标签页
formCheck: true, // 非必传，离开时是否需要表单校验
isReport: false // 非必传，是否为报表类型
})
console.log('新页面返回的数据:', result)

// 获取父页面的token数据（自动等待初始化完成）
const tokens = await sdk.getToken()

// 获取另一个子页面或父页面的表单数据（自动等待初始化完成）
// 需要URL包含openlink_id参数
const formData = await sdk.getFormData()
console.log('获取到的表单数据:', formData)
`
`

API

$3


- linkSingleFrame(iframe) - 父页面连接单个iframe（支持onOpenLink功能）
- linkFrame(iframe1, iframe2) - 父页面连接两个 iframe（完整通信功能）
- retryConnection() - 父页面手动重试连接
- getConnectionStatus() - 获取当前连接状态

$3

- onSubmit(data) - 子页面发送数据给另一个子页面或父页面
- onSelect(data) - 子页面发送选择数据（SelectionData对象）给另一个子页面或父页面
- onOpenLink(data) - 子页面请求父页面打开链接，传入OpenLinkData对象
- getToken() - 子页面向父页面请求token数据
- getFormData() - 子页面获取另一个子页面或父页面的表单数据（需要URL包含openlink_id参数）
- setToken(iframe, tokenData) - 父页面向指定子页面发送token数据
- retryConnection() - 父页面手动重试连接
- getConnectionStatus() - 获取当前连接状态

重试机制

SDK 内置了连接失败重试机制：

- 默认重试3次，每次间隔2秒
- 可通过构造函数参数自定义重试次数和间隔
- 支持手动调用 retryConnection() 重新尝试连接
- 所有Comlink连接操作都会自动重试

AI助手环境检测

被AI助手嵌入或者打开的页面会有一个 openlink_id 的参数，可以用这个参数判断是否在AI助手中：

`javascript
// 检查是否在AI助手环境中
const urlParams = new URLSearchParams(window.location.search);
const isInAIAssistant = urlParams.has('openlink_id');

if (isInAIAssistant) {
console.log('当前页面运行在AI助手中');
const openlinkId = urlParams.get('openlink_id');
console.log('OpenLink ID:', openlinkId);
}
`

重试机制

SDK 内置了连接失败重试机制：

- 默认重试3次，每次间隔2秒
- 可通过构造函数参数自定义重试次数和间隔
- 支持手动调用 retryConnection() 重新尝试连接
- 所有Comlink连接操作都会自动重试

getFormData API

getFormData() 方法用于在子页面中获取另一个子页面或父页面的表单数据。

$3

现在 getFormData() 支持自动等待SDK初始化完成，确保在子页面完全初始化之前调用也能正常工作。

$3

- URL 校验：只有当前页面URL包含 openlink_id 参数时才能调用此方法
- 双向获取：可以获取另一个子页面的数据，或获取父页面的数据
- 自动降级：如果对等连接不可用，会自动尝试从父页面获取数据

$3

#### 父页面配置

`javascript
const sdk = new AIAssistantSDK({
getFormData: () => {
// 返回父页面的表单数据
return {
parentField1: 'value1',
parentField2: 'value2',
currentUser: localStorage.getItem('username')
}
}
})
`

#### 子页面配置

`javascript
const sdk = new AIAssistantSDK({
getFormData: () => {
// 返回当前子页面的表单数据
return {
username: document.querySelector('#username').value,
email: document.querySelector('#email').value,
selectedOption: document.querySelector('#option').value
}
}
})

// 在需要的时候获取另一个页面的表单数据
// 注意：只有URL包含openlink_id参数时才能调用
try {
const formData = await sdk.getFormData()
console.log('获取到的表单数据:', formData)

// 使用获取到的数据预填表单
if (formData.username) {
document.querySelector('#username').value = formData.username
}
} catch (error) {
console.error('获取表单数据失败:', error)
}
`

$3

1. 双iframe模式：子页面A → 子页面B 的表单数据
2. 单iframe模式：子页面 → 父页面 的表单数据
3. 连接降级：如果对等连接断开，自动切换到父页面数据源

$3

- 必须在URL包含 openlink_id 参数的页面中调用
- 需要配置对应的 getFormData 回调函数
- 数据会自动序列化，移除Vue等框架的Proxy包装
- 如果目标页面未配置回调或连接断开，会抛出错误


SDK使用的Token数据结构如下：

`typescript
interface TokenData {
/* 商龙云token /
sly_token: string;
/* 组织ID /
orgId: string;
/**
* orgType 可以是字符串或数字，表示组织类型
* 0 - 门店
* 1 - 集团
*/
orgType: string | number;
/* 账户ID /
accountId: string;
}
`

示例

查看 examples/` 目录下的完整示例。