# spreadjs-docs

**Repository Path**: GrapeCity/spreadjs-docs

## Basic Information

- **Project Name**: spreadjs-docs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SpreadJS 产品文档

[English](README.en.md) | 中文

这个仓库是 SpreadJS 中文产品文档的 Markdown 版本，方便开发者和 AI Agent 直接检索、引用和离线阅读。正文为中文。

仓库里有完整的产品文档，但**不含图片资源**；也**不含方法级 API 文档**——那部分单独开源在 `spreadjs-api-reference`（见下方「相关仓库」）。要查某个类、方法、参数或返回值，请去那个仓库。

## 相关仓库

| 仓库 | 内容 |
| --- | --- |
| [spreadjs-docs](https://github.com/GrapeCityXA/spreadjs-docs) | 产品文档：使用指南、功能说明、公式函数参考，按版本分目录（本仓库） |
| [spreadjs-api-reference](https://github.com/GrapeCityXA/spreadjs-api-reference) | API 参考：TypeDoc 生成的完整符号文档，按版本分目录 |
| [spreadjs-practice-samples](https://github.com/GrapeCityXA/spreadjs-practice-samples) | 实战示例：按场景分类的可运行示例工程 |

## 版本目录

| 目录 | 说明 |
| --- | --- |
| [`v19.1/`](v19.1/) | 1354 篇。重构后的新结构，当前最新 |
| [`v19.0/`](v19.0/) | 1297 篇。重构前的结构 |
| [`v18.2/`](v18.2/) [`v18.1/`](v18.1/) [`v18.0/`](v18.0/) [`v17.1/`](v17.1/) [`v17.0/`](v17.0/) | 与 v19.0 结构一致 |

### 两套结构的分界

从 **19.1** 起，产品文档的目录结构做过一次重构：章节重新划分，原本散落的信息按主题聚合。**19.0 及更早**（18.x、17.x）沿用重构前的结构，各版本之间差别不大。

按你项目的版本选目录即可。如果只是想找某个主题在哪，用下面这张对照表：

| 内容 | 19.1 | 19.0 及更早 |
| --- | --- | --- |
| 产品概述 | `0.新手入门/0.概述.md` | `0.SpreadJS 概述.md` |
| 快速开始 | `0.新手入门/1.快速开始/` | `1.快速开始/` |
| 框架集成 | `1.开发指南/0.框架集成/` | `2.框架中开发/` |
| 性能优化 | `1.开发指南/2.平台与质量/1.性能优化/` | `3.最佳实践/` |
| 移动端与触控 | `1.开发指南/2.平台与质量/2.移动端与触控.md` | `8.移动端与触控/` |
| 产品功能 | `2.产品功能/` | `4.产品特性/` |
| 设计器组件 | `3.设计器（工具栏）/` | `6.设计器组件/` |
| 桌面端应用 | `3.设计器（工具栏）/11.桌面端应用/` | `5.桌面端应用/` |
| 协同编辑 | `4.协同编辑/` | `7.SpreadJS 协同编辑/` |
| 公式与函数 | `5.公式/` | `9.公式引用/` |
| 导入导出 | `2.产品功能/4.文件操作/` | `10.导入导出参考/` |
| 常用事件 | 未收入 19.1 | `11.常用事件.md` |
| API 索引 | `7.API 与参考/0.API 索引.md` | `12.API 索引.md` |
| 发布说明 | `7.API 与参考/2.发布说明/` | `14.发布说明/` |
| VSCode 插件 | `6.VSCode 插件.md` | 无 |

「常用事件」是重构时被去掉的一章，19.1 里事件示例分散在各功能章节。需要集中看事件用法时，查 `v19.0/11.常用事件.md`。

## SpreadJS 是什么

SpreadJS 是运行在浏览器端的类 Excel 电子表格控件。把它嵌进 Web 应用，用户就获得了表格编辑、数据录入、公式计算、样式设置、Excel 导入导出和数据可视化这些能力。

核心对象模型只有三层：

```text
Workbook -> Worksheet -> Range / Cell
```

一个页面创建一个 `Workbook`，工作簿里包含多个 `Worksheet`，绝大多数数据、公式和样式操作都落在单元格或区域上。

| | |
| --- | --- |
| 产品主页 | https://www.grapecity.com.cn/developer/spreadjs |
| 在线文档 | https://demo.grapecity.com.cn/spreadjs/help/docs/ |
| API 参考（在线） | https://demo.grapecity.com.cn/spreadjs/help/api/ |
| 在线示例 | https://demo.grapecity.com.cn/spreadjs/SpreadJSTutorial/ |
| NPM | [`@grapecity-software/spread-sheets`](https://www.npmjs.com/package/@grapecity-software/spread-sheets) |

## 目录怎么组织的

每个版本文件夹的内部结构都对应文档站的目录树：

- **顶层文件夹**是一级章节，前缀数字是阅读顺序，例如 `2.产品功能`
- **叶子文档**命名为 `{顺序}.{标题}.md`
- **章节自身的正文**（章节概述页）有两个位置：`{顺序}.{标题}/index.md`，或者与文件夹同级的 `{顺序}.{标题}.md`。两种写法都在用，找某一章的概述页时两处都看一眼
- **每篇文档的第一行**是 `# 英文-slug`，不是它的中文标题。例如工作表那篇的开头是 `# work-with-worksheets`。这个 slug 可以当英文关键词用
- **编号不一定连续**，缺号是正常的，以实际目录为准

单篇平均 3 KB 左右，最长的（报表模板的基本函数）约 130 KB。

## 各章节速查（v19.1）

| 目录 | 篇数 | 里面有什么 |
| --- | --- | --- |
| `0.新手入门` | 7 | 产品概述与适用场景、快速开始（Vite + NPM）、试用与许可、最终用户许可协议、FAQs |
| `1.开发指南` | 38 | Vue / React / Angular / NextJS / NuxtJS 集成、TypeScript、按需加载、独立模块打包（Webpack / Vite / Rollup / ESBuild 等）、兼容性与运行环境、性能优化、移动端与触控、无障碍、CSP |
| `2.产品功能` | 492 | 核心概念（工作簿、工作表、行列、单元格、数据绑定、键盘行为、文化）；数据处理与分析（数据管理器、集算表、甘特表、报表、数据透视表、排序、筛选、分组、假设分析）；可视化（图表、迷你图、数据图表、形状、浮动对象、条件格式、主题）；文件操作（导入导出 Excel / CSV / JSON、导出 PDF、打印、JSON Schema）；AI 助手 |
| `3.设计器（工具栏）` | 94 | 设计器组件：主题、界面、定制、工具栏功能区、打印、JavaScript 框架、桌面端应用 |
| `4.协同编辑` | 65 | 协同快速开始、功能配置、协同原理与机制（js-collaboration 系列底层框架）、开发参考、附录 |
| `5.公式` | 589 | 公式概述、公式使用（增量计算、语言包、工作表之外计算公式）；**公式函数 542 篇**，一个函数一篇，按类别分目录（数学与三角函数、查找与引用、财务、统计、日期和时间、文本、工程、信息、逻辑、正则、Web、条形码等） |
| `6.VSCode 插件.md` | 1 | 在 VSCode 里直接编辑 `.sjs` / `.xlsx` / `.csv` 等文件的插件 |
| `7.API 与参考` | 68 | API 索引（命名空间级）、各版本发布说明（19.x 回溯到 10.x） |

## 各章节速查（v19.0 及更早）

19.0 的章节划分如下，18.x 和 17.x 与之一致：

| 目录 | 篇数 | 里面有什么 |
| --- | --- | --- |
| `0.SpreadJS 概述.md` | 1 | 产品定位、对象模型、适用场景 |
| `1.快速开始` | 13 | 脚手架创建工程、运行环境、组件库、TypeScript、UMD 支持、对象继承、第三方依赖、辅助功能、NPM 包迁移、试用与许可、EULA、FAQs |
| `2.框架中开发` | 38 | Vue、React、Angular、AngularJS、Breeze、Knockout、NextJS、NuxtJS、独立模块打包 |
| `3.最佳实践` | 8 | 绘制挂起与恢复、设置大量公式、设置大量数据、避免 Volatile 类函数、事件监听挂起与恢复、脏数据机制挂起与恢复、增量加载、简化复杂公式 |
| `4.产品特性` | 447 | 工作簿、工作表、行列、单元格、数据绑定、数据管理器、集算表、甘特表、报表、数据图表、数据验证、条件格式、排序、分组、公式、序列化、键盘行为、形状、表单控件、浮动对象、条形码、图表、迷你图、表格、数据透视表、切片器、打印、主题、用户管理、文化、AI 助手 |
| `5.桌面端应用` | 3 | 启动设计器、打开和保存文件 |
| `6.设计器组件` | 76 | 快速入门、主题、界面、JavaScript 框架、定制、工具栏功能区、打印、API 文档 |
| `7.SpreadJS 协同编辑` | 56 | 协同框架基础、协同框架、性能测试报告、术语表、协同授权 |
| `8.移动端与触控` | 1 | 选择操作 |
| `9.公式引用` | 564 | 公式概述、公式函数（540 篇） |
| `10.导入导出参考` | 23 | Excel 导入导出、导出 PDF、CSV、JSON、区域导出 HTML |
| `11.常用事件` | 1 | 各类事件的代码示例（单击单元格、剪贴板变更等） |
| `12.API 索引.md` | 1 | 命名空间级 API 索引 |
| `14.发布说明` | 61 | 各版本发布说明（19.0 回溯到 9.x） |

## API 文档在另一个仓库

本仓库的 API 部分只有一个命名空间级别的索引（`7.API 与参考/0.API 索引.md`），列到 `GC.Spread.Sheets.Charts` 这样的层级就结束了，没有类、方法、参数和返回值。

完整 API 参考在这里：**https://github.com/GrapeCityXA/spreadjs-api-reference**

那份文档由 TypeDoc 从源码注释生成，纯 Markdown，同样按版本分目录，覆盖 v17.0 到 v19.1（README 中另列有 v16.2）。每个版本下是 `modules/`、`classes/`、`interfaces/`、`enums/` 四棵树，另加 `designer/`、`excelio/`、`collaboration/` 三棵子树（`collaboration/` 从 v18.0 起才有）。正文说明是中文，签名、类型名和代码示例与语言无关。

几条使用提示：

- 不要用类名直接拼路径。文件名通常等于全限定名，但 TypeDoc 遇到重名会加 `-1` 后缀（有 23 个这样的文件）。先 `find` 或 `grep` 定位
- 想先建立整体印象，从对应版本的 `modules/` 入口文件读起，成本最低
- 各版本都带一个 `toc.json`，适合浏览结构，不适合精确查找：`Text` 和 `DisplayName` 字段不唯一，标为 `"file"` 的条目也没有对应文件

## 怎么读

第一次上手，按这个顺序：

1. [`v19.1/0.新手入门/0.概述.md`](v19.1/0.新手入门/0.概述.md) — 弄清楚产品边界，哪些场景不适合用
2. [`v19.1/0.新手入门/1.快速开始/index.md`](v19.1/0.新手入门/1.快速开始/index.md) — 跑起来一个最小示例
3. [`v19.1/1.开发指南/0.框架集成/`](v19.1/1.开发指南/0.框架集成/) — 按你用的框架进对应的一篇
4. 之后按需查 `2.产品功能` 或 `5.公式`

想全量搜索的话，clone 下来用 ripgrep 比在 GitHub 网页上点更快：

```bash
git clone <repo-url>
rg "工作表保护" v19.1/           # 按中文标题找
rg "work-with-worksheets" v19.1/  # 按英文 slug 找
rg "SUMIF" v19.1/5.公式/          # 找某个函数
```

## 已知限制

这两条会直接影响引用和检索，用之前先知道。

### 1. 站内链接全部失效

约 2416 处，分布在 475 个文件里，形如：

```markdown
您可以使用 [Workbook.addSheet](gcdocsite__documentlink?toc-item-id=8a4039d6-22a0-4e4c-81a6-dd3e37d185b0#addSheet) 方法将工作表添加到工作簿。
```

`toc-item-id` 是文档站的内部标识，仓库里没有对应的映射文件，链接点不开。但链接的两部分仍然有信息量：

- 链接文字 `Workbook.addSheet` 是目标文档的标题，拿它反查文件名或正文能定位到目标
- URL 片段 `#addSheet` 是目标 API 成员名，可以拿去 [GrapeCityXA/spreadjs-api-reference](https://github.com/GrapeCityXA/spreadjs-api-reference) 里查

### 2. 图片不在仓库里

约 2214 处，分布在 535 个文件里，形如：

```markdown
![image](/DOCUMENT_SITE_LINK_PREFIX_HERE/document-site-files/images/0f73f140-.../image-20260526.png?width=800)
```

`DOCUMENT_SITE_LINK_PREFIX_HERE` 是发布时替换的占位符。代码示例和文字说明都完整，纯文字章节不受影响；依赖截图或示意图的章节（图表、形状、设计器界面、条件格式效果）需要对照[在线文档](https://demo.grapecity.com.cn/spreadjs/help/docs/)看。

## 给 AI Agent 的检索说明

### 定位顺序

1. **先按章节路由**，别一上来就全库满量搜索。上面的速查表基本能直接定位到目录
2. **再在目录里搜关键词**。中文标题和正文用中文词搜，`#` 开头的英文 slug 用英文词搜
3. **公式问题**直接定位到 `v19.1/5.公式/2.公式函数/{类别}/{序号}.{函数名}.md`。这些文件很短，每篇是固定的「说明 / 语法 / 参数 / 注释」结构，适合整篇读
4. **API 签名问题去 spreadjs-api-reference 仓库查**，不要从本仓库正文的代码示例反推签名。同一个问题在旧版本上问，就去那个仓库的对应版本目录
5. **跨版本查询**：19.1 和 19.0 的路径不通用，先判断用户用的是哪个版本，再选目录。用户没说版本时，19.1 优先

### 引用格式

引用时给**文件路径 + 标题**，不要给 `toc-item-id`：

```
来源：v19.1/2.产品功能/1.核心概念/1.工作表/0.使用工作表.md
```

### 别做的事

- 不要试着解析或还原 `gcdocsite__documentlink` 里的 UUID，仓库内没有任何东西能把它映射到文件
- 不要假设图片存在，也不要在回答里引用图片内容
- 不要把 19.1 的章节路径套到 19.0 或更早的版本上

### 给 Agent 的开场说明（可复制）

```text
你可以在本地仓库 <path> 里查 SpreadJS 产品文档，API 参考在另一个仓库 <api-path>。

产品文档规则：
- 按版本分目录：v19.1/（重构后的新结构，优先用）、v19.0/（旧结构，18.x/17.x 同）
- 目录对应文档树：{序号}.{标题}/ 是章节，{序号}.{标题}.md 是叶子文档，
  章节概述页在 {序号}.{标题}/index.md 或同级的 {序号}.{标题}.md
- 每篇第一行是英文 slug（如 # work-with-worksheets），不是中文标题
- 公式函数一篇一个文件，在 v19.1/5.公式/2.公式函数/{类别}/ 下
- 19.1 没有「常用事件」章节，事件示例要查 v19.0/11.常用事件.md

已知缺陷，注意避开：
- 站内链接形如 [文字](gcdocsite__documentlink?toc-item-id=<uuid>) 全部失效，
  不要尝试打开。链接文字是目标标题，可用它反查文件
- 图片形如 ![...](/DOCUMENT_SITE_LINK_PREFIX_HERE/...) 缺失，内容不可见
- 本仓库没有方法级 API 文档，只有命名空间索引。API 签名问题去 API 仓库查

引用时给出文件路径，不要给 toc-item-id。
```

## 版权与许可

文档内容的版权归西安葡萄城软件有限公司所有。仓库中不含开源许可证声明；如需转载或商用文档内容，请遵循葡萄城的许可条款。