nxxy335/halo-theme-WarmIsland
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

first commit

Browse Source
This commit is contained in:
nxxy335top
2026-05-18 17:29:18 +08:00
parent e85fbd62f4
commit a0c64736eb
119 changed files with 13527 additions and 1228 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -97
View File
@@ -1,121 +1,73 @@
# Theme Astro Starter
# WarmIsland 暖屿
面向 [Halo](https://www.halo.run/) 的主题脚手架：以 **Astro** 作为预渲染框架，将组件与页面编译为干净的 HTML，交由 **Thymeleaf** 在运行时完成数据渲染。
一座深夜里温暖、安静、治愈的小岛 — 具有独特气质的生活博客主题。
官方主题开发指南：<https://docs.halo.run/developer-guide/theme/prepare>
> 本项目由AI开发完成，人工仅进行部分功能测试及问题找寻
## 为什么选择 Astro？
## 已适配插件
Halo 主题采用 Thymeleaf 纯后端渲染方案，传统上只能在 HTML 文件里直接写 Thymeleaf 语法。这对简单主题足够用，但若需要 Vue / React 组件或复杂的前端交互，就会很局限。
| 插件名称 | 插件标识 | 适配页面路由 | 说明 |
|----------|---------|-------------|------|
| [瞬间](https://halo.run/store/apps/app-SnwWD) | `PluginMoments` | `/moments` | 瞬间动态页面，支持点赞、评论、标签筛选 |
| [图库](https://halo.run/store/apps/app-BmQJW) | `PluginPhotos` | `/photos` | 图片展示页面，支持分组、灯箱预览 |
| [友情链接](https://halo.run/store/apps/app-hqbe) | `PluginLinks` | `/links` | 友链展示页面，支持分组展示 |
| [朋友圈](https://github.com/halo-sigs/plugin-friends) | `plugin-friends` | `/friends` | RSS 订阅朋友圈页面 |
| [我的装备](https://github.com/halo-sigs/plugin-equipment) | `equipment` | `/equipment` | 装备展示页面，支持分组展示 |
Astro 的特点恰好弥补了这一短板：
> **注意**：插件需要单独安装，安装后主题会自动适配对应页面。若未安装某插件，对应页面会显示提示信息。
- **输出干净的 HTML**：Astro 不同于 SPA 框架，其默认产物是纯 HTML 文件，而不是 JS 包。Thymeleaf 的属性（`th:text`、`th:if`、`th:replace` 等）会作为普通 HTML 属性原样保留，两者互不干扰。
- **Island 架构**：仅在真正需要交互的地方注入客户端 JS（Vue / React 组件），其余部分零 JS 开销。
- **组件化开发体验**：通过 Astro 组件的 `slot` 与 `props` 在 **编译阶段** 组织布局与复用，最终产物是 Thymeleaf 可直接使用的 HTML 模板。
## 安装
## 何时选择此 Starter？
1. 下载主题最新 Release 的 ZIP 包
2. 进入 Halo 后台 → 主题管理 → 安装主题 → 上传 ZIP 包
3. 安装完成后点击「启用」
| 场景 | 推荐 |
| ------------------------------------------------------- | ----------------------------------------------------------------------------- |
| 主题有较多前端交互，希望用 Vue / React 编写 Island 组件 | **本 Starter** |
| 主题以静态展示为主，前端交互需求较少 | [halo-dev/theme-vite-starter](https://github.com/halo-dev/theme-vite-starter) |
或从源码构建：
## 技术栈
| 类别 | 说明 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 运行时 | Halo 使用 **Thymeleaf** 渲染主题；模板变量与 Finder API 随 Halo 版本演进，请以[官方文档](https://docs.halo.run/developer-guide/theme/prepare)为准 |
| 预渲染 | **Astro**，将 `src/` 下的页面与组件编译为 `templates/` 下的纯 HTML |
| UI 框架 | **Vue 3**（通过 `@astrojs/vue` 集成，用于编写 Island 组件） |
| 语言 | TypeScript（Astro 组件 frontmatter 支持） |
| 包管理 | **pnpm** |
## 核心概念：Astro 编译期 vs Thymeleaf 运行期
理解这两个阶段的边界是使用本 Starter 的关键：
```
开发时 构建后 Halo 运行时
───────────────────────────── ────────────────────── ──────────────────────────
src/pages/index.astro → templates/index.html → Thymeleaf 注入数据渲染
Astro 组件 / slot / props 干净的 HTML + th:text / th:if 生效
Vue Island 组件 Thymeleaf 属性原样 客户端 JS 激活 Island
```bash
git clone https://github.com/warm-island/theme-warm-island.git
cd theme-warm-island
npm install
npm run build
```
**重要限制**：
构建产物在 `templates/` 目录下，将其复制到 Halo 主题目录即可。
- `slot`、`props` 是 Astro **编译期**的概念，Thymeleaf 运行时感知不到它们，也无法向 Astro 组件传递动态数据。
- 在 Astro 组件中可以直接写 `th:text`、`th:if`、`th:replace` 等 Thymeleaf 属性——Astro 会将其视为普通 HTML 属性原样输出，Thymeleaf 在运行时才会处理它们。
- Vue / React Island 组件（`client:*`）的数据来源是客户端（例如调用 Halo API），无法直接使用 Thymeleaf 的服务端变量。
## lightgallery.js 灯箱插件集成
## 目录结构
如果你使用 [lightgallery.js](https://www.lightgalleryjs.com/) 灯箱插件来为图片添加放大预览功能，以下是各页面的路径匹配规则和 DOM 节点选择器：
```
.
├── src/
│ ├── pages/ # Astro 页面（编译为 templates/ 下的 HTML）
│ │ ├── index.astro
│ │ ├── post.astro
│ │ ├── category.astro
│ │ └── ...
│ ├── layouts/
│ │ └── Layout.astro # 全局布局组件
│ ├── components/
│ │ ├── Header.astro
│ │ ├── Footer.astro
│ │ ├── ThemeSwitcher.vue # Vue Island 示例
│ │ └── ...
│ └── styles/ # 全局样式
├── public/ # 原样复制到 templates/：静态资源或纯 Thymeleaf 模板均可放此处
│ └── fragments/ # 纯 Thymeleaf 片段示例（不经 Astro 编译，直接输出）
├── templates/ # Astro 构建产物（Halo 实际读取的模板目录）
├── theme.yaml # 主题元数据（必填）
├── settings.yaml # 控制台主题设置表单（可选）
├── astro.config.mjs
└── package.json
```
### 路径匹配与 DOM 节点
> **`templates/` 是构建产物**，不要直接在此目录手动修改；请修改 `src/` 后重新构建。
| 页面 | 路径匹配规则 | 匹配区域 DOM 节点 |
|------|-------------|-------------------|
| 文章详情页 | `/archives/*` | `.wi-post__body` |
| 瞬间页 | `/moments` | `.wi-moments-page__content` |
| 图库页 | `/photos` | `.wi-photos-page__grid` |
| 自定义页面 | 用户自定义 | `.wi-page__body` |
> **注意**：自定义页面的路径匹配由用户自行设定，此处仅提供 DOM 节点选择器 `.wi-page__body`。
## 开发
```bash
git clone https://github.com/halo-sigs/theme-astro-starter.git ~/halo2-dev/themes/astro-starter
cd ~/halo2-dev/themes/astro-starter
pnpm install
pnpm dev
# 安装依赖
npm install
# 开发模式（监听文件变化）
npm run dev
# 构建
npm run build
```
`pnpm dev` 会启动 Astro 开发服务器并监听 `src/` 变更，实时重新生成 `templates/`。
## 技术栈
将主题目录链接或复制到 Halo 的 `themes/astro-starter/` 后，在控制台安装并启用主题即可预览。建议同时关闭 Thymeleaf 缓存以便热更新调试：
- [Halo](https://halo.run) 2.24+
- [Astro](https://astro.build) + [vite-plugin-halo-theme](https://github.com/halo-sigs/vite-plugin-halo-theme)
- [Thymeleaf](https://www.thymeleaf.org) 模板引擎
- [Vue 3](https://vuejs.org) Islands 交互组件
```yaml
# application.yaml
spring:
thymeleaf:
cache: false
```
## 许可
或通过环境变量：`SPRING_THYMELEAF_CACHE=false`
## 构建
```bash
pnpm build
```
执行 Astro 构建，将 `src/` 编译输出到 `templates/`。构建完成后可将主题目录（含 `templates/`、`theme.yaml`、`settings.yaml` 等）打包为 ZIP 上传到 Halo 控制台，或使用 [`@halo-dev/theme-package-cli`](https://github.com/halo-dev/theme-package-cli) 完成打包。
## 其他脚本
| 命令 | 作用 |
| ------------- | ----------------------- |
| `pnpm format` | Prettier 格式化所有文件 |
## 注意事项
- Astro 配置中 `base` 需与 `theme.yaml` 的 `metadata.name` 保持一致（当前为 `astro-starter`），这决定了静态资源的引用路径。
- `public/` 目录不仅可以存放图片、字体等静态资源，也可以存放**纯 Thymeleaf 模板**（例如 `public/fragments/post-list.html`）。这些文件会被 Astro 原样复制到 `templates/` 对应路径，不经过任何编译处理，适合编写不需要 Astro 组件化的 Thymeleaf 片段。
- Vue Island 组件可通过 Halo 提供的 [API Client](https://www.npmjs.com/package/@halo-dev/api-client) 在客户端获取数据。
[GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.en.html)