#Напишіть свій перший плагін

Цей посібник допоможе вам з нуля створити блоковий плагін, який можна використовувати на сторінках. Ви дізнаєтеся про базову структуру та процес розробки плагінів 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 цільового додатка. Детальніше дивіться у розділі Встановлення та оновлення плагінів.