# @codatum/embed-vue 中文文档

规范地址：https://npmcn.com/package/%40codatum/embed-vue/

版本：1\.0\.0
npm 元数据更新时间：2026-03-03T02:59:59.376Z
中文译文更新时间：2026-11-10T06:06:23.507Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40codatum/embed-vue
原文对照：https://npmcn.com/package/%40codatum/embed-vue/?lang=original
项目主页：https://github.com/codatum/codatum-embed-js/tree/main/packages/embed-vue#readme
源码仓库：https://github.com/codatum/codatum-embed-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：42.8 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.12
- 运行依赖：1 个
- peer 依赖：vue \>=3\.0\.0
- 首次发布：2026-02-20T06:26:04.661Z
- 最新版本发布：2026-03-03T02:59:59.048Z
- 近 30 天下载量：6180（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

Vue 3 已签名嵌入的 Codatum 集成

## 安装

```sh
npm install @codatum/embed-vue
```

也可以使用：`pnpm add @codatum/embed-vue`、`yarn add @codatum/embed-vue`、`bun add @codatum/embed-vue`

## README

# @ codatum/embed-vue

Vue 3 为已签名的 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-vue
# or
npm install @codatum/embed-vue
```

要求数 **第3组** (同类依赖).

## 使用量

```vue
<script setup lang="ts">
import { EmbedVue } from "@codatum/embed-vue";

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 };
}
</script>

<template>
  <EmbedVue
    :embedUrl="embedUrl"
    :tokenProvider="tokenProvider"
    :iframeOptions="{ theme: 'LIGHT', locale: 'ja' }"
    @statusChanged="(e) => console.log('Status', e.status)"
    @paramChanged="(e) => console.log('Params', e.params)"
    @executeSqlsTriggered="(e) => console.log('Execute', e.params)"
    @error="(e) => console.error(e)"
  />
</template>
```

### 通话 `reload` 从父母那里

使用模板校对并呼叫已曝光 `reload()` 方法。 它回来了 `true` 成功和 `false` 故障(通过 `@error`它不会抛出.

```vue
<script setup lang="ts">
import { ref } from "vue";
import { EmbedVue } from "@codatum/embed-vue";

const embedRef = ref<InstanceType<typeof EmbedVue> | null>(null);

async function onFilterChange() {
  const ok = await embedRef.value?.reload();
  if (!ok) console.warn("reload failed — see @error");
}
</script>

<template>
  <EmbedVue ref="embedRef" :embedUrl="..." :tokenProvider="..." @error="handleError" />
</template>
```

### 运行时更改道具

道具一上山就读取. 应用新值(例如: `embedUrl` 或者说 `iframeOptions`),使用时 `:key` 强制重载 :

```vue
<EmbedVue :key="embedUrl" :embedUrl="embedUrl" :tokenProvider="tokenProvider" />
```

### 自定义装入 UI (E)`#loading` (插槽)

当你通过 `#loading` 插槽, 组件在加载时隐藏 Iframe( init, 重新加载, 重新刷新等) , 并显示您的自定义 UI 。 使用 `showLoadingOn` 以控制哪个状态显示覆盖(默认 ): `['INITIALIZING', 'RELOADING', 'REFRESHING']`) (中文(简体) ). 没有槽,内置的iframe加载行为不变.

```vue
<!-- Spinner for all loading states -->
<EmbedVue :embedUrl="embedUrl" :tokenProvider="tokenProvider">
  <template #loading>
    <MySpinner />
  </template>
</EmbedVue>

<!-- Only on first load -->
<EmbedVue
  :embedUrl="embedUrl"
  :tokenProvider="tokenProvider"
  :showLoadingOn="['INITIALIZING']"
>
  <template #loading>
    <MySpinner />
  </template>
</EmbedVue>

<!-- Branch by status -->
<EmbedVue :embedUrl="embedUrl" :tokenProvider="tokenProvider">
  <template #loading="{ status }">
    <FullPageLoader v-if="status === 'INITIALIZING'" />
    <SubtleBar v-else />
  </template>
</EmbedVue>
```

## 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<TokenProviderResult>` |
| `iframeOptions` | 没有 | `IframeOptions` |
| `tokenOptions` | 没有 | `TokenOptions` |
| `displayOptions` | 没有 | `DisplayOptions` |
| `devOptions` | 没有 | `DevOptions` |
| `showLoadingOn` | 没有 | `EmbedStatus[]` - 哪个状态显示加载叠加。 默认 : `['INITIALIZING', 'RELOADING', 'REFRESHING']`。当 `#loading` 未设置槽 . |

### 槽数

| 槽 | 范围说明 | 说明 |
| --- | --- | --- |
| `#loading` | `{ status: EmbedStatus }` | 装入时显示自定义 UI 。 重叠仅在提供此槽和当前状态时显示( 并隐藏 ) `showLoadingOn`没有插槽,则使用内置的 Iframe 装载行为. |

### 活动

| 活动 | 有效载荷 | 何时 |
| --- | --- | --- |
| `statusChanged` | `{ type: 'STATUS_CHANGED', status: EmbedStatus, previousStatus: EmbedStatus }` | 参见 SDK 核心 |
| `paramChanged` | `{ type: 'PARAM_CHANGED', params: EncodedParam[] }` | 参见 SDK 核心 |
| `executeSqlsTriggered` | `{ type: 'EXECUTE_SQLS_TRIGGERED', params: EncodedParam[] }` | 参见 SDK 核心 |
| `executionSucceeded` | `{ type: 'EXECUTION_SUCCEEDED' }` | 参见 SDK 核心 |
| `executionFailed` | `{ type: 'EXECUTION_FAILED', errorMessage: string }` | 参见 SDK 核心 |
| `error` | `EmbedError` | 导入、 重新装入或重新装入符号失败 |

### 展览( ref)

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `reload()` | `() => Promise<boolean>` | 重排符号和参数; 返回 `false` 故障(通过 `@error`(中文(简体) ) |
| `status` | `'CREATED' | 'INITIALIZING' | 'RELOADING' | 'REFRESHING' | 'READY' | 'DESTROYED'` | 当前嵌入状态 |

需要自定义容器还是完全控制? 使用 `createEmbed()` 从此套件( 或 [@ codatum/ 嵌入](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme)(单位:千美元) `onMounted` 财务报告和审定财务报表 `instance.destroy()` 内 `onUnmounted`。 。 。 .

## 另见

-   **版本和更改日志**数字 : [版本](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-vue 是什么？

Vue 3 已签名嵌入的 Codatum 集成

### 如何安装 @codatum/embed-vue？

在项目目录运行 npm install @codatum/embed-vue，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（\>=3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @codatum/embed-vue 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @codatum/embed-vue 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @codatum/embed-vue 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.12。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @codatum/embed-vue 可以商用吗？

@codatum/embed-vue 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @codatum/embed-vue 的下载量有多少？

根据 npm 官方下载统计，@codatum/embed-vue 在 2026/10/10 – 2026/11/08 这 30 天内被下载 6,180 次，日均约 206 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @codatum/embed-vue 还在维护吗？

最新版本 1\.0\.0 发布于 2026/03/03（8 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/02/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。