• Русский

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

      Это руководство проведет вас через создание блочного плагина, который можно использовать на страницах, с нуля, и поможет понять базовую структуру и рабочий процесс разработки плагинов 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
  ├─ client.d.ts
  ├─ client.js
  ├─ server.d.ts
  ├─ server.js
  └─ src
     ├─ index.ts                 # Экспорт серверного плагина по умолчанию
     ├─ client                   # Расположение клиентского кода
     │  ├─ index.tsx             # Класс клиентского плагина, экспортируемый по умолчанию
     │  ├─ plugin.tsx            # Точка входа плагина (расширяет @nocobase/client Plugin)
     │  ├─ models                # Необязательно: модели клиентской части (например, узлы потока)
     │  │  └─ index.ts
     │  └─ utils
     │     ├─ index.ts
     │     └─ useT.ts
     ├─ server                   # Расположение серверного кода
     │  ├─ index.ts              # Класс серверного плагина, экспортируемый по умолчанию
     │  ├─ plugin.ts             # Точка входа плагина (расширяет @nocobase/server Plugin)
     │  ├─ collections           # Необязательно: серверные коллекции
     │  ├─ migrations            # Необязательно: миграции данных
     │  └─ utils
     │     └─ index.ts
     ├─ utils
     │  ├─ index.ts
     │  └─ tExpr.ts
     └─ locale                   # Необязательно: мультиязычность
        ├─ en-US.json
        └─ zh-CN.json

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

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

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

      1. Создайте новый файл модели блока client/models/HelloBlockModel.tsx:
      import { BlockModel } from '@nocobase/client';
import React from 'react';
import { tExpr } from '../utils';

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

HelloBlockModel.define({
  label: tExpr('Hello block'),
});
      1. Зарегистрируйте модель блока. Отредактируйте client/models/index.ts, чтобы экспортировать новую модель для загрузки клиентской части во время выполнения:
      import { ModelConstructor } from '@nocobase/flow-engine';
import { HelloBlockModel } from './HelloBlockModel';

export default {
  HelloBlockModel,
} as Record<string, ModelConstructor>;

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

      Шаг 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/@my-project/plugin-hello.tar.gz.

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

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

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