整理日期：2026-06-13
适用对象：从 Excel/Google Sheets 迁移到 Grist 的业务人员、表格管理员、数据维护人员、轻量开发者。
主要来源：Grist 官方帮助中心、官方技术文档，并结合本目录当前自托管环境整理。

1. Grist 是什么

Grist 可以理解为“带数据库能力的电子表格”。它保留了表格网格、复制粘贴、公式、筛选等熟悉体验，同时把数据组织成关系型表，并允许你在同一份文档里创建多个页面、多个视图、多个仪表盘。

与传统 Excel 最大的区别是：

• Excel 更像一个个单元格组成的画布，公式常常引用 A1:B20 这类位置。
• Grist 更像数据库，每一行是一条记录，每一列是一个字段，公式引用字段名和记录对象。
• 同一张数据表可以被多个页面和小组件复用，页面只是展示方式，不是另一份数据副本。

适合 Grist 的场景：

• 收款、订单、库存、客户、项目、费用报销等结构化数据。
• 需要多人协作、权限控制、审计回溯的业务表。
• 需要把 Excel 明细表变成可筛选、可汇总、可联动的轻量系统。
• 需要自托管数据、API 集成、自动化通知的团队。

不太适合 Grist 的场景：

• 大量自由排版、复杂合并单元格、打印版式优先的报表。
• 强依赖 Excel 宏、VBA、复杂工作簿链接的模型。
• 上百万行且大量复杂公式实时计算的重型数据仓库场景。

2. 核心概念

站点、工作区、文档

• 站点：一个 Grist 使用空间，个人站点或团队站点。
• 工作区：文档文件夹，可以按项目、部门、业务线归类。
• 文档：一份 .grist 文件，包含表、页面、小组件、附件、公式、部分历史记录等。

表、记录、字段

• 表：类似数据库表，也类似 Excel 的一个数据表。
• 记录：表里的一行。
• 字段：表里的一列。
• 列标签：界面上看到的中文名。
• 列 ID：公式和 API 使用的内部字段名，建议用英文或拼音，稳定且 Python 友好。

经验建议：

• 中文列名适合给业务人员看。
• 列 ID 适合给公式和 API 用，尽量保持简短稳定。
• 不要频繁改列 ID，因为公式、API、自动化可能依赖它。

3. 从 Excel 迁移到 Grist

直接导入

常见路径：

1. 在 Grist 首页点击 Add New。
2. 选择 Import document。
3. 上传 Excel、CSV、TSV、JSON 等文件。
4. 确认每个工作表导入到哪些 Grist 表。
5. 检查列类型、日期、数字和中文字段。

Grist 默认会把新数据导入成新表；也可以在导入窗口里选择导入到已有表，并手工匹配源列和目标列。

导入后的检查清单

• 行数是否和 Excel 一致。
• 日期字段是否被识别成 Date 或 DateTime。
• 金额字段是否为 Numeric，不是文本。
• 身份证号、手机号、单号等是否应保存为 Text，避免科学计数法或前导零丢失。
• 中文工作表名导入后，界面名可能保留中文，但内部表 ID 可能是 Table1、Table2，公式/API 要看实际表 ID。
• 大表导入后先做只读核查，再加公式列，避免一次性复杂公式拖慢文档。

4. 表和列类型

Grist 常用列类型：

• Text：文本、编号、手机号、备注。
• Numeric：金额、数量、面积、单价。
• Integer：整数。
• Toggle：是/否。
• Date：日期，不含时间。
• DateTime：日期时间，带时区显示。
• Choice：单选枚举，如状态、类别。
• Choice List：多选枚举，如标签。
• Reference：引用另一张表的一条记录。
• Reference List：引用另一张表的多条记录。
• Attachment：附件或图片。

建议：

• 状态类字段用 Choice，例如 待审核、已付款、已对账。
• 多标签字段用 Choice List。
• 客户、房间、项目、供应商等实体用独立表，并通过 Reference 关联。
• 日期时间字段要确认文档时区，当前本地文档时区是 Asia/Shanghai。

5. 页面和小组件

Grist 的页面不是数据本身，而是数据的展示和操作界面。

常见小组件：

• Table：表格视图，适合批量查看和编辑。
• Card：单条记录详情。
• Card List：多条记录卡片列表。
• Chart：图表。
• Calendar：日历。
• Form：表单收集数据。
• Custom：自定义网页组件。

页面设计建议：

• 明细表单独放一页。
• 汇总指标放在一个总览页。
• 常用筛选条件放在总览页顶部或左侧。
• 一页里可以放多张表，通过联动实现“点击一个小区，右边显示该小区明细”。
• 原始导入表尽量保留，新增派生列和汇总表来实现智能分析。

6. 小组件联动

Grist 支持把页面上的小组件连接起来。典型例子：

• 左侧是 小区汇总。
• 右侧是 已收费用明细。
• 点击左侧某个小区，右侧只显示该小区明细。

常见联动方式：

• 同表联动：多个视图展示同一条记录的不同形式。
• 过滤联动：一个表作为筛选器，另一个表显示匹配记录。
• 引用联动：通过 Reference 或 Reference List 关系联动。
• 汇总表联动：点击汇总项，显示底层明细或更细粒度汇总。

设计原则：

• 一个页面只解决一个主要问题。
• 选择器小组件放左侧或上方。
• 明细小组件放右侧或下方。
• 汇总表和图表要尽量使用同一个筛选口径。

7. 公式基础

Grist 公式使用 Python 风格。

常见写法：

$Amount * $Qty

($ReceiptAmount or 0) - ($RefundAmount or 0)

return round($Amount or 0, 2)

说明：

• $字段名 表示当前行的字段值。
• 公式列会自动对整列生效，不需要向下填充。
• 最后一行表达式会自动作为返回值，也可以显式写 return。
• 空值常用 or 0 防止计算报错。
• 多行公式使用 Python 语法，注意缩进。

日期公式

把日期时间转成日期：

import datetime
return $收费时间.date() if isinstance($收费时间, datetime.datetime) else $收费时间

日期范围判断常用半开区间：

start <= d < end

这种口径适合“开始时间含、结束时间不含”的报表，例如 2026-06-09 00:00 到 2026-06-10 00:00 只统计 6 月 9 日。

8. 查找和跨表计算

lookupRecords

查找多条记录：

records = 已收费用.lookupRecords(小区=$小区)
sum(r.实收金额 or 0 for r in records)

按多个条件查找：

items = 已收费用.lookupRecords(小区=$小区, 费用名称=$费用名称)
sum(item.实收金额 or 0 for item in items)

排序：

items = 已收费用.lookupRecords(小区=$小区, order_by="-收费时间")

lookupOne

查找一条记录：

客户表.lookupOne(客户编号=$客户编号)

如果你经常写同一类查找，应考虑改成 Reference 字段，让关系更清晰。

9. 引用字段

引用字段是 Grist 的精髓之一。

例子：

• 房间表：保存房间、小区、楼栋、业主。
• 收款表：每条收款记录引用一个房间。
• 在收款表里可以通过 $房间.小区、$房间.业主 自动取关联信息。

引用字段优点：

• 避免重复录入。
• 名称变更时只改一处。
• 更容易做联动页面。
• 更适合权限规则和数据校验。

什么时候用引用：

• 多张表共享同一个实体，如客户、房间、项目、员工、供应商。
• 一张明细表需要从主数据表带出多个字段。
• 需要做一对多、多对多关系。

10. 汇总表和报表

汇总表类似 Excel 透视表，也类似数据库的 GROUP BY。

常见用途：

• 按小区汇总收款。
• 按支付方式汇总金额。
• 按月份汇总收入。
• 按客户统计订单数量。
• 按项目统计成本和利润。

创建方法：

1. 点击 Add New。
2. 选择 Add Page 或 Add Widget to Page。
3. 在数据表旁边点击汇总图标。
4. 选择分组字段，例如 小区、支付方式、费用名称。
5. Grist 会生成汇总表，并自动添加数量、数值合计等公式列。

汇总公式常见写法：

len($group)

sum(r.实收金额 or 0 for r in $group)

round(sum(r.实收金额 or 0 for r in $group), 2)

注意：

• 汇总表的分组字段来自底层表，不能直接在汇总表里手改。
• 底层数据出现新分组值，汇总表会自动出现新行。
• 如果要在汇总结果上维护人工信息，可以把汇总表“分离”为普通表，或另建维度表。

11. 筛选器表的做法

Grist 没有 Excel 那种全局单元格参数，但可以创建一张只有一行的筛选器表。

例子：SummaryFilter

字段：

• StartDate
• EndDate
• Note

其他汇总表公式读取：

start = SummaryFilter.all[0].StartDate
end = SummaryFilter.all[0].EndDate

然后在公式里判断：

if d and start <= d < end:
  total += item.Amount or 0

这种方式适合：

• 财务期间筛选。
• 项目周期筛选。
• 当前年度配置。
• 报表参数统一管理。

12. 图表和仪表盘

Grist 图表可以基于普通表、联动表、汇总表。

常用图表：

• 柱状图：按小区、类别、人员比较金额。
• 折线图：按日、按月趋势。
• 饼图/环形图：类别占比。
• 散点图：两个数值关系。

建议：

• 图表优先基于汇总表，不要直接画大明细表。
• 图表旁边保留数值表，方便核对。
• 时间趋势图最好有明确的日期或月份字段。
• 一个仪表盘不要塞太多图，先回答最重要的问题。

13. 表单

Form 小组件可以把一张表变成外部填写表单。

适合：

• 报修登记。
• 费用申请。
• 客户资料收集。
• 巡检记录。

基本流程：

1. 先设计好数据表字段。
2. 添加 Form 小组件。
3. 调整字段顺序、说明文字、必填项。
4. 发布表单链接。
5. 用户提交后，数据进入对应 Grist 表。

注意：

• 表单字段对应 Grist 列类型。
• 表单说明可以使用 Markdown。
• 发布前要检查权限和数据可见范围。

14. 权限和共享

Grist 常见角色：

• Viewer：只能查看。
• Editor：可以编辑数据和结构，但通常不能管理共享。
• Owner：完全控制，包括共享设置。

团队站点、工作区、文档都可能有权限设置。文档也可以开启公开链接访问。

安全建议：

• 财务、客户、员工数据不要轻易开放公开编辑。
• 对外共享优先设置 Viewer。
• 复杂权限用 Access Rules。
• 批量修改前先备份或复制文档。

15. 访问规则

Access Rules 可以做到行级、列级控制。

规则里常见变量：

• user：当前用户。
• rec：当前记录。
• newRec：编辑后的记录，适合判断修改行为。

典型场景：

• 销售只能看自己的客户。
• 普通员工看不到工资列。
• 外部用户只能看某个项目的数据。
• 已审核记录不允许再改金额。

建议：

• 先用简单角色权限解决问题。
• 真有必要再写 Access Rules。
• 写规则后用“View As”或测试账号检查效果。
• 权限规则和公开链接一起用时要特别谨慎。

16. 自动化和 Webhooks

Grist Automations 可以在数据变化时触发动作：

• 发送邮件。
• 调用 Webhook。
• 推送到外部系统。

适合：

• 报销提交后通知审批人。
• 订单状态变化后推送到企业微信/飞书。
• 新增收款后通知财务复核。
• 异常金额触发告警。

Webhook 可在 Document Settings 的 API 区域配置，也可在自动化里作为动作使用。

安全注意：

• 自托管环境不要允许不可信用户随便创建 Webhook。
• Webhook 目标地址要可信。
• 不要把内部管理接口暴露给普通用户。
• 生产环境建议配合 Redis/state store 以提高队列和通知能力。

17. 导出、备份和恢复

常见导出：

• 单个表导出 CSV 或 XLSX。
• 整个文档导出 Excel。
• 整个文档下载为 .grist 文件。
• 附件单独打包导出。

.grist 文件本质上是 SQLite 数据库文件，包含数据表、页面、小组件、元数据和部分修改历史。

备份建议：

• 大改结构前先下载 .grist。
• 重要文档定期复制到外部备份目录。
• 自托管环境要备份整个 /persist 数据目录。
• 自动快照很好用，但不能替代离线备份。

恢复方法：

1. 在 Grist 首页点击 Add New。
2. 选择 Import document。
3. 上传 .grist 文件。
4. 检查文档是否完整。

18. 自托管基础

官方 Docker 运行思路：

docker run -p 8484:8484 \
  -v ~/grist:/persist \
  -e GRIST_SESSION_SECRET=invent-a-secret-here \
  -e GRIST_DEFAULT_EMAIL=your-email@example.com \
  -it gristlabs/grist

当前本地项目使用 docker-compose.yml，核心点：

• 容器端口：8484
• 数据卷：./data:/persist
• 默认邮箱：GRIST_DEFAULT_EMAIL=hzx2185@qq.com
• 数据库：TYPEORM_DATABASE=/persist/landing.db
• 文档目录：容器内 /persist/docs，宿主机 /Users/a33/docker/grist/data/docs

运维常用命令：

docker ps --filter name=grist-server

docker logs --tail 100 grist-server

docker compose ps

docker compose restart

只读检查文档 SQLite：

sqlite3 data/docs/<DOC_ID>.grist 'pragma quick_check;'

重要原则：

• 尽量通过 Grist API 或界面改文档。
• 不要直接写 .grist SQLite，除非已经充分理解元数据结构和风险。
• 直接读 SQLite 做核对可以，但写入可能绕过 Grist 计算和历史机制。

19. REST API 入门

Grist API 使用 Bearer Token。

测试 API Key：

curl -H "Authorization: Bearer <API_KEY>" \
  http://10.144.144.2:8484/api/orgs

列出文档表：

curl -H "Host: 10.144.144.2:8484" \
  -H "Authorization: Bearer <API_KEY>" \
  http://127.0.0.1:8484/api/docs/<DOC_ID>/tables

读取表记录：

curl -H "Host: 10.144.144.2:8484" \
  -H "Authorization: Bearer <API_KEY>" \
  http://127.0.0.1:8484/api/docs/<DOC_ID>/tables/<TABLE_ID>/records

新增记录：

curl -X POST \
  -H "Host: 10.144.144.2:8484" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"fields":{"Name":"张三","Amount":100}}]}' \
  http://127.0.0.1:8484/api/docs/<DOC_ID>/tables/<TABLE_ID>/records

注意：

• 当前本地服务通过 Host: 10.144.144.2:8484 识别域名。
• API Key 权限等同于该用户权限。
• 写入 JSON 时必须设置 Content-Type: application/json。
• 批量写入前先在测试文档验证。

20. 面向财务/收款统计的建模建议

推荐结构：

• 原始明细表：尽量保留导入数据，不随意删改。
• 维度表：小区、费用项目、收款方式、客户、房间。
• 辅助列：日期归一、金额正负、业务分类、小区解析。
• 参数表：例如 SummaryFilter。
• 汇总表：按日、按小区、按项目、按方式。
• 仪表盘：把关键汇总放到同一个页面。

金额口径必须明确：

• 已收金额来自哪个字段。
• 退款是否扣减。
• 调额增加和减少如何判断。
• 日期范围是否包含结束日。
• 对账状态是否参与过滤。

建议在文档里保留一页“口径说明”，避免人员交接时丢失规则。

21. 常见问题

为什么导入后表名变成 Table1、Table2？

Grist 为了保证内部表 ID 稳定和兼容，可能会使用自动表 ID。页面标题仍可显示中文。公式和 API 应以实际表 ID 为准。

为什么中文列名公式不好写？

中文标签适合显示，公式更适合使用稳定列 ID。可以在列设置里调整 Column ID。

为什么公式改一格，整列都变了？

Grist 的普通公式列是整列公式，不是 Excel 单个单元格公式。每行按同一公式计算。

想只在新增记录时自动填默认值怎么办？

用触发公式 Trigger Formula，而不是普通公式列。

汇总表能不能手工改分组值？

不能。汇总表分组值来自底层表。如果要维护额外字段，建维度表或把汇总表分离成普通表。

大表变慢怎么办？

• 减少跨表全表扫描公式。
• 优先用汇总表。
• 给常用中间结果加辅助列。
• 避免在每一行里循环大表。
• 考虑 On-demand tables 或拆分文档。

22. 本项目的 Grist 维护约定

本目录已有规则文件：AGENTS.md。

后续维护必须做到：

• 导入、公式、页面、运维流程有变更时，更新中文说明。
• 大改前确认文档 ID。
• 旧文档尽量保留。
• 优先通过 Grist API 或界面改文档。
• 关键金额变更后和原 Excel 汇总页核对。

参考资料

• Grist Help Center
• Pages & widgets
• Columns & types
• Reference columns
• Intro to formulas
• Summary tables
• Importing more data
• Exports & backups
• Sharing a document
• Intro to access rules
• Automations
• Webhooks
• Self-hosted Grist
• REST API usage
• REST API reference