# onlyoffice

**Repository Path**: yertqyang/onlyoffice

## Basic Information

- **Project Name**: onlyoffice
- **Description**: onlyoffice
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-30
- **Last Updated**: 2025-12-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ONLYOFFICE Vue 2 Integration Demo

这是一个基于 Vue 2 + Vite 集成 ONLYOFFICE Document Server 的示例项目，演示了在线编辑、多人协同（Word/Excel）等功能。

## ✨ 功能特性

- 📝 **在线编辑**: 支持 Word (.docx) 和 Excel (.xlsx) 在线编辑
- 🤝 **多人协同**: 支持多用户同时编辑同一文档
- 🔄 **实时切换**: 可在不同文档类型间无缝切换
- 🐳 **Docker 集成**: 包含完整的 Document Server 部署配置指南
- 🛠 **故障自愈**: 自动检测 IP 配置和网络问题

## 🚀 快速开始

### 1. 前置要求

确保你已安装：

- [Node.js](https://nodejs.org/) (推荐 v16+)
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)

### 2. 启动 Document Server (Docker)

ONLYOFFICE 编辑器核心依赖后端服务。请在终端运行以下命令：

```bash
# 1. 启动服务 (关闭 JWT 验证以便于测试)
docker run -i -t -d -p 80:80 --restart=always -e JWT_ENABLED=false onlyoffice/documentserver

# 2. (重要) 允许 Document Server 访问局域网 IP
# 否则无法下载宿主机上的文件，会导致 "Download failed"
docker exec $(docker ps -q) sed -i 's/"allowPrivateIPAddress": false/"allowPrivateIPAddress": true/' /etc/onlyoffice/documentserver/default.json && docker restart $(docker ps -q)
```

> **注意**: 如果你是国内用户，下载镜像失败（timeout），请在 Docker Desktop 设置中配置镜像加速器（如 `https://docker.m.daocloud.io`）。

### 3. 启动前端项目

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

### 4. 访问

打开浏览器访问：**http://localhost:5173/**

- 在顶部下拉框切换 **User** 可模拟不同用户协同。
- 切换 **Type** 可在 Word 和 Excel 之间切换。

## 📂 项目结构

```
.
├── public/                  # 静态资源 (示例文件 sample.docx/xlsx)
├── src/
│   ├── components/
│   │   └── OnlyOfficeEditor.vue  # 核心编辑器组件
│   ├── App.vue             # 主应用逻辑 (配置生成)
│   └── main.js             # 入口文件
├── vite.config.js          # Vite 配置
└── package.json
```

## 💻 核心代码说明

### 1. 动态生成编辑器配置 (App.vue)

前端的核心逻辑在于 `editorConfig` 计算属性，它根据用户选择动态生成配置对象。

```javascript
// src/App.vue
editorConfig() {
  // 1. 自动适配文件类型 (Word/Excel)
  const isWord = this.currentDocType === 'word';
  const fileExt = isWord ? 'docx' : 'xlsx';
  const documentKey = isWord ? 'sample-word-key-v1' : 'sample-excel-key-v1';

  // 2. 使用局域网 IP (关键: 否则 Docker 容器无法访问 localhost)
  const baseUrl = `http://${this.myIp}:3000`;

  return {
    document: {
      fileType: fileExt,
      key: documentKey, // 唯一标识符，相同 Key 的用户进入同一协同会话
      title: isWord ? 'Sample Document.docx' : 'Sample Spreadsheet.xlsx',
      url: baseUrl + (isWord ? '/sample.docx' : '/sample.xlsx'), // 文档下载地址
      permissions: {
        edit: true,    // 开启编辑权限
        download: true // 允许下载
      }
    },
    documentType: isWord ? 'word' : 'cell', // 'word' | 'cell' | 'slide'
    editorConfig: {
      callbackUrl: baseUrl + '/api/callback', // 3. 配置回调接口 (保存文件)
      user: {
        id: this.users[this.currentUser].id,
        name: this.users[this.currentUser].name
      }
    }
  }
}
```

### 2. 后端回调处理 (server.js)

当用户编辑完成（关闭页面）或触发自动保存时，ONLYOFFICE 会向 `callbackUrl` 发送 POST 请求。

```javascript
// server.js
app.post('/api/callback', (req, res) => {
	const { status, url, users } = req.body

	// Status 2 表示文档已准备好保存
	if (status === 2) {
		console.log('💾 Document is ready for saving!')
		console.log('🔗 Download URL:', url) // ONLYOFFICE 生成的临时下载链接

		// TODO: 在此处使用 http/axios 下载 `url` 内容并覆盖本地文件
	}

	// 必须返回 error: 0 告知 ONLYOFFICE 处理成功
	res.json({ error: 0 })
})
```

### 3. SPA 路由兜底 (server.js)

为了支持 Vue 的 History 模式路由，后端需要拦截所有非 API 请求并返回 `index.html`。

```javascript
// server.js
// 排除 /api 开头的请求，其他请求全部返回 index.html
app.get(/^\/(?!api).*/, (req, res) => {
	res.sendFile(path.join(__dirname, 'dist', 'index.html'))
})
```

## ⚠️ 常见问题

**Q: 界面一直显示 "Loading Editor API..."**
A: 检查 Docker 容器是否运行 (`docker ps`)，确保 80 端口未被占用。

**Q: 打开文档提示 "Download failed"**
A:

1. 确保前端启动命令是 `npm run dev` (我们配置了 `--host` 暴露网络)。
2. 确保执行了上面的第 2 步 Docker 命令（开启 `allowPrivateIPAddress`）。
3. 检查页面顶部的 "Local IP" 是否是你电脑真实的局域网 IP。

**Q: 保存文件提示成功，但本地文件没变？**
A: 这是纯前端演示。`callbackUrl` 指向了一个静态 JSON 文件用于模拟成功响应。要实现真实保存，需要编写后端接口接收 ONLYOFFICE 的 POST 回调并下载文件流。

## 📚 参考文档

- [ONLYOFFICE API Documentation](https://api.onlyoffice.com/docs/docs-api/)
- [Vue 2 Integration Guide](https://api.onlyoffice.com/editors/vue)