ZBlog to WordPress 插件 —— 完整开发文档、更新日志

第一部分：开发文档（面向开发者 / AI 协作）

1. 项目概述

插件名称：ZBlog to WP Converter
版本：2.3.0
目标：将 ZBlogPHP 导航主题（Yunnav）完整、独立地移植为 WordPress 插件，不修改主主题，通过短代码和小工具实现原主题所有页面布局与功能。

2. 架构设计

2.1 目录结构

zblog-to-wp/
├── zblog-to-wp.php                 # 插件主文件（入口）
├── includes/
│   ├── class-settings.php          # 后台设置面板
│   ├── class-widgets.php           # 小工具（热门/最新文章）
│   ├── class-nav-walker.php        # 自定义菜单输出（适配原主题样式）
│   ├── shortcodes.php              # 短代码注册与回调
│   └── template-functions.php      # 模板辅助函数
├── templates/
│   ├── index-template.php          # [zb_index] 首页
│   ├── list-template.php           # [zb_list] 分类列表（含加载更多）
│   └── single-template.php         # [zb_single] 内容详情
├── assets/
│   ├── css/pc/                     # PC 端样式（原 style/ 目录）
│   ├── css/wap/                    # 移动端样式（原 m/ 目录）
│   ├── js/pc/                      # PC 端 JS
│   ├── js/wap/                     # 移动端 JS
│   └── images/                     # 图片资源（br/, sr/, gg/, web_ico/ 等）
└── readme.txt                      # WordPress 插件信息

2.2 核心常量

2.3 数据存储

• 设置项：wp_options 表，键名 zb2wp_settings（数组）
• 文章扩展字段：wp_postmeta 表，键名 _zb2wp_*（前缀）
• 阅读数：wp_postmeta 表，键名 zb2wp_views（可自定义）

2.4 短代码一览

2.5 核心函数

2.6 AJAX 接口

2.7 钩子（Hooks）

激活钩子：register_activation_hook 初始化默认设置。

资源加载：wp_enqueue_scripts -> zb2wp_enqueue_assets

小工具注册：widgets_init -> zb2wp_register_widgets

自定义字段：add_meta_boxes / save_post

菜单注册：init -> zb2wp_register_menus

后台脚本：admin_enqueue_scripts 加载 admin.js

3. 扩展指南

3.1 新增短代码

1. 在 shortcodes.php 用 add_shortcode 注册
2. 回调函数中引用模板文件（置于 templates/）
3. 在 zb2wp_enqueue_assets 中为其添加资源加载条件

3.2 增加后台字段

1. 在 class-settings.php 的 defaults 数组添加默认值
2. 在 settings_page() 输出表单元素
3. 模板中用 zb2wp_get_settings() 读取

3.3 添加新文章扩展字段

1. 在 zb2wp_meta_box_callback() 的 $fields 数组中添加
2. 在 zb2wp_save_meta_box() 的循环中确保保存
3. 模板中用 zb2wp_get_meta(‘field_name’) 读取

3.4 适配其他主题样式

将 CSS 放入 assets/css/pc/ 或 wap/，在 zb2wp_enqueue_assets 中用 wp_enqueue_style 按需加载即可。

4. 注意事项

• PC/WAP 隔离：资源路径已按设备分开，避免样式冲突。
• 安全：所有输出均使用 esc_* 函数，AJAX 带 nonce 验证。
• 性能：资源仅在含短代码页面加载，避免全站冗余。
• 兼容性：不修改任何 WordPress 核心或主题文件，独立运行。

第二部分：更新记录（Changelog）

v2.3.0（2026-08-02）

• 修复：列表页分页样式与功能（使用 paginate_links 并适配原主题）。
• 修复：内容页框架错乱，补全原主题 info、other、lists 等容器。
• 修复：顶部菜单栏高亮（.hover 类自动添加）。
• 新增：菜单独立注册（zb2wp_primary），不干扰主题菜单。
• 新增：LOGO 链接跳转到插件首页（zb2wp_get_index_page_url()）。
• 新增：列表页“加载更多”功能（AJAX 无刷新加载）。
• 新增：后台文章编辑页“获取网址信息”按钮（自动填充标题、关键词、图标）。
• 调整：PC/WAP 资源完全分离，按设备加载对应样式。
• 移除：独立搜索页（改为 WordPress 默认搜索，减少冗余）。
• 优化：分页链接生成，避免 404。

v2.2.0（2026-07-31）

• 整合原主题所有 CSS/JS，按短代码类型按需加载。
• 增加 PC/WAP 分目录支持。
• 完善后台设置面板。

v2.1.0（2026-07-30）

• 初始版本，包含三个核心短代码及基础模板。