1. 简介与核心特性

可视化构建器在页面 / 文章编辑页提供一个名为「可视化页面构建器」的编辑框。它把 53+ 种区块（组件）以「单一 Schema → 渲染引擎 → 画布」的方式组织：你在画布里拖出来的页面，会以一份 JSON 结构保存到文章数据中，前台再按同一套样式 1:1 还原，保证后台预览与线上展示完全一致。

• ◈
  拖拽排版：从左侧组件库拖到画布，或点击直接追加到末尾。
• ◈
  三栏界面：组件库 / 画布 / 配置面板，每屏看到整体又方便精修。
• ◈
  所见即所得：后台预览与前端复用同一套 CSS class，改完即所见。
• ◈
  内联编辑：画布里双击标题 / 正文，原地修改文字。
• ◈
  嵌套布局：区块包裹、分栏容器可逐层放入子组件，做复杂版式。
• ◈
  导入 / 导出：整页以 JSON 形式导出备份、跨站点迁移或复用。
• ◈
  响应式预览：一键切换桌面 / 平板 / 手机宽度查看效果。
• ◈
  安全存储：保存时对 Schema 做白名单校验与 XSS 净化，防止注入。

2. 打开构建器

在后台编辑任意页面（Page）时，构建器会出现在编辑区下方：

1. 后台进入 页面 → 全部页面，新建或编辑一个页面。
2. 在编辑器下方找到名为 「可视化页面构建器」 的编辑框（位于正文编辑器之下）。
3. 画布空着也没关系 —— 点击左侧组件即可开始添加；首次进入会载入示例区块帮助熟悉操作（可在开发者接口中关闭）。

3. 界面布局：三栏 + 顶栏

顶栏（操作工具条）

• 撤销 / 重做：回退或恢复上一步操作（含快捷键）。
• 桌面 / 平板 / 手机：切换画布预览宽度，验证响应式表现。
• 导入 / 导出 JSON：整页结构的备份与迁移。
• 清空：一键清除画布上所有区块（有二次确认）。
• 预览：新窗口打开纯页面预览，脱离后台框架看真实效果。

左侧 · 组件库（Palette）

按分类列出全部可用区块。拖拽到画布任意位置即可插入；单击则追加到画布末尾。每个组件显示名称与分类标签。

中间 · 画布（Canvas）

页面最终样式的实时预览。每个区块带悬浮工具条与标签；点击选中后在右侧编辑；空白处可接收拖入的新组件并出现插入指示线。

右侧 · 配置面板（Config）

选中区块后，这里列出该区块所有可配置字段（文字、选项、可重复列表等）。修改即时反映到画布。容器类区块（区块包裹 / 分栏容器）还会在此显示嵌套内容管理器。

4. 添加区块

方式一：拖拽（推荐，可精确定位）

1. 在左侧组件库按住目标组件。
2. 拖到中间画布，画布会出现一条蓝色插入线表示落点。
3. 松手即在该位置插入新区块。

方式二：单击追加

直接单击左侧组件，区块会添加到画布末尾并自动选中，便于马上配置。

5. 编辑区块内容

右侧配置面板

点击画布中的区块使其选中，右侧面板按字段类型提供对应控件：

• 单行文本（text）：标题、按钮文字、链接等。
• 多行文本（textarea）：副标题、正文、提示内容等，支持简单 HTML（富文本区块）。
• 数字（number）：间距高度、百分比等数值。
• 下拉选择（select）：样式变体、列数、对齐、色调等预设选项。
• 色板（color）：如首屏 Hero 的背景风格，点选深蓝 / 浅蓝 / 品牌橙。
• 可重复列表（repeater）：服务项、案例、团队成员等一组数据的增删（见第 7 节）。

画布内联编辑（双击改字）

画布中带下划虚线可编辑的文字（标题、副标题、引言等）支持双击原地修改：双击进入编辑、改完点击别处（失焦）即保存。适合快速改文案，不必往返右侧面板。

6. 区块工具条：隐藏 / 移动 / 复制 / 删除

鼠标移到画布中的区块上，左上角会出现一排小工具按钮（也出现在嵌套子块的悬浮条上）：

右侧配置面板顶部同样提供「显示 / 隐藏」「删除组件」按钮，与画布工具条一致。

7. 可重复字段（列表类数据）

服务、案例、团队、价格套餐、问答等内容通常是「一组多条」的数据，构建器用可重复字段（repeater）管理。以「服务网格」为例：

• 右侧面板中该字段显示为若干「#1 / #2 …」条目卡片，每张卡是单行 / 多行子字段。
• 点条目右上角「删除」移除某条；改子字段文字即时反映到画布。
• 点「+ 添加一项」在末尾新增一条（默认空，按结构填即可）。
• 条目顺序即展示顺序，可在嵌套管理器中用 ↑ / ↓ 调整（见下节）。

8. 嵌套布局：区块包裹 / 分栏容器

要拼复杂版式（如「带统一背景的卡片区」「左右两栏各放不同内容」），用两个容器类区块：

区块包裹（Section，布局类）

• 相当于一个带背景与内边距的「容器」，内部可放任意子组件。
• 字段：眉标 / 标题 / 副标题、背景（浅色 / 灰底 / 深蓝 / 品牌橙）、内边距（小 / 中 / 大）。
• 在右侧「嵌套内容」区点「+ 添加组件」选择子组件（标题块、富文本、图标信息块、按钮块等），或用 ↑ / ↓ / 复制 / 删除管理。

分栏容器（Columns，布局类）

• 把页面分成 2 / 3 / 4 列，列间距可选小 / 中 / 大。
• 每一列是独立容器，可各自放入子组件；支持「+ 添加一列 / − 删除最后一列」（最多 4 列）。
• 移动端各列自动堆叠为单列，无需手动处理。

9. 响应式预览

顶栏的「桌面 / 平板 / 手机」按钮可即时切换画布宽度：

• 桌面：默认满宽，对应 PC 大屏。
• 平板：中等宽度，验证平板 / 小笔记本表现。
• 手机：窄屏，确认单列堆叠、文字与按钮在移动端可读可点。

10. 撤销 / 重做与快捷键

构建器内置操作历史（最多保留 60 步），可随时回退或恢复：

顶栏的撤销 / 重做按钮也会随可用状态自动启用或置灰。

11. 导入 / 导出 JSON

整页结构以一份 JSON（{ "blocks": [ ... ] }）表示，可备份、迁移或复用：

导出

1. 点顶栏「导出 JSON」，弹窗显示当前页面的完整 Schema。
2. 全选复制保存（如存为 home.json），即可作为整页备份或模板。

导入

1. 点顶栏「导入」，在弹窗粘贴合法 JSON。
2. 点「应用」：若格式正确（含 blocks 数组）即整体替换当前画布；失败会提示「格式不正确 / 解析失败」。

12. 清空画布

点顶栏「清空」会弹出二次确认，确认后移除画布上全部区块。清空后仍可用「撤销」恢复；发布保存后该页面构建器内容即清空，前台回退到文章正文（若有）。

13. 保存与发布

构建器内容跟随 WordPress 正常的「保存草稿 / 发布 / 更新」流程：

• 编辑过程中的每次改动会写入隐藏字段 _hualin_builder_schema（同时本地缓存一份，刷新不丢）。
• 点击编辑器右上角「更新 / 发布」时，隐藏字段随文章一起入库，无需额外按钮。
• 保存前对 Schema 做白名单校验与净化：非法 JSON 会被忽略，区块类型不在白名单内会被丢弃，文本经 sanitize_text_field、富文本经 wp_kses_post 处理，避免存储型 XSS。
• 若隐藏字段为空，则删除已有 Schema，页面回退到普通正文。

14. 前端渲染与默认内容

前台通过 hualin_render_builder() 读取文章 meta 中的 Schema 并渲染；后台预览与前端共用同一套 builder-blocks.css，所以「所见即所得」。

• 被隐藏的区块（工具条 / 面板里的「隐藏」）在前端不输出，但仍留在 Schema 中可随时恢复。
• 未用构建器编辑的页面：主题内置各页面的「开箱即用」默认 Schema（首页、关于、服务、案例、团队、资讯、FAQ、招贤纳士、合作伙伴、隐私、网站地图等），用户不编辑也能直接上线精品内容。
• 默认内容与构建器内容二选一：一旦用构建器保存，即优先使用你的 Schema。

15. 区块参考总览（53+ 种）

以下按组件库分类列出全部区块。类型标识为开发者接口 / JSON 中使用，普通用户只需在左侧组件库按名称挑选。

页首（Page Header）

内容（Content）

媒体（Media）

转化（Conversion）

基础（Basic）

企业（Enterprise）

布局（Layout · 容器类）

自定义（Custom · 原子 / 可复用组件）

16. 进阶：开发者接口

Schema 结构

整页即一份 JSON。每个区块含 id（唯一）、type（类型标识）、props（配置项）；可选 hidden: true 表示隐藏。容器类额外嵌套：

{
  "blocks": [
    { "id": "b1a2c3", "type": "hero",
      "props": { "title": "…", "subtitle": "…", "btn1": "查看案例", "btn2": "了解企业", "bg": "navy" } },
    { "id": "b9", "type": "section",
      "props": { "bg": "gray", "pad": "md",
        "inner": [ { "id": "s1", "type": "card", "props": { … } } ] } },
    { "id": "b10", "type": "columns",
      "props": { "cols": 2, "gap": "md",
        "cells": [ { "head": "左列", "blocks": [ … ] }, { "head": "右列", "blocks": [ … ] } ] } }
  ]
}

在自定义文章类型上启用

默认仅 page。用过滤器扩展：

add_filter( 'hualin_builder_post_types', function ( $types ) {
    $types[] = 'product';   // 例：在产品文章类型启用
    return $types;
} );

关闭首次进入的示例数据

后台编辑新建页面时默认载入示例区块。用前端全局变量关闭：

window.HUALIN_BUILDER_NOSEED = true;   // 保持空白画布

区块类型白名单与净化

保存时仅允许白名单内类型（与 builder-core.js 的 BLOCKS 注册表 1:1），并对 props 递归净化：文本走 sanitize_text_field、富文本（richtext.html）走 wp_kses_post、嵌套结构（section.inner / columns.cells）单独保留层级，杜绝注入。

暴露的全局对象

构建器在浏览器暴露 window.HualinBuilder，含 BLOCKS 注册表与 getSchema() / setSchema() 方法，便于二次开发或外部脚本读写当前页面结构。

17. 常见问题

• 构建器内容没生效？ 确认已点「更新 / 发布」；若页面同时有正文，构建器内容会优先覆盖正文展示。
• 隐藏的区块去哪了？ 没被删除，只是前端不输出；选中后点工具条的「显示 / 隐藏」即可恢复。
• 导入后页面变了？ 导入会整体替换画布，导入前请先「导出 JSON」备份。
• 移动端错位？ 用顶栏「手机」预览宽度检查；分栏容器与多数区块在窄屏会自动堆叠为单列。
• 不想让客户看到示例区块？ 在集成时设置 window.HUALIN_BUILDER_NOSEED = true，新建页面即为空白画布。
• 能放进容器里的组件有限制吗？ 是的，仅 INNER_TYPES 集合内的原子 / 自定义组件可嵌套进区块包裹 / 分栏容器（见第 8 节提示）。