datocms-plugin

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DatoCMS Plugin

DatoCMS插件

Plugin development workflow. Patch existing plugins in place; scaffold only when no plugin exists or the user asks for a new project.

插件开发工作流。直接修补现有插件；仅当不存在插件或用户要求创建新项目时才搭建脚手架。

Workflow

工作流

Inspect silently:
- ```
package.json
```
  , package manager, scripts, plugin metadata, and installed SDK/UI versions
- top-level
```
connect()
```
  call, usually
```
src/main.tsx
```
  or
```
src/index.tsx
```
- touched hook pair, render component, helper, CSS file, and current UI pattern
- plugin-local
```
AGENTS.md
```
  if present
Classify the request:
- Existing plugin: package already exists and user asks to patch, add, maintain, fix, release-prep, or restyle. Default here.
- New plugin: user asks to create/scaffold/bootstrap a plugin folder, or no plugin project exists.
- Design pass: request mentions styling, layout, density, spacing, theme, dark mode, Canvas tokens, legacy CSS variables, hardcoded colors, forms, tables, panels, controls, or matching DatoCMS UI patterns.
- Mixed: combine hook/scaffold work with design changes in one pass.
Ask only when inspection cannot resolve a behavior-changing choice:
- plugin/folder name for a new scaffold
- private vs marketplace plugin when package metadata changes
- target model/field/surface when several are plausible
- whether a new permission or dependency is allowed
- whether direct browser CMA calls are required instead of SDK helpers
Load references after file inspection. Use the reference for the touched surface; do not load the full bundle.
Patch in place:
- keep the existing file layout, package manager, scripts, naming, and UI structure
- update paired hooks together: declaration + render, trigger + modal, dropdown declaration + execute handler
- update permissions and package metadata in the same patch when the code path needs them
- add dependencies only when the implementation imports them
Verify with the plugin's existing command. Prefer the build script; add typecheck, lint, or tests only when the project already defines them and they cover the change.
Report the patch, command result, and remaining DatoCMS check: config save, field render, modal resolve, asset select, permission branch, page navigation, or resize behavior.

静默检查：
- ```
package.json
```
  、包管理器、脚本、插件元数据，以及已安装的SDK/UI版本
- 顶层
```
connect()
```
  调用，通常位于
```
src/main.tsx
```
  或
```
src/index.tsx
```
- 关联的钩子对、渲染组件、工具函数、CSS文件，以及当前UI模式
- 若存在则检查插件本地的
```
AGENTS.md
```
对请求进行分类：
- 现有插件：包已存在，用户要求修补、添加功能、维护、修复、准备发布或重新设计。默认采用此流程。
- 新插件：用户要求创建/搭建/初始化插件文件夹，或不存在插件项目。
- 设计优化：请求提及样式、布局、密度、间距、主题、深色模式、Canvas令牌、旧版CSS变量、硬编码颜色、表单、表格、面板、控件，或匹配DatoCMS UI模式。
- 混合需求：在一次处理中结合钩子/脚手架开发与设计变更。
仅当检查无法确定影响行为的选择时才询问用户：
- 新脚手架的插件/文件夹名称
- 包元数据变更时选择私有插件还是市场插件
- 当多个目标模型/字段/界面都合理时，确认目标对象
- 是否允许新增权限或依赖
- 是否需要直接调用浏览器端CMA而非使用SDK工具函数
文件检查完成后加载参考资料。仅加载与涉及界面相关的参考资料，无需加载完整包。
原地修补：
- 保留现有文件结构、包管理器、脚本、命名规则和UI结构
- 同步更新成对的钩子：声明+渲染、触发+模态框、下拉声明+执行处理函数
- 当代码路径需要时，在同一次修补中更新权限和包元数据
- 仅当实现需要导入时才添加依赖
使用插件现有命令验证。优先使用构建脚本；仅当项目已定义类型检查、 lint或测试且覆盖变更内容时，才执行这些操作。
报告修补内容、命令结果，以及剩余的DatoCMS验证项：配置保存、字段渲染、模态框解析、资源选择、权限分支、页面导航或 resize行为。

Reference map

参考资料映射

Common

通用

Need	Load
Follow-up maintenance shortcuts	`references/rapid-patterns.md`
Hook pairs, render conventions, sizing reminder	`references/connect-conventions.md`
Exact `connect()` , render helper, Canvas, frame sizing	`references/sdk-connect-and-frames.md`
Base `ctx` , entity repos, form values, browser CMA, endpoints, async errors	`references/sdk-context-and-cma.md`
Target code has no clear precedent	`references/current-plugin-patterns.md`
Plugin permission changes	`references/permissions.md`
Localized values, field paths, Structured Text Slate form values	`references/form-values.md`

需求	加载资料
后续维护快捷方式	`references/rapid-patterns.md`
钩子对、渲染约定、尺寸提醒	`references/connect-conventions.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`
本地化值、字段路径、结构化文本Slate表单值	`references/form-values.md`

New plugin

新插件

Need	Load
Project files and package baseline	`references/project-scaffold.md`
First hook pair selection	`references/surface-starters.md`

需求	加载资料
项目文件和包基准	`references/project-scaffold.md`
首个钩子对选择	`references/surface-starters.md`

Surfaces

界面类型

Surface	Load
Config screen	`references/config-screen.md`
Field extension	`references/field-extensions.md`
Sidebar panel or full record sidebar	`references/sidebar-panels.md`
Custom page	`references/custom-pages.md`
Dropdown action	`references/dropdown-actions.md`
Lifecycle hook	`references/lifecycle-hooks.md`
Modal	`references/modals.md`
Outlet	`references/outlets.md`
Inspector	`references/inspectors.md`
Asset source	`references/asset-sources.md`
Upload sidebar or upload panel	`references/upload-sidebars.md`
Structured Text customization	`references/structured-text.md`
Record presentation or picker query	`references/record-presentation.md`

界面	加载资料
配置界面	`references/config-screen.md`
字段扩展	`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`
结构化文本定制	`references/structured-text.md`
记录展示或选择器查询	`references/record-presentation.md`

Design

设计

Need	Load
Dark-mode-only migration	`references/dark-mode-upgrade.md`
First design pass	`references/design-foundations.md` + `references/design-datocms-react-ui-bridge.md`
Token/variable lookup	`references/design-tokens.md`
Layouts, pages, split views, toolbars	`references/design-layouts.md`
Forms, controls, settings	`references/design-forms-and-controls.md`
Dropdowns, tabs, tables, lists, notices	`references/design-navigation-feedback-and-data-display.md`
Surface shell rules	`references/design-plugin-surfaces.md`
Raw CSS fallback snippets	`references/design-raw-css-fallbacks.md`

For design work, prefer public

datocms-react-ui

components when they match the required shape. Fall back to local React/CSS only when public components do not express the layout cleanly. Use Canvas tokens and variables directly; customize beyond them only for explicit product styling, vendor widgets, media treatments, data visualization, or effects they cannot express.

需求	加载资料
仅深色模式迁移	`references/dark-mode-upgrade.md`
首次设计优化	`references/design-foundations.md` + `references/design-datocms-react-ui-bridge.md`
令牌/变量查询	`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令牌和变量；仅在明确的产品样式、供应商组件、媒体处理、数据可视化或令牌无法实现的效果场景下，才进行定制。

Guardrails

约束规则

Keep exactly one top-level
```
connect()
```
call.
Inspect existing
```
connect()
```
before adding hooks.
Import
```
datocms-react-ui/styles.css
```
once in the plugin entry file.
Wrap every rendered surface in
```
<Canvas ctx={ctx}>
```
.
Use
```
<Canvas ctx={ctx} noAutoResizer>
```
for pages, inspectors, and full-width sidebars.
Use
```
switch
```
for ID-dispatched render hooks.
Use
```
import type { ... }
```
for SDK types.
Guard
```
ctx.item
```
before reading saved-record data.
Use
```
get(ctx.formValues, ctx.fieldPath)
```
in field extensions; use localized-value helpers elsewhere.
Use deep-compare effects when depending on
```
ctx
```
object properties.
Keep
```
ctx.openModal()
```
parameters and
```
ctx.resolve()
```
values JSON-serializable.
Normalize stored plugin parameters at read/save boundaries.

Use

ctx.setParameters()

directly in

renderManualFieldExtensionConfigScreen

Do not create editor field extensions for modular content, single block, or Structured Text fields; use addon extensions instead.
Prefer SDK helpers before browser CMA calls. If browser CMA is required, use
```
@datocms/cma-client-browser
```
, add only required permissions, and guard missing
```
ctx.currentUserAccessToken
```
.
Keep modals, sidebars, and config screens compact.

仅保留一个顶层
```
connect()
```
调用。
添加钩子前先检查现有
```
connect()
```
。
在插件入口文件中仅导入一次
```
datocms-react-ui/styles.css
```
。
将每个渲染的界面包裹在
```
<Canvas ctx={ctx}>
```
中。
页面、检查器和全宽侧边栏使用
```
<Canvas ctx={ctx} noAutoResizer>
```
。
对ID调度的渲染钩子使用
```
switch
```
语句。
对SDK类型使用
```
import type { ... }
```
。
读取已保存记录数据前先校验
```
ctx.item
```
。
在字段扩展中使用
```
get(ctx.formValues, ctx.fieldPath)
```
；在其他地方使用本地化值工具函数。
依赖
```
ctx
```
对象属性时使用深度比较副作用。
保持
```
ctx.openModal()
```
参数和
```
ctx.resolve()
```
值可JSON序列化。
在读取/保存边界处规范化存储的插件参数。

在

renderManualFieldExtensionConfigScreen

中直接使用

ctx.setParameters()

。

不要为模块化内容、单个块或结构化文本字段创建编辑器字段扩展；改用附加扩展。
优先使用SDK工具函数而非浏览器端CMA调用。若必须使用浏览器端CMA，使用
```
@datocms/cma-client-browser
```
，仅添加必要权限，并校验缺失的
```
ctx.currentUserAccessToken
```
。
保持模态框、侧边栏和配置界面紧凑。

Routing

路由规则

Standalone CMA scripts, schema imports, record operations, or migrations outside a plugin iframe ->
```
datocms-cma
```
or
```
datocms-cli
```
.
Website preview, Content Link, draft mode, cache tags, frontend rendering, or framework setup ->
```
datocms-frontend-integrations
```
or
```
datocms-setup
```
.
Content modeling decisions ->
```
datocms-content-modeling
```
.
Content delivery GraphQL query work ->
```
datocms-cda
```
.

插件iframe外的独立CMA脚本、 schema导入、记录操作或迁移 -> 转至
```
datocms-cma
```
或
```
datocms-cli
```
处理。
网站预览、内容链接、草稿模式、缓存标签、前端渲染或框架配置 -> 转至
```
datocms-frontend-integrations
```
或
```
datocms-setup
```
处理。
内容建模决策 -> 转至
```
datocms-content-modeling
```
处理。
内容交付GraphQL查询工作 -> 转至
```
datocms-cda
```
处理。