🔥 Humble Heatmap - 智能家居温湿度热力图卡片

一个功能强大的 Home Assistant 自定义卡片，在房屋平面图上实时显示温湿度热力图，让你的智能家居数据可视化更加直观美观。

📸 截图说明: 实际使用时，你将看到基于真实传感器数据的动态热力图，叠加在你的房屋平面图上，实时显示各区域的温湿度分布。

✨ 核心特性

🌡️ 智能数据可视化

实时热力图渲染 - 基于 Canvas 的高性能热力图引擎
温度/湿度双模式 - 一键切换不同传感器类型
自适应颜色渐变 - 智能温度范围映射和颜色插值
数据标准化处理 - 自动处理缺失数据和异常值

🎨 丰富的视觉效果

自定义背景图片 - 支持房屋平面图叠加显示
可调节视觉参数 - 热力半径、模糊度、透明度全面可控
友好名称显示 - 传感器标签和数值格式化
响应式设计 - 适配各种屏幕尺寸

⚡ 性能优化

智能渲染控制 - 可见性检测和渲染暂停
资源管理 - 自动清理和内存优化
刷新频率控制 - 可配置的数据更新间隔
错误恢复机制 - 健壮的错误处理和降级策略

🔧 开发者友好

TypeScript 构建 - 完整的类型安全和 IDE 支持
模块化架构 - 清晰的代码结构和组件分离
全面测试覆盖 - 200+ 测试用例，包含属性基础测试
CI/CD 集成 - 自动化构建、测试和发布流程

🚀 快速开始

📦 安装方式

方法一：HACS 安装（推荐）

🎯 通过 HACS 自定义存储库安装：

打开 HACS
- 在 HomeAssistant 侧边栏点击 "HACS"
添加自定义存储库
- 点击 "Frontend"（前端）
- 点击右上角的三个点 ⋮ → "Custom repositories"
- 添加存储库：https://github.com/forhumility/humble-heatmap
- 类别选择：Lovelace
- 点击 "ADD"
安装插件
- 搜索 "Humble Heatmap" 或在列表中找到
- 点击 "DOWNLOAD" → 选择最新版本 → 确认下载
- 重启浏览器（Ctrl+F5 清除缓存）

✅ 安装成功标志： 浏览器控制台会显示：

🔥 Humble Heatmap Card v1.0.0 已加载
📊 支持温度和湿度传感器可视化

确保已安装 HACS
HACS → 前端 → 右上角菜单 → 自定义存储库
添加仓库 URL 并选择类别 "Lovelace"
搜索 "Humble Heatmap" 并安装
重启浏览器

方法二：手动安装

# 1. 下载最新版本
wget https://github.com/forhumility/humble-heatmap/releases/latest/download/humble-heatmap.js

# 2. 复制到 HomeAssistant
cp humble-heatmap.js /config/www/

# 3. 在 HomeAssistant 中添加资源
# 配置 → 仪表盘 → 资源 → 添加资源
# URL: /local/humble-heatmap.js
# 类型: JavaScript Module

方法三：自动化部署

# Windows 用户
scripts\deploy.bat "C:\path\to\homeassistant\config"

# Linux/Mac 用户
./scripts/deploy.sh /path/to/homeassistant/config

⚡ 3 分钟配置

添加卡片: 仪表盘编辑 → 添加卡片 → "自定义: 温湿度热力图"
配置传感器: 添加传感器实体 ID 和位置坐标
享受可视化: 实时查看温湿度分布热力图

💡 提示: 查看快速开始指南获取详细的 3 步部署教程

📖 使用指南

🎯 基础配置

通过可视化编辑器或 YAML 配置卡片：

可视化配置

仪表盘编辑模式 → 添加卡片
选择 "自定义: 温湿度热力图"
使用图形界面配置所有选项
实时预览效果

YAML 配置示例

type: "custom:humble-heatmap"
title: "🏠 家庭温度分布"
view_mode: "temperature"              # 视图模式: temperature | humidity
background_image: "/local/floorplan.png"  # 背景图片（可选）

# 数值范围配置
min_value: 16                         # 最小值（蓝色区域）
max_value: 30                         # 最大值（红色区域）
force_fahrenheit: false               # 强制华氏度显示

# 视觉效果配置
blur_radius: 40                       # 热力图模糊半径
heat_radius: 60                       # 热力点影响半径
opacity: 0.7                          # 热力图透明度 (0-1)

# 性能配置
refresh_interval: 10                  # 数据刷新间隔（分钟）
decimal_point: true                   # 显示小数点

# 传感器配置
sensors:
  - entity_id: sensor.living_room_temperature
    name: "客厅"
    x: 25                            # X 坐标 (0-100%)
    y: 30                            # Y 坐标 (0-100%)
  - entity_id: sensor.bedroom_temperature
    name: "主卧"
    x: 75
    y: 20
  - entity_id: sensor.kitchen_temperature
    name: "厨房"
    x: 50
    y: 80

🎨 高级配置示例

# 完整功能展示配置
type: "custom:humble-heatmap"
title: "🌡️ 智能家居温度监控"
view_mode: "temperature"
background_image: "/local/house-plan.svg"

# 精细化视觉控制
min_value: 18
max_value: 28
blur_radius: 35
heat_radius: 55
opacity: 0.8
gradient_steps: 10                    # 渐变色阶数量

# 标签和显示
show_labels: true                     # 显示传感器标签
show_values: true                     # 显示数值
decimal_point: true
friendly_names: true                  # 使用友好名称

# 性能优化
refresh_interval: 5                   # 更频繁的更新
visibility_check: true                # 可见性检测
render_throttle: 100                  # 渲染节流（毫秒）

# 多传感器配置
sensors:
  - entity_id: sensor.living_room_temperature
    name: "客厅"
    x: 30
    y: 40
  - entity_id: sensor.master_bedroom_temperature
    name: "主卧"
    x: 70
    y: 25
  - entity_id: sensor.guest_bedroom_temperature
    name: "客卧"
    x: 70
    y: 60
  - entity_id: sensor.kitchen_temperature
    name: "厨房"
    x: 45
    y: 75
  - entity_id: sensor.bathroom_temperature
    name: "浴室"
    x: 85
    y: 45

⚙️ 配置参数详解

📋 基础配置

参数	类型	默认值	描述
`type`	string	-	必需卡片类型，固定为 `"custom:humble-heatmap"`
`title`	string	`"家庭温度热力图"`	卡片标题
`view_mode`	string	`"temperature"`	视图模式：`temperature` \| `humidity`

🎨 视觉效果配置

参数	类型	默认值	描述
`background_image`	string	`null`	背景图片 URL，支持 PNG/JPG/SVG
`min_value`	number	`16`	热力图最小值（对应蓝色）
`max_value`	number	`30`	热力图最大值（对应红色）
`blur_radius`	number	`40`	热力图模糊半径 (10-100)
`heat_radius`	number	`60`	热力点影响半径 (20-150)
`opacity`	number	`0.7`	热力图透明度 (0.1-1.0)
`gradient_steps`	number	`8`	颜色渐变步数 (4-20)

📊 数据显示配置

参数	类型	默认值	描述
`show_labels`	boolean	`true`	显示传感器标签
`show_values`	boolean	`true`	显示数值
`decimal_point`	boolean	`false`	显示小数点
`friendly_names`	boolean	`false`	使用 HomeAssistant 友好名称
`force_fahrenheit`	boolean	`false`	强制使用华氏度

⚡ 性能优化配置

参数	类型	默认值	描述
`refresh_interval`	number	`10`	数据刷新间隔（分钟）
`visibility_check`	boolean	`true`	可见性检测优化
`render_throttle`	number	`100`	渲染节流间隔（毫秒）
`max_sensors`	number	`20`	最大传感器数量限制

🎯 传感器配置

每个传感器对象包含以下属性：

参数	类型	必需	描述
`entity_id`	string	✅	HomeAssistant 传感器实体 ID
`name`	string	✅	显示名称
`x`	number	✅	X 坐标百分比 (0-100)
`y`	number	✅	Y 坐标百分比 (0-100)
`weight`	number	❌	权重系数 (0.1-2.0)，默认 1.0
`color_override`	string	❌	自定义颜色覆盖，如 `"#ff0000"`

🎨 颜色主题配置

# 自定义颜色渐变
color_scheme:
  cold: "#0066cc"      # 低温颜色
  cool: "#00ccff"      # 凉爽颜色  
  warm: "#ffcc00"      # 温暖颜色
  hot: "#ff6600"       # 高温颜色
  
# 或使用预设主题
theme: "blue_red"      # blue_red | rainbow | thermal | custom

🖼️ 背景图片设置

准备背景图片

获取房屋平面图
- 使用建筑图纸、房产资料或手绘平面图
- 推荐格式：PNG（透明背景）、SVG（矢量图）、JPG
- 建议尺寸：800x600 到 1200x900 像素

上传到 HomeAssistant

# 将图片复制到 www 目录
cp floorplan.png /config/www/

配置图片路径

background_image: "/local/floorplan.png"

📐 坐标定位技巧

X 坐标: 0=最左边，100=最右边
Y 坐标: 0=最上边，100=最下边
建议: 使用图片编辑软件标记传感器位置，然后转换为百分比

# 示例：客厅传感器位于图片中央偏左上
sensors:
  - entity_id: sensor.living_room_temperature
    name: "客厅"
    x: 35    # 左边 35% 位置
    y: 25    # 上边 25% 位置

🔧 故障排除

常见问题解决

问题	可能原因	解决方案
🚫 卡片不显示	资源未加载	检查浏览器控制台，确认资源路径正确
📊 数据不更新	传感器实体错误	验证 `entity_id` 在开发者工具中存在
🖼️ 背景图片不显示	图片路径错误	确认图片在 `/config/www/` 目录中
🐌 性能卡顿	渲染参数过高	减小 `blur_radius` 和 `heat_radius`
🎨 颜色异常	数值范围不当	调整 `min_value` 和 `max_value`

🔍 调试技巧

开启浏览器开发者工具

F12 → Console 标签 → 查看错误信息

检查传感器状态

HomeAssistant → 开发者工具 → 状态 → 搜索传感器实体

验证配置语法

# 使用 YAML 验证工具检查配置文件语法

📞 获取帮助

📖 详细文档: 安装指南 | 部署指南 | 功能特性 | 更新日志
🚀 快速开始: 3分钟部署教程
🔧 故障排除: 常见问题解决
🐛 报告问题: GitHub Issues
� *社区讨论: HomeAssistant 社区论坛
📧 联系开发者: 通过 GitHub 提交 Issue

🏗️ 开发与贡献

技术栈

前端框架: LitElement (Web Components)
语言: TypeScript
构建工具: Rollup
测试框架: Jest + fast-check (属性基础测试)
代码质量: ESLint + Prettier

开发环境设置

# 克隆仓库
git clone https://github.com/forhumility/humble-heatmap.git
cd humble-heatmap

# 安装依赖
pnpm install

# 开发模式（热重载）
pnpm dev

# 运行测试
pnpm test

# 构建生产版本
pnpm build

🧪 测试覆盖

200+ 测试用例 - 全面的功能测试覆盖
属性基础测试 - 23 个正确性属性验证
集成测试 - HomeAssistant 集成验证
性能测试 - 渲染性能和内存使用测试

📁 项目结构

humble-heatmap/
├── 📂 src/                    # 源代码
│   ├── 📂 types/             # TypeScript 类型定义
│   ├── 📂 utils/             # 工具函数和验证逻辑
│   ├── 📂 rendering/         # 渲染引擎和视觉效果
│   ├── 📂 __tests__/         # 单元测试和集成测试
│   ├── 📄 humble-heatmap.ts  # 主卡片组件
│   └── 📄 humble-heatmap-editor.ts # 配置编辑器
├── 📂 docs/                   # 📚 项目文档中心
│   ├── 📄 README.md          # 文档导航索引
│   ├── 📄 INSTALL.md         # 安装指南
│   ├── 📄 QUICK_START.md     # 快速开始指南
│   ├── 📄 FEATURES.md        # 功能特性详解
│   ├── 📄 TROUBLESHOOTING.md # 故障排除指南
│   ├── 📄 FIX_SUMMARY.md     # 修复记录总结
│   ├── 📄 DEPLOYMENT.md      # 部署指南
│   ├── 📄 BUILD_INFO.md      # 构建信息说明
│   ├── 📄 HACS_README.md     # HACS 专用说明
│   ├── 📄 README-DEV.md      # 开发者文档
│   └── 📄 ENTITY_SELECTOR_GUIDE.md # 实体选择器指南
├── 📂 scripts/               # 🔧 部署和构建脚本
│   ├── 📄 deploy.bat         # Windows 部署脚本
│   ├── 📄 deploy.sh          # Linux/Mac 部署脚本
│   ├── 📄 prepare-release.sh # 发布准备脚本
│   └── 📄 ...                # 其他脚本文件
├── 📂 tests/                  # 🧪 浏览器测试文件
│   ├── 📄 README.md          # 测试文件说明
│   ├── 📄 config-form-test.html    # 配置表单测试
│   ├── 📄 type-field-test.html     # Type字段修复测试
│   ├── 📄 unit-test.html           # 单元测试页面
│   └── 📄 ...                      # 其他测试文件
├── 📂 .kiro/specs/           # 开发规范和任务
├── 📂 .github/workflows/     # CI/CD 工作流
├── 📄 humble-heatmap.js      # 🚀 构建输出文件 (部署用)
├── 📄 README.md              # 项目主要说明文档
├── 📄 CHANGELOG.md           # 更新日志
└── 📄 package.json           # 项目配置

📚 文档导航

文档	描述	适用人群
README.md	项目概述和快速开始	所有用户
docs/INSTALL.md	详细安装指南	新用户
docs/QUICK_START.md	3分钟快速部署	新用户
docs/FEATURES.md	完整功能特性说明	高级用户
docs/TROUBLESHOOTING.md	问题排查和解决方案	遇到问题的用户
docs/DEPLOYMENT.md	部署和发布指南	开发者
docs/README-DEV.md	开发者文档	开发者
docs/FIX_SUMMARY.md	修复记录和技术细节	开发者

🧪 测试文件说明

测试文件	用途	运行方式
`tests/config-form-test.html`	官方配置表单功能测试	浏览器打开
`tests/type-field-test.html`	Type字段修复验证	浏览器打开
`tests/unit-test.html`	单元测试和边缘情况	浏览器打开
`tests/debug-test.html`	调试和开发测试	浏览器打开
`src/__tests__/*.test.ts`	Jest 单元测试	`pnpm test`

🤝 贡献指南

Fork 项目 并创建功能分支
编写测试 确保新功能有测试覆盖
遵循代码规范 运行 pnpm lint 检查
提交 Pull Request 并描述更改内容

📋 开发路线图

🎨 更多颜色主题和渐变选项
📱 移动端优化和触摸交互
🔄 动画效果和过渡动画
📊 历史数据趋势显示
🌐 多语言国际化支持
🔌 更多传感器类型支持

📄 许可证

本项目采用 MIT 许可证开源。

🙏 致谢

HomeAssistant - 优秀的智能家居平台
LitElement - 现代 Web Components 框架
SimpleHeat - 热力图渲染灵感来源
所有贡献者和用户的反馈与支持

📁 项目整理说明

为了保持项目根目录的整洁和专业性，我们已经重新整理了项目结构：

✅ 整理完成的改进

📚 文档集中管理 - 所有详细文档移至 docs/ 目录，提供完整的文档导航
🔧 脚本统一存放 - 所有部署和构建脚本移至 scripts/ 目录
🧪 测试文件整理 - 浏览器测试文件集中在 tests/ 目录
🗑️ 清理冗余文件 - 删除不再使用的 simpleheat.js 等文件
🔗 路径引用更新 - 更新所有文档和配置中的文件路径引用

📂 新的目录结构

humble-heatmap/
├── 📂 docs/          # 📚 完整文档中心
├── 📂 scripts/       # 🔧 部署构建脚本  
├── 📂 tests/         # 🧪 浏览器测试文件
├── 📂 src/           # 💻 源代码
├── 📄 README.md      # 🏠 项目主页
└── 📄 ...           # 其他核心配置文件

这样的整理让项目更加专业、易于维护，同时保持了所有功能的完整性。

⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src		src
tests		tests
.editorconfig		.editorconfig
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
example.png		example.png
hacs.json		hacs.json
humble-heatmap.js		humble-heatmap.js
jest.config.cjs		jest.config.cjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🔥 Humble Heatmap - 智能家居温湿度热力图卡片

✨ 核心特性

🌡️ 智能数据可视化

🎨 丰富的视觉效果

⚡ 性能优化

🔧 开发者友好

🚀 快速开始

📦 安装方式

方法一：HACS 安装（推荐）

方法二：手动安装

方法三：自动化部署

⚡ 3 分钟配置

📖 使用指南

🎯 基础配置

可视化配置

YAML 配置示例

🎨 高级配置示例

⚙️ 配置参数详解

📋 基础配置

🎨 视觉效果配置

📊 数据显示配置

⚡ 性能优化配置

🎯 传感器配置

🎨 颜色主题配置

🖼️ 背景图片设置

准备背景图片

📐 坐标定位技巧

🔧 故障排除

常见问题解决

🔍 调试技巧

📞 获取帮助

🏗️ 开发与贡献

技术栈

开发环境设置

🧪 测试覆盖

📁 项目结构

📚 文档导航

🧪 测试文件说明

🤝 贡献指南

📋 开发路线图

📄 许可证

🙏 致谢

📁 项目整理说明

✅ 整理完成的改进

📂 新的目录结构

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages