@ codatum/ 嵌入

嵌入 Codatum 笔记本的核心类型SDK 已签名嵌入:在浏览器中创建iframe,从后端通过一个符号,处理参数和事件. 服务器侧式代币发行范围外.

文档数字 : 已签名嵌入 • 妇女 一体化 • 妇女 使用大小写。 。 。 . 包装器数字 : @codatum/embed-反应, (中文(简体) ), @ codatum/embed-vue。 。 。 .

安装

pnpm add @codatum/embed
# or
npm install @codatum/embed

快开始

import { createEmbed } from '@codatum/embed';

const embed = createEmbed({
  container: '#dashboard',
  embedUrl: 'https://app.codatum.com/protected/workspace/xxx/notebook/yyy',
  tokenProvider: async () => {
    // Issue a token in your backend and fetch it here
    const res = await fetch('/api/codatum/token', { method: 'POST' });
    const data = await res.json();
    return { token: data.token };
  },
});
await embed.init();

// cleanup
embed.destroy();

嵌入

EmbedOptions

tokenProvider

需要从后端发出一个令牌并返回它(可选) params) (中文(简体) ). 来电 init(), (中文(简体) ), reload()当迹象即将到期的时候 tokenOptions.disableRefresh 实值 true) (中文(简体) ).

签署: (context: TokenProviderContext) => Promise<{ token: string; params?: EncodedParam[] }>

• context.trigger —— 说 'INIT' | 'RELOAD' | 'REFRESH'。 。 。 .
• context.markNonRetryable() - 调用未跳过重试( ignores) tokenOptions.retryCount) (中文(简体) ).
• params - 可选的。 如果返回, 则发送到嵌入符; 使用 参数马普 encode() 建造.

示例

tokenProvider: async (context) => {
  const res = await fetch('/api/codatum/token', {
    method: 'POST',
    body: JSON.stringify({ tenant_id: currentUser.tenantId }),
  });
  if (!res.ok) {
    if (res.status === 401) context.markNonRetryable();
    throw new Error(`Token failed: ${res.status}`);
  }
  const data = await res.json();
  const params = paramMapper.encode({ 
    store_id: currentUser.defaultStoreId,
    date_range: ['2025-01-01', '2025-01-31']
  });
  return { token: data.token, params };
}

IframeOptions

应用到 Iframe 元素并通过 URL/ search params 传递到嵌入式.

TokenOptions

控制符号寿命, 刷新行为, 并加载超时 .

DisplayOptions

送入所入所入所入所发相.

DevOptions

仅限开发与测试. 未打算生产.

模拟选项 (当 mock 是对象 :

创建嵌入式实例

createEmbed(options: EmbedOptions): EmbedInstance

创建嵌入式实例。 掷出 EmbedError 如果选项无效。 打电话 init() 创建 iframe 并启动符号流.

实例方法

实例属性

容器属性

SDK设定 data-codatum-embed-status 属性,反映当前状态。 当 init() 调用并删除 destroy()。用于基于 CSS 的样式或 E2E 测试选择器.

示例: 自定义装入 UI

初始化时显示您自己的加载指示器, 同时隐藏 Iframe :

<div id="dashboard" style="position: relative;">
  <div class="my-loading">Loading…</div>
</div>

/* Hide iframe and show loading UI while loading */
[data-codatum-embed-status="INITIALIZING"] iframe,
[data-codatum-embed-status="RELOADING"] iframe,
[data-codatum-embed-status="REFRESHING"] iframe {
  visibility: hidden;
}
[data-codatum-embed-status="INITIALIZING"] .my-loading,
[data-codatum-embed-status="RELOADING"] .my-loading,
[data-codatum-embed-status="REFRESHING"] .my-loading {
  display: flex;
  position: absolute;
  inset: 0;
  align-items: center;
  justify-content: center;
}

/* Hide loading UI when ready */
[data-codatum-embed-status="READY"] .my-loading {
  display: none;
}

没有自定义的 CSS,嵌入式内置加载屏幕显示为iframe内置.

活动

订阅 on(event, handler) 财务报告和审定财务报表 off(event, handler)。 。 。 .

解码为 ParamMapper.decode(payload.params)。 。 。 . EncodedParam: 见 参数马普。 。 。 .

参数马普

嵌入式使用 param_ids(每个笔记本参数指定的ID). 您的应用程序通常使用有意义的键, 如 store_id 或者说 date_range。 。 。 . 参数马普 您的应用程序的密钥值对和 Codatum 之间的地图 param_id + 键 param_value 两个方向.

基本用途

import { createParamMapper } from '@codatum/embed';

const paramMapper = createParamMapper({
  store_id: '67a1b2c3d4e5f6a7b8c9d0e1',
  date_range: '67a1b2c3d4e5f6a7b8c9d0e2',
  product_category: '67a1b2c3d4e5f6a7b8c9d0e3',
});

const appState = {
  store_id: 'store_001',
  date_range: ['2025-01-01', '2025-01-31'],
  product_category: ['Electronics'],
};

// encode: app key:value → EncodedParam[] (use in tokenProvider return)
paramMapper.encode(appState);
// → [
//   { param_id: '67a1b2c3...', param_value: '"store_001"' },
//   { param_id: '67a1b2c3...', param_value: '["2025-01-01","2025-01-31"]' },
//   { param_id: '67a1b2c3...', param_value: '["Electronics"]' },
// ]

// decode: EncodedParam[] → app key:value (use in paramChanged / executeSqlsTriggered)
paramMapper.decode(payload.params);
// → { store_id: 'store_001', date_range: [...], product_category: ['Electronics'] }

创建映射器

createParamMapper(mapping, meta?)

ParamMeta (可选,按键):

参数数据类型

何时 meta[key].datatype 已经设定, encode 财务报告和审定财务报表 decode 验证值。 支持的数值 :

实例方法

encode 编号 : decode 选项

这两种方法都接受可选的第二个论点:

第一次使用类型

当定义参数定义(例如: datatype)和想要打入编码/解码,可以使用帮助者类型.

import { createParamMapper, RESET_TO_DEFAULT, type DefineDecodedParams, type EncodedParam } from '@codatum/embed';

const paramDefs = {
  store_id: { datatype: 'STRING', required: true },
  date_range: { datatype: '[DATE, DATE]' },
  product_category: { datatype: 'STRING[]' },
} as const;

type ParamValues = DefineDecodedParams<typeof paramDefs>;
// → { store_id: string, date_range?: [string, string], product_category?: string[] }

const paramValues: ParamValues = {
  store_id: 'store_001',
  date_range: RESET_TO_DEFAULT,
  product_category: ['Electronics']
};

const paramMapper = createParamMapper({
  store_id: '67a1b2c3d4e5f6a7b8c9d0e1',
  date_range: '67a1b2c3d4e5f6a7b8c9d0e2',
  product_category: '67a1b2c3d4e5f6a7b8c9d0e3',
}, paramDefs);

// encode only the date_range and product_category params for client-side params
const clientParams = paramMapper.encode(paramValues, { only: ['date_range', 'product_category'] })
// → [
//   { param_id: '67a1b2c3d4e5f6a7b8c9d0e2', param_value: '["2025-01-01","2025-01-31"]' },
//   { param_id: '67a1b2c3d4e5f6a7b8c9d0e3', param_value: '["Electronics"]' },
// ]

const onParamChanged = (ev: { params: EncodedParam[] }) => {
  const values: ParamValues = paramMapper.decode(ev.params);
  console.log('Changed:', values);
};

错误

所有出错均以 EmbedError 带有 code 属性.

处理错误

init() 财务报告和审定财务报表 reload() 投出失败——尝试/捕获。 自动更新错误通过 tokenOptions.onRefreshError 调用.

import { createEmbed, EmbedError } from '@codatum/embed';

try {
  const embed = createEmbed({
    container: '#dashboard',
    embedUrl: '...',
    tokenProvider: async () => { /* ... */ },
    tokenOptions: {
      onRefreshError: (error) => {
        // Token auto-refresh failed after all retries.
        // e.g. redirect to login, show a banner, etc.
        console.error('Refresh failed:', error);
      },
    },
  });
  await embed.init();

  // reload() also throws on failure
  await embed.reload();
} catch (error) {
  if (error instanceof EmbedError) {
      // error.cause holds the original error thrown by tokenProvider (if applicable)
    console.error(error.code, error.message);
  }
}

用法实例

以下模式显示了《公约》概述的共同一体化设想: 已签名的嵌入式使用例。 。 。 .

例A:嵌入层中的参数形式(服务器验证商店,客户端发送过滤器)

嵌入显示笔记本的参数形式. 服务器验证 store_id 并用符号编码;客户端发送电流 store_id 仅针对每个令牌请求和编码 date_range 财务报告和审定财务报表 product_category 作为客户端参数,窗体和主机保持同步.

客户端

import { createEmbed, createParamMapper, RESET_TO_DEFAULT } from '@codatum/embed';

const paramMapper = createParamMapper({...}, {
  store_id: { datatype: 'STRING' },  // server-side param
  date_range: { datatype: '[DATE, DATE]' },  // client-side param
  product_category: { datatype: 'STRING[]' },  // client-side param
});
let paramValues = { store_id: undefined, date_range: RESET_TO_DEFAULT, product_category: [] };

const embed = createEmbed({
  container: '#dashboard',
  embedUrl: '...',
  displayOptions: { expandParamsFormByDefault: true },
  tokenProvider: async () => {
    const res = await fetch('/api/codatum/token', {
      method: 'POST',
      body: JSON.stringify({ tokenUserId: userId, params: { store_id: paramValues.store_id } }),
    });
    const { token } = await res.json();
    const params = paramMapper.encode(paramValues, { only: ['date_range', 'product_category'] });
    return { token, params };
  },
});
await embed.init();

embed.on('paramChanged', (ev) => { paramValues = paramMapper.decode(ev.params); });
embed.on('executeSqlsTriggered', (ev) => { paramValues = paramMapper.decode(ev.params); });

可运行 : 反应, (中文(简体) ), 阴道

服务器 - 验证 store_id 与房客为敌,并将它写入铭文中:

import { createParamMapper } from '@codatum/embed';

// POST /token body: { tokenUserId, params?: { store_id } }
const paramMapper = createParamMapper({...}, {
  tenant_id: { datatype: 'STRING', required: true },  // server-side param
  store_id: { datatype: 'STRING', required: true },  // server-side param
});
const tenantId = await getTenantIdByUserId(tokenUserId);
const storeIdsForTenant = await getStoreIdsByTenantId(tenantId);
const storeId = params?.store_id ?? storeIdsForTenant[0];
if (!storeIdsForTenant.includes(storeId)) throw new Error('Invalid storeId');
const encoded = paramMapper.encode({ tenant_id: tenantId, store_id: storeId });
// issue token with encoded params

可运行 : 节点.js

例B:仅客户端参数(SaaS拥有过滤器,隐藏参数表)

所有参数除外 tenant_id 由主机管理;嵌入式的参数窗体被隐藏. 道具只携带租户上下文,因此可以缓存并再用. 当用户在主机 UI 中更改过滤器时,请拨 reload() 因此,符号提供者再次以更新的值运行.

客户端

import { createEmbed, createParamMapper } from '@codatum/embed';

const paramMapper = createParamMapper({...}, {
  store_id: { datatype: 'STRING' },  // client-side param
  date_range: { datatype: '[DATE, DATE]' },  // client-side param
  product_category: { datatype: 'STRING[]' },  // client-side param
});
let paramValues = { store_id: 'store_001', date_range: ['2025-01-01', '2025-01-31'], product_category: [] };

const embed = createEmbed({
  container: '#dashboard',
  embedUrl: '...',
  displayOptions: { hideParamsForm: true },
  tokenProvider: async () => {
    const res = await fetch('/api/codatum/token', { method: 'POST', body: JSON.stringify({ tokenUserId: userId }) });
    const { token } = await res.json();
    const params = paramMapper.encode(paramValues);
    return { token, params };
  },
});
await embed.init();

embed.on('paramChanged', (ev) => { paramValues = paramMapper.decode(ev.params); });
embed.on('executeSqlsTriggered', (ev) => { paramValues = paramMapper.decode(ev.params); });

// When the user changes filters in the host UI, update paramValues and reload the embed
async function onDashboardFilterChange(newValues: ParamValues) {
  paramValues = newValues;
  await embed.reload();
}

可运行 : 反应, (中文(简体) ), 阴道

服务器 - Token只需要租房范围(身体没有偏执):

import { createParamMapper } from '@codatum/embed';

// POST /token body: { tokenUserId }
const paramMapper = createParamMapper({...}, {
  tenant_id: { datatype: 'STRING', required: true },  // server-side param
});
const tenantId = await getTenantIdByUserId(tokenUserId);
const encoded = paramMapper.encode({ tenant_id: tenantId });
// issue token with encoded params

可运行 : 节点.js

例 C: 服务器侧存储( 存储更改时重发)

store_id 在符号中被固定,并验证服务器侧;更改商店需要一个新的符号。 参数形式可见于 date_range 财务报告和审定财务报表 product_category参数值 paramChanged 通过 store_id 到服务器,在每一个令牌请求中;当用户切换存储时,重新装入,这样就可以为新商店发行一个新的令牌.

客户端

import { createEmbed, createParamMapper, RESET_TO_DEFAULT } from '@codatum/embed';

const paramMapper = createParamMapper({...}, {
  store_id: { datatype: 'STRING' },  // server-side param
  date_range: { datatype: '[DATE, DATE]' },  // client-side param
  product_category: { datatype: 'STRING[]' },  // client-side param
});
let paramValues = { store_id: undefined, date_range: RESET_TO_DEFAULT, product_category: ['Electronics'] };

const embed = createEmbed({
  container: '#dashboard',
  embedUrl: '...',
  displayOptions: { expandParamsFormByDefault: true },
  tokenProvider: async () => {
    const res = await fetch('/api/codatum/token', {
      method: 'POST',
      body: JSON.stringify({ tokenUserId: userId, params: { store_id: paramValues.store_id } }),
    });
    const { token } = await res.json();
    const params = paramMapper.encode(paramValues, { only: ['date_range', 'product_category'] });
    return { token, params };
  },
});
await embed.init();

embed.on('paramChanged', (ev) => { paramValues = paramMapper.decode(ev.params); });
embed.on('executeSqlsTriggered', (ev) => { paramValues = paramMapper.decode(ev.params); });

async function onStoreSwitch(storeId: string) {
  paramValues.store_id = storeId;
  await embed.reload();
}

可运行 : 反应, (中文(简体) ), 阴道

服务器 ——与例A相同:接受 params.store_id,验证,编码 tenant_id + 键 store_id 在标志.

可运行 : 节点.js

光盘N

独立国际家庭教育研究所的建筑暴露了单一的全球情况 CodatumEmbed。装入脚本并使用 CodatumEmbed.createEmbed 接下来 embed.init()。 。 。 .

<script src="https://unpkg.com/@codatum/embed/dist/index.global.min.js"></script>
<script>
  (async function () {
    const embed = CodatumEmbed.createEmbed({ container: '#dashboard', embedUrl: '...', tokenProvider: ... });
    await embed.init();
  })();
</script>

另见

• 版本和更改日志数字 : 版本
• 安保和部署数字 : 安保和部署
• 支持的环境数字 : 支持的环境