houseplan-card/README.ru.md

# 🏠 House Plan — живой план дома для Home Assistant

[![HACS Default](https://img.shields.io/badge/HACS-Default-41BDF5.svg)](https://github.com/hacs/integration)
[![GitHub release](https://img.shields.io/github/v/release/Matysh/houseplan-card)](https://github.com/Matysh/houseplan-card/releases)
[![CI](https://github.com/Matysh/houseplan-card/actions/workflows/validate.yml/badge.svg)](https://github.com/Matysh/houseplan-card/actions)
[![Live demo](https://img.shields.io/badge/демо-попробовать-00c853?logo=homeassistant&logoColor=white)](https://demo.houseplan.tech)
[![Telegram chat](https://img.shields.io/badge/Telegram-чат-2CA5E0?logo=telegram&logoColor=white)](https://t.me/ha_houseplan)

📘 **[Полное руководство](docs/USER-GUIDE.ru.md)** · 🇬🇧 **[English](README.md)** · 🗂 **[Задачи проекта](https://github.com/Matysh/houseplan-card/issues)**

<!-- docs-section: overview -->

## Дом целиком — одним взглядом

House Plan превращает Home Assistant в живую карту дома. Откройте отдельный
пункт **House Plan** в боковом меню Home Assistant, загрузите изображение плана
или нарисуйте комнаты, свяжите их с зонами Home
Assistant — и устройства появятся на плане автоматически. Сразу видно, где
горит свет, открыта дверь, слишком холодно, слабый Zigbee-сигнал или сработал
датчик протечки.

![Синтетический дом в режиме просмотра: комнаты, устройства, свет и климат](docs/images/01-view-desktop.png)

Настройка выполняется в графическом интерфейсе: без YAML-разметки, Inkscape и
внешнего редактора плана. Данные плана и расположение устройств хранятся на
сервере Home Assistant и синхронизируются между экранами.

> **Редактируйте на компьютере.** Режим просмотра и киоск полноценно работают
> на телефонах и планшетах. Редакторы рассчитаны прежде всего на мышь и
> клавиатуру; на touch отдельные операции могут быть неудобны или недоступны.
> Подробный контракт: [поддержка touch](docs/TOUCH-SUPPORT.md).

<!-- docs-section: features -->

## Что умеет House Plan

- **Живые состояния и безопасные действия.** Свет и другие безопасные устройства
  переключаются с плана; замок нельзя открыть случайным нажатием.
- **Три встроенных редактора.** «План» создаёт комнаты, стены и проёмы;
  «Устройства» размещает и настраивает маркеры; «Подложка» добавляет линии,
  подписи и мебель.
- **Комнаты, связанные с зонами HA.** Новые устройства появляются автоматически,
  а карточки комнат показывают температуру, влажность, свет и средний LQI.
- **Свет и окружение.** Заливки комнат, Glow от ламп, тени от стен, дневной фон и
  солнечные лучи из окон.
- **Двери, окна, ворота и пылесосы.** Проёмы отражают реальные датчики и замки;
  робот показывает позицию, базу и пройденный путь.
- **Несколько этажей и экранов.** Вкладки пространств, жесты переключения,
  локальный масштаб и отдельный стартовый этаж для каждой карточки.
- **Киоск для настенного экрана.** Только план, полноэкранная навигация и размеры
  значков, сохранённые отдельно для этого устройства.

![Тот же синтетический дом в touch-режиме просмотра](docs/images/02-view-touch.png)

<!-- docs-section: first-run -->

## Первая рабочая комната

1. Установите интеграцию и откройте **House Plan** в боковом меню Home Assistant.
2. Создайте первое **пространство**: загрузите SVG/PNG/JPG/WebP либо выберите
   вариант без изображения, чтобы нарисовать план вручную.
3. В редакторе «План» выберите **Контур комнаты**, поставьте вершины и замкните
   контур нажатием на первую точку.
4. Назовите комнату и свяжите её с зоной Home Assistant. Для помещения без
   устройств выберите «Без зоны».
5. Откройте «Устройства»: устройства связанной зоны уже размещены автоматически;
   перетащите маркеры в нужные места.
6. При необходимости оформите подложку линиями, текстом и мебелью.
7. Вернитесь в «Просмотр» — теперь план показывает живые состояния и принимает
   безопасные действия.

![Создание первого пространства](docs/images/03-space-create.png)

![Замыкание контура комнаты на первой точке](docs/images/04-room-contour-close.png)

![Выбранная перегородка и контекстная панель редактора плана](docs/images/05-plan-context-tray.png)

![Настройка устройства с источником привязки и точным результатом действия](docs/images/06-device-editor.png)

![Живой предпросмотр отображения того же устройства](docs/images/06-device-display-preview.png)

Пошаговые сценарии, все инструменты и особые случаи описаны в
[полном руководстве](docs/USER-GUIDE.ru.md). Возможности подложки отдельно
зафиксированы в [документе редактора](docs/DECOR-EDITOR.md), а роботов — в
[руководстве по пылесосам](docs/VACUUM.md).

<!-- docs-section: installation -->

## Установка

### Через HACS

[![Открыть репозиторий в HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=Matysh&repository=houseplan-card&category=integration)

House Plan входит в основной каталог HACS — пользовательский репозиторий
добавлять не нужно.

1. Найдите **House Plan** в поиске HACS и установите.
2. Перезапустите Home Assistant.
3. Откройте **Настройки → Устройства и службы → Добавить интеграцию → House Plan**.

Страница в боковом меню и дополнительные карточки для дашборда регистрируются
автоматически. После установки или обновления
House Plan перезапустите Home Assistant и полностью перезагрузите
страницу: `Ctrl+F5` в Windows/Linux или `Cmd+Shift+R` в macOS.

#### Режим Storage (по умолчанию в Home Assistant)

Обычно YAML не нужен. Если авторегистрация не сделала карточку доступной,
откройте **Настройки → Панели управления → меню ⋮ → Ресурсы → Добавить
ресурс**, укажите `/houseplan_files/houseplan-card.js` и выберите тип
**JavaScript-модуль**.

#### YAML-ресурсы в Home Assistant 2026.2+

Чтобы управлять ресурсами в `configuration.yaml` независимо от режима
самой панели, используйте:

```yaml
lovelace:
  resource_mode: yaml
  resources:
    - url: /houseplan_files/houseplan-card.js
      type: module
```

#### Home Assistant 2024.6–2026.1: устаревший режим

Только для панели, которая уже полностью управляется через YAML:

```yaml
lovelace:
  mode: yaml
  resources:
    - url: /houseplan_files/houseplan-card.js
      type: module
```

`mode: yaml` переводит в YAML-режим саму панель. Не переключайте
storage-панель в устаревший YAML только ради House Plan; используйте
инструкцию для Storage выше. Не используйте путь к файлу внутри
`custom_components`: Home Assistant не публикует его как JavaScript-модуль.

### Вручную

Скопируйте всю папку `custom_components/houseplan` из релиза в
`config/custom_components`, перезапустите Home Assistant и добавьте интеграцию
House Plan. Одного `houseplan-card.js` недостаточно: карточке также нужны
внутренний манифест и хешированные модули из того же релиза.

### Открытие House Plan

После добавления интеграции откройте **House Plan** в боковом меню Home
Assistant. Это основной полноэкранный способ работы: отдельный дашборд и YAML
не нужны. Запоминается последнее пространство, но после перехода на другую
страницу HA панель всегда возвращается в режим просмотра, а не в редактор.
Пользователь без права редактирования видит тот же живой план без редакторов.

Если пункт бокового меню зарегистрировать не удалось, интеграция и уже
добавленные карточки на дашбордах продолжают работать. После перезапуска и
жёсткого обновления HA проверьте состояние House Plan в системной информации.

### Необязательная карточка для дашборда

Добавляйте карточку, только если план нужно встроить в дашборд. В представлении
Sections она по умолчанию занимает всю ширину; вручную выбранный в HA размер
остаётся главным. Добавьте карточку через UI либо:

```yaml
type: custom:houseplan-card
title: План дома
```

Для нескольких экранов можно задать разные стартовые пространства:

```yaml
type: custom:houseplan-card
default_floor: ground
```

Все карточки используют общие серверные комнаты и координаты. Текущий режим,
масштаб и выбранное пространство локальны для экрана. Одновременное
редактирование поддерживает синхронизацию и проверку ревизий, но один объект
лучше не менять параллельно в двух браузерах.

## Где искать подробности

- [Полное руководство пользователя](docs/USER-GUIDE.ru.md)
- [Матрица mouse/touch/keyboard](docs/USER-GUIDE.ru.md#6-навигация-масштаб-и-жесты)
- [Инструменты плана](docs/USER-GUIDE.ru.md#инструменты-плана-в-короткой-таблице)
- [Редактор подложки](docs/DECOR-EDITOR.md)
- [Роботы-пылесосы](docs/VACUUM.md)
- [Поддержка touch](docs/TOUCH-SUPPORT.md)

<!-- docs-section: support -->

## Помощь и обратная связь

- Вопросы и примеры планов: [Telegram @ha_houseplan](https://t.me/ha_houseplan).
- Баги и предложения: [GitHub Issues](https://github.com/Matysh/houseplan-card/issues).
- Перед отчётом обновите House Plan, перезапустите HA и выполните жёсткое
  обновление страницы (`Ctrl+F5`). Приложите версию, браузер, логи и шаги
  воспроизведения; приватные entity ID можно заменить вымышленными.

Скриншоты в документации получены воспроизводимой командой
`npm run build && node demo/docs/capture.mjs` только на синтетических данных. Версия сценариев,
fingerprint исходников и хеш каждого изображения находятся в
[индексе снимков](docs/images/screenshots.json).

Лицензия: [MIT](LICENSE).