---

title: 掌控习惯 - Obsidian 习惯追踪插件 date: 2026-01-10 category:

• Obsidian tag:
• 插件开发
• TypeScript

---

掌控习惯 - Obsidian 习惯追踪插件

基于日记文件的习惯打卡追踪插件，使用习惯列表 + 最近7天圆点展示打卡记录。

✨ 功能特点

• 📊 习惯列表：清晰展示所有习惯及其打卡情况
• 🔵 7天圆点：最近7天的打卡状态一目了然
• 🔥 连续打卡：自动计算连续打卡天数
• ⏰ 时间筛选：本周、上周、本月、上月快速切换
• 📈 统计分析：查看习惯完成次数和趋势
• ⚙️ 自定义配置：自由配置习惯关键词和名称
• 🎨 Notion 风格：现代化的用户界面
• 🚀 性能优化：只扫描日期格式文件，快速加载
• 💾 智能缓存：30秒缓存 + 文件监听自动更新

安装方法

方式一：从 GitHub Release 安装（推荐）

1. 前往 Releases 页面下载最新版本
2. 下载以下文件：
   • main.js
   • manifest.json
   • styles.css
   • config.json
3. 在你的 Obsidian 库中创建插件目录：.obsidian/plugins/obsidian-habit-tracker/
4. 将下载的文件复制到该目录
5. 重启 Obsidian 或刷新插件列表
6. 在设置中启用"掌控习惯"插件

方式二：手动安装

cd /path/to/your/vault/.obsidian/plugins
git clone https://github.com/你的用户名/obsidian-habit-tracker.git
cd obsidian-habit-tracker
npm install
npm run build

📝 快速开始

1. 在日记中打卡

在你的日记文件（如 journals/2024-01-10.md）中，使用标签形式记录打卡：

# 2024年1月10日

今天完成的习惯：
#reading
#exercise
#meditation

或者在句子中：
今天完成了 #reading 和 #exercise，感觉很棒！

2. 查看统计

点击左侧边栏的 ✓ 图标，或使用命令面板搜索"打开掌控习惯"，即可查看：

• 总打卡次数
• 追踪习惯数
• 各习惯完成情况
• 连续打卡天数
• 最近7天打卡圆点

3. 时间筛选

使用顶部的时间筛选按钮：

• 本周：显示本周的打卡记录
• 上周：显示上周的打卡记录
• 本月：显示本月的打卡记录（默认）
• 上月：显示上月的打卡记录

4. 配置习惯

点击"配置习惯"按钮，可以：

• 基础设置：自定义应用名称（默认"掌控习惯"）
• 习惯管理：添加/删除习惯，修改关键词和中文名称

⚙️ 配置说明

默认习惯

• reading - 阅读
• sp - 运动
• en - 学习
• sleep - 早睡

自定义习惯

在配置界面的"习惯管理"标签页中：

1. 点击"+ 添加新习惯"
2. 输入关键词（英文，用于在日记中标记）
3. 输入中文名称（用于显示）
4. 点击"保存"

自定义应用名称

在配置界面的"基础设置"标签页中：

1. 输入你想要的应用名称（如"我的习惯"）
2. 实时预览效果
3. 点击"保存"后，标签页、页面标题、功能区图标都会更新

配置文件

插件使用 config.json 文件进行配置：

{
    "appName": "掌控习惯",
    "habits": {
        "reading": "阅读",
        "sp": "运动",
        "en": "学习",
        "sleep": "早睡"
    },
    "habitPrefix": "#",
    "journalsPath": "journals"
}

📊 习惯列表视图

每个习惯显示：

• 习惯名称：配置的中文名称
• 打卡次数：在选定时间范围内的总打卡次数
• 连续天数：当前连续打卡天数（带火焰图标 🔥）
• 7天圆点：最近7天的打卡状态
  • 绿色圆点：已打卡
  • 灰色圆点：未打卡
  • 鼠标悬停显示日期

🔥 连续打卡

• 自动计算每个习惯的连续打卡天数
• 只有今天或昨天有打卡才会显示连续天数
• 中断后重新开始计算

🎯 最佳实践

1. 每天记录：养成每天在日记中记录习惯的习惯
2. 标签形式：使用 #关键词 的标签形式，简单明了
3. 灵活使用：可以在任何地方使用标签，不限格式
4. 定期回顾：通过7天圆点和时间筛选回顾自己的坚持情况
5. 适量习惯：不要追踪太多习惯，专注于最重要的几个

🚀 性能优化

• 只扫描 yyyy-mm-dd.md 格式的日记文件
• 30秒智能缓存，避免重复扫描
• 文件变化自动检测，立即更新缓存
• 批量并行处理，快速加载

常见问题

Q: 为什么看不到打卡记录？
A: 确保日记文件在 journals 目录下，文件名是 yyyy-mm-dd.md 格式，使用了正确的标签格式（如 #reading）

Q: 如何修改应用名称？
A: 点击"配置习惯"按钮，切换到"基础设置"标签页，输入新名称并保存

Q: 连续天数为什么是0？
A: 连续天数只有在今天或昨天有打卡时才会显示。如果中断了，会重新开始计算

Q: 数据更新不及时怎么办？
A: 点击"刷新数据"按钮手动刷新，或等待30秒缓存自动更新

开发

# 开发模式
npm run dev

# 构建
npm run build

# 部署到本地vault
npm run deploy

# 发布到GitHub
npm run release

License

MIT

---

💪 开始使用掌控习惯，养成好习惯！