Fancy Kanban 看板模式
一个自包含的、基于 Markdown 的看板格式规范。任何读取和写入遵循此模式的应用程序都将生成兼容的看板。
概述
每个看板位于一个带有标识符 fancy-kanban 的围栏代码块内。这意味着：
- 看板可以嵌入在笔记的任何位置，与散文、链接和其他内容并存
- 一个笔记可以包含零个、一个或多个看板
- 如果一个文件仅包含一个看板代码块，它就是一个独立看板文件
- 在没有安装插件的情况下，该代码块将呈现为无样式的代码块——原始文本仍然完全可读
该代码块包含两个部分，由 --- 分隔：
- 一个配置节（类似 YAML 格式），定义字段、工作流和视图选项
- 一个Markdown 表格，包含数据行
完整示例
```fancy-kanban
---
title: 我的看板
fields:
- name: title, type: Text, label: 标题
- name: status, type: Select, options: inbox|doing|done, label: 状态, default: inbox
- name: responsible, type: Text, label: 负责人
- name: start_date, type: Date, label: 开始日期
- name: notes, type: Textarea, label: 备注
- name: effort, type: Number, label: 工作量
- name: docs, type: Link, label: 文档
- name: team, type: Select, options: frontend|backend, label: 团队
card_fields: responsible, effort
lanes: team
workflow: inbox→doing, inbox→done, doing→done, doing→inbox, done→doing, done→inbox
---
| _id | 标题 | 状态 | 负责人 | 开始日期 | 备注 | 工作量 | 文档 | 团队 |
|--------|----------------|------|--------|------------|----------------------------|--------|-----------------------|----------|
| x7k2a1 | 修复登录错误 | inbox | Alice | 2026-01-15 | 需要调查 | 3 | | backend |
| m3p9b2 | 重构认证模块 | doing | Bob | | 多行<br>内容 | 5 | design.md | backend |
| q1r4c3 | 设置 CI | done | | 2026-01-01 | | 1 | setup.md|guide.md | frontend |
```
代码块结构
围栏代码块包含两个部分，由一条 --- 线分隔：
```fancy-kanban
---
{配置}
---
{Markdown 表格}
第一个 `---` 之前的所有内容将被忽略（保留供将来使用）。两个 `---` 线之间的内容为配置。第二个 `---` 之后的所有内容为表格。
## 配置节
类似 YAML 的键值对。按行解析。
### 键
| 键 | 必需 | 默认值 | 描述 |
|-----|----------|---------|-------------|
| `title` | 是 | — | 人类可读的看板名称 |
| `fields` | 是 | — | 字段定义列表（见下文） |
| `version` | 否 | `1` | 由插件写入的格式版本；版本高于当前插件支持的看板将以只读模式打开 |
| `workflow` | 否 | 允许所有转换 | 逗号分隔的 `from→to` 对 |
| `lanes` | 否 | 无 | 用作泳道分组维度的字段名 |
| `card_title` | 否 | 自动检测 | 用作卡标题的字段名；设置为空字符串则不显示标题 |
| `card_fields` | 否 | 无 | 逗号分隔的次级字段名有序列表，显示在卡标题下方 |
| `card_labels` | 否 | `true` | 设置为 `false` 以隐藏次级卡片字段的标签前缀 |
| `card_limit` | 否 | `0`（无限制） | 每列显示的最大卡片数；超出此数量的卡片将隐藏在“显示更多”按钮之后 |
### `card_title`
```yaml
card_title: summary
控制哪个字段被渲染为卡标题：
- 不存在（默认）：自动使用第一个非
_id、非列字段 - 设置为字段名：该字段的值显示为标题
- 设置为空字符串（
card_title:）：不显示标题；卡片仅显示次级字段
card_fields
card_fields: priority, due, docs
一个有序的、逗号分隔的次级字段名列表，将显示在卡标题下方。这些字段显示为带标签的行。
默认行为：当 card_fields 不存在时，卡片仅显示标题字段。未设置 card_fields 键的现有看板不受影响。
未知名称：不匹配任何已定义字段的字段名在渲染时会被静默忽略。从 fields: 中移除一个字段会自动将其从卡片面中隐藏，而不会产生解析错误。
链接字段：当 Link 字段包含在 card_fields 中时，其项将在卡片面上渲染为可点击链接的水平列表。库路径在新标签页中打开；外部 URI 在浏览器中打开。
card_labels
card_labels: false
当设置为 false 时，次级字段行的标签前缀将被省略——仅显示值。默认为 true（标签可见）。该键仅在值为 false 时写入配置。
card_limit
card_limit: 5
当设置为正整数时，每列最多显示相应数量的卡片。超出限制的卡片将被隐藏，并在列底部显示一个显示更多 (N) 按钮。点击该按钮将显示所有剩余的卡片，而无需重新加载看板。设置 card_limit: 0 或省略该键将完全禁用限制。
这对于已完成列随时间累积大量已完成卡片的看板特别有用——最新的卡片保持可见，而旧的历史记录则折叠起来。
lanes
当设置为字段名（必须是 Select 字段）时，看板呈现为矩阵：
- 列——由
status字段的options顺序驱动 - 泳道行——由
lanes字段的options顺序驱动
lanes 字段没有值的卡片将显示在底部的 未分配 伪泳道中。更改 lanes 仅是视图配置更改——不影响任何行数据。
字段定义
fields 列表中的每个条目都是一行逗号分隔的 key: value 对，前缀为 - ：
fields:
- name: title, type: Text, label: 标题
- name: status, type: Select, options: inbox|doing|done, label: 状态, default: inbox
字段排序约定：先列出 title，然后是 status，然后是其他字段。数据节中表格的列顺序与字段定义顺序一致，自动检测到的卡标题会解析为第一个非 _id、非列字段——因此将 title 放在第一位可以确保可预测的标题解析，无需显式的 card_title 键。
字段属性
| 属性 | 必需 | 描述 |
|---|---|---|
name | 是 | 内部标识符。小写，空格用下划线代替。 |
type | 是 | 以下之一：Text、Textarea、Date、Number、Select、Link |
label | 是 | 人类可读的列标题。必须与 Markdown 表格标题完全一致。 |
options | 仅 Select | 竖线分隔 (` |
colors | Select，可选 | 竖线分隔的 name=hex 对，为每个选项分配背景色（例如 `High=#e74c3c |
default | 否 | 新卡片的默认值 |
字段类型
| 类型 | 存储格式 | 描述 |
|---|---|---|
Text | 纯字符串 | 单行文本 |
Textarea | 用 <br> 表示换行的字符串 | 多行文本 |
Date | YYYY-MM-DD | 日历日期 |
Number | 整数或十进制数字符串 | 数字值 |
Select | 从 options 值中选取一项 | 受限选择；选项可通过 colors 属性携带十六进制颜色 |
Link | 用 <br> 分隔的路径或 URI 列表 | 相对于库根的路径（notes/doc.pdf）或外部 URI（https://…、ftp://…、mailto:…） |
特殊字段名
| 名称 | 角色 |
|---|---|
title | 主显示字段。 应列在 fields: 的第一个。当未设置 card_title 时，用作自动检测的卡标题。 |
status | 必需。看板列字段。 必须是 type: Select。卡片按此值分组为列。列顺序遵循 options 顺序。 |
所有其他字段都是次级字段——当在 card_fields 中列出时显示为卡片元数据。
项标识
每个卡片都有一个稳定的隐藏 ID，存储在 Markdown 表格的 _id 列中。UI 从不显示此列。
- 在卡片创建时生成：短随机字母数字字符串（例如 8 个字符：
x7k2a1b3） - 在所有的序列化往返过程中保持不变
- 在重新排序、拖放和字段重命名后仍然存在
- 内部用于所有卡片操作（移动、编辑、删除）
由于标识是基于 ID 而非内容衍生的，重命名卡片的标题不会影响其标识。
工作流
定义 UI 中允许的状态转换：
workflow: inbox→doing, inbox→done, doing→done, doing→inbox, done→doing, done→inbox
- 逗号分隔的
from→to对列表（箭头：→，U+2192） - 如果省略
workflow，则允许状态选项之间的所有转换 - 用于限制 UI 选择（例如，“移动到”菜单仅显示有效目标）
- 对原始表格的手动编辑本质上会绕过工作流验证，因为它们是纯文本
看板模板
创建新看板时，一组预定义的模板提供了常用的 status 选项集。模板仅预填 status 字段选项和 workflow——所有其他字段由用户添加。
| 模板 | 状态选项 | 默认工作流 |
|---|---|---|
| 基本 | `inbox | doing |
| 软件 | `backlog | todo |
| 内容 | `idea | draft |
| 项目 | `planning | active |
| 自定义 | 用户定义 | 用户定义 |
选择自定义将打开一个自由格式编辑器，用于编辑 status 选项和工作流转换。
Markdown 表格
表格紧跟在配置节的结束 --- 之后。
结构
| _id | 标题1 | 标题2 |
|--------|--------|--------|
| abc123 | 值 | 值 |
- 标题行——第一列始终是
_id；其余列按模式定义顺序排列的字段标签 - 分隔行——标准 Markdown 表格分隔符
- 数据行——每个卡片一行；
_id单元格包含卡片的稳定 ID
规则
- 表格中的列顺序必须与字段定义顺序一致（在
_id之后） - 空单元格是有效的（字段值 = 空字符串）
- 状态组内的行顺序是显示顺序
- 空表（标题 + 分隔符，无数据行）是有效的
_id列始终是第一列，并且在渲染的看板中从不显示
转义
| 值中的字符 | 转义为 |
|---|---|
| ` | ` (竖线) |
| 换行符 | <br> |
| 回车符 | <br> |
读取时：| → |，<br> → 换行符。
写入时：| → |，任何换行符 → <br>。
解析算法
- 提取
fancy-kanban代码块的开闭围栏之间的原始字符串 - 在第一个
---行处分割以定位配置节的开始 - 在第二个
---行处分割以将配置与表格分离 - 逐行解析配置：提取
title、version、fields、workflow、lanes、card_title、card_fields、card_labels、card_limit - 对于
fields，收集以-开头的行，并将每一行解析为逗号分隔的key: value对；colors被解码为竖线分隔的name=hex令牌 - 在主体中找到表格行（以
|开头的行） - 第一个表格行是标题行——提取列标签；
_id始终是第一列 - 通过不区分大小写的标签查找将剩余的标题标签映射到字段名
- 解析每个数据行：在未转义的
|处分割，修剪单元格，取消转义|和<br> - 每个数据行的第一个单元格是卡片的
_id - 按
status字段值对卡片进行分组，按options顺序初始化组
模式协调（在解析后应用）：
- 模式中存在但卡片数据中缺少的字段：使用字段的
default值（或空字符串）回填 - 卡片数据中存在但已从模式中移除的字段：作为孤立隐藏数据保留（不删除）
写入算法
- 从当前模式重建配置节（在可能的情况下保留原始格式）
- 生成标题行：
_id在前，然后是模式定义顺序中的字段标签 - 生成分隔行
- 为每个卡片生成一行数据：
_id在前，然后是模式顺序中的字段值，并对竖线和换行符进行转义 - 如果卡片没有现有 ID，则使用随机字母数字字符串生成一个新的卡片
_id - 重建完整代码块：开围栏、配置、
---、空行、表格、闭围栏
写回原则： 仅修改源文件中受影响代码块的文本范围——周围内容不会被重写。
最小可行看板
```fancy-kanban
---
title: 我的看板
fields:
- name: title, type: Text, label: 标题
- name: status, type: Select, options: inbox|doing|done, label: 状态, default: inbox
workflow: inbox→doing, inbox→done, doing→done, doing→inbox, done→doing, done→inbox
---
| _id | 标题 | 状态 |
|-----|-------|--------|
## 兼容性说明
- 没有插件时，代码块呈现为纯文本代码块——所有数据仍然以纯文本形式可见
- 代码块内的 Markdown 表格是有效的 Markdown，可以在任何文本编辑器中阅读
- 配置节遵循 YAML 约定，静态站点生成器和笔记应用程序都很熟悉
- 移除插件后，所有数据保持完整且可恢复
## 已弃用的功能
请参阅 [docs/deprecations.md](deprecations.md) 了解已弃用的功能列表及其迁移路径。