Uygulama kaynaklarına genel bakış

Kaynaklar, kodunuzun kullandığı ek dosyalar ve statik içeriklerdir (ör. bit eşlemler, kullanıcı arayüzü dizeleri, animasyon talimatları).

Resimler ve dizeler gibi uygulama kaynaklarını her zaman kodunuzdan bağımsız olarak tutun. Böylece bunları ayrı ayrı koruyabilirsiniz. Ayrıca, belirli cihaz yapılandırmaları için alternatif kaynaklar sağlayın. Bunun için kaynakları özel olarak adlandırılmış kaynak dizinlerinde gruplandırın. Android, çalışma zamanında mevcut yapılandırmaya göre uygun kaynağı kullanır. Örneğin, dil ayarına bağlı olarak farklı dizeler sağlamak isteyebilirsiniz.

Uygulama kaynaklarınızı haricileştirdikten sonra, projenizin R sınıfında oluşturulan kaynak kimliklerini kullanarak bunlara erişebilirsiniz. Bu belgede, Android projenizdeki kaynakları nasıl gruplandıracağınız gösterilmektedir. Ayrıca, belirli cihaz yapılandırmaları için alternatif kaynakları nasıl sağlayacağınızı ve ardından uygulama kodunuzdan veya diğer XML dosyalarından bunlara nasıl erişeceğinizi de gösterir.

Grup kaynak türleri

Her kaynak türünü projenizin res/ dizininin belirli bir alt dizinine yerleştirin. Örneğin, basit bir projenin dosya hiyerarşisi aşağıda verilmiştir:

MyProject/
    src/
        MyActivity.kt
    res/
        drawable/
            graphic.png
        mipmap/
            icon.png
        values/
            strings.xml

res/ dizini, alt dizinlerindeki tüm kaynakları içerir: bir resim kaynağı, başlatıcı simgeleri için bir mipmap/ dizini ve bir dize kaynak dosyası. Kaynak dizini adları önemlidir ve Tablo 1'de açıklanmıştır.

Not: Mipmap klasörlerini kullanma hakkında daha fazla bilgi için Uygulama simgelerini mipmap dizinlerine yerleştirme başlıklı makaleyi inceleyin.

Tablo 1. Proje res/ dizininde desteklenen kaynak dizinleri.

Dizin Kaynak Türü
drawable/

Aşağıdaki drawable kaynak alt türlerine derlenen bit eşlem dosyaları (PNG, .9.png, JPG veya GIF) ya da XML dosyaları:

  • Bit eşlem dosyaları
  • Dokuz yamalı resimler (yeniden boyutlandırılabilir bit eşlemler)
  • Eyalet listeleri
  • Şekiller
  • Animasyonlu çizilebilir öğeler
  • Diğer çizilebilir öğeler

Daha fazla bilgi için Çizilebilir kaynaklar başlıklı makaleyi inceleyin.

mipmap/ Farklı başlatıcı simgesi yoğunlukları için çizilebilir dosyalar. mipmap/ klasörleriyle başlatıcı simgelerini yönetme hakkında daha fazla bilgi için Uygulama simgelerini mipmap dizinlerine yerleştirme başlıklı makaleyi inceleyin.
raw/

Ham biçiminde kaydedilecek rastgele dosyalar. Bu kaynakları ham InputStream ile açmak için kaynak kimliğiyle R.raw.filename çağrısı yapın.Resources.openRawResource

Ancak orijinal dosya adlarına ve dosya hiyerarşisine erişmeniz gerekiyorsa kaynakları res/raw/ yerine assets/ dizinine kaydetmeyi düşünebilirsiniz. assets/ içindeki dosyalara kaynak kimliği atanmadığından bu dosyaları yalnızca AssetManager kullanarak okuyabilirsiniz.

values/

Dizeler, tam sayılar ve renkler gibi basit değerler içeren XML dosyaları.

Diğer res/ alt dizinlerindeki XML kaynak dosyaları, XML dosya adına göre tek bir kaynak tanımlarken values/ dizinindeki dosyalar birden fazla kaynağı tanımlar. Bu dizindeki bir dosya için, <resources> öğesinin her alt öğesi tek bir kaynağı tanımlar. Örneğin, bir <string> öğesi R.string kaynağı, bir <color> öğesi ise R.color kaynağı oluşturur.

Her kaynak kendi XML öğesiyle tanımlandığından dosyayı istediğiniz gibi adlandırabilir ve farklı kaynak türlerini tek bir dosyaya yerleştirebilirsiniz. Ancak daha net olması için benzersiz kaynak türlerini farklı dosyalara yerleştirebilirsiniz. Örneğin, bu dizinde oluşturabileceğiniz kaynaklar için bazı dosya adı kuralları şunlardır:

Daha fazla bilgi için Dize kaynakları, Stil kaynağı ve Diğer kaynak türleri başlıklı makaleleri inceleyin.

xml/ Çalışma zamanında Resources.getXML çağrılarak okunabilen rastgele XML dosyaları. Çeşitli XML yapılandırma dosyaları buraya kaydedilmelidir.
font/ TTF, OTF veya TTC gibi uzantılara sahip yazı tipi dosyaları ya da <font-family> öğesi içeren XML dosyaları. Kaynak olarak kullanılan yazı tipleri hakkında daha fazla bilgi için Yazı tipini XML kaynağı olarak ekleme başlıklı makaleyi inceleyin.

Dikkat: Kaynak dosyalarını asla doğrudan res/ dizinine kaydetmeyin. Derleyici hatasına neden olur.

Tablo 1'de tanımlanan alt dizinlere kaydettiğiniz kaynaklar, varsayılan kaynaklarınızdır. Yani bu kaynaklar, uygulamanızın varsayılan tasarımını ve içeriğini tanımlar. Ancak, farklı türlerdeki Android destekli cihazlar farklı türlerde kaynaklar gerektirebilir.

Örneğin, cihazın dil ayarına göre kullanıcı arayüzünüzdeki metni çeviren farklı dize kaynakları sağlayabilirsiniz.

Not: Compose'da kullanıcı arayüzleri, animasyonlar ve duruma dayalı renkler Kotlin'de tanımlanır. Bu nedenle layout/, menu/, anim/, animator/ ve color/ dizinleri modern uygulamalar için kullanılmaz. Daha fazla bilgi için Compose'da animasyonlar ve Compose'da temanın yapısı başlıklı makaleleri inceleyin.

Alternatif kaynaklar sağlama

Çoğu uygulama, belirli cihaz yapılandırmalarını desteklemek için alternatif kaynaklar sağlar. Örneğin, farklı ekran yoğunlukları için alternatif çizilebilir kaynaklar ve farklı diller için alternatif dize kaynakları ekleyin. Android, çalışma zamanında mevcut cihaz yapılandırmasını algılar ve uygulamanız için uygun kaynakları yükler.

Bir dizi kaynak için yapılandırmaya özel alternatifler belirtmek üzere aşağıdakileri yapın:

  1. res/ içinde <resources_name>-<qualifier> biçiminde adlandırılmış yeni bir dizin oluşturun.
    • <resources_name>, ilgili varsayılan kaynakların (Tablo 1'de tanımlanmıştır) dizin adıdır.
    • <qualifier>, bu kaynakların kullanılacağı bireysel bir yapılandırmayı belirten bir addır (Tablo 2'de tanımlanmıştır).

    Birden fazla <qualifier> ekleyebilirsiniz. Her birini tireyle ayırın.

    Dikkat: Birden fazla niteleyici eklerken bunları Tablo 2'de listelendikleri sırayla yerleştirmeniz gerekir. Niteleyiciler yanlış sıralanırsa kaynaklar yoksayılır.

  2. Bu yeni dizine uygun alternatif kaynakları kaydedin. Kaynak dosyaları, varsayılan kaynak dosyalarıyla aynı şekilde adlandırılmalıdır.

Örneğin, bazı varsayılan ve alternatif kaynaklar aşağıda verilmiştir:

res/
    drawable/
        icon.png
        background.png
    drawable-hdpi/
        icon.png
        background.png

hdpi niteleyicisi, söz konusu dizindeki kaynakların yüksek yoğunluklu ekrana sahip cihazlar için olduğunu gösterir. Bu drawable dizinlerindeki resimler belirli ekran yoğunlukları için boyutlandırılır ancak dosya adları tamamen aynıdır. Bu sayede, icon.png veya background.png resmine referans vermek için kullandığınız kaynak kimliği her zaman aynı olur. Android, cihaz yapılandırma bilgilerini kaynak dizin adındaki niteleyicilerle karşılaştırarak her kaynağın mevcut cihaza en uygun sürümünü seçer.

Dikkat: Alternatif bir kaynak tanımlarken kaynağı varsayılan bir yapılandırmada da tanımladığınızdan emin olun. Aksi takdirde, cihaz bir yapılandırmayı değiştirdiğinde uygulamanızda çalışma zamanı istisnaları oluşabilir. Örneğin, yalnızca values-en öğesine bir dize ekleyip values öğesine eklemezseniz kullanıcı varsayılan sistem dilini değiştirdiğinde uygulamanız Resource Not Found istisnasıyla karşılaşabilir.

Tablo 2'de yapılandırma niteleyicileri öncelik sırasına göre listelenmektedir. Her niteleyiciyi tireyle ayırarak tek bir dizin adına birden fazla niteleyici ekleyebilirsiniz. Bir kaynak dizini için birden fazla niteleyici kullanıyorsanız bunları tabloda listelendikleri sırayla dizin adına eklemeniz gerekir.

Tablo 2. Yapılandırma niteleyici adları.

Yapılandırma Niteleyici değerleri Açıklama
MCC ve MNC Örnekler:
mcc310
mcc310-mnc004
mcc208-mnc00

Mobil ülke kodu (MCC), isteğe bağlı olarak cihazdaki SIM kartın mobil ağ kodu (MNC) ile birlikte. Örneğin, mcc310 herhangi bir operatörde ABD, mcc310-mnc004 Verizon'da ABD ve mcc208-mnc00 Orange'da Fransa anlamına gelir.

Cihaz radyo bağlantısı kullanıyorsa (yani GSM telefonsa) MCC ve MNC değerleri SIM karttan alınır.

Örneğin, ülkeye özgü yasal kaynakları uygulamanıza dahil etmek için de tek başına MCC'yi kullanabilirsiniz. Yalnızca dile göre belirtmeniz gerekiyorsa bunun yerine dil, alfabe (isteğe bağlı) ve bölge (isteğe bağlı) niteleyicisini kullanın. MM ve MNC niteleyicisini kullanıyorsanız dikkatli bir şekilde kullanın ve beklendiği gibi çalıştığını test edin.

Ayrıca, sırasıyla mevcut mobil ülke kodunu ve mobil ağ kodunu gösteren yapılandırma alanları mcc ve mnc'ya da bakın.

Dil, yazı sistemi (isteğe bağlı) ve bölge (isteğe bağlı) Örnekler:
en
fr
en-rUS
fr-rFR
fr-rCA
b+en
b+en+US
b+es+419
b+zh+Hant
b+sr+Latn+RS

Dil, iki harfli ISO 639-1 dil koduyla tanımlanır. İsteğe bağlı olarak, iki harfli ISO 3166-1-alpha-2 bölge kodu (küçük harfli r ile başlar) eklenebilir.

Kodlar büyük/küçük harfe duyarlı değildir. Bölge kısmını ayırt etmek için r öneki kullanılır. Bölgeyi tek başına belirtemezsiniz.

Android 7.0 (API düzeyi 24), dil ve bölgeye özel kaynakları nitelendirmek için kullanabileceğiniz BCP 47 dil etiketleri desteğini kullanıma sundu. Dil etiketi, her biri genel etiket tarafından tanımlanan dil aralığını daraltan veya hassaslaştıran bir veya daha fazla alt etiketin sırasından oluşur. Dil etiketleri hakkında daha fazla bilgi için Dilleri Tanımlama Etiketleri başlıklı makaleyi inceleyin.

BCP 47 dil etiketi kullanmak için b+ ve iki harfli bir ISO 639-1 dil kodunu birleştirin. İsteğe bağlı olarak, + ile ayrılmış ek alt etiketler de ekleyebilirsiniz.

Kullanıcılar sistem ayarlarında dili değiştirirse dil etiketi, uygulamanızın kullanım ömrü boyunca değişebilir. Bunun çalışma zamanında uygulamanızı nasıl etkileyebileceği hakkında bilgi edinmek için Yapılandırma değişikliklerini işleme başlıklı makaleyi inceleyin.

Uygulamanızı diğer diller için yerelleştirme hakkında eksiksiz bir rehber için Uygulamanızı yerelleştirme başlıklı makaleyi inceleyin.

Ayrıca, tanımlanmış yerel ayarlar listesini sağlayan getLocales yöntemine de bakın. Bu listede birincil yerel ayar bulunur.

Dil bilgisine uygun cinsiyet masculine
feminine
neuter

Kullanıcının dil bilgisine uygun cinsiyeti. Dil bilgisine uygun cinsiyet içeren dillerde kullanılır.

Örneğin, Fransızca konuşan kullanıcılara farklı kaynaklar sağlamanız gerekiyorsa aşağıdaki gibi dizinleri kullanabilirsiniz:

res/
  values-fr/
    strings.xml (belirtilmemiş cinsiyetle ilgili varsayılan dizeler)
  values-fr-masculine/
    strings.xml (erkek cinsiyetle ilgili dizeler)
  values-fr-feminine/
    strings.xml (kadın cinsiyetle ilgili dizeler)
  values-fr-neuter/
    strings.xml (nötr cinsiyetle ilgili dizeler)

Uygulamanızın kullanıcı arayüzünü dilbilgisel cinsiyete göre kişiselleştirme başlıklı makaleyi inceleyin.

Dilbilgisel cinsiyeti belirten getGrammaticalGender yapılandırma yöntemine de bakın.

API düzeyi 34'te eklendi.

Wide Color Gamut widecg
nowidecg
  • widecg: Display P3 veya AdobeRGB gibi geniş renk gamına sahip ekranlar
  • nowidecg: sRGB gibi dar renk gamına sahip ekranlar

API düzeyi 26'da eklendi.

Ayrıca, ekranın geniş renk gamına sahip olup olmadığını gösteren isScreenWideColorGamut yapılandırma yöntemine de bakın.

Yüksek Dinamik Aralık (HDR) highdr
lowdr
  • highdr: Yüksek dinamik aralığa sahip ekranlar
  • lowdr: Düşük/standart dinamik aralığa sahip ekranlar

API düzeyi 26'da eklendi.

Ekranın HDR özelliklerine sahip olup olmadığını belirten isScreenHdr yapılandırma yöntemine de bakın.

Kullanıcı arayüzü modu car
desk
television
appliance
watch
vrheadset
  • car: Cihaz, araç kiti yuvasında gösteriliyorsa
  • desk: Cihaz, masaüstü dock'unda gösteriliyorsa
  • television: Cihaz, televizyonda görüntüleniyor. Kullanıcı arayüzünün kullanıcının uzağında olduğu büyük bir ekranda "on fut" deneyimi sunuluyor ve deneyim öncelikle d-pad veya diğer işaretçi olmayan etkileşimler etrafında şekilleniyor.
  • appliance: Cihaz, ekranı olmayan bir cihaz olarak kullanılıyor.
  • watch: Cihazın ekranı var ve bileğe takılıyor
  • vrheadset: Cihaz, sanal gerçeklik başlığında gösteriliyorsa

API düzeyi 8'de eklendi; televizyon API 13'te, cihaz API 16'da, kol saati API 20'de, VR başlığı API 26'da eklendi.

Cihaz bir yuvaya takıldığında veya yuvadan çıkarıldığında uygulamanızın nasıl yanıt verebileceği hakkında bilgi edinmek için Yerleştirme durumunu ve türünü belirleme ve izleme başlıklı makaleyi inceleyin.

Kullanıcı cihazı yerleştirme istasyonuna koyarsa bu durum uygulamanızın kullanım süresi boyunca değişebilir. Bu modlardan bazılarını UiModeManager simgesini kullanarak etkinleştirebilir veya devre dışı bırakabilirsiniz. Bu durumun uygulamanızı çalışma zamanında nasıl etkileyeceği hakkında bilgi edinmek için Yapılandırma değişikliklerini işleme başlıklı makaleyi inceleyin.

Gece modu night
notnight
  • night: gece
  • notnight: gündüz

API düzeyi 8'de eklendi.

Gece modu otomatik modda (varsayılan) bırakılırsa bu durum uygulamanızın kullanım süresi boyunca değişebilir. Bu durumda mod, günün saatine göre değişir. Bu modu UiModeManager simgesini kullanarak etkinleştirebilir veya devre dışı bırakabilirsiniz. Bu durumun uygulamanızı çalışma zamanında nasıl etkileyeceği hakkında bilgi edinmek için Yapılandırma değişikliklerini işleme başlıklı makaleyi inceleyin.

Ekran piksel yoğunluğu (dpi) ldpi
mdpi
hdpi
xhdpi
xxhdpi
xxxhdpi
nodpi
tvdpi
anydpi
nnndpi
  • ldpi: düşük yoğunluklu ekranlar; yaklaşık 120 dpi.
  • mdpi: orta yoğunluklu (geleneksel HVGA) ekranlar; yaklaşık 160 dpi.
  • hdpi: Yüksek yoğunluklu ekranlar; yaklaşık 240 DPI.
  • xhdpi: Ekstra yüksek yoğunluklu ekranlar; yaklaşık 320 DPI. API düzeyinde 8'de eklendi.
  • xxhdpi: Çok çok yüksek yoğunluklu ekranlar; yaklaşık 480 dpi. API düzeyinde 16'da eklendi.
  • xxxhdpi: extra-extra-extra-high-density uses (launcher icon only—see Support different pixel densities); approximately 640 dpi. API düzeyi 18'de eklendi.
  • nodpi: Cihaz yoğunluğuyla eşleşecek şekilde ölçeklendirilmesini istemediğiniz bit eşlem kaynakları için kullanılır.
  • tvdpi: mdpi ve hdpi arasında bir yerde olan ekranlar; yaklaşık 213 dpi. Bu, "birincil" yoğunluk grubu olarak kabul edilmez. Bu ayar, çoğunlukla 720p televizyonlar için tasarlanmıştır ve çoğu uygulama için gerekli değildir. 1080p TV panelleri için xhdpi, 4K TV panelleri için ise xxxhdpi kullanın. API düzeyi 13'te eklendi.
  • anydpi: Tüm ekran yoğunluklarıyla eşleşir ve diğer niteleyicilere göre önceliklidir. Bu, vektör çizilebilir öğeler için kullanışlıdır. API düzeyi 21'de eklenmiştir.
  • nnndpi: Standart olmayan yoğunlukları temsil etmek için kullanılır. Burada nnn pozitif bir tam sayı ekran yoğunluğudur. Bu çoğu durumda kullanılmaz. Standart yoğunluk grupları kullanmak, piyasadaki çeşitli cihaz ekran yoğunluklarını desteklemenin ek yükünü büyük ölçüde azaltır.

Altı temel yoğunluk arasında 3:4:6:8:12:16 ölçeklendirme oranı vardır (tvdpi yoğunluğu hariç). Bu nedenle, ldpi'deki 9x9 boyutlu bir bitmap, mdpi'de 12x12, hdpi'de 18x18, xhdpi'da 24x24 boyutundadır.

Not: Yoğunluk niteleyicisi kullanmak, kaynakların yalnızca bu yoğunluktaki ekranlar için olduğu anlamına gelmez. Mevcut cihaz yapılandırmasına daha iyi uyan niteleyicilerle alternatif kaynaklar sağlamazsanız sistem, en iyi eşleşen kaynakları kullanır.

Farklı ekran yoğunluklarının nasıl işleneceği ve Android'in, mevcut yoğunluğa uyacak şekilde bit eşlemlerinizi nasıl ölçekleyebileceği hakkında daha fazla bilgi için Ekran uyumluluğuna genel bakış bölümüne bakın.

Dokunmatik ekran türü notouch
finger
  • notouch: Cihazda dokunmatik ekran yok.
  • finger: Cihazda, kullanıcının parmağıyla doğrudan etkileşimde bulunarak kullanılması amaçlanan bir dokunmatik ekran vardır.

Cihazdaki dokunmatik ekranın türünü belirten touchscreen yapılandırma alanına da bakın.

Klavye kullanılabilirliği keysexposed
keyshidden
keyssoft
  • keysexposed: Cihazda klavye mevcuttur. Cihazda yazılım klavyesi etkinse (büyük olasılıkla), donanım klavyesi kullanıcıya gösterilmese veya cihazda donanım klavyesi olmasa bile bu klavye kullanılır. Yazılım klavyesi sağlanmamışsa veya devre dışı bırakılmışsa bu yalnızca donanım klavyesi kullanıldığında kullanılır.
  • keyshidden: Cihazda donanım klavyesi mevcut ancak bu klavye gizli ve cihazda yazılım klavyesi etkin değil.
  • keyssoft: Cihazda yazılım klavyesi etkinleştirilmişse (görünür olsun veya olmasın).

keysexposed kaynakları sağlarsanız ancak keyssoft kaynakları sağlamazsanız sistemde yazılım klavyesi etkin olduğu sürece klavye görünür olsun veya olmasın sistem keysexposed kaynaklarını kullanır.

Kullanıcı bir donanım klavyesi açarsa bu durum uygulamanızın kullanım ömrü boyunca değişebilir. Bu durumun uygulamanızı çalışma zamanında nasıl etkileyeceği hakkında bilgi edinmek için Yapılandırma değişikliklerini işleme başlıklı makaleyi inceleyin.

Ayrıca, sırasıyla bir donanım klavyesinin ve her türlü klavyenin (yazılım dahil) görünürlüğünü belirten yapılandırma alanları hardKeyboardHidden ve keyboardHidden'yı inceleyin.

Birincil metin giriş yöntemi nokeys
qwerty
12key
  • nokeys: Cihazda metin girişi için donanım tuşları yok.
  • qwerty: Cihazda donanım QWERTY klavye olup olmadığı ve bu klavyenin kullanıcıya görünür olup olmadığı.
  • 12key: Cihazda 12 tuşlu bir donanım klavyesi olup olmadığı ve bunun kullanıcıya görünür olup olmadığı.

Ayrıca, kullanılabilen birincil metin giriş yöntemini gösteren keyboard yapılandırma alanına da bakın.

Platform sürümü (API düzeyi) Örnekler:
v3
v4
v7
vb.

Cihazın desteklediği API düzeyi. Örneğin, v1 API düzeyi 1 (Android 1.0 veya sonraki sürümlerin yüklü olduğu cihazlar) ve v4 API düzeyi 4 (Android 1.6 veya sonraki sürümlerin yüklü olduğu cihazlar) için. Bu değerler hakkında daha fazla bilgi için Android API düzeyleri belgesine bakın.

Not: Android'in tüm sürümleri, tüm niteleyicileri desteklemez. Yeni bir niteleyici kullanmak, eski cihazların yoksayabilmesi için platform sürümü niteleyicisini dolaylı olarak ekler. Sorun yaşamamak için her zaman bir dizi varsayılan kaynak (nitelik içermeyen bir kaynak grubu) ekleyin. Daha fazla bilgi için kaynaklarla en iyi cihaz uyumluluğunu sağlama bölümüne bakın.

Compose uygulamalarında, düzen ve boyutla ilgili yapılandırma niteleyicileri gerekmez. Bu cihazlar hala mevcut olsa da Tablo 2'ye dahil edilmez. Bu niteleyiciler arasında düzen yönü, en küçük genişlik, kullanılabilir genişlik, kullanılabilir yükseklik, ekran boyutu, ekran en-boy oranı, yuvarlak ekran ve ekran yönü yer alır. Öncelik sırasına göre yapılandırma niteleyicilerinin tam tablosu için Uygulama kaynaklarına genel bakış (Görünümler) başlıklı makaleyi inceleyin.

Nitelik adı kuralları

Yapılandırma niteleyici adlarını kullanmayla ilgili bazı kurallar şunlardır:

  • Tek bir kaynak grubu için tireyle ayrılmış birden çok niteleyici belirtebilirsiniz. Örneğin, drawable-en-rUS-night gece modundaki ABD İngilizcesi cihazlar için geçerlidir.
  • Niteleyiciler, Tablo 2'de listelenen sırada olmalıdır.
    • Yanlış: drawable-hdpi-night/
    • Doğru: drawable-night-hdpi/
  • Alternatif kaynak dizinleri iç içe yerleştirilemez. Örneğin, şunları kullanamazsınız: res/drawable/drawable-en/.
  • Değerler büyük/küçük harfe duyarlı değildir. Kaynak derleyici, büyük/küçük harfe duyarsız dosya sistemlerinde sorun yaşamamak için dizin adlarını işlemeden önce küçük harfe dönüştürür. Adlardaki büyük harfler yalnızca okunabilirliği artırmak için kullanılır.
  • Her niteleyici türü için yalnızca bir değer desteklenir. Örneğin, İspanya ve Fransa için aynı çizilebilir dosyaları kullanmak istiyorsanız drawable-es-fr/ adlı bir dizininiz olamaz. Bunun yerine, uygun dosyaları içeren drawable-es/ ve drawable-fr/ gibi iki kaynak dizinine ihtiyacınız vardır.

Alternatif kaynakları bu niteleyicilerle adlandırılmış dizinlere kaydettikten sonra Android, mevcut cihaz yapılandırmasına göre uygulamanızdaki kaynakları otomatik olarak uygular. Bir kaynak her istendiğinde Android, istenen kaynak dosyasını içeren alternatif kaynak dizinlerini kontrol eder ve en iyi eşleşen kaynağı bulur.

Belirli bir cihaz yapılandırmasına uyan alternatif kaynak yoksa Android, ilgili varsayılan kaynakları (yapılandırma niteleyicisi içermeyen belirli bir kaynak türü için kaynak grubu) kullanır.

Takma ad kaynakları oluşturma

Birden fazla cihaz yapılandırmasında kullanmak istediğiniz ancak varsayılan kaynak olarak sağlamak istemediğiniz bir kaynağınız varsa aynı kaynağı birden fazla alternatif kaynak dizinine yerleştirmeniz gerekmez. Bunun yerine, varsayılan kaynak dizininize kaydedilen bir kaynağın diğer adı olarak işlev gören alternatif bir kaynak oluşturabilirsiniz.

Çizilebilir öğeler

Örneğin, icon.png uygulama simgenizin olduğunu ve farklı yerel ayarlar için bu simgenin benzersiz bir sürümüne ihtiyacınız olduğunu düşünelim. Ancak iki yerel ayar (Kanada İngilizcesi ve Kanada Fransızcası) aynı sürümü kullanmalıdır. Aynı resmi hem İngilizce-Kanada hem de Fransızca-Kanada için kaynak dizinine kopyalamanız gerekmez. Bunun yerine, her ikisi için de kullanılan resmi icon.png dışında herhangi bir adla (ör. icon_ca.png) kaydedip varsayılan res/drawable/ dizinine yerleştirebilirsiniz. Ardından, icon.xml dosyasını res/drawable-en-rCA/ ve res/drawable-fr-rCA/ içinde oluşturun. Bu dosya, <bitmap> öğesini kullanarak icon_ca.png kaynağına referans verir.

<?xml version="1.0" encoding="utf-8"?>
<bitmap xmlns:android="http://schemas.android.com/apk/res/android" android:src="@drawable/icon_ca" />

Bu sayede, PNG dosyasının yalnızca bir sürümünü ve bu dosyayı işaret eden iki küçük XML dosyasını saklayabilirsiniz. Ardından painterResource(R.drawable.icon) simgesini kullanabilirsiniz. Sistem, yerel ayarı algıladığında uygun dosyayı seçer.

Dizeler ve diğer basit değerler

Mevcut bir dizeye takma ad oluşturmak için yeni dizenin değeri olarak istenen dizenin kaynak kimliğini kullanın:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Hello</string>
    <string name="hi">@string/hello</string>
</resources>

R.string.hi kaynağı artık R.string.hello için takma ad olarak kullanılıyor.

Diğer basit değerler de aynı şekilde çalışır. Örneğin renkler:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="red">#f00</color>
    <color name="highlight">@color/red</color>
</resources>

Uygulama kaynaklarınıza erişme

Uygulamanızda bir kaynak sağladıktan sonra, kaynak kimliğine referans vererek bu kaynağı uygulayabilirsiniz. Tüm kaynak kimlikleri, projenizin R sınıfında tanımlanır. Bu sınıf, aapt aracı tarafından otomatik olarak oluşturulur.

Uygulamanız derlendiğinde aapt, res/ dizininizdeki tüm kaynakların kaynak kimliklerini içeren R sınıfını oluşturur. Her kaynak türü için R alt sınıfı vardır. Örneğin, tüm çizilebilir kaynaklar için R.drawable alt sınıfı kullanılır. Ayrıca, bu türdeki her kaynak için statik bir tam sayı vardır (ör. R.drawable.icon). Bu tam sayı, kaynağınızı almak için kullanabileceğiniz kaynak kimliğidir.

Kaynak kimlikleri R sınıfında belirtilse de kaynak kimliği bulmak için bu sınıfa bakmanız gerekmez. Kaynak kimliği her zaman aşağıdakilerden oluşur:

  • Kaynak türü: Her kaynak, string veya drawable gibi bir "tür" içinde gruplandırılır.
  • Uzantı hariç dosya adı olan kaynak adı.

Compose'da kaynaklara erişme

Jetpack Compose, kaynaklara güvenli bir şekilde erişmek için yerleşik, composable'a uygun işlevler sağlar.

  • Dizeler:
    stringResource(id = R.string.hello)
  • Çizilebilir öğeler:
    painterResource(id = R.drawable.my_icon)

Kullanıcı arayüzü olmayan kodlardaki kaynaklara erişme

Kullanıcı arayüzü hiyerarşinizin dışındaki kaynaklara (ör. ViewModel, Repository veya sistem Service) erişmeniz gerekiyorsa bunları Context kullanarak çözebilirsiniz.

// Retrieve a localized string resource
val greeting = context.getString(R.string.hello_world)

Ayrıca, Resources yöntemlerini kullanarak tek tek kaynakları da alabilirsiniz. Bu yöntemlerin örneğini getResources ile alabilirsiniz.

Söz dizimi

Kodda bir kaynağa referans vermek için kullanılan söz dizimi:

[<package_name>.]R.<resource_type>.<resource_name>
  • <package_name>, kaynağın bulunduğu paketin adıdır (kendi paketinizdeki kaynaklara referans verirken gerekli değildir).
  • <resource_type>, kaynak türü için R alt sınıfıdır.
  • <resource_name>, uzantısız kaynak dosya adı veya basit değerler için XML öğesindeki android:name özellik değeridir.

Her kaynak türü ve bunlara nasıl referans verileceği hakkında daha fazla bilgi için Compose'daki Kaynaklar başlıklı makaleyi inceleyin.

Orijinal dosyalara erişme

Nadiren de olsa orijinal dosyalarınıza ve dizinlerinize erişmeniz gerekebilir. Bu durumda, res/ içinde dosya kaydetme işlemi sizin için çalışmaz. Çünkü res/ içindeki bir kaynağı okumanın tek yolu kaynak kimliğini kullanmaktır. Bunun yerine kaynaklarınızı assets/ dizinine kaydedebilirsiniz.

assets/ dizinine kaydedilen dosyalara kaynak kimliği verilmez. Bu nedenle, bu dosyalara R sınıfı veya XML kaynakları üzerinden başvuramazsınız. Bunun yerine, assets/ dizinindeki dosyaları normal bir dosya sistemi gibi sorgulayabilir ve AssetManager kullanarak ham verileri okuyabilirsiniz.

Ancak tek ihtiyacınız ham verileri (ör. video veya ses dosyası) okuma özelliği ise dosyayı res/raw/ dizinine kaydedin ve openRawResource kullanarak bir bayt akışı okuyun.

Platform kaynaklarına erişim

Android, sistem stilleri ve temalar gibi bir dizi standart kaynak içerir. Bunlara erişmek için kaynak referansınızı android paket sınıfıyla nitelendirin. Örneğin: painterResource(android.R.drawable.ic_menu_info_details).

Kaynaklarla en iyi cihaz uyumluluğunu sağlama

Uygulamanızın birden fazla cihaz yapılandırmasını desteklemesi için, uygulamanızın kullandığı her kaynak türü için her zaman varsayılan kaynaklar sağlamanız çok önemlidir.

Örneğin, uygulamanız birden fazla dili destekliyorsa dizelerinizi kaydettiğiniz values/ dizinini dil ve bölge niteleyicisi olmadan her zaman ekleyin. Bunun yerine tüm dize dosyalarınızı dil ve bölge niteleyicisi olan dizinlere yerleştirirseniz uygulamanız, dizelerinizin desteklemediği bir dile ayarlanmış cihazda çalıştırıldığında çöker.

Varsayılan values/ kaynakları sağladığınız sürece uygulamanız, kullanıcı sunduğu dili anlamasa bile düzgün şekilde çalışır. Kilitlenmekten daha iyidir.

Varsayılan kaynaklar sağlamak yalnızca uygulamanızın tahmin etmediğiniz bir yapılandırmada çalışabilmesi için değil, aynı zamanda Android'in yeni sürümlerinde bazen daha eski sürümlerin desteklemediği yapılandırma niteleyicileri eklendiği için de önemlidir. Yeni bir kaynak niteleyici kullanırsanız ancak Android'in daha eski sürümleriyle kod uyumluluğunu korursanız Android'in daha eski bir sürümü uygulamanızı çalıştırdığında varsayılan kaynak sağlamadığınız için uygulama çöker. Bunun nedeni, yeni niteleyiciyle adlandırılan kaynakların kullanılamamasıdır.

Örneğin, minSdkVersion değeriniz 4 olarak ayarlanmışsa ve tüm çizilebilir kaynaklarınızı gece modu (API düzeyine 8'de eklenen night veya notnight) kullanarak nitelendiriyorsanız API düzeyi 4 olan bir cihaz, çizilebilir kaynaklarınıza erişemez ve kilitlenir. Bu durumda, notnight değerinin varsayılan kaynaklarınız olmasını istersiniz. Bu nedenle, bu niteleyiciyi hariç tutun ve çizilebilir kaynaklarınızı drawable/ veya drawable-night/ içine yerleştirin.

Kısacası, en iyi cihaz uyumluluğunu sağlamak için uygulamanızın düzgün çalışması için gereken kaynaklar için her zaman varsayılan kaynaklar sağlayın. Ardından, yapılandırma niteleyicilerini kullanarak belirli cihaz yapılandırmaları için alternatif kaynaklar oluşturun.

Bu kuralın bir istisnası vardır: Uygulamanızın minSdkVersion değeri 4 veya daha yüksekse ekran yoğunluğu niteleyicisiyle alternatif çizilebilir kaynaklar sağladığınızda varsayılan çizilebilir kaynaklara ihtiyacınız yoktur. Android, varsayılan çizilebilir kaynaklar olmasa bile alternatif ekran yoğunlukları arasında en iyi eşleşmeyi bulabilir ve gerektiğinde bit eşlemleri ölçeklendirebilir. Ancak tüm cihaz türlerinde en iyi deneyimi sunmak için üç yoğunluk türünün tümü için alternatif çizilebilir öğeler sağlayın.

Android, en iyi eşleşen kaynağı nasıl bulur?

Alternatifler sağladığınız bir kaynak istediğinizde Android, mevcut cihaz yapılandırmasına bağlı olarak çalışma zamanında hangi alternatif kaynağın kullanılacağını seçer. Android'in alternatif bir kaynağı nasıl seçtiğini göstermek için aşağıdaki drawable dizinlerinin her birinin aynı resimlerin farklı sürümlerini içerdiğini varsayalım:

drawable/
drawable-en/
drawable-fr-rCA/
drawable-en-night/
drawable-en-notouch-12key/
drawable-night-ldpi/
drawable-night-notouch-12key/

Aşağıdaki cihaz yapılandırmasının olduğunu varsayalım:

Yerel ayar = en-GB
Gece modu = night
Ekran piksel yoğunluğu = hdpi
Dokunmatik ekran türü = notouch
Birincil metin giriş yöntemi = 12key

Android, cihaz yapılandırmasını mevcut alternatif kaynaklarla karşılaştırarak drawable-en-night içinden çizilebilir öğeler seçer.

Sistem, hangi kaynakların kullanılacağına karar verirken aşağıdaki mantığı uygular:

Şekil 2. Android'in en iyi eşleşen kaynağı nasıl bulduğunu gösteren akış şeması.

  1. Cihaz yapılandırmasıyla çelişen kaynak dosyalarını ortadan kaldırın.

    drawable-fr-rCA/ dizini, en-GB yerel ayarıyla çeliştiği için kaldırıldı.

    drawable/
    drawable-en/
    drawable-fr-rCA/
    drawable-en-night/
    drawable-en-notouch-12key/
    drawable-night-ldpi/
    drawable-night-notouch-12key/
    

    İstisna: Ekran piksel yoğunluğu, çelişki nedeniyle ortadan kaldırılmayan tek niteleyicidir. Cihazın ekran yoğunluğu hdpi olsa da bu noktada her ekran yoğunluğu eşleşme olarak kabul edildiğinden drawable-night-ldpi/ kaldırılmaz. Daha fazla bilgi için Ekran uyumluluğuna genel bakış başlıklı makaleyi inceleyin.

  2. Listedeki bir sonraki en yüksek öncelikli niteleyiciyi bulun (Tablo 2). (Satıcı Kategorisi Kodu ile başlayın.)
  3. Kaynak dizinlerinden herhangi birinde bu niteleyici var mı?
    • Hayırsa ikinci adıma dönün ve sonraki niteleyiciye bakın. Bu örnekte, dil niteleyicisine ulaşılana kadar yanıt "hayır"dır.
    • Evet ise dördüncü adıma geçin.
  4. Bu niteleyiciyi içermeyen kaynak dizinlerini ortadan kaldırın. Bu örnekte, sistem sonraki adımda dil niteleyicisi içermeyen tüm dizinleri ortadan kaldırır:
    drawable/
    drawable-en/
    drawable-en-night/
    drawable-en-notouch-12key/
    drawable-night-ldpi/
    drawable-night-notouch-12key/
    

    İstisna: Söz konusu niteleyici ekran piksel yoğunluğuysa Android, cihazın ekran yoğunluğuyla en çok eşleşen seçeneği belirler. Genel olarak Android, daha küçük bir orijinal resmi büyütmek yerine daha büyük bir orijinal resmi küçültmeyi tercih eder. Daha fazla bilgi için Ekran uyumluluğuna genel bakış başlıklı makaleyi inceleyin.

  5. Yalnızca bir dizin kalana kadar ikinci, üçüncü ve dördüncü adımları tekrarlayın. Bu örnekte, gece modu, eşleşme olan bir sonraki niteleyicidir. Bu nedenle, gece modunu belirtmeyen kaynaklar elenir:
    drawable-en/
    drawable-en-night/
    drawable-en-notouch-12key/
    

    Kalan dizin drawable-en-night.

Bu prosedür istenen her kaynak için yürütülse de sistem, prosedürün bazı yönlerini optimize eder. Bu optimizasyonlardan biri, cihaz yapılandırması bilindikten sonra hiçbir zaman eşleşemeyecek alternatif kaynakları ortadan kaldırabilmesidir. Örneğin, yapılandırma dili İngilizce ise dil niteleyicisi İngilizce dışında bir dile ayarlanmış olan kaynak dizinleri, kontrol edilen kaynak havuzuna hiçbir zaman dahil edilmez (ancak dil niteleyicisi olmayan bir kaynak dizini yine de dahil edilir).

Sistem, ekran boyutu niteleyicilerine göre kaynak seçerken daha iyi eşleşen kaynak yoksa mevcut ekrandan daha küçük bir ekran için tasarlanmış kaynakları kullanır. Örneğin, büyük boyutlu bir ekranda gerekirse normal boyutlu ekran kaynakları kullanılır.

Ancak, mevcut ekrandan daha büyük kaynaklar varsa sistem bunları kullanmaz ve başka kaynaklar cihaz yapılandırmasıyla eşleşmezse uygulamanız çöker. Örneğin, tüm düzen kaynakları xlarge niteleyicisiyle etiketlenmişse ancak cihaz normal boyutlu bir ekrana sahipse bu durum yaşanır.

Not: Niteleyicinin önceliği (Tablo 2'de), cihazla tam olarak eşleşen niteleyici sayısından daha önemlidir. Önceki örnekte, dördüncü adımda listedeki son seçim, cihazla tam olarak eşleşen üç niteleyici (gece modu, dokunmatik ekran türü ve giriş yöntemi) içerirken drawable-en yalnızca eşleşen bir parametreye (dil) sahiptir. Ancak dil, bu diğer niteleyicilere göre daha yüksek önceliğe sahiptir. Bu nedenle drawable-night-notouch-12key elenir.

Ek kaynaklar

Uygulama kaynakları hakkında daha fazla bilgi edinmek için aşağıdaki ek kaynaklara bakın:

Belgeler

İçeriği görüntüleme