# @codatum/embed-react 中文文档 规范地址：https://npmcn.com/package/%40codatum/embed-react/ 版本：1\.0\.0 npm 元数据更新时间：2026-03-03T02:59:56.357Z 中文译文更新时间：2026-11-10T06:38:40.565Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40codatum/embed-react 原文对照：https://npmcn.com/package/%40codatum/embed-react/?lang=original 项目主页：https://github.com/codatum/codatum-embed-js/tree/main/packages/embed-react#readme 源码仓库：https://github.com/codatum/codatum-embed-js ## 关键信息（来自 npm 元数据） - 包体积（解压后）：108 kB，15 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=20\.12 - 运行依赖：1 个 - peer 依赖：react \>=18\.0\.0 - 首次发布：2026-02-20T06:33:55.999Z - 最新版本发布：2026-03-03T02:59:56.058Z - 近 30 天下载量：2771（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：10（近 12 个月 10 个） ## 中文简介 Codatum 签名嵌入的响应集成 ## 安装 ```sh npm install @codatum/embed-react ``` 也可以使用：`pnpm add @codatum/embed-react`、`yarn add @codatum/embed-react`、`bun add @codatum/embed-react` ## README # @codatum/embed-反应 Codatum 签名 Embed 的响应集成 。 提供将SDK核心包裹在一起的单一组件. 全体人员 [@ codatum/ 嵌入](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme) 被再导出,这样您就可以将这个软件包作为单一的切入点(一个版本,不拆分). 选项、类型、事件和方案 API 详情见 **[@ codatum/ 嵌入](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme)**。 。 。 . ## 安装 ```bash pnpm add @codatum/embed-react # or npm install @codatum/embed-react ``` 要求数 **反应 18+** (同类依赖). ## 使用量 ```tsx import { EmbedReact } from "@codatum/embed-react"; const embedUrl = "https://app.codatum.com/protected/workspace/xxx/notebook/yyy"; const tokenProvider = async () => { const res = await fetch("/api/embed-token", { method: "POST" }); const data = await res.json(); return { token: data.token }; }; function App() { return ( console.log("Status", e.status)} onParamChanged={(e) => console.log("Params", e.params)} onExecuteSqlsTriggered={(e) => console.log("Execute", e.params)} onError={(e) => console.error(e)} /> ); } ``` ### 通话 `reload` 从父母那里 使用校对并呼叫曝光者 `reload()` 方法。 它回来了 `true` 成功和 `false` (错误报告通过 `onError`它不会抛出. ```tsx import { useRef } from "react"; import { EmbedReact, type EmbedReactRef } from "@codatum/embed-react"; function App() { const embedRef = useRef(null); async function onFilterChange() { const ok = await embedRef.current?.reload(); if (!ok) console.warn("reload failed — see onError"); } return ( <> ); } ``` ### 自定义装入 UI 使用 `renderLoading` 在装入时显示自定义的用户界面. `showLoadingOn` 显示状态的控件( 默认 ): `INITIALIZING` 编号 : `RELOADING` 编号 : `REFRESHING`) (中文(简体) ). ```tsx } /> ``` 只在第一个负载上显示 : ```tsx } /> ``` 按状况划分: ```tsx status === "INITIALIZING" ? : } /> ``` ### 运行时更改道具 道具一上山就读取. 应用新值(例如: `embedUrl` 或者说 `iframeOptions`),使用时 `key` 强制重载 : ```tsx ``` ## API 密码 选项类型和行为(例如:. `iframeOptions`, (中文(简体) ), `tokenOptions`, (中文(简体) ), `displayOptions`, (中文(简体) ), `devOptions`) 与在 [@ codatum/ 嵌入](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme)该组件使用根元件作为iframe容器(无) `container` (原始内容存档于2013-10-12). prop. ### 道具 | Prop | 需求 | 类型 | | --- | --- | --- | | `embedUrl` | 对 | `string` | | `tokenProvider` | 对 | `(context: TokenProviderContext) => Promise` | | `iframeOptions` | 没有 | `IframeOptions` | | `tokenOptions` | 没有 | `TokenOptions` | | `displayOptions` | 没有 | `DisplayOptions` | | `devOptions` | 没有 | `DevOptions` | | `showLoadingOn` | 没有 | `EmbedStatus[]` - 哪个状态显示加载叠加。 默认 : `['INITIALIZING', 'RELOADING', 'REFRESHING']`。当 `renderLoading` 未设置. | | `renderLoading` | 没有 | `(props: { status: EmbedStatus }) => ReactNode` ——自定义在装入时显示 UI 。 未设置时,使用iframe的内置加载. | ### 回电 | 回电 | 有效载荷 | 何时 | | --- | --- | --- | | `onStatusChanged` | `(payload: { type: 'STATUS_CHANGED', status: EmbedStatus, previousStatus: EmbedStatus }) => void` | 参见 SDK 核心 | | `onParamChanged` | `(payload: { type: 'PARAM_CHANGED', params: EncodedParam[] }) => void` | 参见 SDK 核心 | | `onExecuteSqlsTriggered` | `(payload: { type: 'EXECUTE_SQLS_TRIGGERED', params: EncodedParam[] }) => void` | 参见 SDK 核心 | | `onExecutionSucceeded` | `(payload: { type: 'EXECUTION_SUCCEEDED' }) => void` | 参见 SDK 核心 | | `onExecutionFailed` | `(payload: { type: 'EXECUTION_FAILED', errorMessage: string }) => void` | 参见 SDK 核心 | | `onError` | `(err: EmbedError) => void` | 导入、 重新装入或重新装入符号失败 | ### 参考文献( E)`EmbedReactRef`(中文(简体) ) | 财产 | 类型 | 说明 | | --- | --- | --- | | `reload()` | `() => Promise` | 重排符号和参数; 返回 `false` 失败(通过 `onError`(中文(简体) ) | | `status` | `'CREATED' | 'INITIALIZING' | 'RELOADING' | 'REFRESHING' | 'READY' | 'DESTROYED'` | 当前嵌入状态 | 需要自定义容器还是完全控制? 使用 `createEmbed()` 从此套件( 或 [@ codatum/ 嵌入](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme)(a) 内 `useEffect` 打电话 `instance.destroy()` 在清理中. ## 另见 - **版本和更改日志**数字 : [版本](https://github.com/codatum/codatum-embed-js#versioning) - **安保和部署**数字 : [安保和部署](https://github.com/codatum/codatum-embed-js#security-and-deployment) - **支持的环境**数字 : [支持的环境](https://github.com/codatum/codatum-embed-js#supported-environments) ## 常见问题 ### @codatum/embed-react 是什么？ Codatum 签名嵌入的响应集成 ### 如何安装 @codatum/embed-react？ 在项目目录运行 npm install @codatum/embed-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @codatum/embed-react 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @codatum/embed-react 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @codatum/embed-react 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20\.12。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @codatum/embed-react 可以商用吗？ @codatum/embed-react 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @codatum/embed-react 的下载量有多少？ 根据 npm 官方下载统计，@codatum/embed-react 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,771 次，日均约 92 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @codatum/embed-react 还在维护吗？ 最新版本 1\.0\.0 发布于 2026/03/03（8 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/02/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。