一、方案介绍

在 WordPress 产品详情页开发过程中,经常需要为不同产品配置独立的配件展示内容。如果直接在页面模板中编写固定 HTML,不仅后期维护不方便,也难以满足不同产品之间的内容差异化需求。

本方案通过 WordPress ACF(Advanced Custom Fields)插件 创建独立的 Group 自定义字段组,在产品后台提供多个 WYSIWYG 富文本编辑器,用于维护不同配件卡片的图片、标题、描述及图片跳转链接。

前端则通过自定义 Shortcode(短代码)读取当前产品对应的 ACF 字段数据,并按照预设的 UI 设计方案动态生成配件展示模块。

整个方案将后台内容管理与前端布局渲染分离,实现产品配件模块的独立维护和复用。

核心实现思路

功能模块 实现方式
后台字段管理 ACF Group 自定义字段组
配件内容编辑 多个 WYSIWYG 富文本编辑器
数据读取 WordPress get_field()
前端调用 自定义 Shortcode
页面结构 PHP 动态生成 HTML
样式控制 独立 CSS 样式前缀
响应式布局 PC 双列、移动端单列

前端布局效果

PC 端采用两列卡片布局,每张卡片内部采用图片左侧、文字右侧的横向结构。

移动端自动切换为单列布局,图片位于文字上方,卡片宽度自适应屏幕。

卡片支持鼠标悬浮边框高亮效果,图片可以单独配置跳转链接。

二、前置准备工作

开始部署前,需要确保具备以下条件:

  1. WordPress 网站已经安装并启用 Advanced Custom Fields(ACF)插件。
  2. 可以访问网站服务器文件,或者使用主题后台文件管理器。
  3. 建议使用子主题部署所有 PHP 代码,避免主题更新时造成代码丢失。
  4. 已经明确产品文章类型及配件模块的前端设计方案。

三、ACF 后台自定义字段配置

本方案通过一个 Group 字段组统一管理产品配件内容,内部配置四个 WYSIWYG 富文本编辑器,每个编辑器对应一张配件卡片。

3.1 创建 ACF 字段组

进入 WordPress 后台:

ACF → 字段组 → 新建字段组

字段组名称设置为:

1
lier_essential_accessories

3.2 设置字段组显示规则

在字段组的位置规则中,将显示条件设置为需要使用该模块的产品文章类型。

例如:

  • 文章类型:Product
  • 规则:文章类型等于 Product

这样在编辑对应产品时,后台就会自动显示配件模块的字段配置区域。

3.3 创建 Group 字段

在字段组中新增一个字段:

配置项目 设置内容
字段标签 Essential Accessories
字段类型 Group
字段名称 lier_essential_accessories

3.4 创建四个富文本子字段

进入 Group 字段内部,依次创建以下四个子字段。

字段标签 字段名称 字段类型
配件卡片一 lier_essential_accessories_card_one WYSIWYG Editor
配件卡片二 lier_essential_accessories_card_two WYSIWYG Editor
配件卡片三 lier_essential_accessories_card_three WYSIWYG Editor
配件卡片四 lier_essential_accessories_card_four WYSIWYG Editor

四个字段的类型全部选择 WYSIWYG Editor(所见即所得富文本编辑器)。

完成配置后保存字段组。

此时进入产品编辑页面,就可以在后台看到四个独立的富文本编辑区域。

3.5 后台内容填写方式

每个富文本编辑器对应一张前端配件卡片。

建议按照以下顺序填写:

  1. 插入配件图片。
  2. 根据需要为图片添加跳转链接。
  3. 在图片后面输入配件标题。
  4. 输入配件描述内容。

每个富文本框独立维护一张卡片,不需要展示的卡片直接留空即可。

四、PHP 短代码功能开发与部署

ACF 字段配置完成后,接下来需要通过 PHP 编写自定义短代码,实现字段数据读取及前端模块渲染。

4.1 创建 PHP 文件

进入 WordPress 子主题目录,新建一个 PHP 文件:

1
essential-accessories-for-this-machine-shortcode.php

将以下代码完整复制到文件中并保存。

4.2 PHP 完整实现代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
<?php
/**
* 短码名称:essential_accessories_for_this_machine
* 文件名称:essential-accessories-for-this-machine-shortcode.php
* 引入方式:require_once get_stylesheet_directory() . '/essential-accessories-for-this-machine-shortcode.php';
* ACF配置说明:
* 字段组name:lier_essential_accessories
* 字段类型:Group
* 子字段(4个WYSIWYG Editor)
* 1. lier_essential_accessories_card_one
* 2. lier_essential_accessories_card_two
* 3. lier_essential_accessories_card_three
* 4. lier_essential_accessories_card_four
* ----------------------------------------------------------------
* 短码参数列表:
* title 主标题,默认:Complete your setup
* subtitle 副标题,默认:Essential accessories for this machine.
* layout 标题栏布局,可选:top-bottom / left-right,默认 left-right
* post_id 指定文章ID,默认当前文章ID
* ----------------------------------------------------------------
* 使用示例:
* 基础调用:[essential_accessories_for_this_machine]
* 自定义标题+副标题:[essential_accessories_for_this_machine title="Complete your setup" subtitle="Essential accessories for this machine."]
* 标题上下布局:[essential_accessories_for_this_machine layout="top-bottom"]
* 指定文章ID:[essential_accessories_for_this_machine post_id="123"]
* ----------------------------------------------------------------
* 前端布局规则:
* PC端:固定2列卡片,移动端:1列卡片
* 卡片内标题字号 clamp(16px,2vw,18px)
* 卡片内描述字号 clamp(14px,2vw,16px)
* 鼠标悬浮卡片边框高亮 #2268a0,对标参考效果图
* 前缀隔离:lier_accessiories_dus_ ,防止样式、函数冲突
*/
if ( ! defined( 'ABSPATH' ) ) exit;

add_shortcode( 'essential_accessories_for_this_machine', 'lier_accessiories_dus_render_shortcode' );
function lier_accessiories_dus_render_shortcode( $atts ) {
$atts = shortcode_atts( [
'title' => 'Complete your setup',
'subtitle' => 'Essential accessories for this machine.',
'layout' => 'left-right',
'post_id' => get_the_ID(),
], $atts, 'essential_accessories_for_this_machine' );

$group_data = get_field( 'lier_essential_accessories', $atts['post_id'] );
$card_keys = [
'lier_essential_accessories_card_one',
'lier_essential_accessories_card_two',
'lier_essential_accessories_card_three',
'lier_essential_accessories_card_four'
];
$card_list = [];
foreach ( $card_keys as $ck ) {
if ( ! empty( $group_data[ $ck ] ) ) {
$card_list[] = $group_data[ $ck ];
}
}
if ( empty( $card_list ) ) return '';
$header_class = $atts['layout'] === 'top-bottom' ? 'lier_accessiories_dus_header_tb' : 'lier_accessiories_dus_header_lr';
ob_start();
?>
<style>
.lier_accessiories_dus_container{width:100%;max-width:100%;margin:60px auto;box-sizing:border-box;padding:0 20px !important;}
.lier_accessiories_dus_header{display:flex;align-items:baseline;justify-content:space-between;gap:24px;margin-top:0 !important;margin-bottom:25px !important;padding-bottom:16px;border-bottom:1px solid #e5e7eb57;}
.lier_accessiories_dus_header.lier_accessiories_dus_header_tb{flex-direction:column;align-items:flex-start;}
.lier_accessiories_dus_header.lier_accessiories_dus_header_lr{flex-direction:row;align-items:baseline;}
.lier_accessiories_dus_header h2{font-size: clamp(28px, 3vw, 42px) !important;font-weight:700;margin:0;color:#1a2b48;line-height:1.2;}
.lier_accessiories_dus_header .lier_accessiories_dus_subtitle{font-size:18px;color:#64748b;margin:0;line-height:1.4;}
.lier_accessiories_dus_grid{display:grid;grid-template-columns:repeat(2,1fr);gap:24px;}
.lier_accessiories_dus_card{display:flex;align-items:center;gap:20px;background:#ffffff;border:1px solid #e2e8f094;border-radius:16px;padding:10px !important;transition:all 0.24s ease;overflow:hidden;}
.lier_accessiories_dus_card:hover{border-color:#39a1fe !important;box-shadow:0 0 0 0 rgba(34,104,160,0.08);}
.lier_accessiories_dus_imgbox{flex:0 0 120px;width:120px;height:120px;border-radius:12px;overflow:hidden;}
.lier_accessiories_dus_imgbox img{width:100%;height:100%;object-fit:cover;display:block;}
.lier_accessiories_dus_textbox{flex:1;min-width:0;}
.lier_accessiories_dus_textbox h3{font-size:clamp(16px,2vw,18px);font-weight:700;color:#1a2b48;margin:0 0 8px;line-height:1.3;}
.lier_accessiories_dus_textbox p{font-size:clamp(14px,2vw,16px);color:#475569;margin:0;line-height:1.6;}
.lier_accessiories_dus_textbox a{color:inherit;text-decoration:none;}
.lier_accessiories_dus_textbox a:hover{color: #39a1fe;}
.lier_sf_related_text h4{margin-top: 0px !important;margin-bottom: 15px !important}
@media(max-width:768px){
.lier_accessiories_dus_container{padding:0 0 !important;}
.lier_accessiories_dus_grid{grid-template-columns:1fr;}
.lier_accessiories_dus_card{flex-direction:column;text-align:center;}
.lier_accessiories_dus_imgbox{flex:0 0 auto;width:100%;max-width:100%;height:auto;}
.lier_accessiories_dus_header{display: block !important}
.lier_accessiories_dus_header h2{margin-bottom: 15px !important}
.lier_sf_related_text h4{text-align: left !important;}
.lier_accessiories_dus_textbox p {text-align: left !important;}
.lier_accessiories_dus_container{
margin: 60px auto 0px auto !important;
}
}
</style>
<div class="lier_accessiories_dus_container">
<div class="lier_accessiories_dus_header <?php echo esc_attr($header_class); ?>">
<h2><?php echo esc_html($atts['title']); ?></h2>
<p class="lier_accessiories_dus_subtitle"><?php echo esc_html($atts['subtitle']); ?></p>
</div>
<div class="lier_accessiories_dus_grid">
<?php foreach($card_list as $card_html):
$img_src = '';
$link_href = '';
$content_html = $card_html;
if(preg_match('/<a href="([^"]+)"[^>]*>.*?<img[^>]*src="([^"]+)"/is',$card_html,$match)){
$link_href = $match[1];
$img_src = $match[2];
$content_html = preg_replace('/<a href="[^"]+"[^>]*>.*?<\/a>/is','',$content_html,1);
}elseif(preg_match('/<img[^>]*src="([^"]+)"/is',$card_html,$match)){
$img_src = $match[1];
$content_html = preg_replace('/<img[^>]*>/is','',$content_html,1);
}
?>
<div class="lier_accessiories_dus_card">
<?php if($img_src): ?>
<div class="lier_accessiories_dus_imgbox">
<?php if($link_href): ?>
<a href="<?php echo esc_url($link_href); ?>">
<img src="<?php echo esc_url($img_src); ?>" alt="">
</a>
<?php else: ?>
<img src="<?php echo esc_url($img_src); ?>" alt="">
<?php endif; ?>
</div>
<?php endif; ?>
<div class="lier_accessiories_dus_textbox">
<?php echo $content_html; ?>
</div>
</div>
<?php endforeach; ?>
</div>
</div>
<script>
(function(){
var lierAccessioriesDusCards = document.querySelectorAll('.lier_accessiories_dus_card');
lierAccessioriesDusCards.forEach(function(el){
el.addEventListener('mouseenter',function(){
this.style.borderColor = '';
});
el.addEventListener('mouseleave',function(){
this.style.borderColor = '';
});
})
})();
</script>
<?php
return ob_get_clean();
}

4.3 在 functions.php 中引入文件

打开子主题目录下的 functions.php 文件,在文件末尾添加:

1
require_once get_stylesheet_directory() . '/essential-accessories-for-this-machine-shortcode.php';

保存文件后,PHP 短代码功能部署完成。

注意:如果文件已经被引入过,不需要重复添加。

五、前端短代码调用方法

完成 PHP 文件部署后,即可在 WordPress 文章编辑器、产品详情页或支持短代码的页面构建器中调用。

5.1 基础调用

1
[essential_accessories_for_this_machine]

默认显示:

  • 主标题:Complete your setup
  • 副标题:Essential accessories for this machine.
  • 标题布局:左右排列

5.2 自定义主标题和副标题

如果需要根据不同产品调整模块标题,可以直接传入参数:

1
[essential_accessories_for_this_machine title="Complete your setup" subtitle="Essential accessories for this machine."]

5.3 修改标题排版方式

默认标题和副标题采用左右排列。

如果希望主标题与副标题上下排列,可以使用:

1
[essential_accessories_for_this_machine layout="top-bottom"]

支持两种布局:

  • left-right:标题与副标题左右排列。
  • top-bottom:标题与副标题上下排列。

5.4 指定其他文章 ID

默认情况下,短代码会读取当前页面对应的产品 ACF 数据。

如果需要调用其他产品的配件内容,可以指定文章 ID:

1
[essential_accessories_for_this_machine post_id="123"]

将 123 替换为需要读取的产品文章 ID 即可。

六、后台产品配件内容填写规范

短代码部署完成后,进入需要配置配件模块的产品编辑页面。

找到 ACF 创建的四个富文本编辑器,按照以下规范填写内容。

6.1 配件图片配置

在富文本编辑器中插入图片。

建议使用正方形图片素材,以便卡片在不同屏幕尺寸下保持良好的视觉效果。

如果需要让图片支持点击跳转,可以在 WordPress 富文本编辑器中为图片添加超链接。

6.2 配件标题和描述

图片后面依次填写配件名称及相关描述。

例如:

Ice Storage Bin

Designed for efficient ice storage and convenient daily operation.

实际内容根据产品配件类型进行调整。

6.3 空白卡片处理

如果当前产品只有两种配件,只需要填写前两个富文本编辑器即可。

剩余编辑器保持空白,前端会自动跳过未填写的字段,不会生成空白卡片。

七、前端样式与布局说明

本方案通过独立 CSS 类名前缀控制配件模块样式,减少与 WordPress 主题及其他页面组件之间的样式冲突。

7.1 PC 端双列布局

PC 端采用 CSS Grid 实现两列卡片排列。

每张卡片内部采用 Flex 布局:

  • 左侧展示配件图片。
  • 右侧展示配件标题和描述。
  • 卡片之间保持 24px 间距。
  • 卡片圆角设置为 16px。
  • 默认边框颜色为 #e2e8f0。

7.2 移动端单列布局

当浏览器视口宽度小于等于 768px 时,自动切换为单列布局。

具体变化:

  • 卡片由横向布局切换为纵向布局。
  • 图片移动到文字上方。
  • 图片宽度调整为容器宽度。
  • 卡片文字居中显示。
  • 模块容器取消左右内边距。

7.3 卡片悬浮交互

鼠标悬浮卡片时,边框颜色切换为:

1
#2268a0

鼠标离开后恢复默认边框颜色。

7.4 字体自适应

卡片标题使用:

1
font-size: clamp(16px, 2vw, 18px);

卡片描述使用:

1
font-size: clamp(14px, 2vw, 16px);

主标题使用:

1
font-size: clamp(28px, 3vw, 42px);

通过 CSS clamp() 实现不同屏幕尺寸下的字体自适应。

八、前端效果验收标准

完成部署后,建议按照以下标准进行检查。

验收项目 预期效果
PC 端布局 两列卡片并排展示
卡片内部结构 图片左侧,文字右侧
移动端布局 自动切换为单列
移动端图片 图片位于文字上方
悬浮交互 边框变为 #2268a0
标题区域 下方间距为 15px
字体大小 根据屏幕宽度自适应
图片跳转 点击图片跳转至设置的链接
空字段处理 未填写的卡片不进行渲染
产品数据 根据当前产品读取对应内容

九、常见问题排查

9.1 配件模块不显示

检查以下内容:

  1. ACF 字段组是否已经启用。
  2. Group 字段名称是否为 lier_essential_accessories。
  3. 四个子字段名称是否与 PHP 代码一致。
  4. 当前产品是否已经填写富文本内容。
  5. 短代码 PHP 文件是否成功引入。

9.2 前端样式错乱

检查主题是否存在全局 CSS 样式覆盖。

本方案使用独立类名前缀 lier_accessiories_dus_,可以降低与其他组件之间的样式冲突。

9.3 配件图片不显示

重点检查:

  1. 图片地址是否有效。
  2. 图片是否成功插入富文本编辑器。
  3. 图片是否按照要求放置在富文本内容前面。
  4. 图片 HTML 是否符合当前 PHP 正则表达式的匹配格式。

9.4 移动端布局异常

检查媒体查询是否正常生效。

如果网站使用了页面缓存、CSS 压缩或 CDN,建议清除相关缓存后重新测试。

十、后期维护与样式修改

后期如果需要调整配件模块的视觉效果,可以直接修改 PHP 文件中的 CSS 样式。

常见调整位置如下:

修改需求 对应 CSS 选择器或属性
修改悬浮边框颜色 .lier_accessiories_dus_card:hover
修改卡片内边距 .lier_accessiories_dus_card
修改容器最大宽度 .lier_accessiories_dus_container
修改主标题字号 .lier_accessiories_dus_header h2
修改副标题字号 .lier_accessiories_dus_subtitle
修改卡片标题字号 .lier_accessiories_dus_textbox h3
修改卡片描述字号 .lier_accessiories_dus_textbox p
修改卡片间距 .lier_accessiories_dus_grid
修改移动端断点 @media (max-width: 768px)

如果需要修改悬浮边框颜色,建议同步检查 CSS 和 JavaScript 中的颜色设置,避免两处样式不一致。

十一、方案总结

通过 WordPress ACF 自定义字段组与 PHP Shortcode 相结合,可以实现产品配件模块的独立内容管理和前端动态渲染。

整个方案不需要为每个产品单独编写 HTML,也不需要重复修改页面模板。

后台只负责维护产品配件内容,前端短代码负责读取数据并按照统一的设计规范输出页面结构。

本方案的主要优势:

  1. 内容管理独立化:每个产品拥有独立的配件内容配置区域。
  2. 前端组件化:通过短代码即可在不同页面位置调用配件模块。
  3. 布局统一化:所有产品共享同一套前端结构和样式。
  4. 内容维护便捷化:运营人员可以直接通过后台富文本编辑器维护配件图片、标题及描述。
  5. 后期扩展灵活化:可以根据实际需求增加配件卡片数量、调整布局方式或扩展短代码参数。

整体实现了从 ACF 后台内容录入、PHP 数据读取到前端模块动态渲染的完整流程,适用于工业设备、制冰机、机械设备及其他具有配件展示需求的 WordPress 产品详情页。

另外提醒两个原代码中的技术细节,正式上线前建议修正:

  1. 当前 PHP 使用正则表达式解析富文本 HTML,对图片外层存在额外属性、HTML 格式变化等情况可能不够健壮。后期建议改用 DOMDocument 解析 HTML。
  2. 当前移动端图片容器设置了 height: auto,但图片本身仍然设置 height: 100%,可能导致图片高度异常。建议移动端将图片设置为 height: auto,并使用 aspect-ratio 控制图片比例。

这两个问题不影响文章的整体结构,但会影响实际部署后的兼容性和稳定性。