# Home Pages 使用手册

**给 Obsidian 一个可拼装的首页：12 列自适应网格上自由增删、拖拽、缩放组件，桌面与手机通用。**

插件版本 0.1.0 · 最低 Obsidian 1.7.2 · 桌面端与移动端（iOS / Android）· 免费开源（GPL-3.0）

源码与安装包：[github.com/jepicaju862-lab/home-pages](https://github.com/jepicaju862-lab/home-pages)

> **本地优先。** 布局、番茄钟记录与打卡数据都保存在本地 Vault 的 `data.json`，插件不收集使用数据，也没有后台分析脚本。只有在你配置了天气数据源后，欢迎横幅才会向对应服务发起天气查询。

---

## 1. 安装

### 1.1 手动安装（当前方式）

插件已提交 Obsidian 官方社区插件市场，审核通过前请手动安装：

1. 前往 [GitHub Releases](https://github.com/jepicaju862-lab/home-pages/releases) 下载最新版本的三个文件：`main.js`、`manifest.json`、`styles.css`。
2. 在库目录下进入 `.obsidian/plugins/`，新建 `home-pages` 文件夹。
3. 把三个文件放进该文件夹。
4. 在 Obsidian「设置 → 第三方插件」中重新加载并启用 **Home Pages**。

### 1.2 官方社区市场（上架后）

1. 打开「设置 → 第三方插件」，关闭「受限模式」。
2. 点击社区插件的「浏览」，搜索 **Home Pages**。
3. 点击「安装」，完成后点击「启用」。

## 2. 打开首页

- 单击左侧功能区（Ribbon）的首页图标；
- 或按 `Ctrl/Cmd + P` 打开命令面板，执行 **Home Pages: 打开首页**。

默认在 Obsidian 启动时自动打开首页，可在设置中关闭。

## 3. 编辑布局

首页标题栏右侧点击 **编辑布局** 进入编排模式：

| 操作 | 方式 |
| --- | --- |
| 添加组件 | 顶部「添加组件」，在弹窗中挑选 |
| 重排 | 拖拽卡片 |
| 调宽 | 卡片底部「宽 − / +」，1–12 列 |
| 调高 | 卡片底部「高 − / +」，按网格行数 |
| 前移 / 后移 / 复制 / 删除 | 卡片底部对应按钮 |
| 修改组件配置 | 卡片右上角齿轮图标 |

编辑完成后点击右上角 **完成**。

### 3.1 多页面

- 标签栏的「+」可新建多个独立首页，例如「工作台」「生活记录」「项目仪表盘」。
- 右键标签页可重命名、拖拽排序或删除。
- 单页面时标签栏默认隐藏，可在设置中改为常驻。

### 3.2 布局导入 / 导出

「设置 → Home Pages → 页面」提供 JSON 格式的完整布局与组件配置导出，可跨设备、跨库迁移，也可作为备份。要恢复初始布局，点击「＋ 新建默认布局页面」。

## 4. 内置组件

| 组件 | 功能 | 主要配置项 |
| --- | --- | --- |
| 欢迎横幅 | 时段问候、称呼、笔记与标签总量、实时时钟、天气、库龄与目标倒计时徽章、自定义背景图 | 天气源（中国气象局国家站 / Open-Meteo / 和风天气）、城市、背景遮罩、各字段开关、库龄起算日、目标日期 |
| 最近笔记 | 最近修改或创建的笔记列表，点击打开 | 条数、文件夹白名单 / 黑名单、排序方式、显示父目录 |
| 快捷入口 | 置顶常用笔记、文件夹或任意附件的图标磁贴 | 路径联想、自定义名称、Lucide 图标、排序、每行列数 |
| 倒计时与纪念日 | 距目标日还有多少天，或纪念日已过多少天 | 目标日期、方向、备注 |
| 番茄专注时钟 | 专注 / 短休息 / 长休息循环计时，带进度环与今日 / 本周完成数；切页或重启后继续计时 | 工作与休息时长、长休息间隔、自动轮转、提示音、系统通知 |
| 每日一言 | 从指定笔记（一行一条）或内置语录中每天取一句 | 来源笔记、按天轮换或随机、自定义语录 |
| 习惯打卡 | 今日打卡清单 + GitHub 风格热力图（周 / 月 / 年） | 习惯列表、存储位置（插件本地 / Daily Note 任务块） |
| 任务看板 | 提取笔记中的 `- [ ]` 待办，按待办 `[ ]` / 进行中 `[/]` / 已完成 `[x]` 三列分栏；拖拽换列、回车新增、双击编辑 | 来源过滤、默认收集箱、列标题、隐藏已完成 |
| 全库统计 | 笔记总数、标签数、估算字数、附件数、文件夹数、库龄、今日新建、本周修改 | 指标开关、分列数、排除文件夹 |
| 那年今日 | 往年同月同日创建或记录的笔记 | 条数、日期属性字段、按文件名日期回退 |
| 笔记嵌入 | 把任意笔记正文（或指定标题下的内容）渲染在首页上 | 笔记路径、定位标题、隐藏 Frontmatter |

### 4.1 联动组件

以下组件依赖对应插件，未安装时不显示数据：

| 组件 | 数据来源 | 作用 |
| --- | --- | --- |
| 待办与日程 | 库内 `.duowei` 多维表格 | 提取逾期、今天、待办与最近更新，直达表格行与关联笔记 |
| 微信收件箱 | WeChat2Ob 或个人收件箱 | 查看文字、语音转写与图片缩略图，快速标记已整理 |
| 批注与复习 | Mobile Ink Annotation Pro | 待处理批注、复习进度与题库收藏，一键打开批注中心 |
| 聚合信息流（可选） | 以上三个来源 | 合成一条信息流；只想要一张卡片时用它 |

多维表格 `duowei-table-pro ≥ 1.4.0` 还通过宿主 API 注册了 `duowei-view`：在表格视图上右键「固定到首页」，即可把看板、日历、时间线或甘特图直接放进首页。

## 5. 全局设置

打开「设置 → Home Pages」：

| 设置项 | 说明 | 默认 |
| --- | --- | --- |
| 启动时自动打开 | 启动 Obsidian 时打开默认首页 | 开启 |
| 在新标签页中打开 | 关闭则复用当前标签页 | 开启 |
| 行高 | 网格高度单位，24–96px | 36px |
| 间距 | 卡片之间的网格边距，4–40px | 12px |
| 内容最大宽度 | 0 表示全屏铺满 | 0 |
| 始终显示页面标签栏 | 单页面时也常驻标签栏 | 关闭 |
| 页面管理 | 增删、复制、重命名多首页 | 默认首页 |
| 布局导入 / 导出 | JSON 备份与恢复 | — |

## 6. 给其他插件的宿主 API

Home Pages 开放了轻量的宿主 API，第三方插件可以向首页注册自定义卡片：

```ts
// 首页插件加载完成后获取 API（也可监听 "home-pages:ready" 事件）
const api = app.plugins.plugins["home-pages"]?.api;

// 注册组件类型（渲染、配置表单与默认值）
const unregister = api.registerWidget(myWidgetDefinition, "my-plugin-id");

// 把卡片固定到当前首页
api.pinWidget("my-widget-kind", { ref: "note-path" }, {
  title: "我的自定义卡片", w: 6, h: 4, provider: "my-plugin-id"
});

// 源数据变化时触发重绘
api.refresh("my-widget-kind");

// 与内置组件风格一致的 UI 助手
api.ui.renderKpi(containerEl, { label: "今日完成", value: 12 });
api.ui.renderEmpty(containerEl, { message: "暂无数据" });
```

## 7. 数据与隐私

- 所有布局、番茄钟记录、习惯打卡数据保存在本地 Vault 的 `data.json`。
- 不收集使用数据，没有后台分析脚本。
- 天气：中国气象局数据源直接请求国家气象公开接口，免 API Key；Open-Meteo 与和风天气仅在你选择对应数据源后才发起标准天气查询。
- 构建时通过 `scripts/verify-bundle.mjs` 审查，禁止 `eval()`、动态 `createElement('script')` 与 `new Function()`。

## 8. 常见问题

| 情况 | 说明 |
| --- | --- |
| 手机端布局会乱吗 | 不会。窄屏下 12 列网格自动折成全宽单列或紧凑双列，触控与阅读均可用 |
| 番茄钟切页或重启后还计时吗 | 会。计时起点与状态持久化在插件后台，切换笔记、重绘视图或重启 Obsidian 都能恢复并准时提醒 |
| 如何恢复初始布局 | 「设置 → Home Pages → 页面」点击「＋ 新建默认布局页面」 |
| 联动组件没有数据 | 确认已安装并启用对应插件（Duowei Table Pro / WeChat2Ob / Mobile Ink Annotation Pro） |
| 天气不显示 | 在欢迎横幅的齿轮里选择天气源并指定城市；和风天气需要自己的 Key |

## 9. 反馈

- Bug 与建议：[GitHub Issues](https://github.com/jepicaju862-lab/home-pages/issues)，请附 Obsidian 版本、操作系统与复现步骤。
- 使用交流：QQ 群 `1094620986`。
- 邮件：jepicaju862@gmail.com。