Discord Components V2 Nedir? Container, Section ve Media Gallery Rehberi

IS_COMPONENTS_V2 bayrağı

Components V2 mesaj başına açılan bir moddur. Mesajın flags alanına IS_COMPONENTS_V2 bayrağını, yani 1 << 15 (32768) değerini eklersiniz. discord.js'te karşılığı MessageFlags.IsComponentsV2'dir. Bayrak; mesaj oluşturma, webhook çalıştırma ve interaction yanıtlarında kullanılabilir.

{
  "flags": 32768,
  "components": [
    { "type": 10, "content": "Bu mesaj bir Text Display bileşeniyle yazıldı" }
  ]
}

Bu modda neler değişir, neleri yapamazsınız?

• content ve embeds çalışmaz. Belgeye göre bayrak açıkken mesaj yalnızca components içerebilir; content, embeds, sticker_ids, poll veya shared_client_theme göndermek 400 BAD REQUEST ile sonuçlanır.
• Ekler kendiliğinden görünmez. Yüklediğiniz dosyaları Thumbnail, Media Gallery ya da File bileşeninde attachment://dosya-adi ile açıkça göstermeniz gerekir.
• Anket ve çıkartma yok. poll ve stickers alanları devre dışıdır.
• Toplam 40 bileşen. discord.js rehberine göre iç içe bileşenler de bu sayıya dahildir.
• Toplam metin 4000 karakter. discord.js rehberi, tüm Text Display bileşenlerindeki metnin toplamının 4000 karakteri geçemeyeceğini belirtiyor.
• Sonradan geçiş mümkün, geri dönüş değil. Klasik bir mesajı düzenlerken bayrağı ekleyebilirsiniz; ancak content ve poll değerlerini null, embeds ve sticker_ids değerlerini boş dizi yapmanız gerekir. Aksi hâlde 400 hatası döner.

Components V2 bileşenleri

Aşağıdaki tablo, mesajlarda Components V2 ile gelen yeni yerleşim (layout) ve içerik (content) bileşenlerini özetliyor. Buton ve select menu gibi etkileşimli bileşenler de bu mesajlarda kullanılabilir.

Görsel ve dosya kaynakları

Thumbnail, Media Gallery ve File bileşenleri medyayı "unfurled media item" yapısıyla alır. Geliştirici olarak yalnızca url alanını ayarlayabilirsiniz; yükseklik, genişlik, içerik türü gibi diğer alanları Discord doldurur. url doğrudan bir bağlantı ya da attachment://dosya-adi referansı olabilir; File bileşeni ise yalnızca attachment:// kabul eder. Dosya yüklemek için istek multipart/form-data olarak gönderilir. 28 Ekim 2026 değişiklik kaydıyla bu öğelere Discord'un içerik taramasının sonucunu taşıyan content_scan_metadata alanı da eklendi; kullanıcı görsellerini yeniden yayımlayan botlar bu bayrakları kontrol etmeli.

discord.js ile Components V2 mesajı

discord.js rehberi her bileşen için bir builder sunuyor: TextDisplayBuilder, SectionBuilder, ThumbnailBuilder, MediaGalleryBuilder ve MediaGalleryItemBuilder, FileBuilder, SeparatorBuilder ve ContainerBuilder. Aşağıdaki örnek bir sunucu durum kartı oluşturuyor:

const {
  ContainerBuilder, ButtonStyle, SeparatorSpacingSize, AttachmentBuilder, MessageFlags,
} = require('discord.js');

const logo = new AttachmentBuilder('./logo.png');

const kart = new ContainerBuilder()
  .setAccentColor(0x2ecc71)
  .addTextDisplayComponents((t) => t.setContent('## Sunucu Durumu\nTüm sistemler çalışıyor.'))
  .addSeparatorComponents((s) => s.setDivider(true).setSpacing(SeparatorSpacingSize.Small))
  .addSectionComponents((sec) =>
    sec
      .addTextDisplayComponents(
        (t) => t.setContent('**Çevrimiçi oyuncu:** 42'),
        (t) => t.setContent('**Gecikme:** 35 ms'),
      )
      .setThumbnailAccessory((th) => th.setURL('attachment://logo.png').setDescription('Sunucu logosu')))
  .addSectionComponents((sec) =>
    sec
      .addTextDisplayComponents((t) => t.setContent('Ayrıntılı rapor almak için butona basın.'))
      .setButtonAccessory((b) => b.setCustomId('durum-detay').setLabel('Detay').setStyle(ButtonStyle.Primary)));

await channel.send({
  components: [kart],
  files: [logo],
  flags: MessageFlags.IsComponentsV2,
  allowedMentions: { parse: [] },
});

• files ile yüklediğiniz her dosyayı bir bileşende attachment:// ile referans etmeyi unutmayın; yoksa görünmez.
• Text Display içindeki @kullanıcı ve @rol bahsetmeleri bildirim gönderir. Kullanıcı girdisi basıyorsanız allowedMentions ile kısıtlayın.
• Accent rengi vermezseniz Container'ın sol kenarı arka planla aynı renkte görünür.
• Yalnızca Separator içeren bir mesaj görünür bir içerik taşımaz.

Interaction yanıtlarında Components V2

Slash komut yanıtı olarak da Components V2 kullanabilirsiniz. Tek dikkat edilecek nokta defer: resmî belgeye göre DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE yanıtında geçerli tek bayrak EPHEMERAL'dır; bileşen tabanlı mesajı orijinal yanıtı düzenlerken oluşturmanız gerekir. discord.js rehberi de bayrağın defer sırasında değil, mesaj gönderilirken verileceğini söylüyor.

const { TextDisplayBuilder, MessageFlags } = require('discord.js');

// Hızlı yanıt: doğrudan reply
await interaction.reply({
  components: [new TextDisplayBuilder().setContent('Pong! **Components V2** ile yanıt.')],
  flags: MessageFlags.IsComponentsV2,
});

// Uzun iş: önce defer (yalnızca Ephemeral bayrağı geçerli), sonra editReply ile V2
await interaction.deferReply({ flags: MessageFlags.Ephemeral });
const sonuc = await uzunIs();
await interaction.editReply({
  components: [new TextDisplayBuilder().setContent(`Sonuç: ${sonuc}`)],
  flags: MessageFlags.IsComponentsV2,
});

3 saniye kuralı ve defer mantığının tamamı için etkileşim başarısız oldu hatası yazısına bakabilirsiniz.

Embed mi, Components V2 mi?

Belge yeni uygulamalar ve yeni özellikler için IS_COMPONENTS_V2 bayrağını öneriyor. Embed tarafının sınırları ve kullanımı için Discord embed mesaj oluşturma rehberine bakın.

Webhook ile Components V2

Webhook üzerinden bileşen gönderiyorsanız resmî belge, Execute Webhook isteğinde ?with_components=true sorgu parametresini kullanmanızı istiyor; aksi hâlde bileşenler yok sayılır. Webhook temelleri için Discord webhook ve bot entegrasyonu yazımıza bakabilirsiniz.

Sık Sorulan Sorular

Components V2 mesajına content ekleyince neden 400 hatası alıyorum?

Bayrak açıkken content, embeds, sticker_ids ve poll gönderilemez. Metni bir Text Display bileşenine taşıyın.

Gönderdiğim görsel mesajda görünmüyor, neden?

Components V2'de ekler varsayılan olarak gösterilmez. Dosyayı files ile yüklemenin yanında Thumbnail, Media Gallery veya File bileşeninde attachment://dosya-adi ile referans etmelisiniz.

Eski bir mesajı Components V2'ye çevirebilir miyim?

Evet, mesajı düzenlerken bayrağı ekleyebilirsiniz; ama content ve poll değerlerini null, embeds ve sticker_ids değerlerini boş dizi olarak göndermelisiniz. Tersine, V2 mesajını klasik moda döndüremezsiniz.

Components V2 modallarda da kullanılıyor mu?

Text Display bileşeni modallarda da kullanılabilir. Container, Section, Media Gallery, Thumbnail, File ve Separator ise belgeye göre şu an yalnızca mesajlarda kullanılabiliyor. Modal yapısı için modal rehberine bakın.

discord.py'de Components V2 var mı?

Bu yazı discord.js builder'larına dayanıyor. Diğer kütüphanelerde aynı API alanları farklı sınıf adlarıyla sunulur; kütüphane seçimi için Discord bot kütüphaneleri karşılaştırması yazısına bakabilirsiniz.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Buton, select menu ve modal · Embed mesaj oluşturma · Etkileşim başarısız oldu hatası · Slash komut oluşturma · Bot kütüphaneleri karşılaştırma · JavaScript nedir