# @bendyline/squisq-react 中文文档

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

版本：2\.12\.26
npm 元数据更新时间：2026-11-07T19:47:58.153Z
中文译文更新时间：2026-11-07T22:04:33.806Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：15.5 MB，52 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.22\.2 \|\| ^24\.15\.0 \|\| \>=26\.0\.0
- 运行依赖：3 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-03-16T02:10:41.418Z
- 最新版本发布：2026-11-07T19:47:57.797Z
- 近 30 天下载量：7657（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：93（近 12 个月 93 个）

## 中文简介

用于 doc 回放、块渲染和媒体层的回放组件库

## 安装

```sh
npm install @bendyline/squisq-react
```

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

## README

# @bendyline/squisq-反应

用于播放、渲染和与 Squisq 文档互动的响应组件库 。 包括一个全功能多克播放器,基于SVG的块渲染器,介质层和回放钩.

部分 [斯奎斯克语Name](https://github.com/bendyline/squisq) 单相机.

[![npm](https://img.shields.io/npm/v/@bendyline/squisq-react)](https://www.npmjs.com/package/@bendyline/squisq-react) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/bendyline/squisq/blob/main/LICENSE)

## 安装

```bash
npm install @bendyline/squisq-react @bendyline/squisq
```

**同伴依赖性 :** `react` 财务报告和审定财务报表 `react-dom` (v18或v19) (中文(简体) ).

## 快速启动

```tsx
import { DocPlayer } from '@bendyline/squisq-react';
import '@bendyline/squisq-react/styles';

function App() {
  return <DocPlayer markdown={'# Hello\n\nWelcome to Squisq.'} />;
}
```

`DocPlayer` 接受 **无论是** 原始内容 `markdown` (内部分解和转换) **或者说** 解析 `doc`; 如果你已经有一个 `Doc`,通过 `<DocPlayer doc={doc} />`。 。 。 . `basePath` 可选( 默认) `'.'`),是解决相对关系的基础 URL 媒体路径。 没有 `markdown` 也没有 `doc`,玩家使主题为空 而不是崩溃.

> **v1.5 断开更改 :** 旧的 `script` 道具现在 `doc`,则 `audioProvider` 道具现在 `audioController` (类型) `AudioProvider` 曾经 重新命名为 `AudioController`) (中文(简体) ). `LinearDocView` 获得同样的 `markdown` 道具 (英语).

## 构成部分

| 构成部分 | 说明 |
| --- | --- |
| `DocPlayer` | 主要文档播放器, 播放时间、 音频同步及控制 |
| `LinearDocView` | 所有块的以滚动为基础的线性渲染 |
| `BlockRenderer` | 单块基于 SVG 的渲染器 |
| `MarkdownRenderer` | 作为视觉文档的 Renders Squisq 标记 |
| `DocPlayerWithSidebar` | 带有侧边栏导航面板的 DocPlayer |
| `CaptionOverlay` | 时间性字幕/字幕覆盖 |
| `DocProgressBar` | 播放进度指标 |
| `DocControlsOverlay` | 浮动回放控制 |
| `DocControlsBottom` | 下行播放控制 |
| `DocControlsSidebar` | 侧边栏导航控制 |
| `DocControlsSlideshow` | 幻灯片放映式导航控制 |
| `SocialCaptionOverlay` | 大型以字为中心(TikTok/Reels-style)的标题 |
| `InlineVideoPlayer` | 土著 `<video>` 包装解析 `src`编号 :`poster` 通过媒体链接 |
| `InlineAudioPlayer` | 土著 `<audio>` 包装解析 `src` 通过媒体链接 |
| `AnimatedImageControls` | 播放/暂停对动画 GIF/WebP/APNG 图像的控制 |
| `MediaClipLayer` | 隐藏 `<audio>`编号 :`<video>` 定时媒体剪辑的元素 |
| `JsonView` | JSON 值只读查看器, 绑定在 Squisq- a附加说明的图中 |

### 栅栏码复制控制

`MarkdownRenderer` 而线性文档表面保持代码复制UI 默认。 打开 `showCodeCopyButton`。网络主机可以依赖 `navigator.clipboard`;电能或原生嵌入可以提供自己的 剪贴板桥:

```tsx
<LinearDocView
  markdown={'```\n$ node packages/tooling/dist/cli.mjs components\n```'}
  showCodeCopyButton
  onCopyCode={(code, { language }) => hostClipboard.writeText(code)}
/>
```

同样的两个道具可以使用 `DocPlayer` (用于线性模式),和 独立静态 `mount()` 选项。 召回收到准确的栅栏 内装物,不包含后置分隔符.

## 层

块由作为 SVG 渲染的打字层组成:

| 层 | 说明 |
| --- | --- |
| `ImageLayer` | 背景和前景图像 |
| `TextLayer` | 带有定位和动画的样式文本 |
| `ShapeLayer` | SVG 形状( 矩形、 圆形、 线形) |
| `PathLayer` | Freeform SVG 路径绘图 |
| `VideoLayer` | 播放同步的内嵌视频 |
| `TableLayer` | 通过 SVG 嵌入的 HTML 表格 `<foreignObject>` |
| `MapLayer` | 基于平面图的渲染 |
| `TreeLayer` | 交互式文件系统/外线树 |

## 钩子

| 钩子 | 说明 |
| --- | --- |
| `useDocPlayback` | 核心回放状态机——计时,块过渡,脚本 |
| `useAudioSync` | 以 doc 时间表同步音频播放 |
| `useMediaSchedule` | 确定当前哪些定时媒体剪辑活动 |
| `useViewportOrientation` | 用于响应布局的音轨视图方向 |
| `useAutoSurface` | 活光/暗地表探测 `prefers-color-scheme` |
| `useMediaProvider` 编号 : `useMediaUrl` | 通过媒体 URL 分辨率 `MediaContext` |

`useDocPlayback` 将配置作为选项对象 :

```ts
useDocPlayback(doc, currentTime, { viewport, theme, onSeek });
```

## 独立玩家

非反应环境可使用全球建筑。 它暴露了一个 `SquisqPlayer` 全球 `mount`, (中文(简体) ), `getHandle`, (中文(简体) ), `unmount`,以及 `version`。 。 。 . `mount` 返回实例控件。 将软件包样式表与 原始全局架构, 这样作者Font Aweasy 图标可以使用共享的 Webfonts .

默认构建为轻玩家并省略美人鱼的多兆字节解析器 还有布局引擎 装有人鱼围栏的文档应使用全套 变量在 `dist/squisq-player.full.global.js` (也导出为 `@bendyline/squisq-react/standalone/full`) (中文(简体) ). 其他图表由 两个变体.

前者 `mountStatic()` 快捷键被删除; 通过 `mode: 'static'` 改为 `mount()`。渲染方法是实例范围,不再复制到 顶级 `window.seekTo` 编号 : `window.getDuration` 属性.

交互式挂载 :

```html
<link rel="stylesheet" href="https://unpkg.com/@bendyline/squisq-react/dist/styles/index.css" />
<script src="https://unpkg.com/@bendyline/squisq-react/dist/squisq-player.global.js"></script>
<div id="player"></div>
<script>
  // docJson is a Doc (e.g. produced by markdownToDoc and serialized)
  const root = document.getElementById('player');
  const handle = SquisqPlayer.mount(root, docJson, {
    mode: 'slideshow', // or 'static' for a scrollable document view
    basePath: '/',
  });

  // In render mode: const api = await handle.renderAPI;
  // The same handle is available later as SquisqPlayer.getHandle(root).
</script>
```

对于无头捕捉,添加 `renderMode: true`,然后等待着 `handle.renderAPI` 打电话前 `seekTo()` 或读取生成元数据. `seekTo()` 只有在 React 承诺了所需的视觉时间后才能解决, CSS动画已定位, 活动视频已生成其追求 画框,一个最后的油漆机会完成. `getRenderedTime()` 返回承诺的 DOM 所代表的时间. 类型脚本主机可以导入 `MountOptions` 财务报告和审定财务报表 `SquisqPlayerHandle` 从 软件包根.

设定 `animationsEnabled: false` 打开 `DocPlayer`, (中文(简体) ), `BlockRenderer`,或独立 `mount()` 作为静态使编译的图层动画和块过渡 内容。 嵌入式视频、定时媒体、字幕、音频和文件计时停留 活动;这使得选项适合紧凑的MP4和动画-GIF导出.

对于构建时间嵌入, `@bendyline/squisq-react/standalone-source` 出口 玩家作为自定义的字符串常数( q)`PLAYER_BUNDLE`与 共享图标样式 。 它被使用为 `@bendyline/squisq-formats` 和 CLI 来生产单文件 HTML 并提供了视频导出.

## 图表

`@bendyline/squisq-react/diagram-pictures` 为文档绘制 PNG 图表 导出( 只浏览器) : `renderMermaidPicture`, (中文(简体) ), `renderSquisqDiagramPicture` (ASCII 图表和时间表、绘图、布局和图表块,裁剪到 他们的含量,没有滑动的铬, `renderTreePicture`,以及 `createDiagramPictureRenderer`,显示器 `rasterizeDiagrams` 内 `@bendyline/squisq-formats/diagrams` 拿着 图片是 Plain SVG 绘制到 a 画布 — SVG 文字标签的美人鱼, 不 `<foreignObject>` - 所以回读 在每个浏览器中工作,文本使用系统字体,因为图片不能 加载页面的网页字体.

## 样式

导入块过渡的软件包 CSS 和字体优美内线图标 :

```ts
import '@bendyline/squisq-react/styles';
```

## 完整 API 参考

见 [文件/API.md](https://github.com/bendyline/squisq/blob/main/docs/API.md) 用于完整的道具表格、钩子签名和类型.

## 相关软件包

| 软件包 | 说明 |
| --- | --- |
| [@bendyline/squisq (英语)](https://www.npmjs.com/package/@bendyline/squisq) | 无头核心——计划,模板,空间,标记下,存储 |
| [@bendyline/squisq-formats (中文(简体) )](https://www.npmjs.com/package/@bendyline/squisq-formats) | DOCX, PDF, HTML 导入/导出 |
| [@bendyline/squisq-editor-反应](https://www.npmjs.com/package/@bendyline/squisq-editor-react) | 使用原始/ WYSIWYG/ 预览模式进行反应编辑器 |

## 许可证

[麻省理工学院](https://github.com/bendyline/squisq/blob/main/LICENSE)

## 常见问题

### @bendyline/squisq-react 是什么？

用于 doc 回放、块渲染和媒体层的回放组件库

### 如何安装 @bendyline/squisq-react？

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

### @bendyline/squisq-react 支持 TypeScript 吗？

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

### @bendyline/squisq-react 支持 ESM 还是 CommonJS？

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

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

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

### @bendyline/squisq-react 可以商用吗？

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

### @bendyline/squisq-react 的下载量有多少？

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

### @bendyline/squisq-react 还在维护吗？

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