Blocksy主题进阶：高级Hook注入与条件内容显示

🪐前言

Blocksy 免费版已经很强了——Header/Footer Builder、暗黑模式、WooCommerce 深度集成都是标配。但做内容站和复杂电商站时，你会卡在一个瓶颈：怎么在免费版里实现需要 Pro 才能做到的条件内容显示？怎么在不破坏主题结构的情况下注入自定义代码？

这篇文章的核心就是这两个问题。我们会用 Code Snippets 插件配合 Blocksy 的 Hook 系统实现可视化注入，教 Content Blocks 如何按用户角色、设备类型、页面模板来条件显示，再用 ACF 和 Meta Box 做动态数据渲染，最后单独讲 WooCommerce 页面的定制 Hook。

一、Code Snippets + Hook 可视化注入实战

Blocksy 在 Customizer 里提供了一个隐藏很深但极其有用的功能——Content Blocks。配合它的 Hooks 定位能力，你不用写一行代码就能把自定义内容注入到页面的任意位置。

🧩 理解 Content Blocks 的运行机制

Content Blocks 是 Blocksy 的一个独立内容类型（Custom Post Type），路径：后台导航 → Content Blocks → Add New。

每个 Content Block 有三个关键决策：

内容来源：自己写（Gutenberg 编辑） / 引用已有的 Hook / 引用模板
挂载位置：Hook 名称，决定内容出现在页面的哪个位置
显示条件：什么时候显示、在哪个页面上显示、对谁显示

Content Blocks 的运作流程：

创建一个 Content Block
  → 用 Gutenberg/Gutenberg 写内容（或引用模板）
    → 在 Hook 字段填入挂载位置（如 blocksy:head:start）
      → 设置 Display Conditions（如 "Only on Products" / "Only for Logged-In Users"）
        → 保存 → 页面自动生效

🔌 常用 Hook 位置清单

Blocksy 暴露了大量 Action Hook，下面是最高频用到的 12 个，按页面位置分类：

页面位置	Hook 名称	典型用途
`<head>` 开头	`blocksy:head:start`	插入第三方跟踪代码（Google Analytics、Hotjar）
`<head>` 结尾	`blocksy:head:end`	结构化数据 JSON-LD、自定义 meta 标签
`<body>` 开头	`blocksy:body:start`	全站公告栏、紧急通知条
Header 之前	`blocksy:header:before`	顶部促销横幅
Header 之后	`blocksy:header:after`	面包屑导航（全局）
Content 之前	`blocksy:content:before`	页面标题覆盖、Hero 区域
Content 之后	`blocksy:content:after`	相关文章推荐、CTA 横幅
Footer 之前	`blocksy:footer:before`	订阅表单（全局）
Footer 之后	`blocksy:footer:after`	Schema 结构化数据、Back to Top 按钮
文章内容之前	`blocksy:single:content:before`	文章顶部作者信息、更新日期提醒
文章内容之后	`blocksy:single:content:after`	作者简介卡片、相关文章
WooCommerce 产品页 Loop	`blocksy:woocommerce:after-loop`	分类页底部 SEO 文字

💻 实操：用 Content Block 注入全局公告栏

场景：你的外贸站在春节期间需要显示一条全站公告"Holiday notice: Orders placed between Jan 25 - Feb 5 will ship on Feb 6"。

步骤：

Content Blocks → Add New → 标题写 Global Notice Bar
内容区域用 Gutenberg 写公告内容。建议用 Group 块 + 背景色，让公告醒目但不刺眼
Hook 位置选 blocksy:body:start
Display Conditions → 选 Whole Website（全站显示）
保存。公告条会立即出现在所有页面顶部，紧接 <body> 标签之后

⚠️ 如果你启用了服务器缓存（如 SiteGround Optimizer），保存 Content Block 后记得清一下缓存，否则你可能看不到变化，然后怀疑自己的配置有问题——这个坑我踩过不止一次。

🔧 用 Code Snippets 插件做更精细的 Hook 注入

Content Blocks 适合静态内容的注入，但如果涉及 PHP 逻辑（比如查询数据库、判断当前用户状态后动态输出），必须用代码方式。推荐用 Code Snippets 插件管理所有自定义代码片段，而不是往 functions.php 里堆——后者一旦出错会导致整个网站白屏，Code Snippets 则会在语法错误时自动停用片段。

示例：在文章标题下方动态显示"本文最后更新于 X 天前"：

// Code Snippets → Add New → 命名为 "Display Last Updated Below Post Title"
// Hook 选择 blocksy:single:content:before
add_action('blocksy:single:content:before', function () {
    if (!is_single() || 'post' !== get_post_type()) {
        return; // 只在文章页执行
    }

    $updated_time = get_the_modified_time('U');
    $current_time = current_time('timestamp');
    $days_ago = floor(($current_time - $updated_time) / DAY_IN_SECONDS);

    if ($days_ago > 30) {
        echo '<div class="update-notice" style="
            background: #fff3cd;
            padding: 12px 20px;
            border-radius: 6px;
            border-left: 4px solid #ffc107;
            margin-bottom: 20px;
            font-size: 14px;
        ">⚠️ This article was last updated ' . $days_ago . ' days ago. Some information may be outdated.</div>';
    }
}, 10);

Code Snippets 执行 Hook 时不需要在 Blocksy 的 Content Blocks 里手动填 Hook 名称——直接在代码里通过 add_action() 绑定即可，更灵活也更稳定。

二、Content Blocks 按条件显示

条件显示（Display Conditions）是 Content Blocks 真正的杀手功能。它让你精确控制内容对谁、在哪里、什么时候显示。

👥 按用户角色显示

场景：你是 B2B 站，想对已登录的经销商（Dealer 角色）显示专属批发价入口，对未登录用户不显示。

Content Blocks → Display Conditions → 添加条件：

Include Condition:
  User Role → is → Wholesale Customer（或 Dealer 角色名）

或者更简单的二选一：
  User Login Status → is → Logged In

如果你的站用的是 WooCommerce 默认角色（Customer / Shop Manager / Administrator），Condition 里直接选即可。如果是自定义角色（比如用 Members 插件创建的），Blocksy 也能自动识别并显示在下拉列表里。

📱 按设备类型显示

场景：移动端的 Header 空间有限，想把桌面端 Footer 里的一张合作品牌 Logo 墙挪到移动端的独立页面上显示。

Content Blocks → Display Conditions → 添加条件：

Include Condition:
  Device Visibility → is → Mobile

Blocksy 支持的设备粒度：

Desktop — 屏幕宽度 > 992px
Tablet — 768px ~ 991px
Mobile — < 768px
Tablet + Mobile 组合 — 小于 991px 的所有设备

💡 这个功能比 CSS 的 @media display:none 好太多——用 Display Conditions 控制时，内容在不需要的设备上根本不会渲染到 DOM 里，CSS 的方案虽然隐藏了，但 HTML 仍然加载了，浪费带宽。

📄 按页面类型显示

这是 B2B 和 B2C 站都会高频用到的条件。一些常见的组合：

场景 1：只在产品分类页底部放 SEO 文字

Include Condition:
  Page Type → is → Product Category Archive

场景 2：只在特定产品的详情页放售后说明

Include Condition:
  Page Type → is → Single Product
  AND
  Specific Product → is → Product-A（选择具体产品）

场景 3：排除购物车和结账页（全局 CTA 不显示在这些页面上）

Include Condition:
  Whole Website → is → All
  AND
  Exclude Condition:
    Page Type → is → Cart Page
    Page Type → is → Checkout Page

🎯 多条件叠加逻辑

Content Blocks 的 Display Conditions 支持 AND / OR 逻辑组合：

条件组 1（AND 关系）：
  ✓ Page Type is Single Post
  ✓ Post has Category "tutorial"
条件组 2（OR 关系）：
  ✓ Page Type is Page
  ✓ Specific Page is "About Us"

最终逻辑：当页面是分类为 tutorial 的文章或页面是 About Us 时，Content Block 显示。

三、动态数据渲染（ACF / Meta Box）

如果你的 Blocksy 站用了 ACF（Advanced Custom Fields）或 Meta Box 添加了自定义字段，需要把字段值渲染到前端页面——Content Blocks 做不到这件事，因为它本质上是静态内容。

这时需要走 Code Snippets 的 add_action() 路线。

🗂️ ACF 字段渲染示例

场景：你在 B2B 产品页上通过 ACF 添加了自定义字段：证书编号（cert_number）、工厂地址（factory_address）、最小起订量（moq）。需要在产品描述下方以表格形式展示这些数据。

// Code Snippets：Render ACF custom fields on WooCommerce product page
// Hook：blocksy:single:content:after（用 add_action，不在 Content Block UI 里填）
add_action('blocksy:single:content:after', function () {
    // 只在 WooCommerce 产品页执行
    if (!function_exists('is_product') || !is_product()) {
        return;
    }

    // 从 ACF 获取字段值
    $cert_number = get_field('cert_number');
    $factory_address = get_field('factory_address');
    $moq = get_field('moq');

    // 如果所有字段都没有值，不渲染
    if (!$cert_number && !$factory_address && !$moq) {
        return;
    }

    // 输出自定义字段表格
    echo '<div class="product-custom-fields" style="
        margin-top: 30px;
        padding: 24px;
        background: #f8f9fa;
        border-radius: 8px;
    ">';
    echo '<h3 style="margin-top: 0;">Factory Information</h3>';
    echo '<table style="width: 100%; border-collapse: collapse;">';

    if ($cert_number) {
        echo '<tr><td style="padding: 8px 0; color: #666; width: 180px;">Certificate Number</td>
              <td><strong>' . esc_html($cert_number) . '</strong></td></tr>';
    }
    if ($factory_address) {
        echo '<tr><td style="padding: 8px 0; color: #666;">Factory Address</td>
              <td><strong>' . esc_html($factory_address) . '</strong></td></tr>';
    }
    if ($moq) {
        echo '<tr><td style="padding: 8px 0; color: #666;">MOQ</td>
              <td><strong>' . esc_html($moq) . '</strong></td></tr>';
    }

    echo '</table></div>';
}, 20);

📦 Meta Box 字段渲染

如果你的自定义字段是用 Meta Box 创建的，获取字段的函数略有不同，但注入逻辑完全一样：

// Meta Box 获取字段使用 rwmb_meta()
$product_spec = rwmb_meta('product_specifications');
// 渲染逻辑同上，仅字段获取函数不同

🔄 动态数据渲染的最佳实践

先判空再渲染：永远用 if (!$field_value) 检查字段是否有值。空字段渲染出一行空白的 tr 会让页面看起来很粗糙
用 esc_html() 做安全输出：防止自定义字段里被意外插入脚本标签。除非字段内容是 HTML（如 ACF 的 WYSIWYG 字段），这种情况下用 wp_kses_post()
优先级（priority）设 20+：让自定义内容在 Blocksy 默认的 WooCommerce 内容之后渲染。优先级 10 是 WordPress 默认值，Blocksy 的大部分 hook 操作也在这个优先级，设 20 可以确保自定义内容在默认内容之后显示

四、WooCommerce 页面定制

Blocksy 对 WooCommerce 的底层支持做得不错，但仍然有一些高频定制需求需要用到 Content Blocks 或 Code Snippets。

🛒 在产品页描述下方插入售后保障说明

这是转化率优化最重要的一个位置——在产品添加购物车按钮下方放一段售后保障说明（退货政策、保修、发货时间），能显著降低用户下单犹豫。

// Code Snippets：在 WooCommerce 产品页标题下方插入售后Trust Badge
add_action('woocommerce_single_product_summary', function () {
    echo '<div class="trust-badges" style="
        display: flex;
        gap: 16px;
        align-items: center;
        margin: 12px 0 20px;
        padding: 16px;
        background: #f0fdf4;
        border-radius: 8px;
        font-size: 13px;
        color: #166534;
    ">
        <span>✓ Free Shipping over $99</span>
        <span>✓ 30-Day Returns</span>
        <span>✓ Secure Checkout</span>
    </div>';
}, 25);

注意这里用的是 WooCommerce 原生的 woocommerce_single_product_summary Hook，而不是 Blocksy 的 Hook。WooCommerce 页面建议优先用 WooCommerce 自身的 Action Hook——它们不受主题切换影响，换主题后自定义仍然生效。

🏷️ 在产品分类页列表顶部插入自定义 SEO 描述

很多外贸站需要在产品分类页的顶部放一段文字——既是给用户看的当前分类说明，也是给 Google 看的 SEO 内容。

用 Content Blocks 实现：Hook 位置选 blocksy:woocommerce:before-loop，Display Condition 选 Product Category Archive。如果每个分类内容不同，需要创建多个 Content Block，分别设置 Specific Product Category。

📋 购物车页面添加交叉销售推荐

WooCommerce 默认的交叉销售（Cross-Sells）位置是购物车页面的底部，不够显眼。用 Blocksy 的 Hook 把它提到购物车商品列表上方：

add_action('blocksy:woocommerce:cart:before', function () {
    if (function_exists('woocommerce_cross_sell_display')) {
        woocommerce_cross_sell_display(4, 4); // 显示 4 列 × 4 个产品
    }
}, 10);

总结

Blocksy 的 Content Blocks + Hooks 系统，本质上是把 WordPress 的 add_action / add_filter 机制做成了一个可视化界面。这让非开发者也能做 80% 的内容注入需求，同时开发者仍然可以通过 Code Snippets 实现剩余 20% 的复杂逻辑。

完整配置检查单：

[ ] 理解 Content Blocks 的三个要素：内容来源、Hook 挂载位置、Display Conditions
[ ] 已掌握至少 6 个常用 Hook 位置（head / header / content / footer / single / WooCommerce）
[ ] Code Snippets 插件已安装，所有自定义 PHP 代码通过 Code Snippets 管理（不进 functions.php）
[ ] 需要按条件显示的 Content Block 已设置正确的 Display Conditions（用户角色 / 设备 / 页面类型）
[ ] ACF 或 Meta Box 字段值已通过 add_action() + Hook 渲染到前端
[ ] 所有自定义代码做了判空检查和 esc_html() 安全输出
[ ] WooCommerce 自定义优先使用 WooCommerce 原生 Hook（而非主题 Hook）以保证可移植性
[ ] 每次修改 Content Block 后已清理缓存

遇到问题时的排查路径：

确认 Hook 名称是否正确——在 Blocksy 官方文档的 Hooks Reference 里搜索 https://docs.creativethemes.com/blocksy/
检查缓存——Content Block 修改后没刷新缓存的案例占了求助量的一半
用 Code Snippets 的「Safe Mode」关闭所有片段，逐个启用，定位冲突的片段
Blocksy 官方 Facebook 社区——开发者活跃，提问时附带你的 Content Block 截图会得到更快的回应