# onlyoffice-web-comp

**Repository Path**: xdqa01/onlyoffice-web-comp

## Basic Information

- **Project Name**: onlyoffice-web-comp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OnlyOffice Web Comp

> 📖 [English](README.md) | 中文

🌐 **在线演示**: [https://onlyoffice-web-comp.vercel.app/](https://onlyoffice-web-comp.vercel.app/)

基于 OnlyOffice 静态 SDK 的浏览器端文档处理方案：在客户端完成 Word / Excel / PowerPoint 的查看、编辑与转换，**无需 Document Server**。

本仓库包含两部分：

| 部分 | 路径 | 说明 |
|------|------|------|
| **组件库** | [`src/components/onlyoffice-web-comp/`](src/components/onlyoffice-web-comp/) | 可复用的 Web 端编辑器封装 + Markdown 文档源 |
| **演示站点** | [`src/app/`](src/app/) + [`src/features/`](src/features/) | Next.js 主页、文档站、在线示例 |

## 项目定位

这个项目目前不是一个 `npm install` 后直接引入的包，而是一个浏览器端 OnlyOffice 集成模板：可复用的运行时代码在 `src/components/onlyoffice-web-comp/`，仓库同时包含这套运行时需要的 OnlyOffice SDK / x2t 静态资源。

如果你希望在自己的 Web 项目里接入 OnlyOffice，并且不想部署 OnlyOffice Document Server，可以把这里当作一套可复制的工程实现。演示站点也是项目的一部分，目的是让你直接参考一个已经跑通的编辑器生命周期，而不是只看零散 API 片段。

## 怎么集成进你的项目

实际接入可以按这个路径做：

1. 复制 [`src/components/onlyoffice-web-comp/`](src/components/onlyoffice-web-comp/) 到你的项目源码目录。
2. 复制 [`public/packages/onlyoffice/`](public/packages/onlyoffice/) 静态资源到你的项目 `public/packages/onlyoffice/` 目录。
3. 参考 [`src/features/demo/office-preview-page.tsx`](src/features/demo/office-preview-page.tsx) 构造自己的界面：准备编辑器容器，维护一个 `OnlyOfficeManager` 实例，按需调用 `openDocument`、`downloadExport`、`toggleReadOnly`，并在页面卸载时销毁 manager。

静态资源读取统一在 [`src/components/onlyoffice-web-comp/const/index.ts`](src/components/onlyoffice-web-comp/const/index.ts) 配置。本地与 CDN 模式默认均读取 Developer Edition Docker 导出的 9.4 SDK：`/packages/onlyoffice/9.4.0-develop`；如 CDN 目录不同，可通过 `onlyofficeVersion` 覆盖。

## 核心优势

- **数据留在本地**：文档处理在浏览器内完成
- **格式兼容**：Word、Excel、PowerPoint、CSV、DOCM 等
- **零后端**：托管静态 SDK 即可使用
- **工程化 API**：只读/编辑、主题/语言、多实例容器隔离

## 快速体验

1. 访问 [在线演示](https://onlyoffice-web-comp.vercel.app/) 或本地启动：

```bash
git clone <repository-url>
cd onlyoffice-web-comp
pnpm install
pnpm dev
# http://localhost:3001
```

2. 打开路由：

| 路由 | 说明 |
|------|------|
| `/` | 产品主页 |
| `/docs` | 组件库文档（直接渲染 Markdown） |
| `/docs/demos/single` | 单实例在线示例 |
| `/docs/demos/multi` | 多实例 Tab 在线示例 |

3. 上传本地文件 → 编辑 → 导出

旧路由 `/examples` 会重定向到单实例示例；`/multi` 会重定向到多实例示例。

## 组件库文档

**API 与接入说明不在本 README 重复**，请阅读组件库文档：

- **入口**：[组件库 README（中文）](src/components/onlyoffice-web-comp/readme.zh.md)
- **概述**：[docs/概述.md](src/components/onlyoffice-web-comp/docs/概述.md)

| 文档 | 内容 |
|------|------|
| [快速开始](src/components/onlyoffice-web-comp/docs/快速开始.md) | 初始化与容器挂载 |
| [核心API](src/components/onlyoffice-web-comp/docs/核心API.md) | `OnlyOfficeManager`、多实例 |
| [事件系统](src/components/onlyoffice-web-comp/docs/事件系统.md) | EventBus |
| [完整示例](src/components/onlyoffice-web-comp/docs/完整示例.md) | React 集成模式 |
| [API参考](src/components/onlyoffice-web-comp/docs/API参考.md) | 常量与类型 |
| [注意事项与格式](src/components/onlyoffice-web-comp/docs/注意事项与支持格式.md) | 前置条件与格式 |
| [字体配置](src/components/onlyoffice-web-comp/docs/字体配置.md) | 自定义字体注册 |
| [批注修订](src/components/onlyoffice-web-comp/docs/批注修订与-Word-API.md) | 批注、修订 |
| [单实例示例](src/components/onlyoffice-web-comp/docs/单实例示例.md) | 单实例 Demo 与源码说明 |
| [多实例示例](src/components/onlyoffice-web-comp/docs/多实例示例.md) | Tab 多实例完整源码 |

```typescript
import { OnlyOfficeManager, FILE_TYPE, ONLYOFFICE_ID } from "@/components/onlyoffice-web-comp";
```

## 项目结构

```
onlyoffice-web-comp/
├── src/
│   ├── app/                              # Next.js 路由
│   │   ├── page.tsx                      # 主页
│   │   ├── docs/                         # 文档站
│   │   │   ├── page.tsx                  # /docs（概述 md）
│   │   │   ├── [slug]/page.tsx           # /docs/*
│   │   │   └── demos/                    # /docs/demos/single|multi
│   │   └── examples/                     # → 重定向至单实例示例
│   ├── features/
│   │   ├── docs/                         # 文档壳、Markdown 渲染、site-map
│   │   ├── demo/                         # 在线演示组件
│   │   ├── marketing/                    # 着陆页
│   │   └── shell/                        # 站点 Header / Footer / Layout
│   └── components/
│       └── onlyoffice-web-comp/          # SDK 封装 + docs/*.md 文档源
├── public/                               # OnlyOffice SDK 静态资源
└── ...
```

文档页直接读取 `src/components/onlyoffice-web-comp/docs/` 下的 Markdown；示例 Tab 内嵌 `src/features/demo/` 的可交互编辑器。

## 技术栈

- **OnlyOffice SDK**：文档编辑核心
- **x2t + WebAssembly**：格式转换
- **Next.js 15 + React 19**：演示应用

## 部署

```bash
pnpm install
pnpm build
```

可部署至 Vercel 或任意静态托管。演示地址：[https://onlyoffice-web-comp.vercel.app/](https://onlyoffice-web-comp.vercel.app/)

### 将 SDK 静态资源部署到 Cloudflare Pages CDN

OnlyOffice SDK 资源可以和应用分开托管。把 `public/packages` 的内容部署到 Cloudflare Pages，然后在创建编辑器前注册 Pages 地址即可。

```bash
# 首次创建项目
npx wrangler pages project create onlyoffice-packages

# 将 public/packages 作为 CDN 根目录上传
npx wrangler pages deploy public/packages \
  --project-name onlyoffice-packages \
  --commit-dirty=true
```

部署后资源地址应该类似：

```text
https://<project>.pages.dev/onlyoffice/9.4.0-develop/web-apps/apps/api/documents/api.js
```

在运行时把 Pages origin 注册为静态资源根地址：

```typescript
import { OnlyOfficeManager } from "@/components/onlyoffice-web-comp";

OnlyOfficeManager.registerStaticResource({
  cdnOrigin: "https://<project>.pages.dev",
});
```

`cdnOrigin` 对应上传后的 `public/packages` 根目录，不需要再追加 `/packages`。在 [`src/components/onlyoffice-web-comp/const/index.ts`](src/components/onlyoffice-web-comp/const/index.ts) 中修改 `buildStaticResource` 的 `cdnOrigin` 逻辑即可固定资源来源。Cloudflare Pages Direct Upload 支持用 Wrangler 上传目录；由于 SDK 文件数量较多，Dashboard 拖拽上传不太适合本仓库。

## 字体配置

自定义字体通过 **`__custom_font_registry__`** 注册，配合 **`ttf-to-catalog-font.mjs`** 生成 OnlyOffice catalog 线格式。完整步骤见组件库文档 **[字体配置](src/components/onlyoffice-web-comp/docs/字体配置.md)**。

简要流程：

1. 运行 `ttf-to-catalog-font.mjs --id <id> --verify` 生成 `fonts/{id}` catalog 文件
2. 在 `AllFonts.js` 的 `window["__custom_font_registry__"]` 中注册 id 与别名
3. 确保别名覆盖文档内实际使用的字体名

请确保所用字体文件符合相关许可协议。

## 相关资源

- [OnlyOffice API 文档](https://api.onlyoffice.com/zh-CN/docs/docs-api/usage-api/config/document/)
- [OnlyOffice Web Apps](https://github.com/ONLYOFFICE/web-apps)
- [OnlyOffice SDK](https://github.com/ONLYOFFICE/sdkjs)
- [x2t-wasm](https://github.com/cryptpad/onlyoffice-x2t-wasm)

## 参与贡献

欢迎提交 Issue 和 Pull Request。

## 开源许可

详见 [LICENSE](LICENSE)。