Создать плагин

Соберём панель «Счётчик проверок»: кнопка отмечает ещё один проверенный пункт, другая сбрасывает счётчик. Пример хранит состояние только в открытой панели и не отправляет запросов.

Нужен GrigDesk с поддержкой манифеста v1. Для этой панели достаточно готового JavaScript: сервер, сборщик и npm-зависимости не требуются.

Подготовьте папку и манифест

Создайте отдельный каталог first-plugin вне исходников приложения. Сохраните этот файл как plugin.json в его корне:

{
  "id": "first-plugin",
  "api": 1,
  "name": "Счётчик проверок",
  "version": "1.0.0",
  "description": "Учебная панель со счётчиком проверенных пунктов",
  "icon": "assets/icon.png",
  "category": "dev",
  "entrypoints": {
    "web": {
      "dir": "ui",
      "entry": "panel.js",
      "css": ["panel.css"],
      "locales": { "ru": "locales/ru.json", "en": "locales/en.json" }
    }
  },
  "contributes": {
    "panels": [{ "title": "Счётчик проверок", "group": "tools", "order": 50 }]
  },
  "install": { "npm": [] }
}

Создайте папки assets, ui/locales и docs. Скачайте иконку примера и сохраните как assets/icon.png. Позже замените её своей PNG/JPEG/WebP-иконкой. Поле id должно быть уникальным для вашей установки.

Добавьте панель

Сохраните как ui/panel.js:

import { h, ref } from 'vue';
import { UiButton } from '@grigdesk/ui';

export default {
  props: ['context', 'active', 'compact', 'presentation'],
  setup(props) {
    const count = ref(0);

    return () => h('section', { class: 'first-plugin' }, [
      h('h2', props.context.t('title')),
      h('p', { role: 'status' }, props.context.t('count', { count: count.value })),
      h(UiButton, {
        onClick: () => { count.value += 1; },
      }, () => props.context.t('add')),
      h(UiButton, {
        disabled: count.value === 0,
        onClick: () => { count.value = 0; },
      }, () => props.context.t('reset')),
    ]);
  },
};

h создаёт элементы без компилятора шаблонов. Vue и UiButton берутся из окна GrigDesk; в пакет не нужно добавлять их реализации. Каждый экземпляр панели хранит собственный count.

Сохраните стили как ui/panel.css:

.first-plugin {
  display: grid;
  align-content: start;
  justify-items: start;
  gap: 16px;
  padding: 20px;
}

.first-plugin h2,
.first-plugin p {
  margin: 0;
}

Селекторы ограничены .first-plugin. Оформление кнопок, фокус и цвета темы предоставляет общий UI приложения.

Добавьте переводы и документацию

Сохраните оба словаря по указанным путям:

ui/locales/ru.json

{
  "title": "Счётчик проверок",
  "count": "Проверено пунктов: {count}",
  "add": "Отметить ещё один",
  "reset": "Сбросить"
}

ui/locales/en.json

{
  "title": "Review counter",
  "count": "Items checked: {count}",
  "add": "Check one more",
  "reset": "Reset"
}

Панель вызывает props.context.t во время отрисовки, поэтому смена языка меняет подписи, сохраняя счётчик. Значения настроек и язык также нельзя копировать один раз при загрузке, если интерфейс должен следовать их изменениям.

В docs/README.md опишите назначение и ограничения. Например:

# Счётчик проверок

Учебная панель: отмечает проверенные пункты и сбрасывает счётчик.

Состояние хранится только в экземпляре панели. После размонтирования
или перезагрузки окна оно сбрасывается. Серверных запросов, файлов и внешних сервисов нет.

Для установки выберите тег v1.0.0, затем включите плагин и примените изменение.
Панель открывается в группе «Инструменты».

Если руководство вырастет, оставьте здесь оглавление со ссылками на соседние документы.

Установите и проверьте

Инициализируйте Git в папке своего плагина, добавьте подготовленные файлы, создайте коммит и тег:

git init
git add plugin.json assets ui docs
git commit -m "Initial plugin"
git tag -a v1.0.0 -m "First release"

Для проверки на той же машине используйте «Установить из Git…» с адресом file:///абсолютный/путь/first-plugin. Если GrigDesk работает на удалённом сервере, путь относится к серверу; можно вместо этого отправить репозиторий и тег на доступный ему Git-хостинг.

Пройдите установку, включите плагин и примените изменение. В группе «Инструменты» появится «Счётчик проверок» с адресом /ext/first-plugin.

Проверьте результат:

• Кнопка увеличивает счётчик, сброс возвращает ноль.
• Кнопки работают с клавиатуры; при нуле сброс недоступен.
• Смена RU/EN меняет подписи и сохраняет значение.
• Панель помещается в узком окне и следует светлой и тёмной теме.
• После размонтирования панели или перезагрузки окна счётчик начинается заново.

Для следующего выпуска измените version, создайте новый коммит и тег, например v1.0.1, и проверьте обновление. Исходную папку разработки и установленную копию GrigDesk храните отдельно.

Когда понадобится сборка

Для Vue SFC и TypeScript используйте сборщик своего проекта. Шаблон .vue должен быть скомпилирован заранее: runtime-компилятора в окне нет. Оставляйте vue и @grigdesk/ui внешними импортами, CSS выпускайте отдельным файлом. В устанавливаемый репозиторий включайте готовые файлы.

Установщик не собирает исходники: npm-подготовка ставит production-зависимости с отключёнными скриптами. Для них нужны package.json, lockfile v2/v3 и корректный install.npm; локальные file:-зависимости, workspaces и поставляемые .npmrc не поддерживаются.

Типы можно получить из checkout GrigDesk, сохранив их в пустую папку вне его исходников:

npm --prefix web run build:plugin-types -- --out-dir /absolute/path/to/sdk

В проекте автора подключите папку как devDependency. Используйте import type из @grigdesk/plugin-types, /web и /server; для проверки @grigdesk/ui настройте TypeScript paths на node_modules/@grigdesk/plugin-types/ui.d.ts. Пакет типов — снимок версии GrigDesk; пересобирайте его при обновлении приложения. Dev-зависимости с локальным SDK оставляйте в проекте разработки, а установщику передавайте отдельный готовый пакет.