# Joplin Habit Tracker

[English](README.md)

在 Joplin 笔记中以热力图方式追踪日常习惯，支持年、月、周三种视图。

![Habit Tracker Screenshot](assets/habit-tracker-demo.webp)

## 功能特性

- 在任意笔记中嵌入 `habitmap` 代码块，渲染为交互式热力图
- 支持年视图（全年热力图）、月视图（日历网格）、周视图（横排单周）
- 点击任意格子切换打卡状态，再次点击取消
- 多习惯独立追踪，互不干扰
- 支持语言切换（English / 中文）
- 支持每周起始日设置（周日 / 周一）
- 数据存储在专用 Joplin 笔记中，随 Joplin 同步到所有设备
- 支持亮色/深色主题

## 安装

### 方式一：从 .jpl 文件安装（推荐）

1. 从 [Releases 页面](https://github.com/Mdreame/Joplin-Habit-Tracker/releases) 下载最新的 `.jpl` 文件
2. 在 Joplin 中打开：**Preferences → Plugins → Install from file**
3. 选择 `.jpl` 文件，重启 Joplin

### 方式二：从源码构建

```bash
git clone https://github.com/Mdreame/Joplin-Habit-Tracker.git
cd Joplin-Habit-Tracker
pnpm install   # 安装依赖并自动构建
```

构建产物在 `publish/` 目录下，按方式一安装即可。

## 使用方法

### 基本语法

在笔记中插入代码块，切换到预览模式（或分栏模式）即可看到热力图。**点击任意格子**切换该日期的打卡状态：

````markdown
```habitmap
habit: 运动
year: 2026
```
````

### 配置项说明

| 字段 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- |
| `habit` | 是 | 习惯名称，作为数据存储的唯一 key | `habit: 运动` |
| `view` | 否 | 视图类型：`year` / `month` / `week`，默认 `year` | `view: month` |
| `year` | 否 | 年份，默认当前年 | `year: 2026` |
| `month` | 否 | 月份 1–12，仅 `month` 视图使用，默认当前月 | `month: 5` |
| `week` | 否 | ISO 周数，仅 `week` 视图使用，默认当前周 | `week: 19` |
| `title` | 否 | 显示标题，不填则使用 habit 名称 | `title: 每日跑步` |

### 年视图（默认）

全年 53 列热力图，左侧标注第 1、3、5、7 行对应的星期：

````markdown
```habitmap
habit: 运动
view: year
year: 2026
```
````

### 月视图

传统日历网格，列标题为 Sun–Sat 或 Mon–Sun（取决于每周起始日设置）：

````markdown
```habitmap
habit: 运动
view: month
year: 2026
month: 5
```
````

### 周视图

单周横排 7 格，每格上方显示星期名，下方显示月/日：

````markdown
```habitmap
habit: 运动
view: week
year: 2026
week: 19
```
````

### 多习惯、多视图混排

同一笔记中可放任意数量的 `habitmap` 块：

````markdown
```habitmap
habit: 运动
title: 每日运动
```

```habitmap
habit: 读书
view: month
title: 每日阅读
```

```habitmap
habit: 冥想
view: week
```
````

### 查看历史数据

修改 `year` / `month` / `week` 字段即可回溯历史记录，所有视图共享同一份数据：

````markdown
```habitmap
habit: 运动
view: month
year: 2025
month: 12
```
````

## 插件设置

**工具 → 选项 → Habit Tracker**：

| 设置项 | 选项 | 说明 |
| --- | --- | --- |
| Week starts on / 每周起始 | Sunday / 周日，Monday / 周一 | 控制年视图和月视图的起始列 |
| Language / 语言 | English，中文 | 切换月份名称、星期标签及副标题格式 |

## 数据存储

所有打卡数据存储在标题为 `__habit-tracker-data__` 的笔记中，格式为 JSON：

```json
{
  "运动": {
    "2026-05-01": 1,
    "2026-05-08": 1,
    "2026-05-09": 1
  },
  "读书": {
    "2026-05-03": 1
  }
}
```

该笔记在**首次打卡后**自动创建，**不建议手动删除**。可直接编辑 JSON 来批量修正或导入历史数据。

## 开发

**环境要求：** Node.js ≥ 18、pnpm ≥ 9

```bash
pnpm install        # 安装依赖
pnpm dist           # 构建插件（生成 .jpl 文件）
pnpm updateVersion  # 自动递增 package.json 和 manifest.json 的版本号
```

本地调试无需每次安装 `.jpl`：在 Joplin 中选择 **工具 → 插件 → 开发者选项 → 加载开发插件**，指向项目的 `dist/` 目录即可热加载。

## 项目结构

```text
Joplin-Habit-Tracker/
├── api/                          # Joplin Plugin API 类型声明
│   ├── index.ts                  # 导出类型化的 joplin 全局对象
│   ├── types.ts                  # 枚举：ContentScriptType、SettingItemType 等
│   └── Joplin.d.ts               # 插件中用到的所有 joplin.* API 接口定义
├── src/
│   ├── manifest.json             # 插件元数据（id、名称、版本、分类）
│   ├── index.ts                  # 插件入口：
│   │                             #   - 注册设置项（weekStart、language）
│   │                             #   - 注册 MarkdownIt content script
│   │                             #   - 处理消息：loadData / checkIn / getSettings
│   └── contentScript/
│       ├── habitmap.ts           # Markdown-it 插件（服务端渲染）：
│       │                         #   - 拦截 ```habitmap 代码块
│       │                         #   - 解析配置（habit、view、year、month、week、title）
│       │                         #   - 输出带 data-* 属性的容器 HTML
│       ├── habitmap-runtime.js   # 浏览器端运行时（作为渲染器 asset 加载）：
│       │                         #   - 通过 webviewApi.postMessage 获取数据和设置
│       │                         #   - 构建年/月/周格子 DOM
│       │                         #   - 处理格子点击 → 切换 → 重新渲染
│       │                         #   - 通过 MutationObserver 监听新容器
│       └── habitmap.css          # 三种视图的样式及深色模式适配
├── plugin.config.json            # 声明 habitmap.ts 为需要单独编译的 extra script
├── webpack.config.js             # Joplin 官方标准构建脚本
├── tsconfig.json                 # TypeScript 编译配置
└── package.json                  # 依赖和构建脚本
```

## 许可证

MIT