npm package: @pingansec/qixin.sharepublic.sdk
Description: SDK for initializing shared public components into a container
Latest version: 1.0.0

# @pingansec/qixin.sharepublic.sdk

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

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

## 安装

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

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

## 引入方式

### 1. 默认导入（推荐）

```javascript
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. 命名导入

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

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

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

```javascript
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`。

```typescript
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