RFC：基于 chartType 注释 + Markdown 表格的文档站卡片列表

    背景

    业务上需要展示「多列信息卡」式内容（如优秀文档站：主标题、站点 URL、简介、标签/亮点），版式上常见为 两列栅格、白底圆角、标签为彩色胶囊。

    本仓库中，图表与部分结构化展示已统一为 HTML 注释（JSON）+ GFM 管道表格 的数据契约（见 parseTable.ts、docs/utils/chart-config.md）。descriptions 等类型将表头映射为字段、每行映射为一块 UI，但 未覆盖「双列卡片 + 标签行」 的版式需求。

    本 RFC 约定：在不破坏现有注释与解析行为的前提下，用与现有图表 同一套作者写法 支持「卡片列表」；若实现，则新增独立 chartType，由 ChartRender（或 chart 插件）专门渲染。

    目标

    • 作者侧：与现有图表一致，在管道表上方写一行（或数组中一项）JSON 注释，包含 chartType 与可选 title 等公共字段。
    • 数据侧：一行 Markdown 表 = 一张卡片；表头列名可配置为固定语义字段（见下文「列契约」）或通过配置映射到列。
    • 呈现侧：默认 桌面端两列 卡片网格式布局；窄屏 可降为单列；卡片内需展示标题、副标题/URL、正文、可换行的标签组。
    • 可访问性：整体为文档型列表时，使用合适标题层级或 list/article 语义（实现阶段再定，避免用「纯数据表」误导读屏，必要时 role/aria 与现有 chart 区一致由设计评审确认）。

    非目标

    • 不把 手写的 HTML <table> 作为本能力的主数据入口；主路径保持 GFM 表格（与现有一致，便于 parseTable 统一产 chart 节点）。
    • 不在本 RFC 中规定具体像素级设计稿；仅规定 信息架构与数据契约。
    • 不强制与某个图表库（ECharts）复用；UI 为静态卡片时可仅用 React + token/CSS。

    建议命名

    • chartType 取值（拟定）：docCards（或 infoCards）。
      命名需在实现前与 i18n、图类型切换器（若有）中展示文案一次对齐。

    列契约（拟定）

    在注释中不重复列举列名时，采用 约定表头（与 x/y 需匹配表头类似，可实现「宽松匹配」子 RFC 复用表头单位后缀规则）：

    语义建议表头（可讨论）是否必填说明
    主标题名称 或 标题是卡片主标题，大号字重。
    URL / 副标题地址 或 链接 或 URL否小字、弱化色；可渲染为可点击 a[href] 或纯文本。
    描述简介 或 描述否正文段落。
    标签亮点 或 标签否多个标签建议 半角逗号/顿号/分号 分隔，或统一为一种分隔符并在 RFC 实现中写死。

    配置扩展（可选，第二阶段）：

    • columns 或 fieldMap：将注释中的逻辑名映射到实际表头（当作者想用自定义列名时）。
    • cardColumns：每行卡片的列数，默认 2；1 用于全宽列表。

    注释示例

    单表、单种展示：

    {/* {"chartType": "docCards", "title": "优秀开发者文档站"} */}

| 名称              | 地址                          | 简介                   | 亮点                       |
| :---------------- | :---------------------------- | :--------------------- | :------------------------- |
| Tailwind CSS Docs | https://tailwindcss.com/docs  | 结构清晰、搜索与导航强 | 交互式示例, 深链, 暗色模式 |
| MDN               | https://developer.mozilla.org | 权威 Web 参考          | 多语言, 可折叠, 示例可编辑 |

    多配置并存（与现有多图数组一致）：

    {/* [{"chartType": "column", "x": "名称", "y": "热度"}, {"chartType": "docCards", "title": "详情卡片"}] */}

| 名称 | 热度 | 简介 | 亮点 |
| ---- | ---- | ---- | ---- |
| ...  | ...  | ...  | ...  |

    多配置时对 docCards 的列集与兄弟图表是否共用同一张表，需与现有多 chartType 对列子集/校验的行为保持一致（见 parseTable 中校验逻辑）。

    与现有类型的关系

    类型作用
    descriptions表格式键值，Ant Design Descriptions；不是双列网格栅格卡片。
    table高级表格能力，不进入图表渲染管线。
    docCards（拟）专用卡片栅格，数据来源仍为同一套管道表。

    解析与渲染（实现指导）

    • parseTable / chart 节点：chartType === 'docCards' 时参与图表节点生成；校验规则需定义「最少必需列」与失败时整表降级策略（与现有 isChart 行为对齐）。
    • ChartRender（或 src/Plugins/chart 下子模块）：新分支渲染卡片容器；标签字符串 拆分为 Tag 或自绘胶囊，颜色可用哈希或行索引轮换，与主题 token 一致。
    • 样式：优先使用 prefixCls + CSS-in-JS/现有 chart 容器的边距，避免与 Slate 表格占位层 z-index 冲突（参考现有多图 data-chart-box 布局经验）。
    • 国际化：若工具栏或空状态有 copy，在 src/I18n/locales.ts 中增加键值。

    兼容性

    • 未使用 docCards 的文档与现有表图行为不变。
    • 新类型占用了新的 chartType 字符串；不与现有 pie、bar、descriptions 等冲突。
    • 回滚：仅移除 docCards 分支与作者示例即可，解析器可保留「未知类型降级」的默认策略（以当前代码为准）。

    测试用例建议

    • 单表 + docCards：表头带单位后缀时是否仍能匹配到「简介」等逻辑列（若复用列名匹配 RFC）。
    • 无「亮点」列：卡片仅显示标题+简介，不抛错。
    • 标签字符串含连续分隔符、首尾空白、中英文混合。
    • 多 chartType 数组里同时包含 docCards 时，与仅 docCards 的列校验一致。
    • 小视口下布局为单列（或横向滚动不溢出），与现有 chart 容器的 minWidth 行为不冲突。

    开放问题

    1. 标签列是否允许多行 Markdown 或内联 HTML，还是纯文本？建议第一版仅纯文本 + 固定分隔符。
    2. 卡片主链接：整卡可点还是仅 URL 可点？涉及 pointer-events 与编辑器内可编辑性。
    3. 是否需要与 链接卡片（type: "card" 注释 + Markdown 链接，见语法 skill）在视觉上统一；若统一，设计 token 是否从一处继承。

    状态

    • Implemented：v2.33.0 起以 chartType: "docCards" 落地。实现细节：
      • 渲染：src/Plugins/chart/DocCards/（DocCards.tsx + style.ts + utils.ts）。
      • 解析降级：src/MarkdownEditor/editor/parser/parse/parseTable.ts 在 chartType === 'docCards' 时仅校验「主标题」最少必需列；命中失败整表降级为普通 Markdown 表格。
      • 公共契约：columns/dataSource/title 与现有 chart 节点一致；cardColumns、fieldMap 放在 chart config 的 rest 中（与 groupBy、colorLegend 等附加配置同位）。
      • i18n：新增 docCards 标签（中文「卡片列表」/英文「Card List」）。
      • 单元测试：src/Plugins/chart/__tests__/DocCards.test.tsx、src/MarkdownEditor/editor/parser/__tests__/parseTable.test.ts。
      • 演示与文档：docs/demos/markdown-doc-cards.tsx、docs/demos-pages/chart.md 与 docs/utils/chart-config.md。