{"id":50709233,"url":"https://github.com/coowinit/wp-fullscreen-post-modal-theme","last_synced_at":"2026-06-09T14:01:46.567Z","repository":{"id":351231243,"uuid":"1210113124","full_name":"coowinit/wp-fullscreen-post-modal-theme","owner":"coowinit","description":"一个带卡片文章列表、路由驱动全屏详情弹层，以及静态 HTML 预览的 WordPress 博客主题。","archived":false,"fork":false,"pushed_at":"2026-04-14T05:30:18.000Z","size":31,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-14T07:28:29.163Z","etag":null,"topics":["blog","blog-theme","cards","css","frontend","html","javascript","modal","php","responsive","rest-api","theme-development","wordpress","wordpress-theme"],"latest_commit_sha":null,"homepage":"https://coowinit.github.io/wp-fullscreen-post-modal-theme/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coowinit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-14T05:16:45.000Z","updated_at":"2026-04-14T05:26:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/coowinit/wp-fullscreen-post-modal-theme","commit_stats":null,"previous_names":["coowinit/wp-fullscreen-post-modal-theme"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/coowinit/wp-fullscreen-post-modal-theme","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coowinit%2Fwp-fullscreen-post-modal-theme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coowinit%2Fwp-fullscreen-post-modal-theme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coowinit%2Fwp-fullscreen-post-modal-theme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coowinit%2Fwp-fullscreen-post-modal-theme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coowinit","download_url":"https://codeload.github.com/coowinit/wp-fullscreen-post-modal-theme/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coowinit%2Fwp-fullscreen-post-modal-theme/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34110012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blog","blog-theme","cards","css","frontend","html","javascript","modal","php","responsive","rest-api","theme-development","wordpress","wordpress-theme"],"created_at":"2026-06-09T14:01:45.712Z","updated_at":"2026-06-09T14:01:46.556Z","avatar_url":"https://github.com/coowinit.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HTML 预览 + WordPress 主题\n\n一个以 **“列表页卡片 + 路由化详情弹层”** 为核心交互的博客主题示例仓库。\n\n这个仓库同时包含两部分：\n\n- **静态 HTML 预览**：用于直接在 GitHub / GitHub Pages 预览界面结构与交互原型。\n- **WordPress 主题代码**：用于在真实 WordPress 环境中运行动态模板、评论区、相关文章、分享按钮与详情弹层逻辑。\n\n---\n\n## 1. 主题目标\n\n这个主题不是单纯的博客列表，也不是一个普通弹窗。\n\n它要同时实现两件事：\n\n1. **列表浏览不断流**：用户在卡片列表里阅读文章时，不必每次都整页跳转。\n2. **文章仍然有真实 URL**：每篇文章都能被单独访问、分享和收录。\n\n因此主题采用的是 **route-driven modal** 思路：\n\n- 从列表页点击文章时，打开 **全屏详情弹层**。\n- 弹层打开后，浏览器地址会切换成这篇文章的真实 permalink。\n- 关闭弹层时，返回列表，并恢复之前的滚动位置。\n- 如果用户直接打开该 permalink，则显示为正常的 `single.php` 单篇文章页，而不是弹层。\n\n也就是说：\n\n- **URL 是真的**\n- **展示方式取决于进入方式**\n\n---\n\n## 2. 弹层详情的实现原理\n\n### 2.1 两种入口，共用同一篇文章\n\n同一篇文章有两种阅读方式：\n\n#### A. 从列表页进入\n- 列表卡片里的链接带有 `data-modal-link` 和 `data-post-id`\n- 前端脚本 `modal-route.js` 接管点击\n- 阻止整页跳转\n- 请求自定义 REST 接口 `/wp-json/insight/v1/post/{id}`\n- 把返回的数据渲染进全屏弹层\n- 使用 `history.pushState()` 把地址改成真实 permalink\n\n#### B. 直接访问 permalink\n- WordPress 正常走 `single.php`\n- 页面作为独立详情页渲染\n- 不显示“关闭弹层”按钮，因为当前没有背景列表上下文可回退\n\n### 2.2 为什么不用“纯弹窗不改地址”\n\n纯弹窗虽然简单，但有几个明显问题：\n\n- 文章链接不可直接复制分享\n- 刷新后无法自然恢复状态\n- 浏览器前进 / 后退语义不自然\n- SEO 与单篇文章访问体验较弱\n\n当前方案的优势是：\n\n- 文章保留真实 URL\n- 列表浏览不被打断\n- 浏览器后退可以关闭弹层\n- 直接访问仍是完整详情页\n\n### 2.3 数据流\n\n#### 1）列表模板输出卡片\n由下面这些模板负责：\n\n- `home.php`\n- `archive.php`\n- `index.php`\n- `template-parts/content-card.php`\n\n每张卡片会输出：\n\n- 标题\n- 摘要\n- 日期\n- 分类\n- 缩略图\n- permalink\n- post ID\n\n#### 2）列表页预先挂载空弹层容器\n由 `template-parts/content-single-modal.php` 输出：\n\n- 遮罩层\n- 面板容器\n- 关闭按钮\n- 内容挂载区 `#detailWrap`\n- 加载态 / 错误态容器\n\n#### 3）前端脚本请求 REST 数据\n`assets/js/modal-route.js` 负责：\n\n- 监听卡片点击\n- 发起 fetch 请求\n- 渲染文章详情\n- 渲染作者信息卡\n- 渲染分享按钮\n- 渲染上一篇 / 下一篇\n- 渲染相关文章\n- 处理 `pushState` / `popstate`\n- 恢复列表滚动位置\n\n#### 4）REST 接口返回弹层所需完整数据\n`functions.php` 注册了：\n\n```text\n/wp-json/insight/v1/post/{id}\n```\n\n接口返回内容包括：\n\n- 标题\n- 摘要\n- 正文 HTML\n- permalink\n- 日期\n- 阅读时长\n- 分类 / 标签\n- 特色图\n- 作者信息\n- 分享链接\n- 上一篇 / 下一篇\n- 相关文章\n\n---\n\n## 3. 主题当前能力\n\n### 列表与详情\n- 卡片式文章列表\n- 单篇文章页\n- 路由化全屏详情弹层\n- 列表点击进入弹层，直接访问进入 `single.php`\n\n### 浏览器行为\n- 弹层打开时地址切换为真实 permalink\n- 后退关闭弹层\n- 前进重新打开对应文章\n- 关闭后恢复列表滚动位置\n\n### 文章详情区\n- 特色图\n- 标题 / 摘要 / 分类 / 日期\n- 阅读时长\n- 作者信息卡\n- 标签区域\n- 分享按钮\n- 上一篇 / 下一篇导航\n- 相关文章推荐\n\n### 评论区\n- `comments.php` 评论模板\n- 评论列表\n- 回复按钮\n- 嵌套评论\n- 留言表单\n\n### 弹层状态\n- 加载态\n- 错误态\n- 重试按钮\n- 失败时可退回普通详情页\n\n---\n\n## 4. 仓库结构\n\n```text\nwp-modal-blog-repo/\n├─ index.html\n├─ README.md\n├─ .gitignore\n├─ assets/\n│  ├─ css/\n│  │  └─ style.css\n│  └─ js/\n│     └─ app.js\n└─ theme/\n   └─ insight-journal/\n      ├─ style.css\n      ├─ functions.php\n      ├─ header.php\n      ├─ footer.php\n      ├─ index.php\n      ├─ home.php\n      ├─ archive.php\n      ├─ single.php\n      ├─ comments.php\n      ├─ searchform.php\n      ├─ assets/\n      │  ├─ css/\n      │  │  └─ theme.css\n      │  └─ js/\n      │     └─ modal-route.js\n      └─ template-parts/\n         ├─ content-card.php\n         ├─ content-single.php\n         └─ content-single-modal.php\n```\n\n---\n\n## 5. 文件用途速查\n\n### 根目录：静态预览\n\n| 文件 | 用途 |\n|---|---|\n| `index.html` | 静态预览入口，演示列表 + 全屏详情弹层 |\n| `assets/css/style.css` | 静态预览样式 |\n| `assets/js/app.js` | 静态预览交互逻辑：模拟数据、弹层、路由状态、分享与相关文章 |\n\n### WordPress 主题主文件\n\n| 文件 | 用途 |\n|---|---|\n| `theme/insight-journal/style.css` | 主题头信息与基础入口样式 |\n| `theme/insight-journal/functions.php` | 主题支持、资源加载、自定义 REST 接口、阅读时长、分享链接、相关文章数据 |\n| `theme/insight-journal/header.php` | 页面头部 |\n| `theme/insight-journal/footer.php` | 页面尾部 |\n| `theme/insight-journal/home.php` | 博客首页 / 文章列表 |\n| `theme/insight-journal/archive.php` | 分类 / 标签 / 归档页 |\n| `theme/insight-journal/index.php` | 模板兜底 |\n| `theme/insight-journal/single.php` | 单篇文章页 |\n| `theme/insight-journal/comments.php` | 评论列表与表单 |\n| `theme/insight-journal/searchform.php` | 搜索表单 |\n\n### 主题模板片段\n\n| 文件 | 用途 |\n|---|---|\n| `template-parts/content-card.php` | 单张文章卡片 |\n| `template-parts/content-single.php` | 单篇文章正文、作者卡、分享区、相邻文章、相关文章 |\n| `template-parts/content-single-modal.php` | 列表页中的全局弹层壳子 |\n\n### 主题前端资源\n\n| 文件 | 用途 |\n|---|---|\n| `assets/css/theme.css` | 主题视觉样式 |\n| `assets/js/modal-route.js` | 列表页拦截文章点击、请求 REST、渲染弹层、处理历史记录 |\n\n---\n\n## 6. 如何安装主题\n\n### 方法一：直接安装主题 ZIP\n\n1. 打开 WordPress 后台\n2. 进入 **外观 → 主题 → 添加主题 → 上传主题**\n3. 上传 `theme/insight-journal/` 打包后的 ZIP\n4. 安装并启用主题\n\n### 方法二：手动放入主题目录\n\n把目录：\n\n```text\ntheme/insight-journal/\n```\n\n复制到：\n\n```text\nwp-content/themes/\n```\n\n然后在后台启用 **Insight Journal** 主题。\n\n---\n\n## 7. 安装后建议设置\n\n为了让主题看起来接近预期，建议先完成这些内容准备：\n\n1. 发布几篇文章\n2. 给文章设置：\n   - 特色图\n   - 分类\n   - 标签\n   - 摘要\n3. 在 **设置 → 阅读** 中设置博客首页或最新文章页\n4. 在 **设置 → 讨论** 中开启评论（如果你需要评论区）\n\n这样列表卡片、相关文章、相邻文章和评论区都会更完整。\n\n---\n\n## 8. 静态预览与 WordPress 主题的关系\n\n### 静态 HTML 预览负责什么\n\n静态预览只负责演示：\n\n- 卡片网格布局\n- 全屏详情弹层结构\n- 打开 / 关闭动画与交互逻辑\n- URL 查询参数驱动的弹层体验\n- 作者卡、分享按钮、相关文章的视觉布局\n\n它不依赖 WordPress，也不具备真实内容管理能力。\n\n### WordPress 主题负责什么\n\n主题部分才是真正可运行的动态版本：\n\n- 文章内容来自 WordPress 数据库\n- 卡片列表来自 Loop\n- 单篇页来自 `single.php`\n- 评论来自 WordPress 评论系统\n- 弹层数据来自自定义 REST 接口\n- 相关文章与相邻文章根据真实文章数据生成\n\n---\n\n## 9. REST 接口说明\n\n主题注册了一个自定义接口：\n\n```text\n/wp-json/insight/v1/post/{id}\n```\n\n这个接口的用途是：\n\n- 给列表页弹层提供“单篇详情数据”\n- 避免在打开弹层时整页刷新\n\n返回字段大致包括：\n\n- `id`\n- `title`\n- `excerpt`\n- `content`\n- `permalink`\n- `date`\n- `reading_time`\n- `categories`\n- `tags`\n- `featured_image`\n- `author`\n- `share`\n- `adjacent`\n- `related`\n\n这样前端只需要请求一次，就能把弹层详情完整渲染出来。\n\n---\n\n## 10. 后续扩展建议\n\n这套主题现在已经具备“展示型博客主题”的核心骨架。后续可以继续扩展：\n\n- 搜索结果页增强\n- 分类筛选与标签筛选\n- 404 页面与空状态页\n- 文章目录（TOC）\n- 暗色 / 浅色主题切换\n- AJAX 评论提交\n- 阅读进度条\n- 自定义文章类型支持\n\n---\n\n## 11. 适用场景\n\n这个主题特别适合以下类型的网站：\n\n- 设计 / 开发博客\n- 研究笔记型博客\n- 产品更新日志站点\n- 杂志风文章站\n- 需要兼顾“浏览连续性”和“真实文章链接”的内容站\n\n如果你的核心诉求是：\n\n- 列表页浏览流畅\n- 文章详情可分享\n- 详情既能弹层展示，也能独立访问\n\n那么这套结构就是比较合适的起点。\n\n---\n\n## 自由开发版说明\n\n本项目同时适合作为一个可继续扩展的 **自由开发版基础主题** 使用。\n\n你可以在当前结构上继续进行二次开发，包括但不限于：\n\n- 自定义首页布局\n- 扩展文章卡片字段与筛选条件\n- 优化全屏详情弹层交互\n- 接入分类、标签、搜索与相关文章推荐\n- 增加分享、点赞、阅读统计等内容功能\n- 对接自定义文章类型（Custom Post Type）\n- 替换为自己的设计系统或品牌样式\n\n### 适合的使用方式\n\n- 作为博客主题原型继续深化\n- 作为企业内容站 / 杂志站的开发起点\n- 作为 WordPress 前端交互主题研究样板\n- 作为静态原型 + 动态主题双版本工程基础\n\n### 开发说明\n\n当前仓库保留了两套结构：\n\n1. **静态 HTML 预览版**  \n   用于 GitHub 页面预览、样式确认与前端交互演示。\n\n2. **WordPress 动态主题版**  \n   用于实际部署到 WordPress 环境中，结合文章、分类、评论、作者、相关文章等动态内容运行。\n\n### 二次开发建议\n\n建议优先按以下顺序继续扩展：\n\n1. 完善列表页筛选与搜索体验  \n2. 增强详情弹层的数据加载、动画与状态管理  \n3. 补充 404 页面、无结果页面、归档页细节  \n4. 接入更多 WordPress 原生能力或自定义字段系统  \n5. 根据项目需要拆分为更细粒度的模板组件\n\n### 注意\n\n本项目当前版本更适合作为一个 **可视化明确、结构清晰、便于继续开发的主题基础工程**。  \n如果你计划用于正式上线环境，建议继续补充以下内容：\n\n- 更完整的响应式适配\n- 更严格的可访问性优化\n- 更完善的异常状态处理\n- 更细致的 SEO 输出\n- 更完整的性能优化与缓存策略\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoowinit%2Fwp-fullscreen-post-modal-theme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoowinit%2Fwp-fullscreen-post-modal-theme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoowinit%2Fwp-fullscreen-post-modal-theme/lists"}