React 组件

可以通过在字段上设置 ui.component 属性来传递和渲染自定义组件。

这个组件完全覆盖了原始组件，提供给用户完全自定义字段的能力。

自定义组件中的环境变量

自定义字段组件在 TinaCMS 管理界面中运行，该界面作为一个与您的网站分开的静态 SPA构建。环境变量在构建时嵌入到管理 JavaScript 中——它们不会在运行时读取。这意味着要使变量可用，必须满足两个条件：

1. 必须使用允许的前缀。 出于安全原因，仅包括这些变量：
   • TINA_PUBLIC_*
   • NEXT_PUBLIC_*
   • NODE_ENV
   • HEAD
2. 必须在运行 tinacms build（或 tinacms dev）时设置。 如果变量在构建期间不在环境中，则无论其名称如何，它都不会存在于管理界面中。

任何其他环境变量（例如 process.env.MY_SECRET_KEY）在自定义组件中将是 undefined。

如果您的自定义组件依赖于环境变量并且它总是 undefined，请检查：(1) 变量名称是否以 TINA_PUBLIC_ 或 NEXT_PUBLIC_ 开头，以及 (2) 变量是否在 tinacms build 运行时在您的 .env 文件或 CI 环境中定义。请注意，TinaCMS 仅加载 .env 文件——不加载 .env.local 或 .env.development。有关详细信息，请参阅 配置参考 和 安全公告。

ui.component 属性

这应该设置为一个有效的 React 组件，该组件最多接受四个属性：

• field: 当前字段的字段定义。
• input: 创建输入所需的数据和回调。
• meta: 表单中关于字段的元数据。（例如 dirty、valid）。
• form: CMS 表单，用于检索和更新同一集合中的其他字段。

查看 react-final-form 文档以获取 input 和 meta 属性的更详细描述。

保留元数据

要在自定义组件上保留相同的标签、描述、验证和其他元设置，可以使用包装函数 wrapFieldsWithMeta。

表单管理

form 属性可用于控制其他字段中的表单值。

集合中的任何字段都可以使用 form.change 更新 – form.change(name: string, value: any) => void，使用字段的 name 属性。

集合中的任何字段都可以使用 form.getFieldState(name: string)?.value 访问，使用字段的 name 属性。

可以从 react-final-form FormAPI 文档中推断出进一步的使用模式。

隐藏字段

将 component.ui 设置为值 "hidden" 会将字段从编辑器中移除。

该字段仍然在后台存在，并可以通过其他方式访问。

示例

滑块组件

这是一个可用于调整图像饱和度的自定义滑块组件。

带有隐藏元字段的图像组件

NextJS 和其他框架能够在提前知道图像宽度和高度的情况下提高性能。

TinaCMS 可以用于在上传时确定并存储这些信息。

我们可以传递现有的 TinaCMS 图像组件，并通过 useEffect 拦截对它的更改，以更新我们的宽度和高度字段。

在内容模型中，我们还需要两个用于高度和宽度的附加字段，它们被设置为 "hidden"，因此不会出现在编辑器中。

这在编辑器中显示为一个单一的图像输入，但每次更新时将保存 3 个值（图像源、高度和宽度）。

条件组件

可以通过检查其他表单字段的值来创建条件字段。

使用这种方法，隐藏的条件字段将保留在隐藏之前保存的任何值。

图标选择器组件（视频）

下面的教程包括一个关于使用自定义字段组件创建自定义图标选择器的部分。

图像缩放滑块组件

通过一些额外的 CSS，您可以在 TinaCMS 中创建可缩放的图像。这将节省您为博客裁剪图像的时间。

使用 AI 构建自定义组件

在下面的视频中，探索了一种构建自定义组件的氛围编码方法。这展示了如何通过使用 AI 快速迭代复杂的 UI 逻辑和样式，以创建个性化的字段体验。

视频：Vibe Coding TinaCMS 自定义组件（7 分钟）