# @dittolive/react-ditto 中文文档

规范地址：https://npmcn.com/package/%40dittolive/react-ditto/

版本：1\.0\.1
npm 元数据更新时间：2026-10-22T15:51:42.378Z
中文译文更新时间：2026-11-12T11:38:27.671Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：202 kB，104 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- peer 依赖：react \>=16\.0\.0，react-dom \>=16\.0\.0，@dittolive/ditto ^5\.0\.0
- 首次发布：2021-10-04T08:50:37.725Z
- 最新版本发布：2026-06-09T17:57:26.561Z
- 近 30 天下载量：23871（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 2 个）

## 中文简介

Ditto 的回放包装

## 安装

```sh
npm install @dittolive/react-ditto
```

也可以使用：`pnpm add @dittolive/react-ditto`、`yarn add @dittolive/react-ditto`、`bun add @dittolive/react-ditto`

## README

# Ditto 的回放收发夹库

[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) ![example workflow](https://github.com/getditto/react-ditto/actions/workflows/ci.yml/badge.svg)

这是用于 [抖出](https://www.ditto.live/)。 。 。 .

目前,这个项目在网页浏览器,Node.JS和Electron环境中工作.

如果对该项目有疑问或需要任何援助,请通过 [支持@ ditto.com](mailto:support@ditto.com)。 。 。 .

> **Ditto SDK v5 软件**
> 
> 这个图书馆的目标是 **Ditto v5 SDK 软件** (单位:千美元)`@dittolive/ditto@^5.0.0`)和使用 [DQL (Ditto 查询语言)](https://docs.ditto.live/dql) 专有. 4号 查询- 构建器钩子( t)`usePendingCursorOperation`, (中文(简体) ), `useMutations`(等等)和 身份钩(`useOnlinePlaygroundIdentity`已删除。 见 [Ditto v5 迁移指南](https://docs.ditto.live/sdk/latest/migration-guides/web-js-v4) 根本的SDK改变.

## 安装

用 npm 或 纱线安装此库 :

```
npm install @dittolive/ditto @dittolive/react-ditto
```

```
yarn add @dittolive/ditto @dittolive/react-ditto
```

在您的 React app的顶层,用一个上下文提供者包装它, `DittoProvider` 或者说 `DittoLazyProvider`数字 :

```tsx
<DittoProvider setup={createDittoInstance}>
  {({ loading, error }) => {
    if (loading) return <span>Loading Ditto...</span>
    if (error)
      return (
        <span>There was an error loading Ditto. Error: {error.toString()}</span>
      )
    return <App />
  }}
</DittoProvider>
```

此时此刻,您准备使用由 提供钩子来构建您的 Ditto 应用 图书馆。 阅读以学习如何选择 `DittoProvider` 财务报告和审定财务报表 `DittoLazyProvider`,如何用 v5 API 打开 Ditto 实例,以及如何使用 页:1 `useQuery` 财务报告和审定财务报表 `useExecuteQuery` 钩子.

## 选择提供者

库包括两个初始化 Ditto 上下文的上下文提供者 为您的应用程序: `DittoProvider` 财务报告和审定财务报表 `DittoLazyProvider`。 。 。 .

`DittoProvider` 当您的应用程序所使用的 Ditto 实例集时使用 当应用程序被拖出时,可以创建。 总之 其他情况, `DittoLazyProvider` 可用于懒惰地创建 Ditto 实例 当供养者的孩子首先需要时.

两个供应商的API相同,但 `setup` 道具,哪个 返回时 `Ditto | Ditto[] | Promise<Ditto | Ditto[]>` 页:1 `DittoProvider` 财务报告和审定财务报表 `Promise<Ditto | null>` 页:1 `DittoLazyProvider`。 。 。 .

选择一个供货商而不是另一个供货商对剩下的钩子没有任何影响——它们 无论供应商是谁,使用方式都完全相同.

### Ditto 提供示例

```tsx
import { Ditto, DittoConfig } from '@dittolive/ditto'

const createDittoInstance = async () => {
  const ditto = await Ditto.open(
    new DittoConfig('my-database-id', { mode: 'smallPeersOnly' }, 'some-path'),
  )
  ditto.sync.start()
  return ditto
}

;<DittoProvider setup={createDittoInstance}>
  {({ loading, error }) => {
    if (loading) return <span>Loading Ditto...</span>
    if (error)
      return (
        <span>There was an error loading Ditto. Error: {error.toString()}</span>
      )
    return <App />
  }}
</DittoProvider>
```

### DittoLazy 提供示例

```tsx
import { Ditto, DittoConfig } from '@dittolive/ditto'

const createDittoInstance = async (path: string) => {
  const ditto = await Ditto.open(
    new DittoConfig('my-database-id', { mode: 'smallPeersOnly' }, path),
  )
  ditto.sync.start()
  return ditto
}

;<DittoLazyProvider setup={createDittoInstance}>
  {({ loading, error }) => {
    if (loading) return <span>Loading Ditto...</span>
    if (error)
      return (
        <span>There was an error loading Ditto. Error: {error.toString()}</span>
      )
    return <App />
  }}
</DittoLazyProvider>
```

当多个实例被注册时,钩子通过 `persistenceDirectory` 选项,与您设置的持久性目录匹配 在个案中 `DittoConfig`。省略时,第一审登记为 已使用.

## 打开 Ditto 实例

在v5中,打开一个 Ditto 实例 `Ditto.open(config)` (同步)或 `Ditto.openSync(config)`,其中配置是一个 `DittoConfig` 说明 数据库 ID,连接模式,和一个可选的持久目录.

### 离线/ 对等点

```ts
import { Ditto, DittoConfig } from '@dittolive/ditto'

const ditto = await Ditto.open(
  new DittoConfig('my-database-id', { mode: 'smallPeersOnly' }, '/path'),
)
ditto.sync.start()
```

### 在线( 连接到 Ditto 服务器 / Big Peer)

服务器连接需要设置认证过期处理器 在同步开始前 - `ditto.sync.start()` 抛出其他。 整个复制 从 Ditto 门户网站连接 URL( 通过 SDK 连接) ~ **網址**; 不构建 从数据库的ID.

```ts
import { Authenticator, Ditto, DittoConfig } from '@dittolive/ditto'

const ditto = await Ditto.open(
  new DittoConfig(
    'my-database-id',
    { mode: 'server', url: 'REPLACE_ME_WITH_YOUR_URL' },
    '/path',
  ),
)

await ditto.auth.setExpirationHandler(async (ditto) => {
  await ditto.auth.login('your-token', Authenticator.DEVELOPMENT_PROVIDER)
})

ditto.sync.start()
```

## 查询 `useQuery`

`useQuery` 持续获取非调试 DQL 查询的结果 注册商店观察员和(除非 `localOnly` 设置) 同步 订阅。 它返回当前项目、 装入状态以及任何错误 .

```tsx
import { useQuery } from '@dittolive/react-ditto'

type Task = { _id: string; body: string; isCompleted: boolean }

export default function App() {
  const { items, isLoading, error } = useQuery<Task>(
    'SELECT * FROM tasks WHERE isCompleted = :isCompleted',
    { queryArguments: { isCompleted: false } },
  )

  if (isLoading) return <p>Loading…</p>
  if (error) return <p>Error: {String(error)}</p>

  return (
    <ul>
      {items.map((task) => (
        <li key={task.value._id}>{task.value.body}</li>
      ))}
    </ul>
  )
}
```

## 更改和按需查询 `useExecuteQuery`

`useExecuteQuery` 返回按要求运行 DQL 查询的执行函数. 用于用户引发的突变(插入/更新/删除)和临时查询 行动。 它没有设置同步订阅, 所以双突变与一个 `useQuery` 用于同一收藏,如果需要同步和观察.

```tsx
import { useExecuteQuery } from '@dittolive/react-ditto'

export default function AddTask() {
  const [insertTask] = useExecuteQuery<void, { value: { body: string } }>(
    'INSERT INTO tasks DOCUMENTS (:value)',
  )

  return (
    <button onClick={() => insertTask({ value: { body: 'Buy milk' } })}>
      Add Task
    </button>
  )
}
```

在设置钩和/或调用时可以提供查询参数 执行函数; 当两者都得到提供时, 两者均被浅浮并带有 执行函数的参数优先.

## 快速开始 `vite`

1.  安装库 :

```
npm install @dittolive/ditto @dittolive/react-ditto
```

2.  单位 `./src/index.tsx`,设置 Ditto 与 `DittoProvider`数字 :

```tsx
// ... other imports from vite above
import { Ditto, DittoConfig } from '@dittolive/ditto'
import { DittoProvider } from '@dittolive/react-ditto'

/**
 * This configuration is optional for web browser-based React applications. It
 * tells the `DittoProvider` where to load the .wasm file. If no path is provided
 * (ie. initOptions is undefined), the wasm is loaded from our CDN. If you enable
 * this, make sure to serve `ditto.wasm` with the correct MIME type and CORS
 * headers. See
 * https://www.npmjs.com/package/@dittolive/ditto#browser-environments for
 * details.
 **/
const initOptions = {
  webAssemblyModule: '/ditto.wasm',
}

const RootComponent = () => (
  <DittoProvider
    setup={async () => {
      // Create a database at https://portal.ditto.live/ and copy its database
      // ID and connection URL from the settings page.
      const ditto = await Ditto.open(
        new DittoConfig(
          'your-database-id',
          { mode: 'smallPeersOnly' },
          'testing',
        ),
      )
      ditto.sync.start()
      return ditto
    }}
    /* initOptions={initOptions} */
  >
    {({ loading, error }) => {
      if (loading) return <p>Loading</p>
      if (error) return <p>{error.message}</p>
      return <App />
    }}
  </DittoProvider>
)

const root = ReactDOM.createRoot(document.getElementById('root'))
root.render(
  <React.StrictMode>
    <RootComponent />
  </React.StrictMode>,
)
```

3.  在你身边 `App` 组件,使用 `useQuery` 观察文件 `useExecuteQuery` - 参见以上例子和完整的 [vite 示例应用](https://npmcn.com/package/%40dittolive/react-ditto/examples/vite-typescript-example)。 。 。 .

## 与在线应用程序合作

使用 [门户](http://portal.ditto.live/) 您可以创建同步的应用程序 a Ditto 服务器(大对等服务器)。 配置实例为 a `{ mode: 'server', url }` 连接和认证通过 `ditto.auth`数字 :

-   设置一个过期处理器 `ditto.auth.setExpirationHandler(handler)`编辑 处理器接收 Ditto 实例,并在每次( 重新) 认证时被引用 需要时间.
-   在操作员内部,呼叫 `ditto.auth.login(token, provider)`启用 `Authenticator.DEVELOPMENT_PROVIDER` 游乐场/开发标志,或您的 已配置认证的 webhooks 时, 拥有提供者字符串 门户网.
-   过期的处理器必须在呼叫前设置 `ditto.sync.start()` 页:1 服务器连接 .

当前认证状态可通过 `ditto.auth.status` (单位:千美元)`{ isAuthenticated, userID }`) (中文(简体) ).

## 建此库并进行测试

-   **大楼:** 运行 `npm run build`。 。 。 .
-   **类型检查 :** 运行 `npm run types`。 。 。 .
-   **林特:** 运行 `npm run lint`。 。 。 .
-   **运行测试 :** 运行 `npm test`套房以无头Chrome方式通过卡玛和 练习真正的 Ditto WASM 构建.

## 运行示例应用程序

每个实例项目都在下方的自己的目录中 [./实例](https://npmcn.com/package/%40dittolive/react-ditto/examples) 目录.

## 常见问题

### @dittolive/react-ditto 是什么？

Ditto 的回放包装

### 如何安装 @dittolive/react-ditto？

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

### @dittolive/react-ditto 支持 TypeScript 吗？

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

### @dittolive/react-ditto 支持 ESM 还是 CommonJS？

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

### @dittolive/react-ditto 需要什么版本的 Node\.js？

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

### @dittolive/react-ditto 可以商用吗？

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

### @dittolive/react-ditto 的下载量有多少？

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

### @dittolive/react-ditto 还在维护吗？

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