Напишите свой первый плагин

Это руководство проведет вас через создание блочного плагина, который можно использовать на страницах, с нуля, и поможет понять базовую структуру и рабочий процесс разработки плагинов NocoBase.

Предварительные требования

Перед началом убедитесь, что NocoBase успешно установлен. Если нет, воспользуйтесь следующими руководствами по установке:

После завершения установки можно официально начать путь разработки плагинов.

Шаг 1: создание каркаса плагина через консольный интерфейс

Выполните следующую команду в корневом каталоге репозитория, чтобы быстро сгенерировать пустой плагин:

yarn pm create @my-project/plugin-hello

После успешного выполнения команды в каталоге packages/plugins/@my-project/plugin-hello будут созданы базовые файлы. Структура по умолчанию:

packages/plugins/@my-project/plugin-hello/
├─ package.json
├─ README.md
├─ .npmignore
├─ client-v2.d.ts            # Объявление типов точки входа клиента v2
├─ client-v2.js              # Точка входа клиента v2
├─ client.d.ts               # Объявление типов точки входа клиента v1
├─ client.js                 # Точка входа клиента v1
├─ server.d.ts               # Объявление типов серверной точки входа
├─ server.js                 # Серверная точка входа
└─ src
   ├─ index.ts               # Экспорт серверного плагина по умолчанию
   ├─ client-v2              # Расположение клиентского кода v2
   │  ├─ index.tsx           # Класс клиентского плагина, экспортируемый по умолчанию
   │  ├─ plugin.tsx          # Точка входа плагина (расширяет @nocobase/client-v2 Plugin)
   │  └─ client.d.ts
   ├─ client                 # Расположение клиентского кода v1
   │  ├─ index.tsx
   │  ├─ plugin.tsx
   │  ├─ locale.ts
   │  ├─ models
   │  │  └─ index.ts
   │  └─ client.d.ts
   ├─ server                 # Расположение серверного кода
   │  ├─ index.ts            # Класс серверного плагина, экспортируемый по умолчанию
   │  ├─ plugin.ts           # Точка входа плагина (расширяет @nocobase/server Plugin)
   │  └─ collections         # Серверные коллекции (изначально пустой каталог)
   └─ locale                 # Ресурсы локализации
      ├─ en-US.json
      └─ zh-CN.json

Каркас генерирует минимальный скелет — в src/client-v2/ есть только файлы точки входа. Каталог models/ и файл locale.ts, используемые в следующих шагах, вы создаёте самостоятельно.

Затем запустите режим разработки, чтобы изменения кода подхватывались горячей перезагрузкой:

Если проект создан с помощью NocoBase CLI (nb init), выполните в корне проекта (<app-path>):
```
nb source dev
```
Если вы самостоятельно склонировали репозиторий с исходным кодом NocoBase, выполните в корне исходников:
```
yarn dev
```

После запуска откройте в браузере страницу менеджера плагинов (URL по умолчанию: http://localhost:13000/admin/settings/plugin-manager), чтобы проверить, появился ли плагин в списке.

Шаг 2: реализуйте простой клиентский блок

Далее добавим в плагин пользовательскую модель блока для отображения приветственного сообщения.

Создайте файл со вспомогательными функциями перевода src/client-v2/locale.ts. tExpr объявляет выражение перевода с пространством имён, а useT даёт функцию перевода внутри компонентов:

import { tExpr as _tExpr, useFlowEngine } from '@nocobase/flow-engine';
// @ts-ignore
import pkg from '../../package.json';

export function useT() {
  const engine = useFlowEngine();
  return (str: string) => engine.context.t(str, { ns: [pkg.name, 'client'] });
}

export function tExpr(key: string) {
  return _tExpr(key, { ns: [pkg.name, 'client'] });
}

Создайте новый файл модели блока src/client-v2/models/HelloBlockModel.tsx:

import React from 'react';
import { BlockModel } from '@nocobase/client-v2';
import { tExpr } from '../locale';

export class HelloBlockModel extends BlockModel {
  renderComponent() {
    return (
      <div>
        <h1>Привет, NocoBase!</h1>
        <p>Это простой блок, отрисованный с помощью HelloBlockModel.</p>
      </div>
    );
  }
}

HelloBlockModel.define({
  label: tExpr('Hello block'),
});

Зарегистрируйте модель блока. Создать файл модели недостаточно — клиентская среда выполнения не сканирует каталог models/ автоматически, поэтому модель нужно явно зарегистрировать в точке входа плагина. Отредактируйте src/client-v2/plugin.tsx и объявите способ загрузки модели через registerModelLoaders внутри load():

import { Plugin } from '@nocobase/client-v2';

export class PluginHelloClientV2 extends Plugin {
  async load() {
    this.flowEngine.registerModelLoaders({
      HelloBlockModel: {
        loader: () => import('./models/HelloBlockModel'),
      },
    });
  }
}

export default PluginHelloClientV2;

registerModelLoaders принимает функции отложенной загрузки, поэтому модель загружается только тогда, когда она действительно используется. Ключ (HelloBlockModel) должен совпадать с именем класса модели — по нему среда выполнения извлекает класс модели из именованных экспортов модуля.

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

Шаг 3: активируйте и протестируйте плагин

Включить плагин можно через командную строку или интерфейс:

Командная строка
```
yarn pm enable @my-project/plugin-hello
```
Интерфейс управления: откройте менеджер плагинов, найдите @my-project/plugin-hello и нажмите «Активировать».

После активации создайте новую страницу «Современная страница (v2)». При добавлении блоков вы увидите «Приветственный блок». Вставьте его на страницу, чтобы увидеть приветственный контент, который вы только что написали.

20250928174529

Предустановка и включение плагина по умолчанию (необязательно)

Выше описан способ вручную включить отдельный плагин. Если вы поддерживаете собственное приложение NocoBase и хотите, чтобы определённые плагины были автоматически готовы к работе после выполнения nocobase install (первоначальная установка) или nocobase upgrade (обновление), можно использовать две переменные среды для управления состоянием плагинов по умолчанию:

APPEND_PRESET_LOCAL_PLUGINS (добавить предустановленные плагины) — добавляет плагин в список предустановленных локальных плагинов; после установки он появится в «Менеджере плагинов», но по умолчанию не будет активирован — потребуется включить его вручную
APPEND_PRESET_BUILT_IN_PLUGINS (добавить встроенные плагины) — добавляет плагин в список встроенных плагинов; при установке он активируется автоматически, и как встроенный плагин его нельзя отключить или удалить через «Менеджер плагинов»

Значением обеих переменных является имя пакета плагина (поле name в package.json); несколько плагинов разделяются запятыми. В файле .env конфигурация выглядит следующим образом:

# Предустановка по умолчанию: плагин появляется в списке менеджера плагинов, но не активируется автоматически
APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world

# Включение по умолчанию: автоматически устанавливается и активируется, отключить через интерфейс невозможно
APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world

Как правило, для локальной разработки и отладки достаточно команды yarn pm enable, описанной выше. Эти две переменные больше подходят для сценариев «готового к использованию» дистрибутива — например, когда вы упаковываете приложение NocoBase с фиксированным набором плагинов и хотите, чтобы они были доступны сразу после инициализации.

Подсказка

Плагин должен быть загружен локально и доступен для разрешения в каталоге node_modules. См. Структура проекта
После настройки переменных необходимо повторно выполнить nocobase install или nocobase upgrade, чтобы изменения вступили в силу
Полное описание переменных среды см. в разделе Переменные среды

Шаг 4: сборка и упаковка

Когда вы будете готовы распространять плагин в другие окружения, сначала выполните сборку и упаковку:

yarn build @my-project/plugin-hello --tar
# Или выполнить в два шага
yarn build @my-project/plugin-hello
yarn nocobase tar @my-project/plugin-hello

Примечание: если плагин создан в исходном репозитории, первая сборка запустит полную проверку типов всего репозитория, что может занять время. Рекомендуется убедиться, что зависимости установлены, а репозиторий находится в собираемом состоянии.

После завершения сборки файл пакета по умолчанию находится в каталоге storage/tar/ с именем <имя-пакета>-<версия>.tgz — например, storage/tar/@my-project/plugin-hello-0.1.0.tgz.

Шаг 5: загрузка в другое приложение NocoBase

Загрузите архив и распакуйте его в каталог ./storage/plugins целевого приложения. Подробнее см. Установка и обновление плагинов.

Если целевое приложение создано с помощью NocoBase CLI (nb init), плагин можно импортировать напрямую командой nb plugin import, не распаковывая архив вручную:

nb plugin import /your/path/plugin-hello-0.1.0.tgz

Связанные ссылки

Обзор разработки плагинов — микроядерная архитектура NocoBase и жизненный цикл плагина
Структура проекта плагина — соглашения о структуре каталогов, пути загрузки и приоритеты плагинов
Обзор серверной разработки — общее введение в серверные плагины и основные концепции
Обзор клиентской разработки — общее введение в клиентские плагины и основные концепции
Сборка и упаковка — процесс сборки, упаковки и распространения плагина
Тестирование — написание тестов для серверных плагинов
Установка с помощью create-nocobase-app — один из способов установки NocoBase
Установка из исходного кода Git — установка NocoBase из исходного кода
Установка и обновление плагинов — загрузка упакованного плагина в другие среды
Переменные среды — настройка переменных среды для предустановленных и встроенных плагинов

#Напишите свой первый плагин

#Предварительные требования

#Шаг 1: создание каркаса плагина через консольный интерфейс

#Шаг 2: реализуйте простой клиентский блок

#Шаг 3: активируйте и протестируйте плагин

#Предустановка и включение плагина по умолчанию (необязательно)

#Шаг 4: сборка и упаковка

#Шаг 5: загрузка в другое приложение NocoBase

#Связанные ссылки