Focalboard Todoist 数据迁移实战将 Todoist JSON 归档一键导入 Focalboard 看板【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard导读本文介绍 Focalboard 官方提供的 Todoist 导入器focalboard-todoist-importer讲解如何把 Todoist 的完整数据导出为 JSON 归档再通过importTodoist.ts脚本转换为 Focalboard 可识别的boardarchive归档文件最终在 Focalboard 中一键导入为可编辑的看板。读完本文你将掌握从数据导出、环境安装、命令行运行到源码级映射原理的完整迁移链路并了解项目Project→看板Board、分组Section→列表选项Select Option、任务Item→卡片Card、备注Note→卡片描述等核心映射规则。一、工作原理概述Todoist 导入器是一个运行在 Node.js 环境下的命令行应用其核心思路是数据中转Todoist JSON 归档 │ ▼ importTodoist.ts数据转换ts-node 运行 │ ▼ Focalboard 归档.boardarchiveJSONL 格式 │ ▼ Focalboard 前端 Import archive解析并落库整个链路不依赖 Todoist API 的实时鉴权而是使用 Todoist 官方数据导出服务生成的全量 JSON 文件作为输入因此迁移过程可重复、可离线、可审计。核心脚本位于 import/todoist/importTodoist.ts它复用了webapp中 Focalboard 自身的块Block与看板Board数据模型保证生成的归档与 Focalboard 内部数据结构完全一致。二、第一步从 Todoist 导出全量 JSON 数据导入器要求输入一个包含 Todoist 全部数据的 JSON 文件。按以下步骤获取访问 Todoist 的开源数据导出服务darekkay.com 提供的 Todoist Export 工具。在Export As导出格式选项中选择JSON (all data)JSON 全量数据。若Archived已归档选项被勾选请取消勾选以确保导出范围符合预期。点击Authorize and Backup授权并备份。此时会跳转到你的 Todoist 账号进行授权请按屏幕提示完成操作。记下下载得到的json文件名称与存放位置后续命令行参数需要引用该路径。需要说明的是导出工具与 Todoist 的授权交互属于第三方服务行为本仓库仅消费其产出的 JSON 文件从源码结构看导入器只依赖该 JSON 的结构不绑定特定导出渠道。三、第二步安装依赖导入器是一个独立的 TypeScript 项目其声明位于 import/todoist/package.json运行时依赖minimist命令行参数解析开发依赖包括ts-node、typescript、eslint等。由于脚本直接引用webapp下的源码模块见下文源码解析因此需要先在webapp目录安装一次依赖。在仓库根目录下依次执行# 1. 安装 Focalboard 前端依赖提供 Block / Board / Card 等数据模型 cd focalboard/webapp npm install # 2. 安装 Todoist 导入器自身依赖 cd ../import/todoist npm install说明focalboard/webapp即本仓库的 webapp 目录若你已将仓库克隆到其他路径请按实际路径调整。安装完成后import/todoist下会出现node_modules与ts-node可执行环境。四、第三步运行导入命令在focalboard/import/todoist目录内执行npx ts-node importTodoist.ts -i path-to-todoist.json -o archive.boardarchive其中参数含义默认值说明-i输入的 Todoist JSON 文件路径无必填指向第一步下载的 json 文件-o输出的 Focalboard 归档文件路径archive.boardarchive可自定义如todoist-import.focalboard命令成功后会打印Exported to outputFile。若文件不存在程序会输出File not found: path并以退出码2结束若缺少-i参数则调用showHelp()后以退出码1结束见 importTodoist.ts。也可以直接复用项目预置的测试脚本见 package.json 的scripts段npm test # 等价于 ts-node importTodoist.ts -i test/todoist.json -o test/todoist-import.focalboard npm run debug:test # 以调试模式运行--inspect5858可配合 Chrome DevTools 断点调试转换逻辑五、第四步在 Focalboard 中导入归档启动 Focalboard进入目标工作区。点击界面上的Settings设置。选择Import archive导入归档。选中上一步生成的archive.boardarchive文件。导入完成后Todoist 中的各个项目会以看板形式出现在工作区中。归档的解析与落库由 Focalboard 前端 archiver.ts 与后端 API 配合完成前端先使用ArchiveUtils.parseBlockArchive读取 JSONL 内容再通过导入接口写入存储。六、源码级解析Todoist 数据如何映射到 Focalboard转换的核心逻辑集中在convert(input, project)函数importTodoist.ts映射规则如下1. 项目 → 看板Board遍历input.projects每个非 Inbox 的 Todoist 项目生成一个 Focalboard 看板。看板标题与描述均取项目名project.name。命令行会打印Board: project.name便于跟踪进度。2. 分组Section→ 列表选择属性Select项目内的分组Section被映射为一个名为List、类型为select的卡片属性IPropertyTemplate每个分组对应一个带颜色的选项option。选项颜色从 10 色调色板轮换分配propColorGray、propColorBrown、propColorOrange、propColorYellow、propColorGreen、propColorBlue、propColorPurple、propColorPink、propColorRed见 importTodoist.ts。关键分支逻辑getProjectColumns会先收集项目自身的 section若项目没有任何 section列表长度不大于 1则退化为使用五个默认分组No Status、Next Up、In Progress、Completed、ArchivedimportTodoist.ts。这是让无分组项目也能在 Focalboard 看板中呈现列结构的关键设计。3. 任务Item→ 卡片Card每个任务生成一张卡片标题为任务内容item.content。卡片所属分组通过section_id映射为List属性的选项值无分组任务归入No Status选项。若映射失败会打印警告Invalid idList: ...但不会中断转换。卡片在 Focalboard 数据模型中的类型定义可参考 webapp/src/blocks/card.ts。4. 备注Note与附件 → 卡片描述getCardDescription收集该任务下的所有备注input.notes中item_id匹配的任务合并为卡片描述文本以空行分隔。若备注带文件附件file_attachment描述中会追加 Markdown 链接Attachment: titleimportTodoist.ts。描述以独立的文本块Text Block形式挂载到卡片下并通过contentOrder建立父子关系文本块的创建逻辑见 webapp/src/blocks/textBlock.ts。5. 看板视图Board View每个看板附带一个名为Board View、类型为board的视图块使导入结果默认以看板Kanban形态展示importTodoist.ts视图字段结构可对照 webapp/src/blocks/boardView.ts 中的createBoardView。6. 特殊处理Inbox 项目名为Inbox的项目会被直接跳过不生成看板importTodoist.ts避免把 Todoist 的收件箱杂项带入工作区。七、归档文件格式JSONL 与 ArchiveUtils生成的.boardarchive是一个JSON LinesJSONL文件由 import/util/archive.ts 中的ArchiveUtils.buildBlockArchive构建第一行为头Header{version:1,date:时间戳}。之后每行一个 JSON 对象type为board或blockdata为对应的看板或块数据。{version:1,date:1699999999999} {type:board,data:{...}} {type:block,data:{...}}读取侧parseBlockArchive会校验头版本号version 1逐行解析并按type分类解析失败会抛出ERROR parsing line n。这种一行一实体的格式便于增量扩展与流式处理源码注释中亦提到未来可扩充更多行类型。八、Todoist JSON 数据结构速览import/todoist/todoist.ts 使用 quicktype 根据实际导出样本生成了完整的 TypeScript 类型定义转换脚本只消费其中四类核心数据projects项目数组含id、name、inbox_project、is_archived等字段。sections分组数组含id、project_id、name、is_deleted等字段。items任务数组含id、project_id、section_id、content、parent_id、priority等字段。notes备注数组含id、item_id、content、file_attachment等字段。理解该结构有助于排查某类数据未被迁移的问题——例如标签labels、提醒reminders、过滤器filters在类型定义中存在但当前导入器并未做映射属于已知的覆盖范围边界。九、其他实现细节与注意事项ID 生成转换过程中所有 Focalboard 实体 ID 由 import/todoist/utils.ts 的Utils.createGuid()生成基于crypto.randomBytes的 UUID 实现保证每次转换生成的归档 ID 互不冲突。运行环境脚本顶部有(global.window as any) {}的兼容处理importTodoist.ts用于在 Node 环境复用时让依赖浏览器全局对象的工具函数正常工作。类型检查tsconfig.json启用了strict与strictNullChecks若二次开发请保持类型完整避免引入空值访问。适用前提本文命令基于仓库当前版本typescript ^4.1.5、ts-node ^9.1.1、minimist ^1.2.6验证导入仅覆盖上文所述的映射范围Todoist 中未映射的数据如标签、重复任务规则、提醒不会出现在导入结果中请在迁移前评估业务影响。十、小结Focalboard 的 Todoist 导入器以JSON 导出 → 命令行转换 → 前端导入三段式流水线提供了一条低成本、可复现的数据迁移路径。其设计复用webapp的块模型与统一的 JSONL 归档协议也让开发者可以参照 import/todoist 的结构为其他数据源仓库内另有 asana、jira、trello、notion、nextcloud-deck 等导入器快速编写同类迁移工具。【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Focalboard Todoist 数据迁移实战：将 Todoist JSON 归档一键导入 Focalboard 看板
Focalboard Todoist 数据迁移实战将 Todoist JSON 归档一键导入 Focalboard 看板【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard导读本文介绍 Focalboard 官方提供的 Todoist 导入器focalboard-todoist-importer讲解如何把 Todoist 的完整数据导出为 JSON 归档再通过importTodoist.ts脚本转换为 Focalboard 可识别的boardarchive归档文件最终在 Focalboard 中一键导入为可编辑的看板。读完本文你将掌握从数据导出、环境安装、命令行运行到源码级映射原理的完整迁移链路并了解项目Project→看板Board、分组Section→列表选项Select Option、任务Item→卡片Card、备注Note→卡片描述等核心映射规则。一、工作原理概述Todoist 导入器是一个运行在 Node.js 环境下的命令行应用其核心思路是数据中转Todoist JSON 归档 │ ▼ importTodoist.ts数据转换ts-node 运行 │ ▼ Focalboard 归档.boardarchiveJSONL 格式 │ ▼ Focalboard 前端 Import archive解析并落库整个链路不依赖 Todoist API 的实时鉴权而是使用 Todoist 官方数据导出服务生成的全量 JSON 文件作为输入因此迁移过程可重复、可离线、可审计。核心脚本位于 import/todoist/importTodoist.ts它复用了webapp中 Focalboard 自身的块Block与看板Board数据模型保证生成的归档与 Focalboard 内部数据结构完全一致。二、第一步从 Todoist 导出全量 JSON 数据导入器要求输入一个包含 Todoist 全部数据的 JSON 文件。按以下步骤获取访问 Todoist 的开源数据导出服务darekkay.com 提供的 Todoist Export 工具。在Export As导出格式选项中选择JSON (all data)JSON 全量数据。若Archived已归档选项被勾选请取消勾选以确保导出范围符合预期。点击Authorize and Backup授权并备份。此时会跳转到你的 Todoist 账号进行授权请按屏幕提示完成操作。记下下载得到的json文件名称与存放位置后续命令行参数需要引用该路径。需要说明的是导出工具与 Todoist 的授权交互属于第三方服务行为本仓库仅消费其产出的 JSON 文件从源码结构看导入器只依赖该 JSON 的结构不绑定特定导出渠道。三、第二步安装依赖导入器是一个独立的 TypeScript 项目其声明位于 import/todoist/package.json运行时依赖minimist命令行参数解析开发依赖包括ts-node、typescript、eslint等。由于脚本直接引用webapp下的源码模块见下文源码解析因此需要先在webapp目录安装一次依赖。在仓库根目录下依次执行# 1. 安装 Focalboard 前端依赖提供 Block / Board / Card 等数据模型 cd focalboard/webapp npm install # 2. 安装 Todoist 导入器自身依赖 cd ../import/todoist npm install说明focalboard/webapp即本仓库的 webapp 目录若你已将仓库克隆到其他路径请按实际路径调整。安装完成后import/todoist下会出现node_modules与ts-node可执行环境。四、第三步运行导入命令在focalboard/import/todoist目录内执行npx ts-node importTodoist.ts -i path-to-todoist.json -o archive.boardarchive其中参数含义默认值说明-i输入的 Todoist JSON 文件路径无必填指向第一步下载的 json 文件-o输出的 Focalboard 归档文件路径archive.boardarchive可自定义如todoist-import.focalboard命令成功后会打印Exported to outputFile。若文件不存在程序会输出File not found: path并以退出码2结束若缺少-i参数则调用showHelp()后以退出码1结束见 importTodoist.ts。也可以直接复用项目预置的测试脚本见 package.json 的scripts段npm test # 等价于 ts-node importTodoist.ts -i test/todoist.json -o test/todoist-import.focalboard npm run debug:test # 以调试模式运行--inspect5858可配合 Chrome DevTools 断点调试转换逻辑五、第四步在 Focalboard 中导入归档启动 Focalboard进入目标工作区。点击界面上的Settings设置。选择Import archive导入归档。选中上一步生成的archive.boardarchive文件。导入完成后Todoist 中的各个项目会以看板形式出现在工作区中。归档的解析与落库由 Focalboard 前端 archiver.ts 与后端 API 配合完成前端先使用ArchiveUtils.parseBlockArchive读取 JSONL 内容再通过导入接口写入存储。六、源码级解析Todoist 数据如何映射到 Focalboard转换的核心逻辑集中在convert(input, project)函数importTodoist.ts映射规则如下1. 项目 → 看板Board遍历input.projects每个非 Inbox 的 Todoist 项目生成一个 Focalboard 看板。看板标题与描述均取项目名project.name。命令行会打印Board: project.name便于跟踪进度。2. 分组Section→ 列表选择属性Select项目内的分组Section被映射为一个名为List、类型为select的卡片属性IPropertyTemplate每个分组对应一个带颜色的选项option。选项颜色从 10 色调色板轮换分配propColorGray、propColorBrown、propColorOrange、propColorYellow、propColorGreen、propColorBlue、propColorPurple、propColorPink、propColorRed见 importTodoist.ts。关键分支逻辑getProjectColumns会先收集项目自身的 section若项目没有任何 section列表长度不大于 1则退化为使用五个默认分组No Status、Next Up、In Progress、Completed、ArchivedimportTodoist.ts。这是让无分组项目也能在 Focalboard 看板中呈现列结构的关键设计。3. 任务Item→ 卡片Card每个任务生成一张卡片标题为任务内容item.content。卡片所属分组通过section_id映射为List属性的选项值无分组任务归入No Status选项。若映射失败会打印警告Invalid idList: ...但不会中断转换。卡片在 Focalboard 数据模型中的类型定义可参考 webapp/src/blocks/card.ts。4. 备注Note与附件 → 卡片描述getCardDescription收集该任务下的所有备注input.notes中item_id匹配的任务合并为卡片描述文本以空行分隔。若备注带文件附件file_attachment描述中会追加 Markdown 链接Attachment: titleimportTodoist.ts。描述以独立的文本块Text Block形式挂载到卡片下并通过contentOrder建立父子关系文本块的创建逻辑见 webapp/src/blocks/textBlock.ts。5. 看板视图Board View每个看板附带一个名为Board View、类型为board的视图块使导入结果默认以看板Kanban形态展示importTodoist.ts视图字段结构可对照 webapp/src/blocks/boardView.ts 中的createBoardView。6. 特殊处理Inbox 项目名为Inbox的项目会被直接跳过不生成看板importTodoist.ts避免把 Todoist 的收件箱杂项带入工作区。七、归档文件格式JSONL 与 ArchiveUtils生成的.boardarchive是一个JSON LinesJSONL文件由 import/util/archive.ts 中的ArchiveUtils.buildBlockArchive构建第一行为头Header{version:1,date:时间戳}。之后每行一个 JSON 对象type为board或blockdata为对应的看板或块数据。{version:1,date:1699999999999} {type:board,data:{...}} {type:block,data:{...}}读取侧parseBlockArchive会校验头版本号version 1逐行解析并按type分类解析失败会抛出ERROR parsing line n。这种一行一实体的格式便于增量扩展与流式处理源码注释中亦提到未来可扩充更多行类型。八、Todoist JSON 数据结构速览import/todoist/todoist.ts 使用 quicktype 根据实际导出样本生成了完整的 TypeScript 类型定义转换脚本只消费其中四类核心数据projects项目数组含id、name、inbox_project、is_archived等字段。sections分组数组含id、project_id、name、is_deleted等字段。items任务数组含id、project_id、section_id、content、parent_id、priority等字段。notes备注数组含id、item_id、content、file_attachment等字段。理解该结构有助于排查某类数据未被迁移的问题——例如标签labels、提醒reminders、过滤器filters在类型定义中存在但当前导入器并未做映射属于已知的覆盖范围边界。九、其他实现细节与注意事项ID 生成转换过程中所有 Focalboard 实体 ID 由 import/todoist/utils.ts 的Utils.createGuid()生成基于crypto.randomBytes的 UUID 实现保证每次转换生成的归档 ID 互不冲突。运行环境脚本顶部有(global.window as any) {}的兼容处理importTodoist.ts用于在 Node 环境复用时让依赖浏览器全局对象的工具函数正常工作。类型检查tsconfig.json启用了strict与strictNullChecks若二次开发请保持类型完整避免引入空值访问。适用前提本文命令基于仓库当前版本typescript ^4.1.5、ts-node ^9.1.1、minimist ^1.2.6验证导入仅覆盖上文所述的映射范围Todoist 中未映射的数据如标签、重复任务规则、提醒不会出现在导入结果中请在迁移前评估业务影响。十、小结Focalboard 的 Todoist 导入器以JSON 导出 → 命令行转换 → 前端导入三段式流水线提供了一条低成本、可复现的数据迁移路径。其设计复用webapp的块模型与统一的 JSONL 归档协议也让开发者可以参照 import/todoist 的结构为其他数据源仓库内另有 asana、jira、trello、notion、nextcloud-deck 等导入器快速编写同类迁移工具。【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考