ifs-code-tools

轻量级 Widget 嵌入工具库，用于在第三方平台加载并渲染由 IFS Code / Mixo 平台生产的 Widget。

支持两种加载方式： 通过 appId（推荐）或 url 加载 Widget，内置资源缓存、超时控制和错误处理。

安装

npm install ifs-code-tools

| 环境要求 | 版本 | | --- | --- | | 浏览器 | 支持 ES2020 的现代浏览器 | | React（可选） | >= 16.8.0（仅使用 WidgetRender 组件时需要） |

快速开始

import { loadWidget } from 'ifs-code-tools';

const instance = await loadWidget({
  appId: 'my-app-id',
  container: '#widget-container',
  props: { theme: 'dark' },
});

instance.update({ theme: 'light' }); // 更新属性
instance.unmount();                  // 卸载

API

loadWidget(options): Promise<WidgetInstance>

加载并挂载 Widget 到指定容器，返回可控制的实例对象。

import { loadWidget } from 'ifs-code-tools';

// 方式一：通过 appId 加载（推荐）
const instance = await loadWidget({
  appId: 'my-app-id',
  container: '#widget-container',
  props: { theme: 'dark' },
});

// 方式二：通过 url 加载
const instance = await loadWidget({
  url: 'https://cdn.example.com/widgets/my-widget',
  container: document.getElementById('widget-container'),
});

Options (LoadWidgetOptions)：

| 参数 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | appId | string | 二选一 | — | Widget 应用 ID | | url | string | 二选一 | — | Widget 根目录地址 | | container | HTMLElement \| string | 是 | — | 挂载容器（DOM 元素或 CSS 选择器） | | props | WidgetProps | 否 | {} | 传递给 Widget 的属性 | | timeout | number | 否 | 30000 | 加载超时时间（ms） | | onLoad | () => void | 否 | — | 加载成功回调 | | onError | (error: Error) => void | 否 | — | 加载失败回调 |

appId 和 url 必须提供其中一个，同时提供时 appId 优先。

返回值 (WidgetInstance)：

| 方法 | 说明 | | --- | --- | | update(newProps) | 更新 Widget 属性（不会重新加载） | | unmount() | 卸载 Widget 并清理资源 |

preloadWidget(options): Promise<void>

提前加载 Widget 资源到缓存（不挂载），后续调用 loadWidget 时可跳过网络请求，实现秒开。

import { preloadWidget, loadWidget } from 'ifs-code-tools';

// 页面初始化时预加载
preloadWidget({ appId: 'my-app-id' });

// 用户交互时快速挂载（命中缓存，无需等待网络）
const instance = await loadWidget({
  appId: 'my-app-id',
  container: '#container',
});

| 参数 | 类型 | 说明 | | --- | --- | --- | | appId | string | Widget 应用 ID（与 url 二选一） | | url | string | Widget 根目录地址（与 appId 二选一） |

预加载失败时静默处理，不会抛出异常。

<WidgetRender /> React 组件

声明式的 React 组件，封装了 Widget 的加载、更新和卸载生命周期。

import { WidgetRender } from 'ifs-code-tools';

function App() {
  return (
    <WidgetRender
      appId="my-app-id"
      widgetProps={{ theme: 'dark' }}
      loading={<div>加载中...</div>}
      fallback={(error) => <div>加载失败: {error.message}</div>}
      onLoad={() => console.log('Widget 已加载')}
      onError={(err) => console.error(err)}
    />
  );
}

Props (WidgetRenderProps)：

| 参数 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | appId | string | 二选一 | — | Widget 应用 ID | | url | string | 二选一 | — | Widget 根目录地址 | | widgetProps | WidgetProps | 否 | {} | 传递给 Widget 的属性 | | timeout | number | 否 | 30000 | 加载超时时间（ms） | | className | string | 否 | — | 容器 CSS 类名 | | style | React.CSSProperties | 否 | — | 容器内联样式 | | loading | ReactNode | 否 | — | 加载中占位内容 | | fallback | ReactNode \| ((error: Error) => ReactNode) | 否 | — | 加载失败兜底内容 | | onLoad | () => void | 否 | — | 加载成功回调 | | onError | (error: Error) => void | 否 | — | 加载失败回调 |

组件行为：

• url / appId 变化时自动卸载旧实例并重新加载
• widgetProps 变化时通过 instance.update() 增量更新，不触发重新加载
• 组件卸载时自动清理 Widget 实例

TypeScript 支持

本库使用 TypeScript 编写，开箱即用地提供完整类型定义，支持类型检查和 IDE 智能提示。

核心类型导出：WidgetProps、WidgetInstance、LoadWidgetOptions。

License

MIT