FcDesigner

Appearance

二开文档书写规范与通用策略 ​

本文用于统一 FcDesigner Pro（二开/扩展）类文档的结构、写法、示例标准与维护策略，降低“写文档靠经验”的不确定性，让任何二开主题都能做到：可复制、可落地、可长期维护。

适用对象：扩展组件、扩展右侧配置、扩展事件/行为、扩展 API、跨端适配、兼容迁移、渲染/设计态链路改造等二开主题。

写作目标（必须明确） ​

一篇合格的二开文档，应至少回答清楚以下问题：

  • 我想实现什么？（目标与业务价值）
  • 我需要改哪些地方？（变更点与项目位置）
  • 我怎么一步步做？（从 0 到 1 的可执行步骤）
  • 我怎么验证是对的？（验收清单/测试点）
  • 我踩坑了怎么排查？（常见错误与定位路径）
  • 有哪些兼容/迁移注意点？（版本、跨端、历史规则、破坏性变更）

文档“标准结构”模板（建议照抄） ​

以下章节顺序是推荐的默认顺序；若主题不适用，可删，但不建议随意重排。

1. 标题与一句话概述 ​

  • 标题：用“动词 + 对象”命名（例：添加新组件、扩展右侧配置规则、接入自定义预览回显）
  • 概述：1-2 段描述本文解决的问题、对使用方的收益、提供的能力边界

2. 适用范围与前置条件 ​

建议以清单形式写清：

  • 适用版本：例如 “FcDesigner Pro v6.x（Vue3）” / “Vue2 版本另见 ...”
  • 适用端：PC / Mobile（若只覆盖一端必须说明）
  • 依赖：UI 框架（Element Plus / Ant Design Vue / Vant）、form-create 版本、运行环境要求
  • 读者基础：需要了解的概念（rule、DragRule、renderer、designerForm、preview/readMode 等）

3. 你要改哪些地方？（先给全局视图） ​

用“分层/链路”表达，优先给 3-6 条要点：

  • Runtime（表单渲染组件）
  • Renderer 注册（让 rule.type 可渲染）
  • DragRule（左侧菜单 + 右侧属性/事件/多语言 + 默认 rule 结构）
  • Designer 画布注册（设计态也要能渲染）
  • 可选链路：预览/阅读模式适配、跨端注册、值解析/格式转换、数据请求注入、多语言补齐

这一节的目标是：读者在 30 秒内知道“要改哪几块”和“为什么要改”。

4. 参考样例（推荐） ​

选一个仓库内现有能力作为对照，给出：

  • 它是什么类型组件/功能
  • 相关文件位置（路径列表）
  • 关键设计点（比如命名、事件透出、预览模式分支、双端差异）

目的：把“抽象规范”落到“仓库真实写法”，降低学习成本。

5. 方案设计与约定（先定规则再写代码） ​

建议包含：

  • 命名约定：rule.type / 注册 key / 组件 name 是否一致（强烈建议一致）
  • 数据契约：v-model 事件、输出值类型、空值含义、change 触发时机
  • 配置契约：哪些来自 rule.props，哪些来自 rule 顶层字段（如 title、field、readMode）
  • 跨端策略：PC/Mobile 是否同名同契约；不一致要明确差异点

6. 实现步骤（从 0 到 1，可执行） ​

用编号小节写清每一步要做什么、改哪个文件、怎么验证：

  • 新增/修改文件
  • 注册（Renderer + Designer）
  • 拖拽规则（DragRule）
  • 侧边栏/菜单入口（如果需要文档入口/功能入口）
  • 多语言（建议）
  • 预览/阅读模式（按需）

每一步尽量遵循：

  • 给出最小可运行代码（能复制粘贴）
  • 解释关键字段为什么这么写（只解释关键点，避免长篇原理）
  • 若存在“历史兼容点”，明确标注为“可选/兼容/不推荐”

7. 完整示例（强烈建议保留） ​

对于“新增能力”类二开，建议提供一个贯穿全文的示例（类似 UserSelect 这种“能跑通”的例子）。

示例至少包含：

  • 组件实现（PC/移动按需）
  • 注册代码
  • DragRule 代码
  • 最终效果（用文字描述或截图/动图）

8. 验收与测试清单（必须有） ​

建议用勾选项：

  • [ ] 设计器左侧能看到入口，能拖拽生成 rule
  • [ ] 设计态画布可正常渲染、可交互（如需）
  • [ ] 运行态渲染正常（渲染器注册无误）
  • [ ] 右侧属性面板配置变更能生效
  • [ ] 事件（change/自定义事件）能被监听到
  • [ ] 禁用态/只读态表现符合预期
  • [ ] 阅读/预览模式表现符合预期（若涉及）
  • [ ] PC/Mobile（若支持）表现一致或差异已说明
  • [ ] 多语言切换不缺项（若涉及）

9. 常见问题排查（必须有） ​

至少覆盖“最常见的 3-6 个坑”，写清：

  • 现象
  • 最可能原因
  • 定位路径（看哪个文件/哪段注册）
  • 修复方式

10. 兼容性与迁移说明（按需但很重要） ​

涉及破坏性变更/历史规则兼容时必须写清：

  • 对已有保存规则的影响（例如新增字段只对新拖入生效）
  • 升级/迁移步骤（如何批量补字段、如何回退）
  • 双注册/兼容转换（如果存在，解释“为什么需要”和“何时可以移除”）

11. 附录（可选） ​

  • 术语表
  • 相关链接（渲染器文档、自定义组件规范等）
  • 设计决策记录（为什么不用某方案）

通用写作策略（强烈建议遵守） ​

命名与可维护性 ​

  • rule.type、组件注册 key、组件 name 尽量一致：这是“减少找不到组件/只在某端生效”的最有效策略。
  • 必须兼容旧命名时：用“兼容策略”小节说明，并建议提供“双注册”或转换层（同时明确计划何时移除兼容）。

“链路写法”优先于“代码堆砌” ​

二开类文档读者最怕“抄一堆代码不知道该放哪”。推荐写法：

  • 先给链路全景（你要改哪些地方）
  • 再给每一步的最小 patch
  • 最后给完整示例作为兜底

示例优先级与颗粒度 ​

  • 优先提供可运行的最小示例，而不是覆盖所有业务分支。
  • 复杂业务可拆成“基础版本 + 进阶版本（可选）”，进阶内容放在后半段或折叠提示中。

代码块与片段规范 ​

  • 代码块要能复制粘贴：不要省略关键 import/注册行（除非明确标注“仅示意”）。
  • 路径要具体：统一使用仓库实际路径（如 src/config/rule/*），避免“某处文件”这种描述。
  • 修改点清晰：更推荐写“在某文件中增加/引入/注册”而不是贴整文件。

提示框使用规范（建议统一） ​

  • tip：最佳实践、推荐写法、经验建议
  • warning：容易踩坑但可恢复的问题（例如旧规则不生效）
  • danger：可能造成数据丢失/线上风险/破坏性升级（必须写迁移方案）

版本与差异说明 ​

  • 跨版本（Vue2/Vue3）：必须明确 v-model 事件差异（value/input vs modelValue/update:modelValue）。
  • 跨端（PC/Mobile）：如果只实现 PC，一定写明移动端“不支持/后续计划/替代方案”。

可观测性与问题定位 ​

二开文档里建议预留“定位入口”信息：

  • 注册位置（渲染器/设计器画布）
  • 规则位置（DragRule 文件）
  • 预览/阅读模式处理位置（如 utils/preview、defaultPreview 等）

“二开文档质量”检查清单（发布前自检） ​

  • 结构完整：至少包含“改哪些地方 / 实现步骤 / 验收清单 / 常见问题”
  • 信息可执行：每个步骤都能定位到具体文件与关键代码
  • 示例可跑通：示例链路覆盖“拖拽 -> 配置 -> 运行态渲染”
  • 兼容说清楚：旧数据/旧规则是否受影响，如何迁移
  • 跨端说清楚：PC/Mobile/版本差异是否明确
  • 术语统一：type/注册 key/组件 name 的叫法一致