Avatar

Bir kişinin ya da bir şeyin resmi: bir fotoğraf, bir adın baş harfleri ya da ikisinin yerini tutan bir ikon.

import com.pantrixui.components.elements.avatar.PantrixAvatar

Baş harfler, ikon ya da hiçbiri. initials verilirse onlar çizilir; verilmezse icon; ikisi de yoksa avatar tonunun rengiyle dolu, düz bir şekildir.
Fotoğraf. Pantrix resim yüklemez. image bir yuvadır: uygulama resmi kendi yükleyicisiyle, bir kaynaktan ya da kendi çizimiyle oraya koyar. Resim baş harflerin üstüne çizilir: yüklenirken ve yüklenemediğinde harfler görünür.
Altı ton. tone avatarı temanın bir rolünün rengiyle doldurur; colors rol dışı bir renk verir. Ton tek başına bir şey söylemez: ekran okuyucu rengi değil açıklamayı okur.
Boyut. size ya da modifier avatarın boyutunu verir. Baş harfler ve ikon avatarın bir payıdır: her boyutta oranını korur. Stildeki boyut Android'de ve iOS'ta 40dp, masaüstünde ve web'de 32dp'dir.
Şekil. Avatar her platformda bir dairedir; AvatarStyle(shape = ...) köşelerini değiştirir.
Yazıldığı gibi. Baş harfler büyük harfe çevrilmez. İlk iki harf tutulur, aralarındaki boşluklar atılır.
Yazı ölçeği. Baş harfler sistemin yazı boyutu büyütülünce de payını korur: avatar çevresindeki yazıyla birlikte büyümez.

Örnekler

En yalın hâli

En az yazılan hâli: bir açıklama ve baş harfler. Tonu Neutral'dır, boyutu stilin boyutu.

Tek başına duran avatar adını açıklamasından alır: ekran okuyucu onu "Ayşe Yılmaz" adında bir görsel olarak okur. "AY" harfleri okunmaz; onlar açıklamanın kısaltmasıdır.

PantrixAvatar(contentDescription = "Ayşe Yılmaz", initials = "AY", tagKey = "ayse")

Bir adın yanında

Adının yanında duran avatarın açıklaması yoktur: contentDescription = null. Ad yanında yazar; ekran okuyucu aynı adı iki kez okumaz ve avatar ondan gizlenir.

Baş harfler yazıldığı gibi çizilir, büyük harfe çevrilmez: son satırdaki "ik" küçük kalır.

CONTACTS.forEachIndexed { index, contact -> ContactRow(contact = contact, key = "contact_$index") }

@Composable
private fun ContactRow(
    contact: AvatarContact,
    key: String
) {
    Row(
        horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.md),
        verticalAlignment = Alignment.CenterVertically
    ) {
        PantrixAvatar(contentDescription = null, initials = contact.initials, tone = contact.tone, tagKey = key)
        Column {
            PantrixText(text = contact.name, style = PantrixTheme.typography.label)
            PantrixText(
                text = contact.lastTransfer,
                style = PantrixTheme.typography.footnote,
                color = PantrixTheme.colors.textSecondary
            )
        }
    }
}

private class AvatarContact(
    val name: String,
    val initials: String,
    val lastTransfer: String,
    val tone: AvatarTone = AvatarTone.Neutral
)

private val CONTACTS = listOf(
    AvatarContact(name = "Ayşe Yılmaz", initials = "AY", lastTransfer = "Dün 250,00 TL gönderildi"),
    AvatarContact(
        name = "İbrahim Öztürk",
        initials = "İÖ",
        lastTransfer = "3 Eylül'de 1.200,00 TL alındı",
        tone = AvatarTone.Info
    ),
    // Baş harfler yazıldığı gibi çizilir: küçük yazılan küçük kalır.
    AvatarContact(name = "ilker kaya", initials = "ik", lastTransfer = "Henüz işlem yok", tone = AvatarTone.Success)
)

Tonlar

tone avatarı temanın bir rolünün rengiyle doldurur ve harfleri o rengin üstünde okunan renkle yazar. Varsayılan Neutral'dır: hiçbir anlamı olmayan bir gri.

Avatar her tonda rolün dolu rengiyle çizilir, soluk container rengiyle değil: o renkte küçük bir daire açık bir sayfada kaybolur. Ton tek başına bir şey söylemez; bir rengin ne anlama geldiği yanındaki sözlerde yazmalıdır.

FlowRow(
    horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm),
    verticalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm)
) {
    AvatarTone.entries.forEachIndexed { index, tone ->
        PantrixAvatar(
            contentDescription = "${tone.name} tonunda avatar",
            initials = TONE_INITIALS[index],
            tone = tone,
            tagKey = "tone_${tone.name}"
        )
    }
}

private val TONE_INITIALS = listOf("AL", "GH", "KJ", "MR", "ŞÖ", "WY")

Boyutlar

size avatarın genişliği ve yüksekliğidir: bir yorumda 24dp, sık bir satırda 32dp, bir satırda 40dp, bir kartta 56dp, bir profilde 72dp. Boyut modifier ile de verilebilir; o zaman size'ın yerine geçer.

Baş harfler avatarın onda dördü, ikon onda altısı kadardır: boyut ne olursa olsun oran aynı kalır, ayrı bir stil gerekmez.

Row(
    horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm),
    verticalAlignment = Alignment.CenterVertically
) {
    listOf(24, 32, 40, 56, 72).forEach { size ->
        PantrixAvatar(
            contentDescription = null,
            initials = "DK",
            tone = AvatarTone.Primary,
            size = size.dp,
            tagKey = "size_$size"
        )
    }
}

Baş harfler

Baş harfler yazıldığı gibi çizilir. Büyük harfe çevrilmez: i Türkçede İ, başka dillerde I olur ve avatar bir adı yanlış yazacak yer değildir. İlk avatara "ik" verildi, öyle kaldı.

Verilenin ilk iki harfi tutulur, aralarındaki boşluklar atılır: "Ayşe Yılmaz" verilen avatar "Ay", "D K" verilen "DK" yazar. Bir adın nasıl kısaltılacağını avatar değil, uygulama söyler: çizilecek harfleri o verir.

Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm)) {
    PantrixAvatar(contentDescription = "ilker kaya", initials = "ik", tagKey = "as_written")
    PantrixAvatar(contentDescription = "Ayşe Yılmaz", initials = "Ayşe Yılmaz", tagKey = "first_two")
    PantrixAvatar(contentDescription = "Deniz Kara", initials = "D K", tagKey = "without_spaces")
    PantrixAvatar(contentDescription = "Zeynep", initials = "Z", tagKey = "one_letter")
}

Sonradan gelen fotoğraf

Fotoğrafı sonradan gelen bir profil. image yuvası avatara baştan verilir, ama "Fotoğrafı yükle"ye basılana kadar hiçbir şey çizmez: o sırada baş harfler görünür. Fotoğraf gelince harflerin üstünü örter. Bir görsel yükleyicinin yüklerken ya da hata verdiğinde yaptığı da budur.

Yuva avatarın boyutundadır ve onun şekline kesilir. Buradaki "fotoğraf" kendi boyutu olmayan bir renk geçişidir; kare olmayan bir resim için ContentScale.Crop istenir. Resmin kendi açıklaması okunmaz: avatarınki ikisinin yerine geçer.

var loaded by rememberSaveable { mutableStateOf(false) }
Row(
    horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.md),
    verticalAlignment = Alignment.CenterVertically
) {
    PantrixAvatar(
        contentDescription = "Deniz Kara'nın profil fotoğrafı",
        initials = "DK",
        tone = AvatarTone.Primary,
        size = 72.dp,
        tagKey = "profile"
    ) {
        if (loaded) Photo()
    }
    Column(verticalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.xs)) {
        PantrixText(text = "Deniz Kara", style = PantrixTheme.typography.callout)
        PantrixButton(
            text = if (loaded) "Fotoğrafı kaldır" else "Fotoğrafı yükle",
            onClick = { loaded = !loaded },
            variant = ButtonVariant.Outline,
            tagKey = "load_photo"
        )
    }
}

@Composable
private fun Photo() {
    val colors = PantrixTheme.colors
    val gradient = remember(colors) {
        BrushPainter(Brush.linearGradient(listOf(colors.warning.color, colors.danger.color, colors.primary.color)))
    }
    PantrixImage(painter = gradient, contentScale = ContentScale.Crop, contentDescription = null)
}

İkonlu ve boş avatar

Baş harfi olmayan avatar icon'unu çizer: bir kişi, bir grup, bir şirket. İkon, harfler gibi, tonun üstünde okunan renkle çizilir.

İkincisine ne harf ne ikon verildi: tonunun rengiyle dolu, düz bir dairedir. Adını yine açıklaması söyler.

Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm)) {
    PantrixAvatar(contentDescription = "Ortak hesap", icon = PantrixIcons.Person, tagKey = "shared")
    PantrixAvatar(contentDescription = "Adı bilinmeyen kişi", tagKey = "unknown")
}

Köşeli avatar

Avatar her platformda bir dairedir. style yalnızca bu avatarın stilini değiştirir: AvatarStyle(shape = ...) köşeleri temanın şekil ölçeğinin bir basamağına çeker. Burada bir klasörün ve bir şirketin avatarı ShapeRole.Medium ile köşeli çizildi.

Yalnızca verilen alan değişir: boyut ve harflerin payı temanın stilinden gelir.

val rounded = AvatarStyle(shape = ShapeRole.Medium)
Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm)) {
    PantrixAvatar(
        contentDescription = "Belgeler",
        icon = PantrixIcons.Folder,
        tone = AvatarTone.Info,
        style = rounded
    )
    PantrixAvatar(
        contentDescription = "Pantrix A.Ş.",
        initials = "PX",
        tone = AvatarTone.Primary,
        style = rounded,
        tagKey = "company"
    )
}

Saydam bir logo

Bir yanı saydam olan resim altındakini gösterir. Böyle bir resim tek başına, baş harfsiz ve ikonsuz verilir: bu logonun arkasında yalnızca tonun rengi durur.

PantrixAvatar(contentDescription = "Compose Multiplatform", tone = AvatarTone.Primary, tagKey = "logo") {
    PantrixImage(painter = painterResource(Res.drawable.compose_multiplatform), contentDescription = null)
}

Kendi rengi

colors avatara bir tonun değil, verilen rengin dolgusunu verir: bir ekibin ya da bir etiketin kendi rengi gibi. İlk avatarın rengi temanın hiçbir rolünde yok; dolgusu da harflerinin rengi de verildi, çünkü temanın tanımadığı bir dolgunun üstünde neyin okunduğunu ancak veren bilir.

İkincisine yalnızca dolgu verildi ve o temanın kendi renklerinden biri, success.container. Harflerin rengi kendiliğinden temanın o dolguyla eşlediği renk olur.

val own = ownColors()
Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm)) {
    PantrixAvatar(
        contentDescription = "Tasarım ekibi",
        initials = "TE",
        colors = AvatarColors(container = own.color, content = own.onColor),
        tagKey = "team"
    )
    PantrixAvatar(
        contentDescription = "Destek ekibi",
        initials = "DE",
        colors = AvatarColors(container = PantrixTheme.colors.success.container),
        tagKey = "support_team"
    )
}

API

contentDescription

Bir kişinin ya da bir şeyin resmi: bir fotoğraf, bir adın baş harfleri ya da ikisinin yerini tutan bir ikon.

Parametre	Tür	Varsayılan	Ne olduğu
`contentDescription`	`String?`		Ekran okuyucunun avatar için söylediği: çoğunlukla avatarın yerini tuttuğu ad. Avatarı okuyucudan gizlemek için null.
`modifier`	`Modifier`	`Modifier`	Avatarın modifier'ı. Burada verilen boyut `size`'ın yerine geçer.
`initials`	`String?`	`null`	Çizilecek harfler, çoğunlukla bir ya da iki tane. İkiden fazlası kesilir, hiç harf yoksa `icon` kalır.
`icon`	`ImageVector?`	`null`	Baş harf olmadığında çizilen: bir kişi, bir grup, bir şirket.
`tone`	`AvatarTone`	`AvatarTone.Neutral`	Baş harflerin ya da ikonun altındaki renk ve onların kendi rengi. Bir resim onu örter.
`colors`	`AvatarColors?`	`null`	Bu avatarın, tonunun renkleri yerine geçen kendi renkleri. Verdiği renkler kullanılır, gerisi tonundan gelir.
`style`	`AvatarStyle?`	`null`	Bu çağrının kendi stili: çevresindeki her stili ezer, yoğunluk ona da uygulanır. Yalnızca verdiği alanlar değişir ve her platformda değişir.
`size`	`Dp`	`PantrixTheme.style(AvatarStyle, style).size`	Avatarın genişliği ve yüksekliği: verilmezse stilin boyutu.
`tagKey`	`String?`	`null`	Avatarın otomasyon anahtarı: avatar `Avatar_<tagKey>` etiketini taşır ve yalnızca anahtar verildiğinde etiketlenir.
`image`	`(@Composable () -> Unit)?`	`null`	Avatarı dolduran, baş harflerin ya da ikonun üstüne gelen resim. Resmin kendi açıklaması okunmaz: avatarın açıklaması ikisinin yerine geçer.

AvatarStyle

PantrixAvatar'ın geometrisi: ne kadar büyük olduğu, köşelerinin nasıl olduğu ve baş harflerin ya da ikonun onun ne kadarını kapladığı.

Parametre	Tür	Varsayılan	Ne olduğu
`size`	`Dp`	`Dp.Unspecified`	Avatarın genişliği ve yüksekliği.
`shape`	`ShapeSpec`	`ShapeSpec.Unspecified`	Avatarın köşeleri: markanın şekil ölçeğinin yuvarlak ucu, bir daire. Bir marka ya da bir tema ölçeğin bir basamağını ya da kendi şeklini isterse o kullanılır.
`initialsScale`	`Float`	`Float.NaN`	Baş harflerin yazıldığı yükseklik: avatarın kısa kenarının bir kesri.
`iconScale`	`Float`	`Float.NaN`	İkonun genişliği ve yüksekliği: avatarın kısa kenarının bir kesri.

AvatarColors

Tonunun renklerini almayan bir avatar için PantrixAvatar'ın boyandığı renkler: verilen renk kullanılır, verilmeyen tonun renginde kalır.

Parametre	Tür	Varsayılan	Ne olduğu
`container`	`Color`	`Color.Unspecified`	Baş harflerin ya da ikonun altında duran ve bir resmin örttüğü dolgu. Tonun rolünün `color` rengi.
`content`	`Color`	`Color.Unspecified`	Baş harfler ya da ikon: `container` üstünde okunan renk. Tonun rolünün `onColor` rengi.

Erişilebilirlik

Ekran okuyucu. contentDescription verilen avatar o adla, bir görsel olarak okunur. Null verilen gizlenir: yanında adı yazan avatar için doğrusu budur. Baş harfler hiçbir zaman okunmaz.