ifs-code-tools 1.0.1

package/README.md

@@ -0,0 +1,115 @@
+# ifs-code-tools
+
+IFS Code 工具库，提供 Widget 加载能力，用于在第三方平台嵌入 Widget。
+
+## 安装
+
+```bash
+npm install ifs-code-tools
+```
+
+## API 文档
+
+### Widget
+
+#### loadWidget - 加载并挂载 Widget
+
+```js
+import { widget } from 'ifs-code-tools';
+
+// 方式一：通过 url 加载
+const instance = await widget.loadWidget({
+  url: 'https://cdn.example.com/widgets/my-widget',
+  container: '#widget-container',
+  props: { theme: 'dark' },
+});
+
+// 方式二：通过 appId 加载
+const instance = await widget.loadWidget({
+  appId: 'my-app-id',
+  container: '#widget-container',
+  props: { theme: 'dark' },
+});
+
+// 更新 props
+instance.update({ theme: 'light' });
+
+// 卸载
+instance.unmount();
+```
+
+**参数 (LoadWidgetOptions):**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| url | `string` | 与 appId 二选一 | Widget 根目录地址 |
+| appId | `string` | 与 url 二选一 | Widget 应用 ID |
+| container | `HTMLElement \| string` | 是 | 挂载容器，DOM 元素或选择器 |
+| props | `WidgetProps` | 否 | 传递给 Widget 的属性 |
+| timeout | `number` | 否 | 加载超时时间（毫秒），默认 30000 |
+| onLoad | `() => void` | 否 | 加载完成回调 |
+| onError | `(error: Error) => void` | 否 | 加载失败回调 |
+
+#### preloadWidget - 预加载 Widget 资源
+
+提前加载 Widget 资源（不挂载），用于优化用户体验。
+
+```js
+import { widget } from 'ifs-code-tools';
+
+// 通过 url 预加载
+widget.preloadWidget({ url: 'https://cdn.example.com/widgets/my-widget' });
+
+// 通过 appId 预加载
+widget.preloadWidget({ appId: 'my-app-id' });
+
+// 用户交互时快速挂载（会从缓存中读取，加载更快）
+const instance = await widget.loadWidget({
+  url: 'https://cdn.example.com/widgets/my-widget',
+  container: '#container',
+});
+```
+
+#### WidgetRender - React 组件
+
+React 组件形式的 Widget 加载器。
+
+```tsx
+import { widget } from 'ifs-code-tools';
+
+function App() {
+  return (
+    <widget.WidgetRender
+      url="https://cdn.example.com/widgets/my-widget"
+      widgetProps={{ theme: 'dark' }}
+      loading={<div>Loading...</div>}
+      fallback={(error) => <div>Error: {error.message}</div>}
+      onLoad={() => console.log('loaded')}
+      onError={(err) => console.error(err)}
+    />
+  );
+}
+```
+
+**Props (WidgetRenderProps):**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| url | `string` | 与 appId 二选一 | Widget 根目录地址 |
+| appId | `string` | 与 url 二选一 | Widget 应用 ID |
+| widgetProps | `WidgetProps` | 否 | 传递给 Widget 的属性 |
+| timeout | `number` | 否 | 加载超时时间（毫秒），默认 30000 |
+| className | `string` | 否 | 容器类名 |
+| style | `React.CSSProperties` | 否 | 容器样式 |
+| loading | `React.ReactNode` | 否 | 加载中渲染内容 |
+| fallback | `ReactNode \| ((error: Error) => ReactNode)` | 否 | 加载失败渲染内容 |
+| onLoad | `() => void` | 否 | 加载完成回调 |
+| onError | `(error: Error) => void` | 否 | 加载失败回调 |
+
+## TypeScript 支持
+
+本库提供完整的 TypeScript 类型定义，支持类型检查和 IDE 智能提示。
+
+## License
+
+MIT