# @cube-dev/embed-sdk 中文文档

规范地址：https://npmcn.com/package/%40cube-dev/embed-sdk/

版本：0\.0\.13
npm 元数据更新时间：2026-05-22T15:55:17.792Z
中文译文更新时间：2026-11-11T04:07:18.772Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cube-dev/embed-sdk
原文对照：https://npmcn.com/package/%40cube-dev/embed-sdk/?lang=original
项目主页：https://cube.dev/

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

- 包体积（解压后）：6.3 MB，114 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：@tanstack/react-query ^5\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，vega-lite ^6\.4\.1
- 首次发布：2026-01-25T15:35:40.012Z
- 最新版本发布：2026-05-22T15:55:17.612Z
- 近 30 天下载量：44782（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

用于嵌入立方体分析的 SDK 反应

## 安装

```sh
npm install @cube-dev/embed-sdk
```

也可以使用：`pnpm add @cube-dev/embed-sdk`、`yarn add @cube-dev/embed-sdk`、`bun add @cube-dev/embed-sdk`

## README

# @cube-dev/embed-sdk (英语)

将 Cube 分析器嵌入到您的应用程序中 .

## 安装

```bash
yarn add @cube-dev/embed-sdk
```

### 同伴依赖关系

此软件包需要以下对等依赖性:

```bash
yarn add react react-dom @tanstack/react-query
```

## 快速启动

```tsx
import { useState } from 'react';
import { EmbedProvider, createDefaultReport, useReportContext } from '@cube-dev/embed-sdk';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  const [report, setReport] = useState(() => createDefaultReport({ title: 'My Report' }));

  return (
    <QueryClientProvider client={queryClient}>
      <EmbedProvider
        token={cubeApiToken}
        apiUrl={cubeApiUrl}
        report={report}
        onReportUpdate={(updates) => setReport((prev) => ({ ...prev, ...updates }))}
      >
        <YourAnalyticsComponent />
      </EmbedProvider>
    </QueryClientProvider>
  );
}
```

## 出口

### 供应商

-   `EmbedProvider` - 联合提供者包罗所有上下文
-   `CubeApiContextProvider` - 立方体 API 客户端背景
-   `DataAssetsContextProvider` - 数据资产和语义视图上下文
-   `ReportProvider` - 报告国家管理背景
-   `ChartBuilderProvider` - 图表建筑公用事业背景

### 钩子

-   `useReportContext` - 进入报告状态和行动
-   `useChartBuilderContext` - 出入图绘制设施
-   `useDataAssetsContext` - 获取数据资产和语义视图
-   `useActiveCubeApi` - 访问 Cube API 客户端
-   `useReport` - 独立报告管理钩

### 公用事业

-   `createDefaultReport` - 创建一个带有可选标题和 SQL 查询的新默认报告
-   `parseSemanticSql` - 解析语义SQL查询
-   `generateSemanticSql` - 从逻辑查询生成语义 SQL
-   `prepareTableData` - 为表格渲染准备数据
-   `prepareChartColumns` - 准备图表渲染的列

## 许可证

麻省理工学院

## 常见问题

### @cube-dev/embed-sdk 是什么？

用于嵌入立方体分析的 SDK 反应

### 如何安装 @cube-dev/embed-sdk？

在项目目录运行 npm install @cube-dev/embed-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@tanstack/react-query（^5\.0\.0）、react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、vega-lite（^6\.4\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cube-dev/embed-sdk 支持 TypeScript 吗？

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

### @cube-dev/embed-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cube-dev/embed-sdk 可以商用吗？

@cube-dev/embed-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cube-dev/embed-sdk 的下载量有多少？

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

### @cube-dev/embed-sdk 还在维护吗？

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