SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场hyva-cms-custom-field

hyva-cms-custom-field

编程与开发

查看项目

更新于 10-15 15:59

技能介绍

用途

本技能用于为 Hyvä CMS 组件创建自定义字段类型（custom field type）与字段处理器（field handler），扩展 CMS 编辑器界面中的字段能力。

Hyvä CMS 内置了 text、textarea、select 等字段类型，本技能指导如何在其基础上添加专用输入控件。

两类自定义字段

  • 基础自定义字段类型（Basic Custom Field Type）：带直接数据录入的自定义输入控件，例如日期范围、颜色选择器、自定义校验。
  • 字段处理器（Field Handler）：带复杂交互的增强 UI，例如带图片的商品选择器、可搜索下拉框、链接配置弹窗。

工作流程

  1. 模块选择：若未指定，可选择新建模块（使用 hyva-create-module 技能，依赖 ["Hyva_CmsBase", "Hyva_CmsLiveviewEditor"]，composer_require 为 {"hyva-themes/commerce-module-cms": "^1.0"}），或使用已有模块（验证其 etc/module.xml 含 Hyva_CmsBase 与 Hyva_CmsLiveviewEditor，composer.json 含 hyva-themes/commerce-module-cms，缺失则补充）。
  2. 字段类型详情：收集字段类型名称（小写标识符，如 date_range、product_selector、color_picker）、用途、UI 模式（基础字段 / 内联处理器 / 弹窗处理器）、数据结构（简单字符串、JSON 对象、数组）、校验要求。
  3. 实现模式选择：模式 A 基础自定义字段类型（单模板，无独立处理器弹窗）；模式 B 内联字段处理器（单模板 + Alpine.js 组件，无独立弹窗）；模式 C 弹窗式字段处理器（字段模板 + 处理器弹窗模板 + 布局 XML 注册）。
  4. 生成字段模板：路径为 view/adminhtml/templates/field-types/[field-type-name].phtml，须包含字段容器（ID 为 field-container-{uid}{fieldName}）、输入元素（name 为 {uid}{fieldName}）、校验消息容器（validation-messages-{uid}_{fieldName}）、值变更时的 updateWireField() 或 updateField() 调用、通过 $magewire->errors 处理错误状态。字段值须用空合并运算符 $block->getData('value') ?? ''，不可用类型转换。可基于 assets/templates/ 中的模板：basic-field.phtml.tpl、inline-handler.phtml.tpl、modal-field.phtml.tpl。
  5. 生成处理器弹窗（仅弹窗式）：路径为 view/adminhtml/templates/handlers/[handler-name]-handler.phtml，使用 <dialog> 元素加 Alpine.js 组件与 open:flex 类，监听字段模板的初始化事件，实现选择 UI，保存时派发 editor-change 事件。可基于 assets/templates/modal-handler.phtml.tpl。
  6. 注册字段类型：在 etc/adminhtml/di.xml 中向 Hyva\CmsLiveviewEditor\Model\CustomField 的 customTypes 数组参数添加条目，值为 [Vendor]_[Module]::field-types/[field-type-name].phtml。
  7. 注册处理器弹窗（仅弹窗式）：在 view/adminhtml/layout/liveview_editor.xml 的 before.body.end 容器中添加对应 block。内联处理器不需要布局 XML 注册。
  8. 用法示例：在 components.json 中配置 type 为 custom_type、custom_type 为具体字段类型名，并可设置 label 与 attributes（如 required、pattern）。

主要约定与准则

  • 模板要求：所有自定义字段类型须遵循必需的标记模式（容器 ID、输入 name、校验消息）。
  • 处理器注册：弹窗处理器需要布局 XML 注册；内联处理器不需要。
  • 校验：通过 $filteredAttributes 应用 HTML5 校验属性以实现自动校验。
  • Alpine 组件：若使用自定义 Alpine 组件，输入字段应放在组件外部，并通过原生 JS 更新。
  • 内置示例参考：可参考 Hyva_CmsLiveviewEditor::page/js/ 中的内置处理器模式。
  • 事件命名约定：使用 toggle-{type}-select 模式（如 toggle-product-select、toggle-link-select、toggle-category-select）。
  • 处理器函数命名约定：使用 init{Type}Select() 模式（如 initProductSelect()、initLinkSelect()、initCategorySelect()）。
  • 字段值更新方法：updateWireField（默认，触发 Magewire 即时服务端校验，保持组件状态同步，用于商品、链接、分类处理器）；updateField（专用，更新预览但不与服务端往返，延迟校验至保存，用于图片处理器及颜色、范围等防抖输入）。
  • JSON 编码模式：所有复杂数据（数组、对象）必须 JSON 编码。
  • Livewire 兼容：可搜索下拉框使用 wire:ignore 包裹。
  • 独立处理器文件：即使内联处理器也可能有独立函数文件。
  • 图标使用 Icons 视图模型，属性过滤使用 FieldTypes 视图模型（getDefinedFieldAttributes 或 getAttributesByKeys）。

关键注意事项

  • 布局 XML 的 referenceContainer 必须使用 before.body.end，不能使用 content，以确保处理器弹窗在页面 body 末尾加载，保证 Alpine.js 正确初始化。
  • 字段值类型处理：绝不使用类型转换，总是使用空合并运算符（字符串用 ?? ''，数组用 ?? []）。
  • 弹窗对话框类：处理器弹窗必须使用 open:flex 而非静态 flex，否则弹窗始终可见。
  • 复杂数据类型处理：对于存储 JSON 或数组数据的字段，需同时处理数组和字符串两种类型，输出到隐藏输入时始终确保为 JSON 字符串。

适用场景

为 Hyvä CMS 组件开发需要自定义输入控件（日期范围、颜色选择器、自定义校验、商品选择器、可搜索下拉框、链接配置等）的编辑器界面时使用。

资源文件

  • references/template-requirements.md：自定义字段类型模板要求的完整参考。
  • references/handler-patterns.md：三种自定义字段类型的实现模式。
  • references/handler-communication.md：字段处理器的事件协议与数据交换。
  • references/built-in-handlers.md：Hyvä CMS 内置字段处理器参考。
  • assets/templates/basic-field.phtml.tpl：基础自定义字段类型模板。
  • assets/templates/inline-handler.phtml.tpl：内联增强控件模板。
  • assets/templates/modal-field.phtml.tpl：弹窗式处理器的字段模板。
  • assets/templates/modal-handler.phtml.tpl：弹窗式处理器模板。

限制

资料未提供该技能的具体运行环境要求、支持版本范围、收费与价格信息。命令执行（如 bin/magento）需借助 hyva-exec-shell-cmd 技能检测环境并确定命令包装方式。