ComponentBuilder
Componha mensagens Components V2 com builders tipados, templates reutilizáveis e integração direta com o runtime do Core.
O que o ComponentBuilder resolve#
Ele representa a mensagem como uma árvore validável antes de converter o documento para o formato aceito pelo Discord.js.
Composição
Builders pequenos representam texto, seções, botões, selects, galerias e containers.
Validação
Limites do Discord são verificados antes de a mensagem chegar à API.
Runtime
Callbacks, prompts e paginações são conectados automaticamente ao Core.
O fluxo possui quatro etapas: você monta builders, gera um ComponentTemplate, converte o documento com toDiscordMessagePayload() e envia pela interação do Discord.
const template = new MessageBuilder() .addComponents( new ContainerBuilder().addTextDisplayComponents( new TextDisplayBuilder().setContent('Olá, Components V2!') ) ) .template()await interaction.reply({ ...toDiscordMessagePayload(template.document()), flags: MessageFlags.IsComponentsV2})As quatro camadas#
| Camada | Papel | Exemplos |
|---|---|---|
| Mensagem | Payload completo | MessageBuilder |
| Layout | Organiza a hierarquia visual | ContainerBuilder, SectionBuilder, ActionRowBuilder |
| Conteúdo | Mostra informação | TextDisplayBuilder, MediaGalleryBuilder, FileBuilder |
| Interação | Recebe ações do usuário | ButtonBuilder e builders de select |
Imports recomendados#
Importe Discord.js pelo Core e os builders visuais pelo ComponentBuilder.
import { MessageFlags, SlashCommandBuilder} from '@ninenity/core'import { ActionRowBuilder, ButtonBuilder, ButtonStyle, ContainerBuilder, MessageBuilder, SectionBuilder, TextDisplayBuilder, toDiscordMessagePayload, type MessageActionRowComponentBuilder} from '@ninenity/componentbuilder'- Use
MessageFlags.IsComponentsV2ao enviar uma árvore Components V2. - Adicione
MessageFlags.Ephemeralquando a resposta só deve aparecer para o autor. - Use o tipo
MessageActionRowComponentBuildernoActionRowBuilderquando misturar builders interativos. - Não importe APIs internas de
src; use apenas os exports do pacote.
Documento, template e payload#
Cada representação existe para um momento diferente do fluxo.
const builder = new MessageBuilder().setContent('Status: pronto')// Objeto serializável do ComponentBuilderconst document = builder.build()// Reutilizável, renderizável e exportávelconst template = builder.template({ name: 'status-card' })// Payload final para interaction.reply/updateconst payload = toDiscordMessagePayload(template.document())| Método | Retorna | Use quando |
|---|---|---|
build() | MessageDocument | Precisa inspecionar ou serializar a árvore |
template() | ComponentTemplate | Vai reutilizar, renderizar tokens ou registrar páginas |
template.document() | MessageDocument | Vai converter e enviar ao Discord |
toDiscordMessagePayload() | Payload Discord.js | Etapa imediatamente anterior a reply() ou update() |
Limites estruturais#
O Builder Studio e a biblioteca aplicam os limites mais importantes antes do envio.
| Estrutura | Regra |
|---|---|
| Mensagem | Até 40 componentes na árvore |
| Container | Até 10 filhos e sem containers aninhados |
| Action row | Até 5 botões ou um único select |
| Section | Acessório deve ser botão ou thumbnail |
| Galeria | Entre 1 e 10 imagens |
| Interativos | Cada customId deve ser único na mensagem |
Escolha o próximo tópico#
Mensagens V2
Layouts completos com seções, mídia, botões e selects.
Abrir tópico →Callbacks
Como tratar cliques e seleções sem registradores duplicados.
Abrir tópico →Prompts
Fluxos de confirmação com páginas de resultado.
Abrir tópico →Paginação
Páginas estáticas, dinâmicas e controles personalizados.
Abrir tópico →