• Português

      • Escreva Seu Primeiro Plugin

      Este guia vai te mostrar como criar um plugin de bloco do zero que pode ser usado em páginas, te ajudando a entender a estrutura básica e o fluxo de trabalho de desenvolvimento de plugins NocoBase.

      Pré-requisitos

      Antes de começar, certifique-se de que você já instalou o NocoBase com sucesso. Se ainda não instalou, você pode consultar os seguintes guias de instalação:

      Após a instalação ser concluída, você pode oficialmente iniciar sua jornada de desenvolvimento de plugins.

      Passo 1: Crie o Esqueleto do Plugin via CLI

      Execute o seguinte comando no diretório raiz do repositório para gerar rapidamente um plugin vazio:

      yarn pm create @my-project/plugin-hello

      Após o comando ser executado com sucesso, ele irá gerar arquivos básicos no diretório packages/plugins/@my-project/plugin-hello. A estrutura padrão é a seguinte:

      ├─ /packages/plugins/@my-project/plugin-hello
  ├─ package.json
  ├─ README.md
  ├─ client.d.ts
  ├─ client.js
  ├─ server.d.ts
  ├─ server.js
  └─ src
     ├─ index.ts                 # Exporta o plugin de servidor por padrão
     ├─ client                   # Localização do código do lado do cliente
     │  ├─ index.tsx             # Classe do plugin do lado do cliente exportada por padrão
     │  ├─ plugin.tsx            # Entrada do plugin (estende @nocobase/client Plugin)
     │  ├─ models                # Opcional: modelos de frontend (como nós de fluxo)
     │  │  └─ index.ts
     │  └─ utils
     │     ├─ index.ts
     │     └─ useT.ts
     ├─ server                   # Localização do código do lado do servidor
     │  ├─ index.ts              # Classe do plugin do lado do servidor exportada por padrão
     │  ├─ plugin.ts             # Entrada do plugin (estende @nocobase/server Plugin)
     │  ├─ collections           # Opcional: coleções do lado do servidor
     │  ├─ migrations            # Opcional: migrações de dados
     │  └─ utils
     │     └─ index.ts
     ├─ utils
     │  ├─ index.ts
     │  └─ tExpr.ts
     └─ locale                   # Opcional: multi-idioma
        ├─ en-US.json
        └─ zh-CN.json

      Após a criação, você pode acessar a página do gerenciador de plugins no seu navegador (URL padrão: http://localhost:13000/admin/settings/plugin-manager) para confirmar se o plugin aparece na lista.

      Passo 2: Implemente um Bloco Cliente Simples

      Em seguida, vamos adicionar um modelo de bloco personalizado ao plugin para exibir uma mensagem de boas-vindas.

      1. Crie um novo arquivo de modelo de bloco 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. Registre o modelo de bloco. Edite client/models/index.ts para exportar o novo modelo para carregamento em tempo de execução no frontend:
      import { ModelConstructor } from '@nocobase/flow-engine';
import { HelloBlockModel } from './HelloBlockModel';

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

      Após salvar o código, se você estiver executando um script de desenvolvimento, deverá ver os logs de hot-reload na saída do terminal.

      Passo 3: Ative e Teste o Plugin

      Você pode habilitar o plugin via linha de comando ou interface:

      • Linha de Comando

        yarn pm enable @my-project/plugin-hello

      • Interface de Gerenciamento: Acesse o gerenciador de plugins, encontre @my-project/plugin-hello e clique em "Ativar".

      Após a ativação, crie uma nova página "Modern page (v2)". Ao adicionar blocos, você verá o "Hello block". Insira-o na página para ver o conteúdo de boas-vindas que você acabou de escrever.

      20250928174529

      Definir Plugin como Padrão ou Ativado por Padrão (Opcional)

      O que foi descrito acima é como ativar um único plugin manualmente. Se você estiver mantendo seu próprio aplicativo NocoBase e quiser que determinados plugins estejam automaticamente prontos após executar nocobase install (instalação inicial) ou nocobase upgrade (atualização), você pode usar duas variáveis de ambiente para controlar o estado padrão dos plugins:

      • APPEND_PRESET_LOCAL_PLUGINS (adicionar plugins locais predefinidos padrão) — adiciona o plugin à lista de plugins locais predefinidos; após a instalação, ele aparece no "Gerenciador de plugins", mas não é ativado por padrão — você precisa ativá-lo manualmente
      • APPEND_PRESET_BUILT_IN_PLUGINS (adicionar plugins integrados padrão) — adiciona o plugin à lista de plugins integrados; ele é ativado automaticamente durante a instalação e, como plugin integrado, não pode ser desativado ou removido no "Gerenciador de plugins"

      O valor de ambas as variáveis é o nome do pacote do plugin (o campo name no package.json), com múltiplos plugins separados por vírgulas. Configure assim no .env:

      # Predefinido por padrão: aparece na lista do gerenciador de plugins, mas não é ativado automaticamente
APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world

# Ativado por padrão: instalado e ativado automaticamente, e não pode ser desativado na interface
APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world

      Em geral, o yarn pm enable descrito anteriormente é suficiente para desenvolvimento e depuração local. Essas duas variáveis são mais adequadas para cenários de distribuição "pronto para uso" — por exemplo, quando você empacota um aplicativo NocoBase com plugins fixos e quer que eles estejam disponíveis imediatamente após a inicialização.

      Dica
      • O plugin precisa ter sido baixado localmente e ser resolvido no node_modules; consulte Estrutura do Projeto de Plugins
      • Após a configuração, é necessário executar nocobase install ou nocobase upgrade novamente para que as alterações tenham efeito
      • A descrição completa das variáveis de ambiente está em Variáveis de Ambiente

      Passo 4: Construa e Empacote

      Quando você estiver pronto para distribuir o plugin para outros ambientes, precisará primeiro construí-lo e depois empacotá-lo:

      yarn build @my-project/plugin-hello --tar
# Ou execute em duas etapas
yarn build @my-project/plugin-hello
yarn nocobase tar @my-project/plugin-hello

      Dica: Se o plugin for criado no repositório de código-fonte, a primeira construção irá acionar uma verificação de tipo de todo o repositório, o que pode levar algum tempo. Recomenda-se garantir que as dependências estejam instaladas e que o repositório esteja em um estado construível.

      Após a construção ser concluída, o arquivo empacotado estará localizado por padrão em storage/tar/@my-project/plugin-hello.tar.gz.

      Passo 5: Faça o Upload para Outro Aplicativo NocoBase

      Faça o upload e extraia para o diretório ./storage/plugins do aplicativo de destino. Para mais detalhes, consulte Instalar e Atualizar Plugins.