# @dialstack/sdk 中文文档

规范地址：https://npmcn.com/package/%40dialstack/sdk/

版本：2\.1\.0
npm 元数据更新时间：2026-10-05T14:33:22.196Z
中文译文更新时间：2026-11-12T06:38:03.980Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dialstack/sdk
原文对照：https://npmcn.com/package/%40dialstack/sdk/?lang=original
项目主页：https://github.com/dialstack/dialstack-sdk#readme
源码仓库：https://github.com/dialstack/dialstack-sdk

弃用说明：@dialstack/sdk is no longer updated\. Use @dialstack/sdk-js, @dialstack/sdk-react, @dialstack/sdk-webrtc, @dialstack/sdk-server or @dialstack/sdk-native: https://docs\.dialstack\.ai/sdks/installation

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

- 包体积（解压后）：14 MB，391 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：2 个
- peer 依赖：react ^19\.2\.8，react-dom ^19\.2\.8
- 首次发布：2025-11-14T19:48:42.505Z
- 最新版本发布：2026-08-10T13:54:36.116Z
- 近 30 天下载量：6845（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

官方 JavaScript SDK for DialStack - 垂直SaaS的商业之声

## 安装

```sh
npm install @dialstack/sdk
```

也可以使用：`pnpm add @dialstack/sdk`、`yarn add @dialstack/sdk`、`bun add @dialstack/sdk`

## README

# @ dialstack/ sdk

官方 JavaScript SDK 为 [拨号](https://dialstack.ai/) - 商业之声的垂直SaaS.

将语音能力直接嵌入您的应用程序中, 并带有用于调用日志、 语音邮件等的即时反应组件 .

## 安装

```bash
npm install @dialstack/sdk
```

## 快速启动

### 反应

```tsx
import { loadDialstackAndInitialize } from '@dialstack/sdk';
import { DialstackComponentsProvider, CallLogs, Voicemails } from '@dialstack/sdk/react';
import { useEffect, useState } from 'react';
import type { DialStackInstance } from '@dialstack/sdk';

function App() {
  const [dialstack, setDialstack] = useState<DialStackInstance | null>(null);

  useEffect(() => {
    // Initialize DialStack with your publishable key and session fetcher
    loadDialstackAndInitialize({
      publishableKey: 'pk_live_YOUR_PUBLISHABLE_KEY',
      fetchClientSecret: async () => {
        const res = await fetch('https://your-backend.com/api/create-session', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ accountId: 'acct_123' }),
        });
        const data = await res.json();
        return data.client_secret;
      },
    }).then(setDialstack);
  }, []);

  if (!dialstack) {
    return <div>Loading...</div>;
  }

  return (
    <DialstackComponentsProvider dialstack={dialstack}>
      <div>
        <h1>My Voice Dashboard</h1>
        <CallLogs />
        <Voicemails />
      </div>
    </DialstackComponentsProvider>
  );
}
```

### 香草 Java 脚本

```html
<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/@dialstack/sdk"></script>
  </head>
  <body>
    <dialstack-call-logs></dialstack-call-logs>
    <dialstack-voicemails></dialstack-voicemails>

    <script>
      // Initialize DialStack with session fetcher
      DialStack.loadDialstackAndInitialize({
        publishableKey: 'pk_live_YOUR_PUBLISHABLE_KEY',
        fetchClientSecret: async () => {
          const res = await fetch('https://your-backend.com/api/create-session', {
            method: 'POST',
            body: JSON.stringify({ accountId: 'acct_123' }),
          });
          const data = await res.json();
          return data.client_secret;
        },
      });
    </script>
  </body>
</html>
```

## 构成部分

### 调用日志

显示调用历史列表, 包括调用者、 持续时间和状态等细节 .

```tsx
<CallLogs
  dateRange={{ start: '2025-01-01', end: '2025-01-31' }}
  limit={50}
  onRowClick={(e) => console.log('Selected call:', e.callId)}
  onLoadError={(e) => console.error(e.error)}
/>
```

**道具 :**

-   `dateRange` - 按日期范围过滤(`{ start?: string, end?: string }`(中文(简体) )
-   `limit` - 要显示的最大记录( 默认: 20)
-   `locale` - 用户界面字符串的自定义区域
-   `formatting` - 日期/电话格式化选项
-   `onLoaderStart` - 开始装入时召回
-   `onLoadError` - 装入失败时召回
-   `onPageChange` - 当页形变化时召回
-   `onRowClick` - 单击一行时召回

### 语音信箱

显示带有回放控件的语音邮件列表 .

```tsx
<Voicemails
  userId="user-uuid-123"
  onVoicemailSelect={(e) => console.log('Selected:', e.voicemailId)}
  onCallBack={(e) => initiateCall(e.phoneNumber)}
/>
```

**道具 :**

-   `userId` - 获取语音邮件的用户ID( 需要)
-   `locale` - 用户界面字符串的自定义区域
-   `formatting` - 日期/电话格式化选项
-   `onLoaderStart` - 开始装入时召回
-   `onLoadError` - 装入失败时召回
-   `onVoicemailSelect` - 选定语音信箱时召回
-   `onVoicemailPlay` - 重播开始后召回
-   `onVoicemailPause` - 回放暂停时召回
-   `onVoicemailDelete` - 语音信箱被删除时召回
-   `onCallBack` - 点击回调按钮时回调

## 他们

使用 CSS 变量自定义组件外观 `appearance` 初始化时的选项 :

```tsx
const dialstack = await loadDialstackAndInitialize({
  publishableKey: 'pk_live_YOUR_KEY',
  fetchClientSecret: async () => {
    /* ... */
  },
  appearance: {
    theme: 'light', // 'light' | 'dark' | 'auto'
    variables: {
      // Colors
      colorPrimary: '#6772E5',
      colorBackground: '#ffffff',
      colorText: '#1a1a1a',
      colorDanger: '#e5484d',
      colorSuccess: '#30a46c',

      // Typography
      fontFamily: 'Inter, system-ui, sans-serif',
      fontSizeBase: '14px',

      // Spacing
      spacingUnit: '8px',
      borderRadius: '4px',
    },
  },
});
```

所有组件都继承了SDK实例的外观并自动为轻/暗主题调整.

## 国际化(i18n)

组成部分支持通过下列途径实现国际化: `locale` 道具 :

```tsx
import { en } from '@dialstack/sdk/locales';

// Create a custom locale by extending the default
const fr: typeof en = {
  common: {
    loading: 'Chargement...',
    error: 'Erreur',
    // ... other translations
  },
  callLogs: {
    title: 'Journal des appels',
    // ... other translations
  },
  voicemails: {
    title: 'Messagerie vocale',
    // ... other translations
  },
};

<CallLogs locale={fr} />;
```

## 格式化

自定义日期和电话号码格式:

```tsx
<CallLogs
  formatting={{
    defaultCountry: 'FR', // ISO 3166-1 alpha-2 country code
    dateLocale: 'fr-FR', // BCP 47 language tag
    use24HourTime: true, // 24-hour format
    showTimezone: false, // Hide timezone
  }}
/>
```

## 处理错误

SDK为优雅地处理错误提供回调:

```tsx
<CallLogs
  onLoaderStart={({ elementTagName }) => {
    console.log(`Loading ${elementTagName}...`);
  }}
  onLoadError={({ error, elementTagName }) => {
    console.error(`Error in ${elementTagName}:`, error);
    // Show user-friendly error message or retry logic
  }}
/>
```

### 提供者出错

如果你忘了把部件包起来 `DialstackComponentsProvider`,你会得到一个有用的错误信息:

```
Error: Could not find DialStack context; You need to wrap your app
in a <DialstackComponentsProvider> provider.
See https://docs.dialstack.ai/sdk/react for setup instructions.
```

### 网络错误

组件自动处理网络错误并显示错误状态. 使用 `onLoadError` 调用以执行自定义错误处理、重试逻辑或错误报告.

## 无障碍

所有组件都考虑到无障碍性:

-   **ARIA 标签**页:1 `role`, (中文(简体) ), `aria-label`,以及 `aria-live` 属性
-   **键盘导航**: 完整的键盘支持(Tab, Enter, Space)
-   **重点管理**: 通过 CSS 变量可见焦点环
-   **屏幕阅读器支持**: 装入/误入状态状态通知

## API 参考

### `loadDialstackAndInitialize(options)`

以您可公布的密钥和会话获取器初始化 DialStack SDK .

**参数:**

-   `options.publishableKey` (字符串, 需要): 您的 DialStack 可发布密钥( 起始于 `pk_live_` 或者说 `pk_test_`(中文(简体) )
-   `options.fetchClientSecret` (职能,要求): 从后端获取客户端机密的 Async 函数 。 可以返回字符串或 `{ clientSecret, expiresAt }`。 。 。 .
-   `options.appearance` (对象,可选): 主题选项
-   `options.apiUrl` (字符串,可选):自定义 API 端点 URL

**回返情况:** `Promise<DialStackInstance>`

### `DialstackComponentsProvider`

反应上下文提供者,使DialStack实例和客户端秘密提供给儿童组件.

**道具 :**

-   `dialstack` (拨号系统,需要): 从 DialStack 实例 `loadDialstackAndInitialize()`
-   `children` (反应节点,需要): 儿童成分

## 认证

SDK使用账户范围会议进行认证. 你必须:

1.  使用 DialStack API 调用您的后端创建会话 :
    
    ```bash
    POST https://api.dialstack.ai/v1/account_sessions
    Authorization: Bearer sk_live_YOUR_SECRET_KEY
    DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41
    Content-Type: application/json
    ```
    
2.  提供a `fetchClientSecret` 呼叫时回调 `loadDialstackAndInitialize()` 返回一个 `client_secret` 从你的后端.
    

1小时后,会议结束。 SDK 使用 `fetchClientSecret` 调用.

**安全说明**:只有服务器侧API键才能创建会话. 无法使用会话符号创建新会话, 防止未经授权的会话扩展 .

## 浏览器兼容性

SDK支持所有现代浏览器:

| 浏览器 | 版本 |
| --- | --- |
| 颜色 | 80岁以上 |
| 火花 | 75岁以上 |
| 萨法里 | 13.1+ (中文(简体) ) |
| 边缘 | 80岁以上 |

**所需经费:**

-   ES2015+(ES6)支持
-   Web 组件 v1( 自定义元素, 阴影 DOM)
-   获取 API

**说明:** 不支持 Internet Explorer .

## 文档

完整的文件可在 [https://docs.dialstack.ai (英语)](https://docs.dialstack.ai/)

## 支助

-   [文档](https://docs.dialstack.ai/)
-   [GitHub 问题](https://github.com/dialstack/dialstack-sdk/issues)
-   [GitHub 讨论](https://github.com/dialstack/dialstack-sdk/discussions)

## 许可证

麻省理工学院-见 [自由主义](https://npmcn.com/package/%40dialstack/sdk/LICENSE) 详情

## 常见问题

### @dialstack/sdk 是什么？

官方 JavaScript SDK for DialStack - 垂直SaaS的商业之声注意：该包已被作者标记为弃用——@dialstack/sdk is no longer updated\. Use @dialstack/sdk-js, @dialstack/sdk-react, @dialstack/sdk-webrtc, @dialstack/sdk-server or @dialstack/sdk-native: https://docs\.dialstack\.ai/sdks/installation

### 如何安装 @dialstack/sdk？

在项目目录运行 npm install @dialstack/sdk，或使用 pnpm add / yarn add / bun add。

### @dialstack/sdk 支持 TypeScript 吗？

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

### @dialstack/sdk 支持 ESM 还是 CommonJS？

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

### @dialstack/sdk 需要什么版本的 Node\.js？

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

### @dialstack/sdk 可以商用吗？

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

### @dialstack/sdk 的下载量有多少？

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

### @dialstack/sdk 还在维护吗？

最新版本 2\.1\.0 发布于 2026/08/10（3 个月前）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2025/11/15。作者已将其标记为弃用，新项目建议寻找替代方案。