datocms-plugin

DatoCMS 插件

插件代码：就地修补；仅在用户要求或插件不存在时才搭建脚手架。项目的插件安装属于 CMA 数据，而非插件代码——如需安装、启用/禁用、在市场软件包与私有 URL 或版本之间切换，或编辑全局 parameters，请使用 datocms-cma 的插件操作。在不影响当前工作安装的情况下进行本地测试：开发副本。

工作流

1. 静默检查：
   • package.json、包管理器、脚本、插件元数据，以及已安装的 SDK/UI 版本
   • 顶层 connect() 调用，通常位于 src/main.tsx 或 src/index.tsx
   • 要修改的钩子对、渲染组件、辅助函数、CSS 文件和当前 UI 模式
   • 插件本地的 AGENTS.md（如果存在）
2. 对请求进行分类：
   • 现有插件： 软件包已存在，且用户要求修补、添加、维护、修复、准备发布或调整样式。默认按此类处理。
   • 新插件： 用户要求创建/搭建脚手架/初始化插件文件夹，或不存在插件项目。
   • 设计调整： 请求提及样式、布局、密度、间距、主题、深色模式、Canvas 令牌、旧版 CSS 变量、硬编码颜色、表单、表格、面板、控件，或与 DatoCMS UI 模式保持一致。
   • 混合请求： 在一次处理中结合钩子/脚手架工作与设计更改。
3. 仅在检查无法确定会改变行为的选择时提问：
   • 新建脚手架时的插件/文件夹名称
   • 更改软件包元数据时，选择私有插件还是市场插件
   • 存在多个合理选项时的目标模型/字段/界面
   • 是否允许新增权限或依赖项
   • 是否必须直接调用浏览器 CMA，而不能使用 SDK 辅助函数
4. 检查文件后再加载参考资料。使用与修改界面相关的参考资料；不要加载完整资料包。
5. 就地修补：
   • 保留现有文件布局、包管理器、脚本、命名和 UI 结构
   • 一起更新成对的钩子：声明 + 渲染、触发器 + 模态框、下拉菜单声明 + 执行处理函数
   • 如果代码路径需要权限和软件包元数据，则在同一补丁中一并更新
   • 仅在实现中导入依赖项时才添加这些依赖项
6. 使用插件现有命令进行验证。优先使用构建脚本；仅当项目已定义类型检查、Lint 或测试，且这些命令覆盖了本次更改时才添加运行。
7. 报告补丁内容、命令结果，以及仍需在 DatoCMS 中检查的事项：保存配置、字段渲染、模态框解析、资产选择、权限分支、页面导航或调整大小行为。

参考资料索引

常用

需求	加载
后续维护快捷方式	references/rapid-patterns.md
精确的 connect()、钩子对、渲染辅助函数、Canvas、框架尺寸	references/sdk-connect-and-frames.md
基础 ctx、实体仓库、表单值、浏览器 CMA、端点、异步错误	references/sdk-context-and-cma.md
目标代码没有明确的先例	references/current-plugin-patterns.md
插件权限更改	references/permissions.md
本地化值、字段路径、Structured Text Slate 表单值	references/form-values.md

新插件

需求	加载
项目文件和软件包基线	references/project-scaffold.md
首个钩子对的选择	references/surface-starters.md

界面

界面	加载
配置屏幕	references/config-screen.md
Field 扩展	references/field-extensions.md
侧边栏面板或完整记录侧边栏	references/sidebar-panels.md
自定义页面	references/custom-pages.md
下拉菜单操作	references/dropdown-actions.md
生命周期钩子	references/lifecycle-hooks.md
模态框	references/modals.md
出口	references/outlets.md
检查器	references/inspectors.md
资源来源	references/asset-sources.md
上传侧边栏或上传面板	references/upload-sidebars.md
Structured Text 自定义	references/structured-text.md
记录展示或选择器查询	references/record-presentation.md

设计

需求	加载
仅深色模式迁移	references/dark-mode-upgrade.md
首轮设计	references/design-foundations.md + references/design-datocms-react-ui-bridge.md
Token／变量查询	references/design-tokens.md
布局、页面、分栏视图、工具栏	references/design-layouts.md
表单、控件、设置	references/design-forms-and-controls.md
下拉菜单、标签页、表格、列表、通知	references/design-navigation-feedback-and-data-display.md
界面外壳规则	references/design-plugin-surfaces.md
原始 CSS 回退代码片段	references/design-raw-css-fallbacks.md

进行设计时，如果公开的 datocms-react-ui 组件符合所需样式，应优先使用。只有在公开组件无法清晰表达布局时，才回退到本地 React／CSS。直接使用 Canvas token 和变量；只有在明确需要产品样式、供应商小组件、媒体处理、数据可视化或组件无法表达的效果时，才在此基础上进行自定义。

注意事项

• 顶层 connect() 调用必须且只能有一个。
• 添加钩子前，先检查现有的 connect()。
• 在插件入口文件中导入一次 datocms-react-ui/styles.css；保留 src/vite-env.d.ts（/// <reference types="vite/client" />），否则 TS 会拒绝。
• 所有渲染的界面都必须包裹在 <Canvas ctx={ctx}> 中。
• 对页面、检查器和全宽侧边栏使用 <Canvas ctx={ctx} noAutoResizer>。
• 对按 ID 分派的渲染钩子使用 switch。
• SDK 类型使用 import type { ... } 导入。
• 读取已保存的记录数据前，先检查 ctx.item。
• 在字段扩展中使用 get(ctx.formValues, ctx.fieldPath)；其他场景使用本地化值辅助函数。
• 依赖 ctx 对象属性时，使用深度比较的 effect。
• 确保 ctx.openModal() 参数和 ctx.resolve() 值可序列化为 JSON。
• 在读取／保存边界处规范化已存储的插件参数。
• 在 renderManualFieldExtensionConfigScreen 中直接使用 ctx.setParameters()。
• Modular Content 在 FieldType 和 API field_type 中对应 rich_text。不要为 Modular Content、单块或 Structured Text 字段创建编辑器字段扩展；应使用附加组件（Modular Content：fieldTypes: ['rich_text']；单块没有 FieldType：使用 overrideFieldExtensions，或者在每种字段类型都可以提供该组件时使用 fieldTypes: 'all'）。
• 优先使用 SDK 辅助函数，而不是浏览器 CMA 调用。如果必须使用浏览器 CMA，请使用 @datocms/cma-client-browser，仅添加所需权限，并检查 ctx.currentUserAccessToken 是否存在。
• 保持模态框、侧边栏和配置屏幕简洁。

路由

• DAST 分析、校验或转换 → datocms-structured-text：文档模型、编辑或转换。在此处保留 Slate 表单值和编辑器钩子；绝不要将 DAST 传递给 ctx.setFieldValue。仅在处理 DAST 时加载专用工具。缺少同级参考资料 → 从 datocms/agent-skills 安装该技能，或更新完整工具包。

• 网站预览、Content Link、草稿模式、缓存标签、前端渲染或框架接线 -> datocms-frontend-integrations；分步骤的网站设置指南 -> datocms-setup。

• 内容建模决策 -> datocms-content-modeling。

• 内容交付 GraphQL 查询工作 -> datocms-cda。