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

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

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

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

• Установка с помощью create-nocobase-app
• Установка из исходного кода Git

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

#Шаг 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'),
});

2. Зарегистрируйте модель блока. Отредактируйте 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». Вставьте его на страницу, чтобы увидеть приветственное содержимое, которое вы только что написали.

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