Home zh CN

🇨🇳 中文 | 🇺🇸 English

Skins Pro — 维基百科

欢迎来到 Skins Pro 维基！本指南涵盖功能、用法、配置、皮肤开发和代码开发。

⚠️ 布局错乱？第一步：清除浏览器缓存。
按 Ctrl+Shift+R（Windows/Linux）或 Cmd+Shift+R（Mac）强制刷新。
如果仍无效，请在浏览器设置中清除 HA 域名的所有缓存数据。
Skins Pro 会积极缓存 — 缓存问题是视觉故障的头号原因。

概述

Skins Pro 是一个 Home Assistant 社区 Lovelace 卡片，可将您的仪表盘转变为沉浸式多皮肤体验。它内置了 modern 毛玻璃风格皮肤，并通过内置皮肤商店提供更多社区皮肤。

主要亮点：

多皮肤架构 — 自由切换皮肤
双语（中/英）— 自动检测你的 HA 语言
全屏 Kiosk 模式 — 沉浸式体验
非管理员强制 Kiosk 锁定 — 阻止右键菜单和开发者工具
自动图标解析 — 直接从 HA 实体读取图标
移动端响应式 — 在手机和平板上均可使用

功能与用法

🏠 首页

主仪表盘显示欢迎问候语、天气预报、设备、房间、场景、能耗和环境传感器 — 均按区域组织。

视图：

首页 — 包含所有区域的主仪表盘
设备 — 按类型分组的全部设备
房间 — 房间快照和场景快捷方式
场景 — 快速场景激活
自动化 — 自动化列表
安全 — 摄像头、门锁、报警控制面板
能源 — 能耗对比

☀️ 天气与问候

欢迎区域显示：

可自定义的问候语（名称 + 消息）
当前天气状况（含图标、温度和预报）
可选：摄像头快照、时间、日期和环境传感器（启用摄像头时显示）

用法： 在卡片编辑器的"信息显示"下配置问候文本。天气实体自动检测或在"天气"设置中配置。

📱 设备控制

设备按房间或类型显示。支持的控件：

灯 — 亮度滑块、色温、颜色选择器、开关
开关 — 开关切换
窗帘 — 位置滑块
空调 — 温度控制（± 按钮）、模式显示
热水器 — 温度控制
风扇 — 速度控制、摆动、方向
加湿器 — 湿度目标控制
扫地机 — 启动、暂停、回充、定位按钮
媒体播放器 — 播放/暂停、切歌、音量滑块
门锁 — 锁定/解锁切换
报警控制面板 — 布防/撤防及模式选择

用法： 设备从 HA 自动检测。在卡片编辑器中，可按区域或设备类型筛选。首页上的"快速控制"区域显示最近使用的设备。

🚪 房间快照

每个房间显示一张背景图片，附带设备图标和房间专属场景标签。点击房间可查看所有设备。

背景图片：

使用 HA 区域图片（在 HA 中设置：设置 → 区域 → 编辑 → 图片）
在卡片编辑器中上传自定义房间图片
皮肤自带的房间图片

🎬 场景按钮

一键场景激活。场景从 HA 自动检测。可在卡片编辑器中启用/禁用特定场景。

🛡️ 安全页面

自动检测的安全设备：

摄像头 — 实时快照，点击查看详情
报警控制面板 — 自动检测，点击布防/撤防，模式选择（外出/在家/夜间/度假）
门锁 — 锁定/解锁状态

🎵 媒体播放器

首页上的完整媒体播放器卡片：

专辑封面显示
播放/暂停、上一曲/下一曲
音量滑块及静音切换
自动检测当前媒体源

🌡️ 环境传感器

显示温度、湿度、CO₂、PM2.5 等传感器数值。图标从 Home Assistant 实体设置中自动解析。

显示模式：

侧边栏 — 带图标和数值的完整列表
内联 — 紧凑行布局（启用摄像头时在欢迎区域显示）

楼层分组： 当 HA 配置了多个楼层时，传感器自动按楼层分组。

🌙 深色模式

自动 — 根据 HA 位置在日落/日出时切换
手动 — 点击时钟切换
皮肤支持 — 皮肤可提供深色优化资源和 CSS

🔍 全局搜索

按名称搜索所有设备。按类型筛选（灯、开关、空调等）。模糊匹配支持部分名称搜索。

↔️ Kiosk 模式

隐藏 HA 侧边栏和顶栏的全屏模式，提供沉浸式体验。

管理员行为： 点击头像切换 Kiosk 开关。

非管理员行为： Kiosk 强制启用。右键菜单和开发者工具快捷键（F12、Ctrl+Shift+I/J/C）被阻止。无法从 UI 退出 Kiosk。

📱 移动端响应式

布局自动适应手机和平板的竖屏和横屏方向。移动端导航切换为底部标签栏。

配置

卡片编辑器设置

将 Skins Pro 添加到仪表盘后，点击卡片打开编辑器：

通用：

标题 — 自定义仪表盘标题（中英双语）
语言 — 自动或强制中/英文

皮肤：

皮肤 — 从已安装的皮肤中选择
皮肤模式 — 浅色/深色/自动
已下载皮肤 — 手动列出本地安装的皮肤

布局：

全屏 — 启用 Kiosk 模式
隐藏侧边栏 — 启动时隐藏侧边栏
筛选房间 — 仅显示特定房间
筛选类型 — 仅显示特定设备类型
隐藏未分配 — 隐藏未分配给任何房间的设备

首页：

天气 — 选择天气实体
信息显示 — 选择问候语的信息实体
摄像头 — 选择首页快照的摄像头实体
媒体播放器 — 选择媒体播放器实体
环境传感器 — 选择要显示的传感器实体

能源：

能源实体 — 用于每日对比的能耗传感器

房间：

场景 — 启用/禁用每个房间的特定场景
房间背景 — 上传自定义图片

环境传感器配置

传感器可通过两种方式添加：

自动检测 — 将实体 ID 添加到 home_selection.environment，图标从 HA 自动解析
手动配置 — 配置 config.environment[]，显式指定 entity、label、unit、icon、variant 字段

完整配置参考

对于高级配置，卡片编辑器会生成 JSON，你可进一步自定义。示例：

{
  "type": "custom:skins-pro-card",
  "title": "My Home",
  "title_zh": "我的家",
  "fullscreen": true,
  "resource_pack": { "skin": "modern" },
  "weather": { "entity": "weather.home" },
  "home_selection": {
    "environment": ["sensor.temperature", "sensor.humidity"]
  }
}

皮肤开发

皮肤是 skins-pro/<皮肤名称>/ 下的一个文件夹，包含图片、CSS 和元数据。npm run build 会自动发现、处理图片并生成代码。

目录结构

skins-pro/
  你的皮肤名称/
    theme.css               # 样式（必需）
    strings.json            # 字符串 + icon_map + author + version（必需）
    avatar.jpg              # 头像，推荐 ≥ 300×300
    background.jpg          # 背景图，推荐宽度 ≥ 2560px
    decoration.jpg          # 侧边装饰，推荐高度 ≥ 400px
    base-texture.jpg        # 基础纹理，推荐宽度 ≥ 2560px
    stage-*.jpg             # 舞台图片，推荐宽度 ≥ 2560px
    room-*.jpg              # 房间图片，推荐宽度 ≥ 1200px
    icon-*.jpg              # 设备图标，推荐最长边 ≥ 300px

必需文件

文件	用途
`theme.css`	通过 `:host` 上的 CSS 变量定义所有样式。参见 `src/skins/modern/theme.css`
`strings.json`	问候文本 + `icon_map`。必须包含非空的 `author` 字段
`avatar.*` (png/jpg)	头像图片，推荐 ≥ 300×300
`background.*` (png/jpg)	主背景图，推荐宽度 ≥ 2560px
`screenshots/<皮肤名称>.png`	商店预览图。文件名必须与皮肤文件夹名称完全一致

深色模式资源（可选）

要支持深色模式，在原文件旁放置 -dark 变体 — 扩展名相同，在扩展名前追加 -dark：

skins-pro/你的皮肤名称/
  background-dark.jpg      # background.jpg 的深色变体
  icon-light-dark.jpg      # icon-light.jpg 的深色变体
  room-living-dark.jpg     # room-living.jpg 的深色变体
  ...                      # 每个原文件对应一个 -dark 文件

同时在 theme.css 中添加 :host([data-sp-theme="dark"]) { ... } 来覆盖深色颜色的 CSS 变量。参考实现见 src/skins/modern/theme.css。

构建时的图片处理

模式	推荐源	说明
`room-*`	宽度 ≥ 1200px	保持比例，缩小至 1200px
`icon-*`	最长边 ≥ 300px	保持比例，缩小至 300px
`avatar.*`	最长边 ≥ 300px	保持比例，缩小至 300px
`decoration.*`	高度 ≥ 400px	保持比例，缩小至高度 400px
`background.`、`base-`、`stage-*`	宽度 ≥ 2560px	保持比例，缩小至 2560px
其他	宽度 ≥ 1200px	保持比例，缩小至 1200px

支持 PNG / JPG / BMP / WebP 输入。图标、头像和装饰输出为 PNG；其他所有内容输出为 JPG。从不放大。

theme.css

所有样式通过 :host 上的 CSS 变量自定义。每个皮肤有自己的 theme.css。:host 块定义了约 120+ 个 CSS 变量，涵盖：

颜色 — 文本、强调色、背景、玻璃效果、设备状态
间距 — 统一的间距标记（--sp-space-3xs 到 --sp-space-xl）
排版 — 通过 clamp() 实现流式字体大小
布局 — 侧边栏宽度、舞台内边距、卡片/房间/场景最小宽度
阴影 — 新拟态、卡片、玻璃、设备、场景阴影
圆角 — 所有元素类型的圆角标记

完整变量列表和参考实现见 src/skins/modern/theme.css。

CSS 架构：

:host — CSS 变量定义
.mc-app — 主布局网格（侧边栏 + 舞台）
.stage-grid — 首页网格（欢迎区、侧边、底部）
.welcome-group — 问候语 + 天气/环境区域
.side — 侧边栏面板（环境、能源、媒体、场景）
.bottom-stack — 设备 + 房间区域
.device、.room、.scene — 卡片组件
.env-row — 环境传感器行
.media-actions — 媒体播放器控件
@media (orientation: portrait) — 移动端响应式布局
:host([data-sp-theme="dark"]) — 深色模式覆盖
@container sp (max-width: ...) — 响应式尺寸的容器查询

strings.json + icon_map + author + version

{
  "version": "1.0.0",
  "author": "your-github-username",
  "dark_mode": true,
  "title_zh": "欢迎回来！",
  "title_en": "Welcome back!",
  "icon_map": {
    "light": "light",
    "switch": "switch",
    "climate": "climate",
    "media_player": "speaker",
    "lock": "lock"
  }
}

version — 皮肤版本号（例如 "1.0.0"）。在商店中显示。
author — 你的 GitHub 用户名（不含 @）。在商店中显示并链接到你的个人主页。
dark_mode — 可选。如果皮肤提供深色变体资源，设为 true。默认为 false。
icon_map — 将实体域映射到图标图片文件名。未映射的域会自动回退。

图标命名约定

图标文件与所代表实体的域匹配：

light → icon-light.jpg（用于所有灯光实体）
switch → icon-switch.jpg
climate → icon-climate.jpg
media_player → icon-speaker.jpg（可通过 icon_map 配置）
sensor → icon-sensor.jpg

最佳参考 — 创建新皮肤时，以 visionOS/ 为起点。它拥有最完整的 icon_map、theme.css 和图标资源。

本地测试新皮肤

你不需要商店即可测试新皮肤。只需：

在 skins-pro/<新皮肤名称>/ 下创建皮肤文件夹，包含常规文件（theme.css、strings.json、图片）
运行 npm run build -- <新皮肤名称> --skins-only — 仅处理该皮肤的图片，输出到 dist/<新皮肤名称>/

将 dist/<新皮肤名称>/ 复制到你的 HA www/ 文件夹：

<HA 配置>/www/skins-pro/<新皮肤名称>/
  ├── theme.css
  ├── avatar.jpg
  ├── background.jpg
  ├── room-*.jpg
  ├── icon-*.jpg
  └── ...（皮肤目录中的所有文件）

在 Skins Pro 卡片编辑器中，将皮肤名称添加到 downloaded_skins：
```
"downloaded_skins": ["<新皮肤名称>"]
```
这告诉卡片该皮肤已安装，因此它会立即显示在皮肤下拉菜单中。选择它并强制刷新。

就这样 — 本地测试不需要商店或 PR。当你对结果满意后，提交 PR 来分享它。

代码开发

前置条件

Node.js 18+
npm

设置

git clone https://github.com/ha-china/Skins-Pro.git
cd Skins-Pro
npm install

构建命令

npm run build                            # 构建所有内容
npm run build -- <皮肤名称>             # 仅构建一个皮肤 + modern（更快）
npm run build -- <皮肤名称> --skins-only  # 仅处理皮肤图片，不重建 JS
npm run watch                            # 文件变更时自动重建
npm run type-check                       # 检查代码错误

构建输出

dist/skins-pro.js — 主 JS 文件（HA 需要的唯一文件）
dist/modern/ — 内置 modern 皮肤的图片和 CSS
dist/<皮肤名称>/ — 每个额外皮肤的资源

项目结构

src/
├── skins-pro-card.ts         # 主卡片组件（LitElement）
├── types.ts                  # TypeScript 接口
├── index.ts                  # 入口文件
├── components/               # UI 组件
│   ├── device-card.ts        # 设备控制卡片
│   ├── media-player.ts       # 媒体播放器面板
│   ├── weather.ts            # 天气显示
│   ├── environment.ts        # 环境传感器
│   ├── nav.ts                # 侧边栏导航
│   ├── alarm-control-panel.ts # 报警面板
│   ├── climate.ts            # 空调控制
│   ├── fan.ts                # 风扇控制
│   ├── humidifier.ts         # 加湿器控制
│   ├── vacuum.ts             # 扫地机控制
│   ├── water-heater.ts       # 热水器控制
│   ├── light.ts              # 灯光控制（颜色、亮度）
│   └── maintenance.ts        # 维护卡片
├── views/                    # 页面视图
│   ├── home.ts               # 首页
│   ├── devices.ts            # 设备页面
│   ├── rooms.ts              # 房间页面
│   ├── scenes.ts             # 场景页面
│   ├── automations.ts        # 自动化页面
│   ├── security.ts           # 安全页面
│   ├── energy.ts             # 能源页面
│   └── search.ts             # 全局搜索覆盖层
├── ha/                       # HA 集成层
│   ├── kiosk.ts              # Kiosk 模式 CSS 注入
│   └── energy.ts             # 能源数据获取
├── render/                   # 渲染工具
│   ├── layout.ts             # 布局计算
│   └── context.ts            # 渲染上下文
├── utils/                    # 工具
│   └── index.ts              # 共享辅助函数
├── skins/                    # 捆绑皮肤
│   ├── generated.ts          # 自动生成的皮肤注册表
│   └── modern/               # Modern 皮肤
│       └── theme.css         # 770+ 行 CSS
└── editor/                   # 卡片编辑器
    ├── template.ts           # 编辑器 UI 模板
    ├── events.ts             # 编辑器事件处理
    └── skin-store.ts         # 皮肤商店管理

关键架构决策

Shadow DOM： 卡片使用开放的 Shadow DOM 进行样式隔离。每个皮肤的 theme.css 通过 <link> 在 shadow root 内加载，防止样式泄漏。

CSS 变量： 所有样式由 :host 上定义的约 120+ 个 CSS 变量驱动。皮肤自定义这些变量。构建系统将用户配置的主题覆盖作为内联样式注入到宿主元素上。

HA 原生组件： 卡片使用 HA 的 <ha-state-icon> 显示实体图标 — 这会将图标解析（包括 device_class 默认值）委托给 HA 自身的前端逻辑。

响应式： 布局使用 CSS Grid 配合 grid-template-areas、流式 clamp() 字体大小和容器查询实现响应式尺寸。

在 Home Assistant 中测试

构建项目：
```
npm run build
```
将 dist/skins-pro.js 复制到你的 HA www/ 文件夹：
```
<HA 配置>/www/skins-pro.js
```
将其添加为 Home Assistant 中的仪表盘资源：
设置 → 仪表盘 → 资源 → 添加资源
- URL：/local/skins-pro.js
- 类型：JavaScript Module
强制刷新（Ctrl+Shift+R）浏览器。

之后，每次运行 npm run build，只需替换 www/skins-pro.js 并强制刷新即可看到更改。

提示 — 如果内置的 modern 皮肤图片或样式未加载，请同时将 dist/modern/ 复制到 www/community/skins-pro/modern/：
<HA 配置>/www/community/skins-pro/modern/  ← 将 dist/modern/ 复制到这里

贡献

贡献皮肤

我们欢迎皮肤贡献！只需：

在 skins-pro/<皮肤名称>/ 下创建皮肤文件夹，包含必需文件（见上文皮肤开发）
添加预览截图 screenshots/<皮肤名称>.png（推荐 1920×1080）
使用 PR 模板提交 PR — 填写所有必填字段

合并后，CI 会自动构建卡片并使其在卡片编辑器的皮肤商店中可用。

⚠️ 版权声明 — 贡献皮肤时，请确保你的图片资源不侵犯他人版权。我们建议使用 AI 生成或原创图片。存在有效版权投诉的皮肤将从商店中移除。

提交后，机器人会自动发布一条 Screenshot Preview 评论，显示你的皮肤预览图。

给皮肤创作者的建议

以 visionOS/ 为参考 — 它拥有最完整的 icon_map 和资源
图片在构建时自动处理（调整大小、JPG 输出）— 无需手动优化
strings.json 中的 icon_map 将实体域映射到图标文件名；未映射的域会自动回退
提交 PR 前在本地测试（见本地测试新皮肤）
CI 机器人在 PR 提交后会自动生成预览图

贡献代码

欢迎提交 Bug 修复、改进和新功能：

Fork 本仓库
创建功能分支
进行修改
运行 npm run build 和 npm run type-check 验证
提交 PR

报告问题

请在 GitHub Issues 页面报告 Bug 和功能请求。

Uh oh!

Home zh CN

Skins Pro — 维基百科

目录

概述

功能与用法

🏠 首页

☀️ 天气与问候

📱 设备控制

🚪 房间快照

🎬 场景按钮

🛡️ 安全页面

🎵 媒体播放器

🌡️ 环境传感器

🌙 深色模式

🔍 全局搜索

↔️ Kiosk 模式

📱 移动端响应式

配置

卡片编辑器设置

环境传感器配置

完整配置参考

皮肤开发

目录结构

必需文件

深色模式资源（可选）

构建时的图片处理

theme.css

strings.json + icon_map + author + version

图标命名约定

本地测试新皮肤

代码开发

前置条件

设置

构建命令

构建输出

项目结构

关键架构决策

在 Home Assistant 中测试

贡献

贡献皮肤

给皮肤创作者的建议

贡献代码

报告问题

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally