Communitygithub.com

discord-components-v2

discord.js (v14.19以上) の Components V2 を使って美しい Discord Bot メッセージを作成します。モダンなレイアウト、コンテナ、セクション、テキスト表示、ボタン、セレクトメニュー、メディアギャラリーが必要な場合や、ユーザーが Components V2、表示コンポーネント、IS_COMPONENTS_V2 に言及した場合、またはクラシックな埋め込みを使わずに洗練されたインタラクティブメッセージを求めている場合に使用します。

discord-components-v2 とは?

このスキルは、discord.js ライブラリ (v14.19以上) で利用可能な Discord の Components V2 機能を完全に網羅し、開発者が従来の埋め込みやアクション行に依存せず、モダンで柔軟なレイアウトを構築できるようにします。Container、TextDisplay、Section、Separator、MediaGallery、File などの新しいビルダーを提供し、メッセージ構造を細かく制御できます。特に、すべての V2 メッセージに必須の `MessageFlags.IsComponentsV2` フラグの設定方法、各コンポーネントの制限(最大 40 コンポーネント、4000 文字制限など)、および `attachment://` 構文を使用した添付ファイルの参照方法について詳しく説明します。また、クリーンな情報カード、サムネイル付きの機能ハイライト、ダッシュボード風のマルチセクションレイアウト、画像中心の告知、エフェメラル確認メッセージなど、具体的で再利用可能な美しいレイアウトのレシピを提供し、ボタンやセレクトメニューを含むインタラクティブコンポーネントの実装パターンも示します。このスキルは、Claude Code、Cursor、Codex など、あらゆる AI エージェントで使用でき、開発者が Discord Bot のメッセージを最新の標準に沿って迅速に実装またはリファクタリングする際の強力なガイドとなります。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Discord Components V2 (discord.js)

新しいメッセージレイアウトにはすべて Components V2 を使用してください。従来の content + embeds + アクション行も引き続き動作しますが、V2 は完全なレイアウト制御を提供し、推奨されるモダンなアプローチです。

要件: discord.js ≥ 14.19 (現在の最新は 14.28.x)。常にフラグを設定してください。

重要なルール

  • すべての V2 メッセージには 必ず flags: MessageFlags.IsComponentsV2 (または MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral) を含める必要があります。
  • V2 フラグを付けてメッセージを送信した後、編集でフラグを 削除することはできません。
  • フラグを設定した場合、content、embeds、poll、stickers を 送信できません。表示されるテキストはすべて TextDisplayBuilder に配置します。
  • コンポーネントの最大数は 40 (ネストされたものを個別にカウント)。すべての TextDisplay の合計文字数は最大 4000 文字です。
  • 添付ファイルは、サムネイル、MediaGallery、または File コンポーネントで attachment://filename 経由で参照されない限り、非表示になります。
  • トップレベルのコンポーネントは次のとおりです: Container、TextDisplay、Section、Separator、MediaGallery、File、ActionRow。
  • Container は他の Container の中にネストできません。
  • すべての Section には、正確に 1 つのアクセサリー (サムネイルまたはボタン) が必要です。

制限

制約上限備考
メッセージあたりのコンポーネント数40ネストされたコンポーネントも個別にカウント
テキスト文字数4,000メッセージ内のすべての TextDisplay の合計
ActionRow あたりのボタン数5または 1 つのセレクトメニュー。同じ行に両方を配置不可
セレクトオプション数25セレクトメニューあたり
MediaGallery アイテム数10ギャラリーあたり
Containerネスト不可Container は別の Container を含めない
Section各 1 つのアクセサリーサムネイル または ボタン。両方もしくはなしは不可
添付ファイルメッセージあたり 10各添付ファイルは可視化のために参照される必要あり

V2 フラグが設定されている場合、従来の「メッセージあたり 5 つの ActionRow」の上限は 40 コンポーネント予算に置き換えられます。ActionRow は 40 コンポーネントのうちの 1 つです。

インポート (典型的な例)

const {
  ContainerBuilder,
  TextDisplayBuilder,
  SectionBuilder,
  SeparatorBuilder,
  SeparatorSpacingSize,
  MediaGalleryBuilder,
  MediaGalleryItemBuilder,
  FileBuilder,
  ThumbnailBuilder,
  ActionRowBuilder,
  ButtonBuilder,
  ButtonStyle,
  StringSelectMenuBuilder,
  UserSelectMenuBuilder,
  RoleSelectMenuBuilder,
  ChannelSelectMenuBuilder,
  MentionableSelectMenuBuilder,
  MessageFlags,
  AttachmentBuilder,
} = require('discord.js');

フラグ

MessageFlags.IsComponentsV2                          // V2 レンダリングに必須
MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral // エフェメラル返信
MessageFlags.IsComponentsV2 | MessageFlags.SuppressEmbeds

V2 コンポーネントをレンダリングするにはフラグが必須であり、これは 永続的 です。フラグを付けて送信したメッセージは、編集で削除できません。

コアビルダーとパターン

1. TextDisplay – すべてのテキストはここに配置

new TextDisplayBuilder().setContent('## 見出し\n**マークダウン**、*イタリック*、`コード`、リスト、メンション、絵文字をサポート。')

標準の Discord マークダウンのみ: 見出し (#–###)、太字、斜体、下線、取り消し線、インラインコード、コードブロック、スポイラー (||テキスト||)、リスト、引用ブロック、リンク、タイムスタンプ、メンション、絵文字。

V2 を使用する場合、メッセージには content フィールドはありません。このビルダーのみがテキストをレンダリングする場所です。視覚的なリズムを良くするために、1 つの巨大なブロックよりも、複数の小さな TextDisplay を使用することをお勧めします。

2. Container – モダンな「埋め込み」

const container = new ContainerBuilder()
  .setAccentColor(0x5865F2)          // オプションの左アクセント (16進数)
  // .setSpoiler(true)               // コンテナ全体をぼかす
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('# タイトル\nサブタイトルまたは説明。'),
  )
  .addSeparatorComponents(
    new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(/* ボタンまたは1つのセレクト */),
  );

完全なメソッドセット: addTextDisplayComponents、addSectionComponents、addSeparatorComponents、addActionRowComponents、addMediaGalleryComponents、addFileComponents、addComponents、およびすべての子要素を置き換える setComponents([...])。子要素の順序は保持されるため、読み取り順に上から下へ構築します。

見栄えの良いアクセントカラー: Discord ブループル 0x5865F2、成功 0x57F287、危険 0xED4245、ソフトグレー 0x99AAB5、またはブランドカラー。アクセントを省略するとクリーンなフラットな外観になります。色は数値である必要があります。'#5865F2' や 'blurple' はエラーになります。

3. Section – テキスト + アクセサリー (サムネイルまたはボタン)

new SectionBuilder()
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('**機能名**'),
    new TextDisplayBuilder().setContent('短い補足テキスト。1~3 個の TextDisplay に抑えます。'),
  )
  .setThumbnailAccessory(
    new ThumbnailBuilder()
      .setURL('https://example.com/icon.png')   // または attachment://file.png
      .setDescription('代替テキスト'),
  )
  // または
  .setButtonAccessory(
    new ButtonBuilder()
      .setCustomId('action')
      .setLabel('実行')
      .setStyle(ButtonStyle.Primary),
  );

サムネイルや単一の目立つボタンを関連テキストの横に配置したい場合に Section を使用します。Section にアクセサリーを付けないままにしたり、両方を設定したりしないでください。

4. Separator – 視覚的な余白

new SeparatorBuilder()
  .setDivider(true)                    // 細い線を表示
  .setSpacing(SeparatorSpacingSize.Small); // または Large

論理グループの間に配置します。ほとんどのカードでは Small + 区切り線を推奨します。より大きな視覚的区切りには Large を使用します。divider: false と Large のスペーシングにより、線のない空白の隙間ができます。

5. MediaGallery と File

new MediaGalleryBuilder().addItems(
  new MediaGalleryItemBuilder()
    .setURL('https://…')          // または attachment://image.png
    .setDescription('代替テキスト')
    .setSpoiler(false),
  // 最大 10 アイテム
);

new FileBuilder().setURL('attachment://report.pdf'); // `files` にもファイルを渡す必要あり

アップロードされたが File、Thumbnail、MediaGallery で参照されないファイルは非表示のままになります。

6. Thumbnail

new ThumbnailBuilder()
  .setURL('https://…/icon.png')   // または attachment://icon.png
  .setDescription('代替テキスト')
  .setSpoiler(false);

サムネイルは Section のアクセサリーとしてのみ存在します。トップレベルのコンポーネントではありません。

7. インタラクティブコンポーネント (ActionRow 内)

  • ActionRow あたり最大 5 ボタン または 1 セレクトメニュー。
  • ボタン: ButtonStyle.Primary | Secondary | Success | Danger | Link | Premium。
  • リンクボタンは .setURL() が必要で、customId は使用しません。プレミアムボタンは .setSKUId() が必要です。
  • インタラクティブコンポーネントには常に一意で名前空間化された customId を付けてください (例: ticket:close、poll:vote:yes)。カスタム ID は最大 100 文字です。
new ActionRowBuilder().addComponents(
  new ButtonBuilder().setCustomId('confirm').setLabel('確認').setStyle(ButtonStyle.Success),
  new ButtonBuilder().setCustomId('cancel').setLabel('キャンセル').setStyle(ButtonStyle.Secondary),
);

new ActionRowBuilder().addComponents(
  new StringSelectMenuBuilder()
    .setCustomId('choose-plan')
    .setPlaceholder('プランを選択…')
    .addOptions(
      { label: 'スターター', value: 'starter', description: '個人向け' },
      { label: 'プロ', value: 'pro', description: 'チーム向け', emoji: '⭐' },
    ),
);

エンティティセレクトは setCustomId、setPlaceholder、setMinValues、setMaxValues、setDisabled を共有します:

ビルダーデフォルト値のセッター
UserSelectMenuBuildersetDefaultUsers(...)
RoleSelectMenuBuildersetDefaultRoles(...)
ChannelSelectMenuBuildersetDefaultChannels(...)、setChannelTypes(...)
MentionableSelectMenuBuildersetDefaultValues(...)

セレクトは ActionRow 内に独自のラベルを持ちません。ユーザーが表示するのはプレースホルダーです。

8. 添付ファイル

const file = new AttachmentBuilder(buffer, { name: 'chart.png' });
// MediaGallery、Thumbnail、File 内で 'attachment://chart.png' として参照

添付ファイルの name は attachment:// が一致する必要があるものです。大文字小文字と拡張子も含みます。

送信と編集

// チャンネルまたはインタラクション
await channel.send({
  components: [container],          // または [text, separator, container, …]
  flags: MessageFlags.IsComponentsV2,
  files: [attachment],              // 参照される場合のみ
  allowedMentions: { parse: [] },   // TextDisplay からの ping を制御
});

// エフェメラル
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral

// 編集 (フラグは永続的)
await message.edit({
  components: [newLayout],
  // V2 フラグをクリアしようとしないでください
});

すべてのビルダーは .toJSON() を実装しています。レイアウトを永続化する場合、container.toJSON() を保存し、JSON を components に戻して再構築します。

美しいレイアウトレシピ

クリーンな情報カード

new ContainerBuilder()
  .setAccentColor(0x5865F2)
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('# サーバールール\n注意深くお読みください。'),
  )
  .addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('1. 敬意を持って接しましょう\n2. スパムは禁止です\n3. Discord 利用規約に従ってください'),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setCustomId('rules:accept').setLabel('同意する').setStyle(ButtonStyle.Success),
    ),
  );

サムネイル付き機能ハイライト

new ContainerBuilder()
  .setAccentColor(0x57F287)
  .addSectionComponents(
    new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('## 新しいダッシュボード'),
        new TextDisplayBuilder().setContent('リアルタイム統計、ロール管理、分析が1か所で。'),
      )
      .setThumbnailAccessory(new ThumbnailBuilder().setURL('attachment://dashboard.png').setDescription('ダッシュボードプレビュー')),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setCustomId('dashboard:open').setLabel('ダッシュボードを開く').setStyle(ButtonStyle.Primary),
      new ButtonBuilder().setLabel('変更ログ').setURL('https://example.com/changelog').setStyle(ButtonStyle.Link),
    ),
  );

コンポーネントと一緒に files: [new AttachmentBuilder(buffer, { name: 'dashboard.png' })] を渡します。

マルチセクションダッシュボード風メッセージ

new ContainerBuilder()
  .setAccentColor(0x5865F2)
  .addTextDisplayComponents(new TextDisplayBuilder().setContent('# コントロールパネル'))
  .addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
  .addSectionComponents(
    new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('**ステータス**'),
        new TextDisplayBuilder().setContent('🟢 全システム稼働中\n👥 1,284 メンバー\n📈 今日の参加者 42 人'),
      )
      .setButtonAccessory(
        new ButtonBuilder().setCustomId('status:refresh').setLabel('更新').setStyle(ButtonStyle.Secondary),
      ),
  )
  .addSeparatorComponents(new SeparatorBuilder().setDivider(false).setSpacing(SeparatorSpacingSize.Large))
  .addSectionComponents(
    new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('**アクション**'),
        new TextDisplayBuilder().setContent('サーバーのモデレート、アナウンス、設定を行います。'),
      )
      .setButtonAccessory(
        new ButtonBuilder().setCustomId('panel:settings').setLabel('設定').setStyle(ButtonStyle.Secondary),
      ),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setCustomId('panel:announce').setLabel('アナウンス').setStyle(ButtonStyle.Primary),
      new ButtonBuilder().setCustomId('panel:moderate').setLabel('モデレート').setStyle(ButtonStyle.Danger),
    ),
  );

画像主体の告知

テキストは 2~3 行の短い行に抑え、画像に焦点が当たるようにします。バナーは MediaGallery アイテムです。忘れずにアップロードしてください。

new ContainerBuilder()
  .setAccentColor(0xFEE75C)
  .addMediaGalleryComponents(
    new MediaGalleryBuilder().addItems(
      new MediaGalleryItemBuilder().setURL('attachment://event-banner.png').setDescription('サマーイベントバナー'),
    ),
  )
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('# サマーイベント\n**金曜日午後8時**からの配信開始にご参加ください。'),
  )
  .addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('-# 参加は任意です · 時刻はUTCで表示'),
  );

-# はサブテキストです。見出しと競合せずに細かい表示に最適です。

エフェメラル確認 / エラー

2 つのレイアウトを記述する代わりに、アクセント + タイトル + メッセージを持つ 1 つのヘルパーを再利用します。

const status = (type, text) => new ContainerBuilder()
  .setAccentColor(type === 'error' ? 0xED4245 : 0x57F287)
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent(`### ${type === 'error' ? '問題が発生しました' : '完了しました'}\n${text}`),
  );

await interaction.reply({
  components: [status('error', 'これを実行する権限がありません。')],
  flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral,
});

エフェメラル返信は 1 つの Container に抑えます。フォローアップボタンが必要な場合を除き、区切り線やアクション行は使用しません。

確認プロンプト

破壊的なアクションは最後に配置し、スタイルは Danger にします。

new ContainerBuilder()
  .setAccentColor(0xFEE75C)
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('## 47 件のメッセージを削除しますか?'),
    new TextDisplayBuilder().setContent('この操作は元に戻せません。'),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setCustomId('purge:cancel').setLabel('キャンセル').setStyle(ButtonStyle.Secondary),
      new ButtonBuilder().setCustomId('purge:confirm').setLabel('削除').setStyle(ButtonStyle.Danger),
    ),
  );

コンパクトリスト

変更ログ、リーダーボード、ステータスリストに: ラベルを太字にし、各エントリを 1 行に収め、メタデータには -# を使用します。

new ContainerBuilder()
  .setAccentColor(0x99AAB5)
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('## 変更ログ'),
  )
  .addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('**v2.1.0** — ダッシュボードの改善'),
    new TextDisplayBuilder().setContent('**v2.0.5** — バグ修正'),
    new TextDisplayBuilder().setContent('**v2.0.0** — メジャーリリース'),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setLabel('詳細を見る').setURL('https://example.com/changelog').setStyle(ButtonStyle.Link),
    ),
  );

ファイル添付

new ContainerBuilder()
  .addFileComponents(
    new FileBuilder().setURL('attachment://report.pdf'),
  )
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('**添付ファイル: レポート**'),
  );
// files: [new AttachmentBuilder(buffer, { name: 'report.pdf' })] を一緒に渡します

ベストプラクティスのまとめ

  • 埋め込みではなく 常に V2 を優先します。特にインタラクティブなペイロードや情報量の多いペイロードの場合。
  • メッセージ構造に応じて Container、Section、TextDisplay を使用します。すべてを 1 つの TextDisplay に詰め込まないでください。
  • レイアウトを構築するときは、setComponents() よりも add*Components メソッドを使用して、可読性を高め、順序のバグを防ぎます。
  • インタラクティブコンポーネントには名前空間化された customId を使用して、競合を防ぎます。
  • V2 メッセージでは ActionRowBuilder を他のすべての V2 ビルダーと自由に混在させますが、V2 フラグが設定されている場合は、components 配列のトップレベル要素として ActionRow のみを含めることはできません。V2 フラグがある場合、トップレベル要素は Container、TextDisplay、Section、Separator、MediaGallery、File、または ActionRow です。
  • discord.js v14.19 は最小バージョンです。古いバージョンで V2 をインポートしようとするとエラーが発生します。

関連スキル