@pingansec/qixin.sharepublic.sdk

在页面指定容器中按 componentId 加载水滴企信「共享公开组件」（iframe），并支持传入鉴权 token、业务 props 与自定义 baseUrl。

本包为 ES 模块（"type": "module"），适用于 Vite、Webpack 等现代打包工具；需在 浏览器环境 中使用（依赖 document、fetch）。

安装

pnpm add @pingansec/qixin.sharepublic.sdk
# 或
npm install @pingansec/qixin.sharepublic.sdk

在 monorepo 中也可通过 workspace 协议引用本仓库内的包。

引入方式

1. 默认导入（推荐）

import SharePublicSDK from '@pingansec/qixin.sharepublic.sdk';

SharePublicSDK.init({
  containerId: 'embed-root',
  componentId: 'your-component-id',
  token: 'optional-token',
  props: { foo: 'bar' },
}).then(instance => {
  // iframe 已挂载
});

2. 命名导入

import { init, BASE_URL } from '@pingansec/qixin.sharepublic.sdk';

// 未传 baseUrl 时使用模块内置的 BASE_URL（与默认导出上的常量一致）
init({
  containerId: 'embed-root',
  componentId: 'your-component-id',
});

3. 仅执行副作用（挂载全局）

import '@pingansec/qixin.sharepublic.sdk';
// 等价于在 globalThis 上挂载：globalThis.QixinSharePublicSDK = { init, BASE_URL }

window.QixinSharePublicSDK.init({
  /* ... */
});

init(options)

| 字段 | 类型 | 必填 | 说明 | | ------------- | ------------------------- | ---- | ---------------------------------------------------------------- | | containerId | string | HTMLElement | 是 | 容器元素 id，或直接传入 DOM 节点 | | componentId | string | 是 | 组件 id | | token | string | 否 | 会作为查询参数拼到 iframe 地址上 | | props | object | 否 | 键值对会编码进 iframe URL；对象/数组会 JSON.stringify 后再编码 | | baseUrl | string | 否 | 接口根地址，默认使用导出对象上的 BASE_URL（见下） |

流程简述：请求 {baseUrl}/api/v1/developer/components/detail?component_id=... 拉取组件详情，校验为 iframe 类型后创建 iframe 并写入容器。

返回值：Promise，resolve 为组件实例（见下）；失败时 reject（网络错误、非 200 业务码、非 iframe 类型等）。

默认 BASE_URL：https://qixin.shuidi.cn/（导出为 SharePublicSDK.BASE_URL 或命名导出 BASE_URL）。

组件实例

init resolve 后得到：

| 属性 / 方法 | 说明 | | --------------------------------- | ------------------------------------------------------------------------- | | iframe | 创建的 HTMLIFrameElement | | componentId | 传入的组件 id | | methods | 服务端返回的可用方法名映射（供 callMethod 校验） | | callMethod(methodName, params?) | 通过 postMessage 调用 iframe 内方法；返回 Promise（成功时表示已发送） | | on(eventName, callback) | 监听 iframe 通过 postMessage 上报的事件；返回取消监听的函数 |

TypeScript

包内已自带 TypeScript 类型声明（sharepublicsdk.d.ts）。TypeScript 项目中可以直接 import 使用，无需再额外补写 declare module。

import SharePublicSDK, { init, BASE_URL } from '@pingansec/qixin.sharepublic.sdk';
import type { QixinSharePublicInitOptions } from '@pingansec/qixin.sharepublic.sdk';

const options: QixinSharePublicInitOptions = {
  containerId: 'embed-root',
  componentId: 'your-component-id',
  token: 'optional-token',
  props: { foo: 'bar' },
};

// 推荐：默认导出对象方式
SharePublicSDK.init(options);

// 或：命名导出方式
init(options);

如果某些仓库仍残留了应用侧的 declare module '@pingansec/qixin.sharepublic.sdk' 声明，建议在确认无冲突后逐步移除，统一以包内类型为准。

与 shuidi.sharepublic.sdk 的区别

npm 上的 shuidi.sharepublic.sdk 是另一条发布线与接口形态；本包 @pingansec/qixin.sharepublic.sdk 面向水滴企信开发者组件详情接口（/api/v1/developer/components/detail）。接入前请确认后端与环境与本文档一致。

License

MIT