Bir Discord embed, düz metin mesajının yapamadığını yapar: bilgiyi renkli bir kenar çizgisi, başlık, alanlar, küçük resim ve altbilgiyle düzenli bir kart hâline getirir. Botunuz bir komuta cevap verdiğinde "ham metin" yerine bu şık kartı gönderdiğinde, sunucudaki herkes mesajı bir anda daha okunabilir ve profesyonel bulur. Bu rehberde discord.js v14'ün EmbedBuilder sınıfıyla renk, alan ve thumbnail kullanımını adım adım kuruyoruz.
Embed nedir, ne zaman kullanılır?
Embed, Discord'un mesajların içine gömdüğü yapılandırılmış bir bloktur. Bir bağlantı paylaştığınızda otomatik beliren önizleme kartı da bir embed'dir; botlar ise bu kartı elle oluşturur. Embed kullanmanın iyi olduğu yerler:
- Komut çıktıları: kullanıcı profili, sunucu istatistikleri, hava durumu gibi alanlara bölünen veriler.
- Loglar ve bildirimler: renk koduyla "başarılı / uyarı / hata" ayrımı yapmak.
- Duyurular: başlık, açıklama ve görselle dikkat çeken mesajlar.
Tek satırlık basit cevaplar için embed gereksizdir; sade metin daha hızlı okunur. Embed'i, bilgi gerçekten yapı kazandığında tercih edin.
EmbedBuilder ile ilk embed
discord.js v14 ile embed'ler artık EmbedBuilder üzerinden zincirleme metotlarla kurulur. Temel bir örnek:
const { EmbedBuilder } = require('discord.js');
const embed = new EmbedBuilder()
.setColor(0x5865F2)
.setTitle('Sunucu Bilgisi')
.setDescription('Aşağıda sunucunun özet bilgileri yer alıyor.')
.setTimestamp();
await interaction.reply({ embeds: [embed] });
Dikkat: embed, mesajın embeds dizisi içinde gönderilir; doğrudan string olarak değil. Bir mesajda en fazla 10 embed bulunabilir, ancak çoğu durumda bir tane yeterlidir.
Renk: markanızı bir tonla anlatın
Renk, embed'in sol kenarındaki dikey çizgidir ve mesajın "tonunu" anında belli eder. setColor birkaç biçim kabul eder:
const { Colors } = require('discord.js');
embed.setColor(0x57F287); // hex sayı (yeşil)
embed.setColor('#ED4245'); // hex string (kırmızı)
embed.setColor([88, 101, 242]); // RGB dizisi (Discord moru)
embed.setColor(Colors.Gold); // hazır renk sabiti
embed.setColor('Random'); // her seferinde rastgele
Pratik bir konvansiyon: yeşil = başarı, sarı = uyarı, kırmızı = hata, marka moru = nötr bilgi. Renkleri kod içinde tek bir nesnede toplarsanız tutarlılık sağlar:
const COLORS = { success: 0x57F287, warn: 0xFEE75C, error: 0xED4245 };
embed.setColor(COLORS.success);
Alanlar (fields): veriyi düzenli sütunlara bölün
Alanlar, embed'in en güçlü yanıdır: her biri bir name (başlık) ve value (değer) taşır. inline: true verirseniz alanlar yan yana dizilir; Discord satır başına en fazla üç inline alan gösterir.
embed.addFields(
{ name: 'Üye sayısı', value: '1.248', inline: true },
{ name: 'Kanal sayısı', value: '37', inline: true },
{ name: 'Oluşturulma', value: '12 Mart 2021', inline: true },
{ name: 'Açıklama', value: 'Topluluğun ana sunucusu.', inline: false },
);
Boş bir hücreyle hizalama yapmak isterseniz, görünmez bir başlık kullanılır:
embed.addFields({ name: '', value: '', inline: true });
Buradaki sıfır genişlikli boşluktur; Discord boş name veya value kabul etmediği için bu hile kullanılır.
Thumbnail, görsel, yazar ve altbilgi
Geriye kalan parçalar embed'i tamamlar. Thumbnail sağ üstteki küçük kare görseldir; image ise alttaki büyük görsel. Author en üstte küçük bir başlık + ikon, footer ise en altta küçük bir not sunar.
embed
.setAuthor({
name: 'Aslain Bot',
iconURL: 'https://example.com/bot.png',
url: 'https://aslain.dev',
})
.setThumbnail('https://example.com/avatar.png')
.setImage('https://example.com/banner.png')
.setFooter({ text: 'aslain.dev', iconURL: 'https://example.com/icon.png' });
Görseller için harici URL kullanabilir ya da bota yüklediğiniz bir dosyayı attachment:// şemasıyla gösterebilirsiniz:
const { AttachmentBuilder } = require('discord.js');
const file = new AttachmentBuilder('./avatar.png', { name: 'avatar.png' });
embed.setThumbnail('attachment://avatar.png');
await interaction.reply({ embeds: [embed], files: [file] });
Sınırlara dikkat edin
Discord embed'lere katı karakter sınırları koyar. Aşarsanız API mesajı reddeder ve bot sessizce hata verir. En önemlileri:
- title: 256 karakter
- description: 4096 karakter
- field sayısı: en fazla 25 (name 256, value 1024 karakter)
- footer.text: 2048, author.name: 256 karakter
- Tek embed'deki tüm metinlerin toplamı: 6000 karakter
Kullanıcı girdisini embed'e koyuyorsanız, değerleri slice(0, 1024) gibi kısaltarak güvene alın; aksi hâlde uzun bir mesaj tüm cevabı bozabilir.
Sık Sorulan Sorular
MessageEmbed yerine neden EmbedBuilder?
discord.js v13'te sınıfın adı MessageEmbed idi. v14 ile bu EmbedBuilder olarak değişti ve addField (tekil) kaldırılıp yerine addFields (çoğul) geldi. Yeni projelerde mutlaka v14 adlarını kullanın; eski örnekleri olduğu gibi kopyalarsanız hata alırsınız.
Embed renklerini kullanıcıya seçtirebilir miyim?
Evet. Slash komutuna bir seçenek ekleyip gelen hex değerini setColor'a verebilirsiniz. Yalnızca girdiyi doğrulayın: geçersiz bir değer hata fırlatır, bu yüzden /^#?[0-9a-f]{6}$/i gibi bir kontrol ekleyin.
Embed'ler herkeste aynı mı görünür?
Yapı aynıdır, fakat açık/koyu tema ve mobil/masaüstü arasında küçük görsel farklar olur. Thumbnail ve image boyutlarının taşmadığını mobilde de test etmek iyi olur.
Botunuzun mesajlarını markanıza yakışır hâle getirmek mi istiyorsunuz? Embed tasarımından komut mimarisine kadar Discord botunuzu birlikte kurabiliriz. Projenizi konuşmak için benimle iletişime geçin.