开始/概览
LeafTheme 开发文档
主题二次开发与维护：覆盖代码结构、页面模板、核心模块、Hooks 与实践
入口：functions.php 引导
核心：inc/ 模块化加载
兼容：PHP8.3+ WordPress6.9+
模式：日间 / 夜间
前端样式与交互
拟物化玻璃风格、夜间模式（body.night）、卡片化列表、顶部导航/搜索、全站悬浮工具条、无刷新浏览（AJAX）与事件重绑定（ajax_render_complete）。
后台主题设置
主题后台配置基于 leaftheme_framework：option.json 定义字段，后台界面负责保存到 WP Options；前端模块从 Options 读取开关并决定是否入队资源/渲染组件。
资源与高亮
静态资源统一通过 enqueue 入队（见 inc/modules/assets.php）。代码高亮使用主题自带 hljs，文档页会自动对示例代码块执行高亮与行号。
拟物化玻璃 UI
全站拟物化设计语言：玻璃层、金属高光、内凹/外凸阴影与细腻动效。
AJAX / 无刷新体验
支持页面内容局部更新（配合主题事件重绑定），提升连续浏览体验。
内置商城与支付
主题内置商城模块与会员体系组件，可扩展支付与订单流程。
用户中心
用户中心模块：登录/注册、资料、订单/钱包等能力，可按需裁剪。
REST API 扩展
面向小程序/前后端分离的接口层，统一输出与权限策略。
相册模块
相册归档/详情/分类/标签与展示组件，支持多样化的画廊布局。
视频模块
视频归档/详情与内容展示组件，适配视频站点内容形态。
聊天室与互动
聊天/互动相关能力，适配站内互动与实时消息场景。
后台设置框架
leaftheme_framework：后端配置、选项/元字段、REST 模板与资源。
小工具 Widgets
leaftheme_plugins/widgets：排行榜、用户列表等小工具，便于快速扩展侧边栏。
区块 Blocks
leaftheme_plugins/blocks：Gutenberg 区块与编辑器样式，增强内容表达能力。
音频/播放器扩展
leaftheme_plugins/baiduAudio：音频播放相关扩展，提升内容站的多媒体体验。
模块化加载
核心逻辑位于 inc/，由 Loader 固定顺序加载，避免顺序依赖引发白屏。
主题目录
/www/wwwroot/shu-ye.cn/wp-content/themes/LeafTheme
主题 URL
https://shu-ye.cn/wp-content/themes/LeafTheme
模块加载入口
functions.php → inc/bootstrap.php → inc/core/loader.php
模块清单（固定顺序）
inc/modules/security.php：安全加固（隐藏版本/头部信息、增强默认策略）
inc/modules/legacy.php：迁移通道与兼容 API
inc/modules/setup.php：主题基础能力（菜单、侧边栏、缩略图等）
inc/modules/options-order.php：后台选项与配置顺序/兼容处理
inc/modules/chat.php：聊天室/消息相关能力
inc/modules/assets.php：前端资源加载与版本控制
inc/modules/rest.php：REST API 扩展接口
inc/modules/video.php：视频模块（归档/详情/短代码等）
inc/modules/gallery.php：相册模块（归档/详情/分类/标签）
inc/modules/compat.php：兼容性修复（插件/老数据/前端行为）
内置模块
leaftheme-user-center/：用户中心
leaftheme-commerce/：商城与支付
leaftheme_framework/：后台配置框架
leaftheme_plugins/：小插件集合（widgets/blocks/音频等）
正在加载管理员目录树…（若一直不出现，说明被缓存为访客视图）
核心模板（根目录）
18 项
⌄
| 文件 |
说明 |
header.php |
页面头部：注入全局 CSS、输出 <body> 与导航容器。夜间模式通过 Cookie 控制 body.night。 |
footer.php |
页面底部：输出脚本与通用组件（含 AJAX 重绑定触发点等）。 |
functions.php |
入口引导：加载 inc/bootstrap.php，尽量不写业务逻辑。 |
inc/bootstrap.php |
启动引导：加载常量/辅助函数/Loader 并启动模块。 |
inc/core/loader.php |
模块加载器：固定顺序加载 inc/modules/*.php，避免加载顺序依赖导致白屏。 |
index.php |
首页/主循环：文章列表、轮播/布局、卡片渲染与交互入口。 |
single.php |
单篇入口：根据文章类型切换不同的内容模板（并触发 modify_single_type 钩子）。 |
page.php |
普通页面：展示 WordPress 页面内容。 |
category.php |
分类归档：分类列表模板。 |
tag.php |
标签归档：标签列表模板。 |
comments.php |
评论区：评论表单与评论列表，含 pf_comment_form_* 扩展点。 |
sidebar.php |
侧边栏：通用 Sidebar 输出。 |
custom_function.php |
历史/兼容逻辑较多：包含旧版功能与大量工具函数（建议二开尽量不要直接改这里）。 |
sandbox_functions.php |
主题工具函数：封装 body_class/post_class 等输出，并提供 globalnav_menu 过滤器等。 |
archive-video.php |
视频归档：视频文章类型的归档页。 |
archive-nir_shop_product.php |
商品归档：商城商品类型的归档页。 |
single-nir_shop_product.php |
商品详情页：商城商品详情模板。 |
404.php |
404 页面：未找到内容时展示。 |
页面模板（可在后台“页面属性 → 模板”选择）
7 项
⌄
| 文件 |
说明 |
template-store.php |
商城首页：商品列表与购买入口（依赖 leaftheme-commerce）。 |
template-cart.php |
购物车：展示选购列表与结算入口。 |
template-user-center.php |
用户中心入口：个人资料/订单/钱包等（依赖 leaftheme-user-center）。 |
template-chatroom.php |
聊天室页面：消息/互动能力入口（依赖 chat 模块）。 |
template-gallery-hub.php |
相册中心：相册聚合页与导航入口。 |
template-video-hub.php |
视频中心：视频聚合页与导航入口。 |
template-documentation-glass.php |
本页面：LeafTheme 开发文档（拟物化/玻璃风格）。 |
片段模板（assets/template，供页面组合复用）
8 项
⌄
| 文件 |
说明 |
assets/template/nav-main.php |
顶部主导航：Logo、主菜单、搜索、用户入口等。 |
assets/template/postlist-item.php |
文章卡片：列表项渲染，包含 pf-post-card-meta-* 扩展点。 |
assets/template/postlist-post.php |
文章列表：组合列表结构，包含元信息扩展点。 |
assets/template/share-modal.php |
分享弹窗：包含 pf-share-modal-* 扩展点。 |
assets/template/slider-glass.php |
玻璃拟物化轮播：主题典型拟物化视觉组件之一。 |
assets/template/single-post.php |
文章详情片段：用于 single.php 的实际内容输出。 |
assets/template/single-video.php |
视频详情片段：用于视频类型文章。 |
assets/template/single-gallery.php |
相册详情片段：用于相册类型文章。 |
示例：自定义一个页面模板（建议放在自定义插件或子主题）
<?php
/*
Template Name: 我的自定义页面
*/
defined('ABSPATH') || exit;
get_header();
?>
<div class="my-page">Hello LeafTheme</div>
<?php get_footer(); ?>
此功能需要深度扫描：请在当前地址后追加 ?lt_doc_full=1。
为避免公开泄露内部扩展点，Hooks 全量扫描仅对管理员可见。
Action（do_action）
用于“在某个位置插入输出/执行副作用”，例如在文章卡片元信息处插入阅读数、在分享弹窗追加按钮等。
Filter（apply_filters）
用于“过滤/修改某个值”，例如修改主题 options、翻译数组、全局菜单输出等。
常见前缀
pf-*（卡片/分享/评论扩展点）、modify_leaftheme_*（框架配置）、nir_uc_*（用户中心支付状态）、ajax_render_complete（前端刷新完成事件）。
核心 Hooks 手册（场景 / 参数 / 用法 / 风险）
按主题真实代码整理
⌄
pf-post-card-meta-*文章卡片元信息扩展点⌄
触发场景
文章列表卡片的“阅读/评论”等元信息区域。
参数结构
无参数（直接 echo 输出 HTML）。
推荐用法
使用 add_action 插入小块标记、统计数、徽章等；输出需自行 esc_html/esc_attr。
风险点
不要输出大型 DOM 或阻塞查询；避免在 Hook 内部进行慢 SQL；注意 XSS 转义。
<?php
add_action('pf-post-card-meta-start', function () {
if (function_exists('display_post_views')) {
display_post_views();
return;
}
echo '<span class="views">Views</span>';
});
pf-share-modal-*分享弹窗扩展点⌄
触发场景
文章分享弹窗（分享按钮/收藏按钮之间的插入点）。
参数结构
无参数（直接 echo 输出按钮/链接）。
推荐用法
在 before-share/before-favorite 插入自定义分享渠道、埋点、复制链接等。
风险点
不要破坏弹窗 DOM 结构；按钮事件建议走主题已有 JS（或在 ajax_render_complete 重绑）。
<?php
add_action('pf-share-modal-before-favorite', function () {
echo '<a class="copy-link" href="#" data-copy-link="1">复制链接</a>';
});
pf_comment_form_*评论表单扩展点⌄
触发场景
评论输入框下方 meta 区域（表情按钮附近）。
参数结构
无参数；另有 WordPress 原生 comment_form action 带 $post_id。
推荐用法
插入“插入代码/插入图片/快捷格式”等；尽量只输出按钮，逻辑放 JS。
风险点
评论区常被缓存/反垃圾策略影响；不要直接信任用户输入；避免破坏 Vue 绑定。
modify_single_type单篇类型兜底扩展⌄
触发场景
当 single.php 遇到未知自定义文章类型时触发（主题未内置模板）。
参数结构
1 个参数：$post_type（字符串）。
推荐用法
根据 $post_type include 你自己的模板片段，或直接 wp_die 友好提示。
风险点
务必保证 include 路径可读；不要在此 Hook 内递归触发 single。
<?php
add_action('modify_single_type', function ($post_type) {
if ($post_type === 'my_post_type') {
locate_template(array('assets/template/single-my-post-type.php'), true, true);
exit;
}
});
示例：在文章卡片元信息区域注入内容（pf-post-card-meta-start）
<?php
add_action('pf-post-card-meta-start', function () {
echo '<span class="views"><i class="fas fa-eye"></i> ' . esc_html__('浏览', 'leaftheme') . '</span>';
});
示例：监听主题前端渲染完成事件（ajax_render_complete）
window.add_action && window.add_action('ajax_render_complete', function () {
console.log('LeafTheme: 内容已刷新，重绑你的 JS');
});
使用方式
在左侧搜索框输入关键词；用“全部/文件/模块/Hook/模板/选项”筛选；结果支持点击跳转或复制。
深度索引
若要启用 options 键名索引、模板调用链等深度数据，请追加 ?lt_doc_full=1。
推荐方式
优先使用子主题或自定义插件；避免直接改 inc/ 与内置模块核心文件，以便后续升级可合并。
资源注入
使用 wp_enqueue_scripts 加载你的 CSS/JS；前端存在 AJAX 更新时，配合 ajax_render_complete 重绑。
夜间模式
主题通过 Cookie 控制 body.night，你的样式用 body.night 覆盖即可实现一致配色。
商城/用户中心二开
优先在模块提供的 Hooks 上扩展；涉及支付/订单请在测试站验证回调、状态流转与权限校验。
扩展主题后台设置（leaftheme_framework）
options / posttype / 翻译
⌄
可用过滤器
modify_leaftheme_translation_array · modify_leaftheme_options · modify_leaftheme_posttype_and_meta
示例：追加一个主题设置项（modify_leaftheme_options）
<?php
add_filter('modify_leaftheme_options', function ($option_json) {
if (!is_array($option_json)) return $option_json;
$option_json[] = array(
'key' => 'my_custom_option',
'title' => '我的自定义选项',
'type' => 'text',
'default' => 'Hello LeafTheme',
);
return $option_json;
});
用户中心/支付流程扩展（leaftheme-user-center）
支付状态钩子
⌄
Action
nir_uc_payment_state_changed：支付状态变更时触发。
示例：监听支付状态并写入日志（nir_uc_payment_state_changed）
<?php
add_action('nir_uc_payment_state_changed', function ($payload) {
if (!is_array($payload)) return;
error_log('[LeafTheme UC] payment_state_changed: ' . wp_json_encode($payload, JSON_UNESCAPED_UNICODE));
});
前端增强：无刷新重绑与动画
ajax_render_complete
⌄
window.add_action && window.add_action('ajax_render_complete', function () {
document.querySelectorAll('.my-widget').forEach(function (el) {
el.classList.add('ready');
});
});
示例：注册并加载你的扩展脚本（插件/子主题）
<?php
add_action('wp_enqueue_scripts', function () {
wp_enqueue_style('my-leaf-doc', get_stylesheet_directory_uri() . '/extend/css/my-doc.css', array(), '1.0.0');
wp_enqueue_script('my-leaf-doc', get_stylesheet_directory_uri() . '/extend/js/my-doc.js', array(), '1.0.0', true);
});
