Discord Components V2 (discord.js)
Use Components V2 para todos os novos layouts de mensagens. O uso clássico de content + embeds + linhas de ação ainda funciona, mas o V2 oferece controle completo do layout e é a abordagem moderna recomendada.
Requer discord.js ≥ 14.19 (a versão estável atual é 14.28.x). Sempre defina a flag.
Regras Críticas
- Toda mensagem V2 deve incluir
flags: MessageFlags.IsComponentsV2(ouMessageFlags.IsComponentsV2 | MessageFlags.Ephemeral). - Depois que uma mensagem é enviada com a flag V2, você não pode removê-la ao editar.
- Com a flag definida, você não pode enviar
content,embeds,polloustickers. Todo texto visível fica emTextDisplayBuilder. - Máximo de 40 componentes no total (contagem aninhada). Máximo de 4000 caracteres em todos os TextDisplays.
- Anexos são invisíveis a menos que sejam referenciados por um componente Thumbnail, MediaGallery ou File via
attachment://nome-do-arquivo. - Componentes de nível superior podem ser: Container, TextDisplay, Section, Separator, MediaGallery, File, ActionRow.
- Containers não podem conter outros Containers.
- Toda Section precisa de exatamente um acessório (miniatura ou botão).
Limites
| Restrição | Limite | Notas |
|---|---|---|
| Componentes por mensagem | 40 | Componentes aninhados são contados individualmente. |
| Caracteres de texto | 4.000 | Soma de todos os TextDisplay na mensagem. |
| Botões por ActionRow | 5 | Ou um menu de seleção, nunca ambos na mesma linha. |
| Opções de seleção | 25 | Por menu de seleção. |
| Itens de MediaGallery | 10 | Por galeria. |
| Containers | Sem aninhamento | Um Container não pode conter outro Container. |
| Sections | 1 acessório cada | Miniatura ou botão, não ambos, nem nenhum. |
| Anexos | 10 por mensagem | Cada um precisa ser referenciado para ser visível. |
O limite clássico de "5 ActionRows por mensagem" é substituído pelo orçamento de 40 componentes quando a flag V2 está definida — uma ActionRow é simplesmente um dos 40 componentes.
Imports (típicos)
const {
ContainerBuilder,
TextDisplayBuilder,
SectionBuilder,
SeparatorBuilder,
SeparatorSpacingSize,
MediaGalleryBuilder,
MediaGalleryItemBuilder,
FileBuilder,
ThumbnailBuilder,
ActionRowBuilder,
ButtonBuilder,
ButtonStyle,
StringSelectMenuBuilder,
UserSelectMenuBuilder,
RoleSelectMenuBuilder,
ChannelSelectMenuBuilder,
MentionableSelectMenuBuilder,
MessageFlags,
AttachmentBuilder,
} = require('discord.js');
Flags
MessageFlags.IsComponentsV2 // necessário para renderização V2
MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral // resposta efêmera
MessageFlags.IsComponentsV2 | MessageFlags.SuppressEmbeds
A flag é necessária para renderizar componentes V2 e é permanente: uma vez que uma mensagem é enviada com ela, a edição não pode removê-la.
Construtores Principais e Padrões
1. TextDisplay – todo texto fica aqui
new TextDisplayBuilder().setContent('## Título\nSuporta **negrito**, *itálico*, `código`, listas, menções, emojis.')
Apenas markdown padrão do Discord: títulos (#–###), negrito, itálico, sublinhado, tachado, código inline, blocos de código, spoilers (||texto||), listas, citações, links, timestamps, menções e emoji.
Não há campo content na mensagem ao usar V2 — este construtor é o único lugar onde o texto é renderizado. Prefira vários TextDisplays pequenos em vez de um bloco gigante para melhor ritmo visual.
2. Container – o "embed" moderno
const container = new ContainerBuilder()
.setAccentColor(0x5865F2) // cor de realce opcional (número hexadecimal)
// .setSpoiler(true) // desfoca o container inteiro
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# Título\nSubtítulo ou descrição.'),
)
.addSeparatorComponents(
new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(/* botões ou um menu de seleção */),
);
Conjunto completo de métodos: addTextDisplayComponents, addSectionComponents, addSeparatorComponents, addActionRowComponents, addMediaGalleryComponents, addFileComponents, addComponents e setComponents([...]) para substituir todos os filhos. A ordem dos filhos é preservada, então construa de cima para baixo na ordem de leitura.
Cores de realce que ficam boas: blurple do Discord 0x5865F2, sucesso 0x57F287, perigo 0xED4245, cinza suave 0x99AAB5 ou cores da marca. Omita o realce para um visual limpo e plano. A cor deve ser um número — '#5865F2' e 'blurple' geram erro.
3. Section – texto + acessório (miniatura ou botão)
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**Nome do recurso**'),
new TextDisplayBuilder().setContent('Texto de apoio curto. Mantenha em 1–3 TextDisplays.'),
)
.setThumbnailAccessory(
new ThumbnailBuilder()
.setURL('https://exemplo.com/icone.png') // ou attachment://arquivo.png
.setDescription('Texto alternativo'),
)
// OU
.setButtonAccessory(
new ButtonBuilder()
.setCustomId('acao')
.setLabel('Faça')
.setStyle(ButtonStyle.Primary),
);
Use Sections quando quiser uma miniatura ou um botão proeminente ao lado de texto relacionado. Nunca deixe uma Section sem acessório e nunca defina ambos.
4. Separator – espaço de respiro visual
new SeparatorBuilder()
.setDivider(true) // mostra a linha fina
.setSpacing(SeparatorSpacingSize.Small); // ou Large
Coloque entre grupos lógicos. Prefira Small + divisor para a maioria dos cartões; Large para quebras visuais maiores. divider: false com espaçamento Large dá um espaço em branco sem linha.
5. MediaGallery e File
new MediaGalleryBuilder().addItems(
new MediaGalleryItemBuilder()
.setURL('https://…') // ou attachment://imagem.png
.setDescription('Alt')
.setSpoiler(false),
// até 10 itens
);
new FileBuilder().setURL('attachment://relatorio.pdf'); // também deve passar o arquivo em `files`
Arquivos enviados, mas nunca referenciados por um File, Thumbnail ou MediaGallery, permanecem invisíveis.
6. Thumbnail
new ThumbnailBuilder()
.setURL('https://…/icone.png') // ou attachment://icone.png
.setDescription('Texto alternativo')
.setSpoiler(false);
Miniaturas só existem como acessório de Section — não são componentes de nível superior.
7. Componentes interativos (dentro de ActionRows)
- Máximo de 5 botões ou 1 menu de seleção por ActionRow.
- Botões:
ButtonStyle.Primary | Secondary | Success | Danger | Link | Premium. - Botões de link precisam de
.setURL(), nunca de um customId. Botões Premium precisam de.setSKUId(). - Sempre dê aos componentes interativos um
customIdúnico e com namespace (ex.:ticket:close,poll:vote:yes). CustomIds têm no máximo 100 caracteres.
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('confirmar').setLabel('Confirmar').setStyle(ButtonStyle.Success),
new ButtonBuilder().setCustomId('cancelar').setLabel('Cancelar').setStyle(ButtonStyle.Secondary),
);
new ActionRowBuilder().addComponents(
new StringSelectMenuBuilder()
.setCustomId('escolher-plano')
.setPlaceholder('Selecione um plano…')
.addOptions(
{ label: 'Iniciante', value: 'iniciante', description: 'Para indivíduos' },
{ label: 'Profissional', value: 'pro', description: 'Para equipes', emoji: '⭐' },
),
);
Seletores de entidade compartilham setCustomId, setPlaceholder, setMinValues, setMaxValues, setDisabled:
| Construtor | Definidor de valor padrão |
|---|---|
UserSelectMenuBuilder | setDefaultUsers(...) |
RoleSelectMenuBuilder | setDefaultRoles(...) |
ChannelSelectMenuBuilder | setDefaultChannels(...), setChannelTypes(...) |
MentionableSelectMenuBuilder | setDefaultValues(...) |
Seletores não têm rótulo próprio dentro de uma ActionRow — o placeholder é o que os usuários veem.
8. Anexos
const file = new AttachmentBuilder(buffer, { name: 'grafico.png' });
// referencie como 'attachment://grafico.png' em um MediaGallery, Thumbnail ou File
O name do anexo é o que attachment:// deve corresponder — incluindo maiúsculas/minúsculas e extensão.
Enviando e Editando
// Canal ou interação
await channel.send({
components: [container], // ou [text, separator, container, …]
flags: MessageFlags.IsComponentsV2,
files: [attachment], // apenas se referenciado
allowedMentions: { parse: [] }, // controle de menções de TextDisplays
});
// Efêmero
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral
// Editar (flag é permanente)
await message.edit({
components: [novoLayout],
// NÃO tente remover a flag V2
});
Todos os construtores implementam .toJSON(). Se você persistir layouts, armazene container.toJSON() e passe o JSON de volta para components para reconstruir.
Receitas de Layout Bonito
Cartão de informação limpo
new ContainerBuilder()
.setAccentColor(0x5865F2)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# Regras do Servidor\nPor favor, leia com atenção.'),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('1. Seja respeitoso\n2. Sem spam\n3. Siga os ToS do Discord'),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('regras:aceitar').setLabel('Eu Aceito').setStyle(ButtonStyle.Success),
),
);
Destaque de recurso com miniatura
new ContainerBuilder()
.setAccentColor(0x57F287)
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('## Novo Painel'),
new TextDisplayBuilder().setContent('Estatísticas em tempo real, gerenciamento de cargos e análises em um só lugar.'),
)
.setThumbnailAccessory(new ThumbnailBuilder().setURL('attachment://painel.png').setDescription('Visualização do painel')),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('painel:abrir').setLabel('Abrir Painel').setStyle(ButtonStyle.Primary),
new ButtonBuilder().setLabel('Changelog').setURL('https://exemplo.com/changelog').setStyle(ButtonStyle.Link),
),
);
Passe files: [new AttachmentBuilder(buffer, { name: 'painel.png' })] junto com os componentes.
Mensagem estilo painel de controle com várias seções
new ContainerBuilder()
.setAccentColor(0x5865F2)
.addTextDisplayComponents(new TextDisplayBuilder().setContent('# Painel de Controle'))
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**Status**'),
new TextDisplayBuilder().setContent('🟢 Todos os sistemas operacionais\n👥 1.284 membros\n📈 42 entradas hoje'),
)
.setButtonAccessory(
new ButtonBuilder().setCustomId('status:atualizar').setLabel('Atualizar').setStyle(ButtonStyle.Secondary),
),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(false).setSpacing(SeparatorSpacingSize.Large))
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**Ações**'),
new TextDisplayBuilder().setContent('Modere, anuncie ou configure o servidor.'),
)
.setButtonAccessory(
new ButtonBuilder().setCustomId('painel:configuracoes').setLabel('Configurações').setStyle(ButtonStyle.Secondary),
),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('painel:anunciar').setLabel('Anunciar').setStyle(ButtonStyle.Primary),
new ButtonBuilder().setCustomId('painel:moderar').setLabel('Moderar').setStyle(ButtonStyle.Danger),
),
);
Anúncio com destaque de imagem
Mantenha o texto em 2–3 linhas curtas para que a imagem continue sendo o foco. O banner é um item de MediaGallery — lembre-se de enviá-lo.
new ContainerBuilder()
.setAccentColor(0xFEE75C)
.addMediaGalleryComponents(
new MediaGalleryBuilder().addItems(
new MediaGalleryItemBuilder().setURL('attachment://banner-evento.png').setDescription('Banner do evento de verão'),
),
)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# Evento de Verão\nJunte-se a nós **sexta às 20h** para a transmissão de lançamento.'),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('-# Participação é opcional · Horários mostrados em UTC'),
);
-# é subtexto — perfeito para letras miúdas sem competir com o título.
Confirmação / Erro efêmero
Reutilize um helper com um realce + título + mensagem em vez de escrever dois layouts.
const status = (tipo, texto) => new ContainerBuilder()
.setAccentColor(tipo === 'erro' ? 0xED4245 : 0x57F287)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent(`### ${tipo === 'erro' ? 'Algo deu errado' : 'Feito'}\n${texto}`),
);
await interaction.reply({
components: [status('erro', 'Você não tem permissão para fazer isso.')],
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral,
});
Mantenha respostas efêmeras em um único Container — sem separadores, sem linhas de ação, a menos que precise de um botão de acompanhamento.
Prompt de confirmação
Coloque a ação destrutiva por último e estilize-a como Danger.
new ContainerBuilder()
.setAccentColor(0xFEE75C)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('## Deletar 47 mensagens?'),
new TextDisplayBuilder().setContent('Isso não pode ser desfeito.'),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('limpar:cancelar').setLabel('Cancelar').setStyle(ButtonStyle.Secondary),
new ButtonBuilder().setCustomId('limpar:confirmar').setLabel('Deletar').setStyle(ButtonStyle.Danger),
),
);
Lista compacta
Para changelogs, leaderboards e listas de status: coloque o rótulo em negrito, mantenha cada entrada em uma linha, use -# para metadados.
new TextDisplayBuilder().setContent('**João** — 1.234 pts\n**Maria** — 987 pts\n-# Atualizado há 5 minutos')