Discord Components V2 (discord.js)
Usa Components V2 para todos los diseños de mensajes nuevos. content + embeds clásicos + filas de acción todavía funcionan, pero V2 proporciona control total del diseño y es el enfoque moderno recomendado.
Requiere discord.js ≥ 14.19 (la versión estable actual es 14.28.x). Siempre establece la bandera.
Reglas Críticas
- Cada mensaje V2 debe incluir
flags: MessageFlags.IsComponentsV2(oMessageFlags.IsComponentsV2 | MessageFlags.Ephemeral). - Una vez que un mensaje se envía con la bandera V2, no puedes eliminarla al editarlo.
- Con la bandera activada no puedes enviar
content,embeds,pollostickers. Todo el texto visible reside enTextDisplayBuilder. - Máximo 40 componentes en total (contando anidados). Máximo 4000 caracteres en todos los TextDisplay.
- Los archivos adjuntos son invisibles a menos que sean referenciados por un componente Thumbnail, MediaGallery o File mediante
attachment://filename. - Los componentes de nivel superior pueden ser: Container, TextDisplay, Section, Separator, MediaGallery, File, ActionRow.
- Los Container no pueden anidarse dentro de otros Container.
- Cada Section necesita exactamente un accesorio (miniatura o botón).
Límites
| Restricción | Límite | Notas |
|---|---|---|
| Componentes por mensaje | 40 | Los componentes anidados cuentan individualmente. |
| Caracteres de texto | 4.000 | Suma de todos los TextDisplay en el mensaje. |
| Botones por ActionRow | 5 | O un menú de selección, nunca ambos en la misma fila. |
| Opciones de selección | 25 | Por menú de selección. |
| Elementos de MediaGallery | 10 | Por galería. |
| Containers | Sin anidamiento | Un Container no puede contener otro Container. |
| Sections | 1 accesorio cada una | Miniatura o botón, no ambos, no ninguno. |
| Archivos adjuntos | 10 por mensaje | Cada uno debe ser referenciado para ser visible. |
El límite clásico de "5 ActionRows por mensaje" se reemplaza por el presupuesto de 40 componentes cuando la bandera V2 está activada: un ActionRow es simplemente uno de los 40 componentes.
Importaciones (típicas)
const {
ContainerBuilder,
TextDisplayBuilder,
SectionBuilder,
SeparatorBuilder,
SeparatorSpacingSize,
MediaGalleryBuilder,
MediaGalleryItemBuilder,
FileBuilder,
ThumbnailBuilder,
ActionRowBuilder,
ButtonBuilder,
ButtonStyle,
StringSelectMenuBuilder,
UserSelectMenuBuilder,
RoleSelectMenuBuilder,
ChannelSelectMenuBuilder,
MentionableSelectMenuBuilder,
MessageFlags,
AttachmentBuilder,
} = require('discord.js');
Banderas
MessageFlags.IsComponentsV2 // requerido para renderizado V2
MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral // respuesta efímera
MessageFlags.IsComponentsV2 | MessageFlags.SuppressEmbeds
La bandera es necesaria para renderizar componentes V2 y es permanente: una vez que un mensaje se envía con ella, la edición no puede eliminarla.
Builders Principales y Patrones
1. TextDisplay – todo el texto vive aquí
new TextDisplayBuilder().setContent('## Título\nSoporta **negritas**, *cursivas*, `código`, listas, menciones, emojis.')
Solo markdown estándar de Discord: títulos (#–###), negrita, cursiva, subrayado, tachado, código en línea, bloques de código, spoilers (||texto||), listas, citas en bloque, enlaces, marcas de tiempo, menciones y emoji.
No hay campo content en el mensaje al usar V2 — este builder es el único lugar donde se renderiza el texto. Prefiere varios TextDisplay pequeños en lugar de un bloque gigante para un mejor ritmo visual.
2. Container – el “embed” moderno
const container = new ContainerBuilder()
.setAccentColor(0x5865F2) // acento izquierdo opcional (número hex)
// .setSpoiler(true) // difumina todo el contenedor
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# Título\nSubtítulo o descripción.'),
)
.addSeparatorComponents(
new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(/* botones o un menú de selección */),
);
Conjunto completo de métodos: addTextDisplayComponents, addSectionComponents, addSeparatorComponents, addActionRowComponents, addMediaGalleryComponents, addFileComponents, addComponents, y setComponents([...]) para reemplazar todos los hijos. El orden de los hijos se conserva, así que construye de arriba a abajo en orden de lectura.
Colores de acento que se ven bien: blurple de Discord 0x5865F2, éxito 0x57F287, peligro 0xED4245, gris suave 0x99AAB5, o colores de marca. Omite el acento para un aspecto limpio y plano. El color debe ser un número — '#5865F2' y 'blurple' lanzan error.
3. Section – texto + accesorio (miniatura o botón)
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**Nombre de la función**'),
new TextDisplayBuilder().setContent('Texto de apoyo breve. Mantén 1–3 TextDisplay.'),
)
.setThumbnailAccessory(
new ThumbnailBuilder()
.setURL('https://example.com/icon.png') // o attachment://archivo.png
.setDescription('Texto alternativo'),
)
// O
.setButtonAccessory(
new ButtonBuilder()
.setCustomId('accion')
.setLabel('Hacerlo')
.setStyle(ButtonStyle.Primary),
);
Usa Sections cuando quieras una miniatura o un botón prominente junto al texto relacionado. Nunca dejes una Section sin accesorio, y nunca establezcas ambos.
4. Separator – espacio visual
new SeparatorBuilder()
.setDivider(true) // mostrar la línea fina
.setSpacing(SeparatorSpacingSize.Small); // o Large
Coloca entre grupos lógicos. Prefiere Small + divisor para la mayoría de las tarjetas; Large para espacios visuales más grandes. divider: false con espaciado Large da un espacio en blanco sin línea.
5. MediaGallery y File
new MediaGalleryBuilder().addItems(
new MediaGalleryItemBuilder()
.setURL('https://…') // o attachment://imagen.png
.setDescription('Alt')
.setSpoiler(false),
// hasta 10 elementos
);
new FileBuilder().setURL('attachment://reporte.pdf'); // también debe pasar el archivo en `files`
Los archivos subidos pero nunca referenciados por un componente File, Thumbnail o MediaGallery permanecen invisibles.
6. Thumbnail
new ThumbnailBuilder()
.setURL('https://…/icon.png') // o attachment://icono.png
.setDescription('Texto alternativo')
.setSpoiler(false);
Las miniaturas solo existen como accesorio de Section — no son componentes de nivel superior.
7. Componentes interactivos (dentro de ActionRows)
- Máximo 5 botones o 1 menú de selección por ActionRow.
- Botones:
ButtonStyle.Primary | Secondary | Success | Danger | Link | Premium. - Los botones de enlace necesitan
.setURL(), nunca un customId. Los botones Premium necesitan.setSKUId(). - Siempre asigna a los componentes interactivos un
customIdúnico y con espacio de nombres (ej.ticket:cerrar,encuesta:votar:si). Los customId tienen un máximo de 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('elegir-plan')
.setPlaceholder('Selecciona un plan…')
.addOptions(
{ label: 'Inicial', value: 'inicial', description: 'Para individuos' },
{ label: 'Pro', value: 'pro', description: 'Para equipos', emoji: '⭐' },
),
);
Los menús de selección de entidades comparten setCustomId, setPlaceholder, setMinValues, setMaxValues, setDisabled:
| Builder | Establecedor de valor predeterminado |
|---|---|
UserSelectMenuBuilder | setDefaultUsers(...) |
RoleSelectMenuBuilder | setDefaultRoles(...) |
ChannelSelectMenuBuilder | setDefaultChannels(...), setChannelTypes(...) |
MentionableSelectMenuBuilder | setDefaultValues(...) |
Los menús de selección no tienen su propia etiqueta dentro de un ActionRow — el placeholder es lo que los usuarios ven.
8. Archivos adjuntos
const archivo = new AttachmentBuilder(buffer, { name: 'grafico.png' });
// refiérelo como 'attachment://grafico.png' en un MediaGallery, Thumbnail o File
El name del archivo adjunto es lo que attachment:// debe coincidir, incluyendo mayúsculas y extensión.
Envío y Edición
// Canal o interacción
await canal.send({
components: [container], // o [texto, separador, container, …]
flags: MessageFlags.IsComponentsV2,
files: [archivo], // solo si se referencia
allowedMentions: { parse: [] }, // controlar pings desde TextDisplay
});
// Efímero
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral
// Edición (la bandera es permanente)
await mensaje.edit({
components: [nuevoDiseno],
// NO intentes eliminar la bandera V2
});
Todos los builders implementan .toJSON(). Si persistes diseños, almacena container.toJSON() y pasa el JSON de vuelta a components para reconstruir.
Recetas de Diseño Atractivas
Tarjeta de información limpia
new ContainerBuilder()
.setAccentColor(0x5865F2)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# Reglas del Servidor\nPor favor, léelas con atención.'),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('1. Sé respetuoso\n2. Sin spam\n3. Sigue los Términos de Servicio de Discord'),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('reglas:aceptar').setLabel('Acepto').setStyle(ButtonStyle.Success),
),
);
Destacado de función con miniatura
new ContainerBuilder()
.setAccentColor(0x57F287)
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('## Nuevo Panel'),
new TextDisplayBuilder().setContent('Estadísticas en tiempo real, gestión de roles y análisis en un solo lugar.'),
)
.setThumbnailAccessory(new ThumbnailBuilder().setURL('attachment://panel.png').setDescription('Vista previa del panel')),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('panel:abrir').setLabel('Abrir Panel').setStyle(ButtonStyle.Primary),
new ButtonBuilder().setLabel('Registro de cambios').setURL('https://example.com/changelog').setStyle(ButtonStyle.Link),
),
);
Pasa files: [new AttachmentBuilder(buffer, { name: 'panel.png' })] junto con los componentes.
Mensaje estilo panel de control de múltiples secciones
new ContainerBuilder()
.setAccentColor(0x5865F2)
.addTextDisplayComponents(new TextDisplayBuilder().setContent('# Panel de Control'))
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**Estado**'),
new TextDisplayBuilder().setContent('🟢 Todos los sistemas operativos\n👥 1.284 miembros\n📈 42 uniones hoy'),
)
.setButtonAccessory(
new ButtonBuilder().setCustomId('estado:actualizar').setLabel('Actualizar').setStyle(ButtonStyle.Secondary),
),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(false).setSpacing(SeparatorSpacingSize.Large))
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**Acciones**'),
new TextDisplayBuilder().setContent('Modera, anuncia o configura el servidor.'),
)
.setButtonAccessory(
new ButtonBuilder().setCustomId('panel:configuracion').setLabel('Configuración').setStyle(ButtonStyle.Secondary),
),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('panel:anunciar').setLabel('Anunciar').setStyle(ButtonStyle.Primary),
new ButtonBuilder().setCustomId('panel:moderar').setLabel('Moderar').setStyle(ButtonStyle.Danger),
),
);
Anuncio liderado por imagen
Mantén el texto en 2–3 líneas cortas para que la imagen sea el foco. El banner es un elemento de MediaGallery — recuerda subirlo.
new ContainerBuilder()
.setAccentColor(0xFEE75C)
.addMediaGalleryComponents(
new MediaGalleryBuilder().addItems(
new MediaGalleryItemBuilder().setURL('attachment://banner-evento.png').setDescription('Banner del evento de verano'),
),
)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# Evento de Verano\nÚnete **viernes a las 20:00** para la transmisión de lanzamiento.'),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('-# La participación es opcional · Horarios mostrados en UTC'),
);
-# es subtexto — perfecto para letra pequeña sin competir con el título.
Confirmación/error efímero
Reutiliza un helper con un acento + título + mensaje en lugar de escribir dos diseños.
const estado = (tipo, texto) => new ContainerBuilder()
.setAccentColor(tipo === 'error' ? 0xED4245 : 0x57F287)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent(`### ${tipo === 'error' ? 'Algo salió mal' : 'Hecho'}\n${texto}`),
);
await interaccion.reply({
components: [estado('error', 'No tienes permiso para hacer eso.')],
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral,
});
Mantén las respuestas efímeras en un solo Container — sin separadores, sin filas de acción a menos que necesites un botón de seguimiento.
Solicitud de confirmación
Coloca la acción destructiva al final y estilízala como Danger.
new ContainerBuilder()
.setAccentColor(0xFEE75C)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('## ¿Eliminar 47 mensajes?'),
new TextDisplayBuilder().setContent('Esto no se puede deshacer.'),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('purga:cancelar').setLabel('Cancelar').setStyle(ButtonStyle.Secondary),
new ButtonBuilder().setCustomId('purga:confirmar').setLabel('Eliminar').setStyle(ButtonStyle.Danger),
),
);
Lista compacta
Para registros de cambios, tablas de clasificación y listas de estado: pon la etiqueta en negrita, mantén cada entrada en una línea, usa -# para metadatos.
new Te
…
[truncada para traducción]