# 为 CMS 页面创建 Magento 2 小部件 ## 目的此技能提供了在 Magento 2 中创建自定义小部件模块（标准 Luma/Blank 主题，不是基于 Hyvä 的）的全面指导，这些模块可以插入到 CMS 页面、CMS 块或使用小部件系统的任何内容区域中。 ## 何时使用此技能当您需要执行以下操作时，请使用此技能： * 创建可插入CMS页面的可重用组件 * 为内容编辑器构建交互元素（按钮、表单、模式） * 开发非技术用户可以添加到页面的自定义功能 * 创建具有可配置参数的小部件，这些参数显示在管理面板中 * 实现与标准 Magento 主题（Luma/Blank）配合使用的小部件 **请勿将此技能用于：** * Hyvä 主题小部件（使用 hyva-tailwind-integration 技能代替） * 后台管理小部件 * UI组件或管理网格 ## 先决条件 * 现有供应商命名空间或愿意创建一个 * 对Magento 2模块结构的基本了解 * XML配置知识 * 熟悉 Magento 模板和块 * 了解 JavaScript 小部件模式（可选，用于交互式小部件） ## Widget 模块结构一个完整的小部件模块需要以下组件：应用程序/代码/供应商/模块名称/ ├── Registration.php # 模块注册 ├── 等等/ │ ├── module.xml # 模块配置 │ ├── widget.xml # Widget定义 │ ├── email_templates.xml # (可选) 电子邮件模板 │ └── 前端/ │ └──routes.xml #（可选）用于表单提交 ├── 方块/ │ └── 小工具/ │ └── WidgetName.php # Widget块类 ├── Controller/ # (可选) 对于表单处理程序 │ └── 索引/ │ └── 提交.php └── 视图/前端/ ├── 模板/ │ └── 小部件/ │ └── template.phtml # 小部件模板 ├── 布局/ │ └── default.xml # (可选)全局加载CSS/JS ├── 网/ │ ├── js/ │ │ └── widget-script.js # (可选)自定义JS │ └── css/ │ └── widget-style.css # (可选)自定义CSS ├── requirejs-config.js # (可选)JS模块映射 └── email/ # (可选) 邮件模板 └── 模板.html ## 逐步创建小部件 ### 第 1 步：创建模块注册 **文件：`registration.php`** <模块名称=“Vendor_ModuleName”setup_version=“1.0.0”> <序列> <模块名称=“Magento_Cms”/> <模块名称=“Magento_Widget”/> **要点：** * `setup_version` 是遗留的，但仍然常用 * 在 `` 中添加依赖项 - 小部件需要 `Magento_Cms` 和 `Magento_Widget` * 添加您的小部件所依赖的其他模块（例如，`Magento_Email`、`Magento_Catalog`） ### 第 3 步：创建小部件配置 **文件：`etc/widget.xml`** 您可以在此处定义小部件的元数据和可配置参数。 <小部件 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Widget:etc/widget.xsd"> 小部件显示名称小部件功能的简要描述 <参数> <参数名称=“text_param”xsi：类型=“文本”必需=“假”可见=“真”> 文本标签管理中显示的说明 <参数名称=“select_param”xsi：类型=“选择”必需=“假”可见=“真”> 选择选项 <选项> <选项名称=“选项1”值=“值1”> <标签>选项1 <选项名称=“选项2”值=“值2”> <标签>选项2 <参数名称=“已启用”xsi：类型=“选择”必需=“假”可见=“真” source_model="Magento\Config\Model\Config\Source\Yesno"> 启用功能 CMS 块 <数据> <项目名称=“按钮”xsi：类型=“数组”> 选择块... <参数名称=“category_id” xsi：类型=“选择”可见=“true” source_model="Magento\Catalog\Model\Category\Attribute\Source\Categories"> 类别 **小部件参数类型：** * `text` \- 简单的文本输入 * `select` \- 下拉选择 * `multiselect` \- 多项选择 * `block` \- CMS 块选择器 * `page` \- CMS页面选择器 * `conditions` \- 产品/类别条件（高级） **重要属性：** * `id` \- 小部件的唯一标识符 * `class` \- 块类的完整命名空间路径 * `required` \- 参数是否为必填 * `visible` \- 参数是否在管理中显示 ### 步骤 4：创建块类 **文件：`Block/Widget/WidgetName.php`** 块类处理小部件的逻辑和数据。 getData('text_param') ?: '默认值'; } /** * 获取小部件选择参数 * * @返回字符串 */ 公共函数 getSelectValue(): 字符串 { return $this->getData('select_param') ?: 'value1'; } /** * 检查该功能是否启用 * * @返回布尔值 */ 公共函数 isEnabled(): bool { return (bool)$this->getData('启用'); } /** * 获取 AJAX 或表单提交的 URL * * @返回字符串 */ 公共函数 getActionUrl(): 字符串 { return $this->getUrl('模块名/索引/提交'); } } **最佳实践：** * 始终“声明(strict_types=1);” * 实现“块接口” * 使用 `$this->getData('param_name')` 访问小部件参数 * 使用“?:”运算符提供默认值 * 添加类型提示和返回类型 * 将业务逻辑置于模板之外 - 将其放入块方法中 ### 步骤 5：创建模板文件 **文件：`view/frontend/templates/widget/template.phtml`** 模板呈现 HTML 输出。为了安全起见，请始终转义数据。 getParameterValue(); $selectValue = $block->getSelectValue(); $isEnabled = $block->isEnabled(); $uniqueId = uniqid('widget_'); ?> **模板最佳实践：** * 文本内容始终使用 `$escaper->escapeHtml()` * 对 HTML 属性使用 `$escaper->escapeHtmlAttr()` * 对 JavaScript 字符串使用 `$escaper->escapeJs()` * 使用 `$escaper->escapeUrl()` 作为 URL * 对可翻译字符串使用`__()` * 生成唯一ID以避免冲突（使用`uniqid()`） * 添加适当的“@var”注释以支持 IDE **常见的转义方法：** // 文本内容 escapeHtml($text) ?> // HTML 属性

"> // JavaScript 字符串 data-value="escapeJs($value) ?>" // 网址 "> // CSS

"> ### 第 6 步：添加 JavaScript（可选）如果您的小部件需要交互性，请使用 Magento 的小部件模式添加 JavaScript。 **文件：`view/frontend/requirejs-config.js`** /** * 版权所有© 供应商。版权所有。 */ 变量配置= { 地图：{ '*': { widgetName: 'Vendor_ModuleName/js/widget-script' } } }; **文件：`view/frontend/web/js/widget-script.js`** /** * 版权所有© 供应商。版权所有。 */ 定义（[ 'jquery', 'jquery-ui-modules/小部件' ], 函数 ($) { '使用严格'； /** * 小部件初始化模式 */ $.widget('vendor.widgetName', { 选项：{ 元素 ID: '', ajax 网址: '' }, /** * 小部件创建 * @私人 */ _创建：函数（）{ this._bind(); }, /** * 绑定事件处理程序 * @私人 */ _bind: 函数 () { var self = this; this.element.on('点击', 函数 (e) { e.preventDefault(); self._handleClick(); }); }, /** * 处理点击事件 * @私人 */ _handleClick: 函数 () { console.log('小部件被点击！'); console.log('元素 ID:', this.options.elementId); // AJAX 调用示例 if (this.options.ajaxUrl) { this._makeAjaxRequest(); } }, /** * 发出AJAX请求 * @私人 */ _makeAjaxRequest：函数（）{ var self = this; $.ajax({ url: this.options.ajaxUrl, 类型：'发布'，数据类型：'json', 数据：{ // 这里是你的数据 }, 成功：函数（响应）{ self._handleResponse(响应); }, 错误：函数（）{ console.error('请求失败'); } }); }, /** * 处理AJAX响应 * @私人 */ _handleResponse：函数（响应）{ 如果（响应.成功）{ console.log('成功：', response.message); } 否则{ console.error('错误：', response.message); } } }); 返回 $.vendor.widgetName; }); **模板中的初始化：** <按钮类型=“按钮” data-mage-init='{"widgetName": { "elementId": "escapeJs($uniqueId) ?>", "ajaxUrl": "escapeUrl($block->getActionUrl()) ?>" }}'> 点我 **使用`data-bind` (Knockout.js) 进行替代初始化：**

<脚本类型=“文本/x-magento-init”> { “[数据绑定]”：{ “Magento_Ui/js/core/app”：{ “组件”：{ “小部件范围”：{ “组件”：“Vendor_ModuleName / js /小部件组件” } } } } } ### 步骤 7：添加 CSS 样式（可选） **文件：`view/frontend/layout/default.xml`** 在所有页面上全局加载 CSS。 <页面 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"> <头> **文件：`view/frontend/web/css/widget-style.css`** /** * 版权所有© 供应商。版权所有。 */ /* 小部件容器 */ .自定义小部件{ 内边距：20px；边距：10px 0； } .custom-widget .widget-content { 背景：#f5f5f5；内边距：15px；边框半径：5px； } .custom-widget h3 { 边距：0 0 10px；字体大小：18px；字体粗细：600； } .custom-widget .widget-button { 顶部边距：10px； } /* 响应式设计 */ @media（最大宽度：768px）{ .自定义小部件{ 内边距：15px； } .custom-widget .widget-content { 内边距：10px； } } **CSS 最佳实践：** * 使用特定的类名以避免冲突 * 媒体查询遵循移动优先方法 * 尊重现有的主题风格 * 使用 CSS 变量进行主题化（如果支持） * 除非绝对必要，否则避免使用“!important” ## 高级：添加表单提交控制器对于需要处理数据（表单、AJAX 请求）的小部件，添加控制器。 ### 第 1 步：创建前端路由 **文件：`etc/frontend/routes.xml`** <路由器id=“标准”> <模块名称=“Vendor_ModuleName”/> **路由 URL 模式：** * URL：`https://yourstore.com/modulename/index/submit` * `模块名称` = frontName * `index` = 控制器目录 * `submit` = 操作文件名 ### 第 2 步：创建控制器操作 **文件：`Controller/Index/Submit.php`** 请求= $请求； $this->resultJsonFactory = $resultJsonFactory; $this->logger = $logger; } /** * 执行动作 * * @return \Magento\Framework\Controller\Result\Json */ 公共函数执行() { $resultJson = $this->resultJsonFactory->create(); if (!$this->request->isPost()) { 返回 $resultJson->setData([ '成功' => 假， 'message' => __('请求方法无效。') ]); } 尝试{ $postData = $this->request->getPostValue(); // 验证数据 $this->validateData($postData); // 在这里处理你的数据 // 示例：保存到数据库、发送电子邮件等。返回 $resultJson->setData([ '成功' => 正确， 'message' => __('您的请求已成功提交。') ]); } catch (LocalizedException $e) { $this->logger->error('小部件表单错误：' . $e->getMessage()); 返回 $resultJson->setData([ '成功' => 假， '消息' => $e->getMessage() ]); } catch (\Exception $e) { $this->logger->error('小部件表单错误：' . $e->getMessage()); 返回 $resultJson->setData([ '成功' => 假， 'message' => __('发生错误。请稍后再试。') ]); } } /** * 验证表单数据 * * @参数数组$data * @抛出本地化异常 */ 私有函数 validateData(array $data): void { if (空($data['field_name'])) { throw new LocalizedException(__('字段名称为必填项。')); } if (!filter_var($data['email'], FILTER_VALIDATE_EMAIL)) { throw new LocalizedException(__('请输入有效的电子邮件地址。')); } } } **控制器最佳实践：** * 使用 `HttpPostActionInterface` 进行 POST 请求 * 使用 `HttpGetActionInterface` 进行 GET 请求 * 返回正确的结果对象（`JsonFactory`、`PageFactory`、`RedirectFactory`） * 始终验证输入数据 * 使用try-catch块进行错误处理 * 记录错误以供调试 * 返回用户友好的错误信息 ## 高级：模态弹出窗口小部件对于像模态形式这样的复杂交互： **模态模板：**

<按钮类型=“按钮” 类=“主要动作” data-mage-init='{"widgetModal": {"modalId": "escapeJs($modalId) ?>"}}'> escapeHtml(__('打开模态')) ?>

**模态 JavaScript：** **重要：** 1. 当您有自定义模态 HTML 结构时，请勿使用 Magento 的 `Magento_Ui/js/modal/modal` 组件 - 它会与 z-index、定位和双重叠加产生冲突 2. 初始化时始终将模态元素移动到 `` 以防止父容器约束（溢出、定位、z-index）定义（[ 'jquery' ], 函数 ($) { '使用严格'； $.widget('vendor.widgetModal', { 选项：{ 模式 ID: '' }, _创建：函数（）{ this._moveModalToBody(); this._bind(); }, /** * 将模态元素移至主体以防止父容器约束 * 这是至关重要的 - 没有这个，模态将被困在小部件容器内 */ _moveModalToBody: 函数 () { var modalElement = $('#' + this.options.modalId); if (modalElement.length && modalElement.parent()[0].tagName !== 'BODY') { // 将模态框移至正文，使其不受父级定位的限制 modalElement.appendTo('body'); } }, _bind: 函数 () { var self = this; // 单击按钮时打开模态框 this.element.on('点击', 函数 (e) { e.preventDefault(); self.openModal(); }); }, openModal: 函数 () { var modalElement = $('#' + this.options.modalId); if (modalElement.length) { // 显示具有淡入淡出效果的模态 modalElement.fadeIn(300); $('body').addClass('modal-open'); // 绑定关闭按钮（仅一次） modalElement.find('.widget-modal-close, .action.cancel').off('click').on('click', function (e) { e.preventDefault(); modalElement.fadeOut(300); $('body').removeClass('modal-open'); }); // 绑定叠加点击（仅一次） modalElement.find('.widget-modal-overlay').off('click').on('click', function (e) { e.preventDefault(); modalElement.fadeOut(300); $('body').removeClass('modal-open'); }); // 绑定ESC键 $(document).off('keyup.widgetModal').on('keyup.widgetModal', function (e) { if (e.key === 'Escape' || e.keyCode === 27) { modalElement.fadeOut(300); $('body').removeClass('modal-open'); $(document).off('keyup.widgetModal'); } }); } } }); 返回$.vendor.widgetModal； }); **模态 CSS 样式：** /** * 模态样式 * 重要： * - 使用非常高的 z-index (999999) 和 !important 以确保模态出现在所有内容之上 * - 许多主题对标题、菜单等使用高 z-index 值（10000+） * - 模态容器和所有子容器使用position:fixed来转义父容器 * - 覆盖层使用较暗的背景（0.7 不透明度）来清楚地指示被阻止的内容 */ .widget-modal { 显示：无；位置：固定；顶部：0；左：0；宽度：100%；高度：100%； z-index：999999！重要； } .widget-modal-overlay { 位置：固定；顶部：0；左：0；宽度：100%；高度：100%；背景：rgba(0,0,0,0.7); z-index：999998！重要；光标：指针； } .widget-modal-content { 位置：固定；顶部：50%；左：50%；变换：翻译（-50%，-50%）；背景：#fff；边框半径：8px；盒子阴影：0 4px 20px rgba(0, 0, 0, 0.2); z-index：999999！重要；最大宽度：600px；宽度：90%；最大高度：90vh；溢出-y：自动； } /* 当模态打开时防止主体滚动 */ body.modal-open { 溢出：隐藏； } /* 确保模态容器阻止所有指向下面元素的指针事件 */ .widget-modal { 指针事件：自动； } .widget-modal * { 指针事件：自动； } .widget-modal-header { 显示：柔性； justify-content：空间之间；对齐项目：居中；内边距：20px 30px；边框底部：1px 实线#e0e0e0； } .widget-modal-header h2 { 保证金：0；字体大小：24px；字体粗细：600；颜色：#333； } .widget-modal-close { 背景：无；边框：无；字体大小：32px；行高：1；颜色：#666；光标：指针；填充：0；宽度：32px；高度：32像素；显示：柔性；对齐项目：居中；调整内容：居中；过渡：颜色0.3s缓和； } .widget-modal-close:悬停{ 颜色：#000； } .widget-modal-body { 内边距：30px； } /* 响应式设计 */ @media（最大宽度：768px）{ .widget-modal-content { 宽度：95%；最大高度：95vh； } .widget-modal-header { 内边距：15px 20px； } .widget-modal-header h2 { 字体大小：20px； } .widget-modal-body { 内边距：20px； } } ## 安装部署 ### 安装命令 # 启用模块 bin/magento 模块：启用 Vendor_ModuleName # 运行安装升级 bin/magento 设置：升级 # 编译依赖注入（生产模式） bin/magento 设置：di：编译 # 部署静态内容（生产模式） bin/magento 设置：静态内容：部署 -f # 清除缓存 bin/magento 缓存：刷新 ### 部署清单 1. ✅ 模块启用 2. ✅ 更新数据库架构（`setup:upgrade`） 3. ✅ DI 编译（`setup:di:compile`） 4. ✅ 部署静态内容 5. 清除缓存 6. ✅ 权限检查（www-数据所有权） ## 使用小部件 ### 方法 1：管理面板（CMS 编辑器） 1. 导航到 **内容 > 页面** 或 **内容 > 块** 2. 编辑所需的页面或区块 3. 将光标置于小部件应出现的位置 4. 单击编辑器工具栏中的 **插入小部件** 按钮 5. 选择**小部件类型**：您的小部件名称 6. 配置小部件参数 7. 单击“**插入小部件**” 8. 保存页面/块 ### 方法 2：直接在 CMS 内容中编码直接在CMS内容中添加小部件代码： {{widget type="Vendor\ModuleName\Block\Widget\WidgetName" text_param="我的价值" 选择参数=“值1” 启用=“1”}} ### 方法 3：XML 布局文件在布局 XML 中以编程方式添加小部件： <参考容器名称=“内容”> <参数> 我的价值 <参数名称=“select_param”xsi：类型=“字符串”>值1 <参数名称=“启用”xsi：类型=“布尔”>真 ### 方法 4：在模板中以编程方式在任何模板中创建小部件块： getLayout() ->createBlock(\Vendor\ModuleName\Block\Widget\WidgetName::class) ->setData('text_param', '我的值') ->setData('启用', true) ->toHtml() ?> ## 真实示例：报价请求表小部件基于为 LCD 屏幕维修创建的“ItTools_QuoteForm”模块： **特点：** * 模态弹出表单 * 文件上传（最多 3 张图片，每张 5MB） * 客户端验证 * AJAX提交 * 带有附件的电子邮件 * 成功/错误消息 **关键文件：** 应用程序/代码/ItTools/QuoteForm/ ├── Block/Widget/QuoteButton.php ├── 控制器/索引/Submit.php ├── 等/widget.xml ├── 等/email_templates.xml ├── view/frontend/templates/widget/quotebutton.phtml ├── view/frontend/web/js/quote-modal.js ├── 查看/frontend/web/js/quote-form.js └── view/frontend/web/css/quote-form.css **用途：** {{widget type="ItTools\QuoteForm\Block\Widget\QuoteButton" button_text="获取免费报价" Button_class="主要操作"}} ## 常见小部件用例 1. **联系表格** \- 自定义联系/查询表格 2. **报价请求按钮** \- 潜在客户生成表格 3. **产品滑块** \- 特色产品轮播 4. **CTA（号召性用语）** \- 促销按钮/横幅 5. **时事通讯注册** \- 自定义订阅表格 6. **社交媒体源** \- 显示社交内容 7. **商店定位器** \- 查找最近的商店小部件 8. **计算器** \- 价格/运费计算器 9. **评论/推荐** \- 客户反馈显示 10. **搜索框** \- 自定义搜索功能 ## 最佳实践总结 ### 安全 1. ✅ 始终转义模板中的输出 2. 验证并清理所有用户输入 3. ✅ 使用表单键进行 POST 请求 4. ✅ 实施CSRF保护 5. ✅ 检查上传的文件类型和大小 6. ✅ 使用参数化查询（避免SQL注入） 7. ✅ 正确验证电子邮件地址 8. ✅ 添加表单提交速率限制 ### 性能 1. ✅ 尽量减少块中的数据库查询 2. ✅ 在适当的情况下使用缓存 3. 尽可能延迟加载 JavaScript 4. ✅ 优化CSS（删除未使用的样式） 5. ✅ 压缩图像和资源 6. 静态资产使用CDN 7. 避免阻塞 JavaScript ### 代码质量 1. ✅ 使用严格类型 (`declare(strict_types=1);`) 2. ✅ 添加类型提示和返回类型 3. ✅ 遵循Magento编码标准 4. ✅ 使用依赖注入（无ObjectManager） 5. ✅ 添加适当的 PHPDoc 注释 6. ✅ 保持方法小而集中 7. ✅ 使用常量作为魔法值 8. ✅ 实施正确的错误处理 9. ✅ 适当记录错误 10. 编写单元/集成测试 ### 用户体验 1. ✅ 使小部件响应式（适合移动设备） 2. ✅ 提供清晰的成功/错误消息 3. ✅ 添加AJAX加载指示器 4. ✅ 验证客户端和服务器端的表单 5. ✅ 使用辅助功能属性 (aria-*) 6. ✅ 测试键盘导航 7. ✅ 提供清晰的标签和说明 8. ✅ 优雅地处理边缘情况 ### 可维护性 1. ✅ 使用有意义的变量/方法名称 2. 保持模板干净（逻辑块） 3. ✅ 记录复杂的逻辑 4. ✅ 使用配置进行设置 5. ✅遵循单一责任原则 6. ✅ 使代码可测试 7. ✅ 正确的版本控制 8. ✅ 添加 README 和使用说明 ## 故障排除 ### 小部件未出现在管理中 **症状：** 小部件未显示在“插入小部件”下拉列表中 **解决方案：** 1.检查 `widget.xml` 语法（验证 XML） 2. 验证模块已启用：`bin/magento module:status` 3.清除缓存：`bin/magento缓存：flush` 4.清除生成的代码：`rm -rf generated/code/*` 5.检查文件权限 6. 检查“system.log”是否有错误 ### 小部件未在前端呈现 **症状：** 小部件代码显示但没有输出 **解决方案：** 1. 验证块类中的模板路径 2.检查指定路径下是否存在模板文件 3.清除缓存：`bin/magento缓存：flush` 4. 检查模板中的 PHP 错误 5. 查看`exception.log`和`system.log` 6.启用开发者模式查看详细错误 ### JavaScript 未加载 **症状：** 小部件功能不起作用 **解决方案：** 1.验证`requirejs-config.js`语法 2.检查JS文件路径是否正确 3.清除静态内容： `bin/magento setup:static-content:deploy -f` 4. 检查浏览器控制台是否有 404 错误 5. 验证文件权限 6. 在控制台中检查 JavaScript 错误 7. 确保 jQuery 和依赖项已加载 ### 未应用 CSS 样式 **症状：** 小部件显示无样式 **解决方案：** 1. 验证`layout/default.xml`中的CSS路径 2.检查CSS文件是否存在 3. 部署静态内容： `bin/magento setup:static-content:deploy -f` 4.清除浏览器缓存 5. 在网络选项卡中检查 CSS 文件 404 6. 验证 CSS 选择器的特异性 7. 检查冲突的样式 ### 表单提交失败 **症状：** AJAX 返回错误或无响应 **解决方案：** 1.检查控制器路由配置 2.验证控制器实现了正确的接口 3. 如果使用 POST，请向表单添加表单键 4. 检查网络选项卡以获取实际的错误响应 5. 查看“exception.log”以了解服务器错误 6.验证AJAX URL是否正确 7. 检查请求/响应格式（JSON） 8. 确保正确的内容类型标题 ### 文件上传问题 **症状：** 文件未上传或验证失败 **解决方案：** 1. 检查 PHP `upload_max_filesize` 和 `post_max_size` 2. 验证文件输入是否有 `enctype="multipart/form-data"` 3.检查上传目录的文件权限 4. 服务器端验证文件 mime 类型 5. 检查 JavaScript 文件验证逻辑 6. 检查文件大小限制（客户端和服务器） 7. 检查控制器中的`$_FILES`数组 ### 模态弹出问题 **症状：** 模态框是半隐藏的，被困在部分/div内，有z索引问题，双重覆盖或定位问题 **根本原因：** 1. Magento 的 `Magento_Ui/js/modal/modal` 组件和自定义模态 HTML 结构之间的冲突 2. 模态元素受父容器约束（溢出、位置、z-index） **解决方案：** 1. **关键：将模态移动到主体** \- 在小部件初始化中添加 `modalElement.appendTo('body')` 以转义父容器 2. **当您已经拥有带有覆盖层和内容 div 的自定义模态 HTML 时，**不要使用 Magento 的模态组件** 3. 使用简单的 jQuery `fadeIn()`/`fadeOut()` 而不是 `modal('openModal')` 4. 在模态容器上使用 !important** 设置 **非常高的 z-index (999999)（主题通常使用 10000+ 作为标题/菜单） 5. 在覆盖层和内容上使用“position:fixed”（不是绝对的） 6. 使用较暗的叠加背景 `rgba(0, 0, 0, 0.7)` 来清晰地遮挡内容 7. 添加`body.modal-open {溢出：隐藏； }` 防止背景滚动 8. 将 `pointer-events: auto` 添加到模态和子项以阻止点击 9.更改后清除静态内容：`rm -rf pub/static/frontend/*` 10.清除浏览器缓存并在隐身模式下测试 11. 使用浏览器 DevTools 检查竞争元素以查找其 z-index 值 **修复示例：** // 错误 - 导致冲突定义（['jquery'，'Magento_Ui/js/modal/modal']，函数（$，模态）{ modalElement.modal({ ... }); }); // 正确 - 简单且有效定义（['jquery']，函数（$）{ modalElement.fadeIn(300); $('body').addClass('modal-open'); }); ## 测试清单在部署您的小部件之前： ### 功能测试 * 小部件出现在管理“插入小部件”下拉列表中 * 所有参数在管理中正确显示 * 小部件在前端呈现 * 所有参数变化都能正常工作 * 表格提交工作（如果适用） * 验证适用于客户端和服务器端 * 正确显示成功/错误消息 * 电子邮件发送有效（如果适用） ### 浏览器/设备测试 * Chrome（最新） * 火狐浏览器（最新） * Safari（最新） * 边缘（最新） * 移动iOS * 安卓手机 * 平板电脑 ### 性能测试 * 页面加载时间可接受 * 控制台中没有 JavaScript 错误 * CSS与主题不冲突 * 缓存工作正常 * AJAX请求快速完成 ### 安全测试 * 所有输出均正确转义 * SQL注入预防 * XSS预防 * CSRF保护 * 文件上传验证 * 输入验证/清理 ### 辅助功能测试 * 键盘导航有效 * 屏幕阅读器友好 * 正确的 ARIA 标签 * 焦点指示器可见 * 色彩对比足够 ## 参考：ItTools 模块示例此代码库中的真实工作示例： 1. **ItTools_QuoteForm** (`app/code/ItTools/QuoteForm/`) * 模态弹出窗口小部件 * 带有文件上传的表单 * 电子邮件功能 * AJAX提交 2. **ItTools_CategorySearch** (`app/code/ItTools/CategorySearch/`) * 简单的搜索小部件 * 扩展现有功能 * 自定义占位符文本参数使用这些作为参考实现。 ## 其他资源 ### Magento 开发文档 * [小部件开发]() * [JavaScript 组件]() * [模板]() ### 代码示例 * Magento 核心小部件：`vendor/magento/module-widget/` * Magento CMS 小部件：`vendor/magento/module-cms/Block/Widget/` * 目录小部件：`vendor/magento/module-catalog/Block/Widget/` ## 版本兼容性该技能兼容： * Magento 开源 2.3.x - 2.4.x * Adobe 商务 2.3.x - 2.4.x * Mage-OS（Magento 分支）不兼容： * Hyvä 主题（使用 hyva-tailwind-integration 技能代替） * Magento 1.x

escapeHtml(__('小部件标题')) ?>

escapeHtml(__('模态标题')) ?>

Magento2 小部件创建

包含技能