Joplin Habit Tracker

English

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

功能特性

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

安装

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

1. 从 Releases 页面 下载最新的 .jpl 文件
2. 在 Joplin 中打开：Preferences → Plugins → Install from file
3. 选择 .jpl 文件，重启 Joplin

方式二：从源码构建

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

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

使用方法

基本语法

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

```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 行对应的星期：

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

月视图

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

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

周视图

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

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

多习惯、多视图混排

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

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

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

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

查看历史数据

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

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

插件设置

工具 → 选项 → Habit Tracker：

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

数据存储

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

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

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

开发

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

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

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

项目结构

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