Communitygithub.com

discord-components-v2

Crea mensajes de bot de Discord atractivos usando Components V2 con discord.js (v14.19+). Ideal al construir o refactorizar bots de Discord que necesiten diseños modernos, contenedores, secciones, textos, botones, menús de selección, galerías multimedia, o cuando el usuario mencione Components V2, componentes de visualización, IS_COMPONENTS_V2, o desee mensajes interactivos pulidos sin embeds clásicos.

¿Qué es discord-components-v2?

Esta habilidad proporciona una guía completa para utilizar el sistema Components V2 de Discord con la librería discord.js (v14.19+). Permite a los desarrolladores crear mensajes de bot con diseños modernos y flexibles, reemplazando el enfoque clásico de `content` + `embeds`. Incluye builders como Container (el 'embed' moderno), TextDisplay para todo el texto visible, Section para texto con miniatura o botón, Separator para espacio visual, y MediaGallery para imágenes. Se destacan reglas críticas: es obligatorio usar la bandera `MessageFlags.IsComponentsV2`, no se puede usar `content`, `embeds`, `poll` o `stickers` con ella activa, y hay límites claros (40 componentes por mensaje, 4000 caracteres de texto, etc.). También se cubren patrones comunes de diseño: tarjetas de información, paneles de control, anuncios con imágenes, confirmaciones efímeras y listas compactas, todo con ejemplos de código listos para usar. Esta habilidad es ideal para desarrolladores que trabajan con discord.js y quieren aprovechar al máximo las capacidades modernas de mensajería de Discord.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Dqrshan/discord-components-v2-skill/tree/HEAD

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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 (o MessageFlags.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, poll o stickers. Todo el texto visible reside en TextDisplayBuilder.
  • 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ónLímiteNotas
Componentes por mensaje40Los componentes anidados cuentan individualmente.
Caracteres de texto4.000Suma de todos los TextDisplay en el mensaje.
Botones por ActionRow5O un menú de selección, nunca ambos en la misma fila.
Opciones de selección25Por menú de selección.
Elementos de MediaGallery10Por galería.
ContainersSin anidamientoUn Container no puede contener otro Container.
Sections1 accesorio cada unaMiniatura o botón, no ambos, no ninguno.
Archivos adjuntos10 por mensajeCada 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:

BuilderEstablecedor de valor predeterminado
UserSelectMenuBuildersetDefaultUsers(...)
RoleSelectMenuBuildersetDefaultRoles(...)
ChannelSelectMenuBuildersetDefaultChannels(...), setChannelTypes(...)
MentionableSelectMenuBuildersetDefaultValues(...)

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]

Skills relacionados