Виджеты

Как фоновый сервис показывает интерфейс: объявление виджетов в манифесте, статика и API на widget-sdk, личные настройки в запросе, тема и где виджет появится у пользователя.

Виджет это веб-страница, которую отдаёт фоновый сервис. Пользователь добавляет её на доску в веб-версии или в панель виджетов EVA Desktop. Данные виджет берёт из API того же сервиса.

EVA DesktopAlt + Space

Пространство: ~/projects/docs

Собери по папке отчёт за неделю и сохрани в report.docx

Просматривает файлы · Читает файл · Записывает файл

Готово: report.docx в папке пространства, 4 раздела, 2 таблицы.

report.docx

Календарь Exchange

Пн

Планёрка

Вт

Демо

Ср

Чт

1:1

Пт

Ретро

Задачи

Сегодня

DOC-112 Обновить манифест

DOC-118 Скриншоты

В работе

DOC-120 Лендинг Студии

Спросите EVA...

Объявление

{
  "eva": {
    "kind": "background",
    "widgets": [
      { "id": "board", "path": "/", "title": "Задачи" },
      { "id": "worklog", "path": "/worklog.html", "title": "Ворклоги" }
    ]
  }
}

id уникален в пакете, path это путь внутри HTTP-сервера сервиса, title видит пользователь в списке виджетов.

Сервер

import { createWidgetServer } from '@eva/widget-sdk';

export async function main(ctx) {
  const app = createWidgetServer(ctx);
  app.serve('public');

  app.get('/api/tasks', async (req, res) => {
    const { jira_url, jira_pat } = req.ctx.settings;
    res.json(await loadTasks(jira_url, jira_pat));
  });

  app.post('/api/board', async (req, res) => {
    ctx.db.prepare('INSERT INTO board (task, column) VALUES (?, ?)').run(req.body.task, req.body.column);
    res.json({ ok: true });
  });

  await app.listen();
}

• app.serve('public') отдаёт статику из папки public/ пакета.
• app.get, app.post объявляют API. Порт выбирать не нужно: платформа сама проксирует запросы к сервису.
• В браузере обращайтесь к API относительными путями: fetch('api/tasks'). Адрес прокси меняется между облаком, Desktop и debug-сервисом.

Пользователь и настройки

Запрос к виджету проходит через API EVA и проверку входа. Поэтому в обработчике известно, кто открыл виджет, и доступны его личные настройки пакета: req.ctx.settings. Если личной настройки не хватает, виджет может показать подсказку и ссылку на форму настроек пакета.

Тема

Платформа передаёт тему в адресе виджета параметром eva-theme со значением light или dark. Для виджетов того же origin EVA переключает классы dark и app-dark на корневом элементе. Используйте CSS-переменные или Tailwind с darkMode: 'class', и виджет будет выглядеть своим в обеих темах.

Где появится виджет

Место	Как добавить
Доска в веб-версии	Раздел Виджеты, добавить виджет на дашборд
EVA Desktop	Панель виджетов по Alt + Space, виджеты из синхронизированных пакетов
Студия	Вкладка Виджеты редактора пакета, на черновике

Примеры

• Jira Widgets: канбан, ворклоги и поиск задач.
• Exchange Calendar: календарь недели с личным паролем.