WordPress 主题 · 开发文档

Nuxare

轻量多用途 WordPress 主题，内置 Nuxare Builder 可视化编辑器 —— Section / Column / Element 三层结构，中心化配色、响应式设备属性、模板系统与 HTML 导入器。

版本 v1.0.0 主类 Nuxare_Builder 命名空间 Nuxare 日期 2026-08-31
01 · 概览

主题元数据

Nuxare 主题以 Nuxare Builder 为核心，布局数据以 JSON 存于 post meta，所见即所得，画布与前台同源渲染。

主题名
Nuxare
版本
1.0.0
主类
Nuxare_Builder（单例，namespace Nuxare）
自动加载
spl_autoload_register，前缀 Nuxare_ → includes/class-nuxare-*.php，防 Nuxare_Core_/Nuxare_Lang_ 前缀冲突
内容模型
Section → Column → Element 三层（列可嵌套）
布局存储
post meta _nuxare_layout（JSON 数组）
编辑入口
前端 ?nuxare_builder_visual=1（全屏 iframe）/ 后端 post.php?post=ID&action=nuxare-builder
编辑器交互
nuxare-visual-builder.js（父窗口）↔ nuxare-vb-frame.js（iframe canvas）via postMessage
渲染源
Nuxare_Builder_Front::render_canvas() 单一渲染源（画布 = 访客视图，除装饰边框）
02 · 架构

三层架构与渲染管线

三层内容模型

Section（区块） → Column（列，可嵌套） → Element（元素）。布局以 JSON 存于 _nuxare_layout，列宽走 Fraction 引擎 + 12 列吸附，元素宽度与水平对齐完全解耦。

B3 导入管线

HTML → Nuxare_Parser（区域探测、Section/Column/Element 映射）→ 布局 JSON → Nuxare_Builder_Front → HTML 渲染。导入器 UI 支持粘贴/上传 → 解析 → 预览 → 保存。

渲染流水线

布局 JSON → Nuxare_Builder_Front::render() → 元素分发到 render_<type>() → 设备属性过滤（desktop/tablet/phone）→ 中心化配色变量解析 → 输出 HTML。画布与前台同源，确保所见即所得。

编辑器三栏

左：图标菜单 + 内容面板（元素库 / 结构树 / 历史）；中：iframe 画布；右：选项面板。结构变更（增删/复制/移动/撤销）触发 nuxare_builder_render_canvas AJAX 防抖重渲染。

元素注册表

Nuxare_El_Renderer 基类 + 注册表模式：渲染器可为方法名、子类实例或 callable，统一调度。设置 schema 在 Nuxare_Builder_Elements。

选中态色规

对象样式
区块绿色实线 #04d86a（4px）
第一层列（depth 0）琥珀虚线 #FF7D29（2px）
第二层列（depth 1）蓝色虚线 #06B6D4（2px）
第三层列（depth 2）粉色虚线 #f887d6（2px）
元素绿色虚线 #0CC8A0（2px）
03 · 模块参考

核心模块

Builder 核心

类职责
Nuxare_Builder布局读写 _nuxare_layout、template_include 过滤、入口管理
Nuxare_Builder_Front前端渲染：JSON → HTML、render_element 分发、设备感知
Nuxare_Builder_Editor可视化编辑器：template_include、iframe 画布、管理栏入口、后台页注册
Nuxare_Builder_AjaxAJAX：save/load/render/render_canvas/upload_media/save_conditions
Nuxare_Builder_Elements元素定义：分类 + 全部元素设置 schema

渲染与系统

类职责
Nuxare_El_Renderer元素渲染基类 + 注册表 + CSS 字段辅助
Nuxare_Options主题选项面板：配色、字体、响应式、布局
Nuxare_Color_Palette中心化配色：:root CSS 变量注入、字段默认映射
Nuxare_Device_Attrs响应式设备属性：desktop/tablet/phone、断点配置、显隐
Nuxare_Icons自研 SVG 图标集（24×24 stroke）、sprite 输出
Nuxare_ParserB3：HTML → 布局 JSON 解析、区域探测
Nuxare_ImporterHTML 导入 UI：粘贴/上传 → 解析 → 预览 → 保存

模板系统

类职责
Nuxare_TemplateCPT nuxare_template：header/footer/global_section/single/archive/product
Nuxare_Template_Admin模板后台 UI
Nuxare_Template_Conditions显示条件：include/exclude 规则、特异性优先级
legacy-compat.phppuretheme_options → nuxare_options、旧短码别名、旧 URL 参数重定向
04 · 元素体系

50+ 元素 · 9 类

每个元素 = 设置 schema + 渲染器 + CSS 三件套；渲染器键名 JS/PHP 一致。

基础

文本、标题、按钮、图标、分隔线、列表、空格、代码

媒体

图片、视频、轮播、图库、图标盒

布局

手风琴、标签页、步骤

结构

面包屑、版权、Logo、导航菜单、社交链接、搜索框

博客

文章循环、文章标题/内容/摘要/特色图/字段、分页

单篇

文章标题、正文、摘要、特色图、字段

工具

短码、HTML、联系表单、地图、FAQ

嵌入

图表、进度条、计数器、价格表、团队成员、评价

页眉/页脚

归档链接/标题、搜索、导航、Logo、社交、版权

视频元素无 URL 时输出与画布同款品牌占位图（placeholder.svg 渐变 + 提示文字），复用对齐/圆角/比例/最大宽度。图标默认 width: fit-content。

05 · 目录结构

文件组织

nuxare/ ├── style.css / functions.php # 主题头 + 引导 ├── 404.php archive.php single.php page.php … # 模板层级 ├── header.php footer.php sidebar.php comments.php ├── front-page.php home.php attachment.php search.php ├── includes/ │ ├── class-nuxare-builder.php │ ├── class-nuxare-builder-front.php │ ├── class-nuxare-builder-editor.php │ ├── class-nuxare-builder-ajax.php │ ├── class-nuxare-builder-elements.php │ ├── class-nuxare-el-renderers.php # 渲染基类+注册表 │ ├── class-nuxare-el-{accordion|button|carousel|chart|…}.php # 50+ 元素渲染器 │ ├── class-nuxare-options.php │ ├── class-nuxare-color-palette.php │ ├── class-nuxare-device-attrs.php │ ├── class-nuxare-icons.php │ ├── class-nuxare-parser.php # B3 解析 │ ├── class-nuxare-importer.php │ ├── class-nuxare-template.php │ ├── class-nuxare-template-admin.php │ ├── class-nuxare-template-conditions.php │ └── legacy-compat.php ├── assets/ │ ├── css/ # nuxare / admin-options / nuxare-visual-builder / nuxare-importer │ ├── js/ # nuxare / nuxare-visual-builder / nuxare-vb-frame / admin-options / nuxare-importer │ └── images/ # logo / placeholder.svg ├── template-parts/ # visual-builder / builder-canvas / content / content-single / content-search / content-none / template-preview ├── tools/ # el-gen-subclasses + tests/（冒烟/结构测试） └── docs/ # 净室文档 / 元素开发规范 / 配色 / 响应式 / 多份设计 HTML
06 · 核心功能

六大能力

Nuxare Builder

Section/Column/Element 三层可视化编辑器，B3 导入管线，画布与前台同源。

全局配色系统

中心化 :root 变量，配色存为变量标识符，渲染期解析。

响应式设备属性

desktop/tablet/phone 三设备，断点可配（默认 1024/767），显隐切换。

自研图标库

24×24 stroke SVG 图标集，sprite 输出。

主题选项面板

配色 / 字体 / 响应式 / 布局统一配置。

模板系统 + 导入器

CPT nuxare_template + 显示条件；HTML 粘贴/上传导入。

四种模式 · 实时切换

浅色

深色

浅色 + 护眼

深色 + 护眼

环境要求 / 安装

WordPress

5.9+

PHP

8.0+

浏览器

现代浏览器（iframe 编辑需 postMessage 支持）

1
上传主题：后台外观 → 主题 → 上传，或放 wp-content/themes/nuxare。
2
启用：激活 Nuxare 主题，进入 Nuxare Builder 编辑。
3
导入 / 搭建：粘贴 HTML 走 B3 导入，或直接在画布拖拽搭建。
07 · 配色 / 响应式

中心化配色与设备属性

中心化配色

Nuxare_Color_Palette 注入 :root CSS 变量（--nx-*），配色选择存为变量标识符，渲染期解析为具体值；后台改色 → 前端直接映射，单色 / 渐变两种模式。

响应式设备属性

Nuxare_Device_Attrs 三设备模型（desktop/tablet/phone），断点在选项配置（默认 1024/767），元素可按设备显隐；画布与前台在缺省时均按横向（row）不换行处理列内排列。

布局红线

元素宽度与水平对齐完全解耦：宽度仅由「高级 > 尺寸 > 宽度」控制；.nx-el-halign-center/right 含 width: fit-content; max-width: 100% 以收缩对齐。列内对齐由布局组 layout_main_align（水平分布）与 layout_cross_align（垂直对齐）单源驱动；元素/区块/列自身定位选项卡移除水平/垂直对齐。新增列默认全宽 1/1，不自动重排同层列。

08 · 模板系统

CPT + 显示条件

模板类型

自定义文章类型 nuxare_template：header / footer / global_section / single / archive / product。

显示条件

Nuxare_Template_Conditions：include/exclude 规则，按特异性优先级匹配，覆盖全站局部。

全局依赖元素

模板编辑画布对全局依赖元素（logo / nav_menu / post_* / breadcrumbs / post_loop = GLOBAL_DEP_TYPES）显示结构化占位，不拉取真实全局内容；结构变更触发 PHP 重新渲染（防抖）。

09 · 钩子与 AJAX

扩展点

关键钩子

钩子类型说明
template_includefilterBuilder / 编辑器接管模板、入口判定
nuxare_el_renderersfilter注册自定义元素渲染器（方法名/子类/callable）
nuxare_builder_elementsfilter注册 / 修改元素设置 schema
postMessage（iframe ↔ 父）JS选中、拖拽、属性改动回写，触发服务端防抖重渲染

AJAX（wp_ajax_nuxare_*）

动作用途
nuxare_builder_save / nuxare_builder_load布局 JSON 存取
nuxare_builder_render / nuxare_builder_render_canvas节点 / 画布重渲染（防抖 30s 自动保存）
nuxare_builder_upload_media媒体上传
nuxare_builder_save_conditions模板显示条件保存

属性字段改动后须置 state.dirty = true 触发 30s 防抖自动保存；AJAX 保存需递归处理嵌套 columns 并保留全部布局字段（方向/间距/水平分布/垂直对齐），仅对颜色类用 sanitize_hex_color 校验。

10 · 命名约定

命名规范

对象规范示例
PHP 类大驼峰 + 下划线Nuxare_Builder_Front
文件名小写连字符class-nuxare-builder-front.php
CSS 变量令牌 / 配色两套--nuxare-*（令牌）/ --nx-*（配色）
CSS 类短前缀.nx-price / .nx-el-halign-center
post meta / 选项下划线_nuxare_layout / nuxare_options
短码 / AJAX短前缀[nx_*] / wp_ajax_nuxare_*
11 · 扩展指南

新元素三件套

1
设置 schema：在 Nuxare_Builder_Elements 注册元素分类与字段 schema（键名 JS/PHP 一致）。
2
渲染器：实现 render_<type>()，挂到 Nuxare_El_Renderer 注册表（方法名/子类/callable），与 PHP render_element 字段映射对齐。
3
样式：CSS 遵循 .nx-* 前缀与 --nuxare-* / --nx-* 变量；画布与前台同源，装饰边框仅画布可见。
开发红线

画布以 Nuxare_Builder_Front::render_canvas() 为单一渲染源；图标渲染器 JS 键名须与 PHP 一致并清理死键；轮播「幻灯按钮」字段需可设四值圆角；文本元素支持分栏/首字下沉/自适应高度。