• Русский

      • Создайте свой первый плагин

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

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

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

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

      Шаг 1: Создание основы плагина с помощью CLI

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

      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

      После создания вы можете открыть страницу менеджера плагинов в браузере (адрес по умолчанию: 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>Hello, NocoBase!</h1>
        <p>This is a simple block rendered by 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 и нажмите «Активировать».

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

      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 целевого приложения. Подробности см. в разделе Установка и обновление плагинов.

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