Anwendungsressourcen

Ressourcen sind die zusätzlichen Dateien und statischen Inhalte, die von Ihrem Code verwendet werden, z. B. Bitmaps, Strings für die Benutzeroberfläche und Animationsanweisungen.

Lagern Sie App-Ressourcen wie Bilder und Strings immer aus Ihrem Code aus, damit Sie sie unabhängig verwalten können. Außerdem können Sie alternative Ressourcen für bestimmte Gerätekonfigurationen bereitstellen, indem Sie sie in speziell benannten Ressourcenverzeichnissen gruppieren. Zur Laufzeit verwendet Android die entsprechende Ressource basierend auf der aktuellen Konfiguration. So möchten Sie vielleicht je nach Spracheinstellung unterschiedliche Strings bereitstellen.

Nachdem Sie die App-Ressourcen externalisiert haben, können Sie über Ressourcen-IDs darauf zugreifen, die in der Klasse R Ihres Projekts generiert werden. In diesem Dokument wird beschrieben, wie Sie die Ressourcen in Ihrem Android-Projekt gruppieren. Außerdem wird gezeigt, wie Sie alternative Ressourcen für bestimmte Gerätekonfigurationen bereitstellen und dann über Ihren App-Code oder andere XML-Dateien darauf zugreifen.

Ressourcentypen gruppieren

Platzieren Sie jede Art von Ressource in einem bestimmten Unterverzeichnis des res/-Verzeichnisses Ihres Projekts. Hier sehen Sie beispielsweise die Dateihierarchie für ein einfaches Projekt:

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

Das Verzeichnis res/ enthält alle Ressourcen in seinen Unterverzeichnissen: eine Bildressource, ein mipmap/-Verzeichnis für Launcher-Symbole und eine String-Ressourcendatei. Die Namen der Ressourcenverzeichnisse sind wichtig und werden in Tabelle 1 beschrieben.

Hinweis:Weitere Informationen zur Verwendung der Mipmap-Ordner finden Sie unter App-Symbole in Mipmap-Verzeichnisse einfügen.

Tabelle 1. Unterstützte Ressourcenverzeichnisse im Projektverzeichnis res/.

Verzeichnis Ressourcentyp
drawable/

Bitmap-Dateien (PNG, .9.png, JPG oder GIF) oder XML-Dateien, die in die folgenden untergeordneten Typen von zeichenfähigen Ressourcen kompiliert werden:

  • Bitmap-Dateien
  • Nine-Patches (Bitmaps, die in der Größe angepasst werden können)
  • Bundesstaatenlisten
  • Formen
  • Drawable-Animationen
  • Andere Drawables

Weitere Informationen finden Sie unter Drawable-Ressourcen.

mipmap/ Drawable-Dateien für verschiedene Launcher-Symbol-Dichten. Weitere Informationen zum Verwalten von Launcher-Symbolen mit mipmap/-Ordnern finden Sie unter App-Symbole in mipmap-Verzeichnisse einfügen.
raw/

Beliebige Dateien, die im Rohformat gespeichert werden sollen. Wenn Sie diese Ressourcen mit einem Roh-InputStream öffnen möchten, rufen Sie Resources.openRawResource mit der Ressourcen-ID auf, die R.raw.filename ist.

Wenn Sie jedoch Zugriff auf die ursprünglichen Dateinamen und die Dateihierarchie benötigen, sollten Sie Ressourcen im Verzeichnis assets/ anstelle von res/raw/ speichern. Dateien in assets/ erhalten keine Ressourcen-ID. Sie können also nur mit AssetManager gelesen werden.

values/

XML-Dateien, die einfache Werte wie Strings, Ganzzahlen und Farben enthalten.

Während in XML-Ressourcendateien in anderen res/-Unterverzeichnissen eine einzelne Ressource basierend auf dem XML-Dateinamen definiert wird, werden in Dateien im values/-Verzeichnis mehrere Ressourcen beschrieben. Für eine Datei in diesem Verzeichnis definiert jedes untergeordnete Element des <resources>-Elements eine einzelne Ressource. Mit einem <string>-Element wird beispielsweise eine R.string-Ressource erstellt und mit einem <color>-Element eine R.color-Ressource.

Da jede Ressource mit einem eigenen XML-Element definiert wird, können Sie die Datei beliebig benennen und verschiedene Ressourcentypen in einer Datei platzieren. Aus Gründen der Übersichtlichkeit empfiehlt es sich jedoch, eindeutige Ressourcentypen in verschiedenen Dateien zu platzieren. Hier sind einige Beispiele für Dateinamenkonventionen für Ressourcen, die Sie in diesem Verzeichnis erstellen können:

Weitere Informationen finden Sie unter String-Ressourcen, Stilressourcen und Weitere Ressourcentypen.

xml/ Beliebige XML-Dateien, die zur Laufzeit durch Aufrufen von Resources.getXML gelesen werden können. Hier müssen verschiedene XML-Konfigurationsdateien gespeichert werden.
font/ Schriftartdateien mit Erweiterungen wie TTF, OTF oder TTC oder XML-Dateien, die ein <font-family>-Element enthalten. Weitere Informationen zu Schriftarten als Ressourcen finden Sie unter Schriftart als XML-Ressource hinzufügen.

Achtung:Speichern Sie Ressourcendateien niemals direkt im Verzeichnis res/. Dies führt zu einem Compilerfehler.

Die Ressourcen, die Sie in den in Tabelle 1 definierten Unterverzeichnissen speichern, sind Ihre Standardressourcen. Diese Ressourcen definieren das Standarddesign und die Standardinhalte für Ihre App. Für verschiedene Arten von Android-Geräten sind jedoch möglicherweise unterschiedliche Arten von Ressourcen erforderlich.

Sie können beispielsweise verschiedene String-Ressourcen bereitstellen, mit denen der Text in Ihrer Benutzeroberfläche basierend auf der Spracheinstellung des Geräts übersetzt wird.

Hinweis:In Compose werden UIs, Animationen und zustandsgesteuerte Farben in Kotlin deklariert. Die Verzeichnisse layout/, menu/, anim/, animator/ und color/ sind für moderne Apps daher nicht mehr erforderlich. Weitere Informationen finden Sie unter Animationen in Compose und Anatomie eines Designs in Compose.

Alternative Ressourcen bereitstellen

Die meisten Apps bieten alternative Ressourcen zur Unterstützung bestimmter Gerätekonfigurationen. Fügen Sie beispielsweise alternative Drawable-Ressourcen für verschiedene Bildschirmdichten und alternative String-Ressourcen für verschiedene Sprachen hinzu. Zur Laufzeit erkennt Android die aktuelle Gerätekonfiguration und lädt die entsprechenden Ressourcen für Ihre App.

So geben Sie konfigurationsspezifische Alternativen für eine Reihe von Ressourcen an:

  1. Erstellen Sie in res/ ein neues Verzeichnis mit dem Namen <resources_name>-<qualifier>.
    • <resources_name> ist der Verzeichnisname der entsprechenden Standardressourcen (in Tabelle 1 definiert).
    • <qualifier> ist ein Name, der eine einzelne Konfiguration angibt, für die diese Ressourcen verwendet werden sollen (siehe Tabelle 2).

    Sie können mehrere <qualifier> anhängen. Trennen Sie die einzelnen Elemente durch einen Bindestrich.

    Achtung:Wenn Sie mehrere Qualifizierer anhängen, müssen Sie sie in derselben Reihenfolge wie in Tabelle 2 auflisten. Wenn die Qualifizierer in der falschen Reihenfolge angegeben sind, werden die Ressourcen ignoriert.

  2. Speichern Sie die entsprechenden alternativen Ressourcen in diesem neuen Verzeichnis. Die Ressourcendateien müssen genau wie die Standardressourcendateien benannt sein.

Hier sind einige Standard- und alternative Ressourcen:

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

Der Qualifizierer hdpi gibt an, dass die Ressourcen in diesem Verzeichnis für Geräte mit einem Bildschirm mit hoher Dichte bestimmt sind. Die Bilder in diesen Drawable-Verzeichnissen sind für bestimmte Bildschirmdichten optimiert, die Dateinamen sind jedoch identisch. So bleibt die Ressourcen-ID, mit der Sie auf das icon.png- oder background.png-Bild verweisen, immer gleich. Android wählt die Version jeder Ressource aus, die am besten zum aktuellen Gerät passt. Dazu werden die Gerätekonfigurationsinformationen mit den Qualifizierern im Namen des Ressourcenverzeichnisses verglichen.

Achtung:Wenn Sie eine alternative Ressource definieren, müssen Sie sie auch in einer Standardkonfiguration definieren. Andernfalls können bei Ihrer App Laufzeitfehler auftreten, wenn das Gerät eine Konfiguration ändert. Wenn Sie beispielsweise einen String nur in values-en und nicht in values hinzufügen, kann in Ihrer App eine Resource Not Found-Ausnahme auftreten, wenn der Nutzer die Standardsystemsprache ändert.

In Tabelle 2 sind die Konfigurationsqualifizierer nach Vorrang geordnet aufgeführt. Sie können einem Verzeichnisnamen mehrere Qualifizierer hinzufügen, indem Sie die einzelnen Qualifizierer durch einen Bindestrich trennen. Wenn Sie mehrere Qualifier für ein Verzeichnis der Ressourcen verwenden, müssen Sie sie in der Reihenfolge, in der sie in der Tabelle aufgeführt sind, dem Verzeichnisnamen hinzufügen.

Tabelle 2 Namen von Konfigurationskennzeichnern.

Konfiguration Qualifierwerte Beschreibung
MCC und MNC Beispiele:
mcc310
mcc310-mnc004
mcc208-mnc00

Der Ländercode des Mobilgeräts (Mobile Country Code, MCC), optional gefolgt vom Netzwerkcode des Mobilgeräts (Mobile Network Code, MNC) der SIM-Karte im Gerät. Beispiele: mcc310 steht für die USA bei einem beliebigen Mobilfunkanbieter, mcc310-mnc004 für die USA bei Verizon und mcc208-mnc00 für Frankreich bei Orange.

Wenn das Gerät eine Funkverbindung verwendet (d. h. ein GSM-Telefon ist), stammen die MCC- und MNC-Werte von der SIM-Karte.

Sie können auch nur den MCC verwenden, um beispielsweise länderspezifische rechtliche Ressourcen in Ihre App aufzunehmen. Wenn Sie nur anhand der Sprache angeben müssen, verwenden Sie stattdessen den Qualifikator Sprache, Schriftsystem (optional) und Region (optional). Wenn Sie den Qualifikator „MCC“ und „MNC“ verwenden, gehen Sie vorsichtig vor und testen Sie, ob er wie erwartet funktioniert.

Sehen Sie sich auch die Konfigurationsfelder mcc und mnc an, die den aktuellen Mobile Country Code und die Mobilfunknetzkennzahl angeben.

Sprache, Schriftart (optional) und Region (optional) Beispiele:
en
fr
en-rUS
fr-rFR
fr-rCA
b+en
b+en+US
b+es+419
b+zh+Hant
b+sr+Latn+RS

Die Sprache wird durch einen zweistelligen ISO 639-1-Sprachcode definiert, dem optional ein zweistelliger ISO 3166-1-Alpha-2-Regionscode (vorangestellt durch Kleinbuchstaben r) folgen kann.

Bei den Codes wird nicht zwischen Groß- und Kleinschreibung unterschieden. Das Präfix r wird verwendet, um den Regionsabschnitt zu unterscheiden. Sie können keine Region allein angeben.

Mit Android 7.0 (API-Level 24) wurde die Unterstützung für BCP 47-Sprachtags eingeführt, mit denen Sie sprach- und regionsspezifische Ressourcen qualifizieren können. Ein Sprach-Tag besteht aus einer Sequenz von einem oder mehreren Untertags, die jeweils den Bereich der durch das gesamte Tag identifizierten Sprache verfeinern oder eingrenzen. Weitere Informationen zu Sprach-Tags finden Sie unter Tags zur Identifizierung von Sprachen.

Um einen BCP 47-Sprachcode zu verwenden, hängen Sie b+ und einen aus zwei Buchstaben bestehenden ISO 639-1-Sprachcode aneinander an. Optional können Sie weitere durch + getrennte Untertags hinzufügen.

Das Sprach-Tag kann sich im Laufe der Lebensdauer Ihrer App ändern, wenn Nutzer die Sprache in den Systemeinstellungen ändern. Informationen dazu, wie sich das auf Ihre App zur Laufzeit auswirken kann, finden Sie unter Konfigurationsänderungen verarbeiten.

Eine vollständige Anleitung zur Lokalisierung Ihrer App für andere Sprachen finden Sie unter App lokalisieren.

Sehen Sie sich auch die Methode getLocales an, die die definierte Liste der Gebietsschemas enthält. Diese Liste enthält das primäre Gebietsschema.

Genus masculine
feminine
neuter

Das grammatische Geschlecht des Nutzers. Wird für Sprachen mit grammatischem Geschlecht verwendet.

Wenn Sie beispielsweise verschiedene Ressourcen für französischsprachige Nutzer bereitstellen müssen, können Sie Verzeichnisse wie die folgenden verwenden:

res/
  values-fr/
    strings.xml (Standardstrings mit nicht angegebenem Geschlecht)
  values-fr-masculine/
    strings.xml (Strings mit männlichem Geschlecht)
  values-fr-feminine/
    strings.xml (Strings mit weiblichem Geschlecht)
  values-fr-neuter/
    strings.xml (Strings mit neutralem Geschlecht)

Weitere Informationen finden Sie unter UI Ihrer App mit grammatischem Geschlecht personalisieren.

Weitere Informationen finden Sie unter der getGrammaticalGender-Konfigurationsmethode, die das grammatische Geschlecht angibt.

In API-Level 34 hinzugefügt.

Breite Farbskala widecg
nowidecg
  • widecg: Displays mit einem breiten Farbraum wie Display P3 oder AdobeRGB
  • nowidecg: Displays mit einem schmalen Farbgamut wie sRGB

In API-Level 26 hinzugefügt.

Weitere Informationen finden Sie unter isScreenWideColorGamut-Konfigurationsmethode, in der angegeben wird, ob der Bildschirm einen großen Farbraum hat.

High Dynamic Range (HDR) highdr
lowdr
  • highdr: Displays mit einem hohen Dynamikbereich
  • lowdr: Displays mit einem niedrigen/standardmäßigen Dynamikbereich

In API-Level 26 hinzugefügt.

Weitere Informationen finden Sie unter isScreenHdr-Konfigurationsmethode. Dort wird angegeben, ob der Bildschirm HDR-fähig ist.

UI-Modus car
desk
television
appliance
watch
vrheadset
  • car: Das Gerät wird in einem Kfz-Dock angezeigt.
  • desk: Das Gerät wird in einem Dock angezeigt.
  • television: Das Gerät wird auf einem Fernseher angezeigt und bietet eine „Ten-Foot“-Erfahrung, bei der die Benutzeroberfläche auf einem großen Bildschirm angezeigt wird, von dem der Nutzer weit entfernt ist. Die Interaktion erfolgt hauptsächlich über das Steuerkreuz oder andere Methoden ohne Zeiger.
  • appliance: Das Gerät dient als Haushaltsgerät ohne Display.
  • watch: Das Gerät hat ein Display und wird am Handgelenk getragen.
  • vrheadset: Das Gerät wird in einem Virtual-Reality-Headset angezeigt.

Hinzugefügt in API-Level 8; Fernseher in API 13; Haushaltsgerät in API 16; Smartwatch in API 20; VR-Headset in API 26.

Informationen dazu, wie Ihre App reagieren kann, wenn das Gerät in ein Dock eingesetzt oder aus einem Dock entfernt wird, finden Sie unter Dockingstatus und ‑typ ermitteln und überwachen.

Dies kann sich im Laufe der Lebensdauer Ihrer App ändern, wenn der Nutzer das Gerät in eine Dockingstation stellt. Einige dieser Modi lassen sich über UiModeManager aktivieren oder deaktivieren. Informationen dazu, wie sich das auf Ihre App während der Laufzeit auswirkt, finden Sie unter Konfigurationsänderungen verarbeiten.

Nachtmodus night
notnight
  • night: Nacht
  • notnight: Tageszeit

In API-Level 8 hinzugefügt.

Das kann sich im Laufe der Lebensdauer Ihrer App ändern, wenn der Nachtmodus im Automatikmodus (Standard) belassen wird. In diesem Fall ändert sich der Modus je nach Tageszeit. Sie können diesen Modus mit UiModeManager aktivieren oder deaktivieren. Informationen dazu, wie sich das auf Ihre App während der Laufzeit auswirkt, finden Sie unter Konfigurationsänderungen verarbeiten.

Pixeldichte des Displays (dpi) ldpi
mdpi
hdpi
xhdpi
xxhdpi
xxxhdpi
nodpi
tvdpi
anydpi
nnndpi
  • ldpi: Bildschirme mit niedriger Dichte, ca. 120 dpi.
  • mdpi: Bildschirme mit mittlerer Dichte (auf herkömmlichen HVGA-Bildschirmen); etwa 160 dpi.
  • hdpi: Bildschirme mit hoher Dichte, ca. 240 dpi.
  • xhdpi: Bildschirme mit besonders hoher Dichte, etwa 320 dpi. Hinzugefügt in API-Level 8.
  • xxhdpi: Bildschirme mit besonders hoher Dichte, ca. 480 dpi. In API-Level 16 hinzugefügt.
  • xxxhdpi: Für die Verwendung mit extrem hoher Dichte (nur Launcher-Symbol – siehe Verschiedene Pixeldichten unterstützen); etwa 640 dpi. In API-Level 18 hinzugefügt.
  • nodpi: Wird für Bitmap-Ressourcen verwendet, die nicht an die Gerätedichte angepasst werden sollen.
  • tvdpi: Bildschirme mit einer Auflösung zwischen „mdpi“ und „hdpi“, etwa 213 dpi. Dies wird nicht als „primäre“ Dichtegruppe betrachtet. Es ist hauptsächlich für Fernseher mit 720p gedacht und wird von den meisten Apps nicht benötigt. Verwende für 1080p-TV-Panels xhdpi und für 4K-TV-Panels xxxhdpi. Hinzugefügt in API-Level 13.
  • anydpi: Entspricht allen Bildschirmdichten und hat Vorrang vor anderen Qualifizierern. Dies ist nützlich für Vektordrawables. In API-Level 21 hinzugefügt.
  • nnndpi: Wird verwendet, um nicht standardmäßige Dichten darzustellen, wobei nnn eine positive Ganzzahl für die Bildschirmdichte ist. In den meisten Fällen wird dies nicht verwendet. Durch die Verwendung von Standarddichte-Buckets wird der Aufwand für die Unterstützung der verschiedenen Bildschirmdichten auf dem Markt erheblich reduziert.

Zwischen den sechs primären Dichten (ohne die tvdpi-Dichte) besteht ein Skalierungsverhältnis von 3:4:6:8:12:16. Eine 9 × 9-Bitmap in ldpi ist also 12 × 12 in mdpi, 18 × 18 in hdpi, 24 × 24 in xhdpi usw.

Hinweis:Die Verwendung eines Pixeldichte-Kennzeichners bedeutet nicht, dass die Ressourcen nur für Bildschirme mit dieser Dichte bestimmt sind. Wenn Sie keine alternativen Ressourcen mit Qualifizierern bereitstellen, die besser zur aktuellen Gerätekonfiguration passen, verwendet das System die Ressourcen, die die beste Übereinstimmung aufweisen.

Weitere Informationen zum Umgang mit verschiedenen Bildschirmdichten und dazu, wie Android Ihre Bitmaps an die aktuelle Dichte anpassen kann, finden Sie unter Bildschirmkompatibilität – Übersicht.

Touchscreentyp notouch
finger
  • notouch: Das Gerät hat keinen Touchscreen.
  • finger: Das Gerät hat einen Touchscreen, der durch direkte Interaktion mit dem Finger des Nutzers bedient werden soll.

Weitere Informationen finden Sie auch im Konfigurationsfeld touchscreen, das den Typ des Touchscreens auf dem Gerät angibt.

Verfügbarkeit der Tastatur keysexposed
keyshidden
keyssoft
  • keysexposed: Auf dem Gerät ist eine Tastatur verfügbar. Wenn auf dem Gerät eine Softwaretastatur aktiviert ist (was wahrscheinlich ist), wird diese auch dann verwendet, wenn die Hardwaretastatur dem Nutzer nicht angezeigt wird oder das Gerät keine Hardwaretastatur hat. Wenn keine Softwaretastatur bereitgestellt oder sie deaktiviert ist, wird diese nur verwendet, wenn eine Hardwaretastatur verfügbar ist.
  • keyshidden: Das Gerät hat eine Hardwaretastatur, die jedoch ausgeblendet ist und auf dem Gerät keine Softwaretastatur aktiviert ist.
  • keyssoft: Auf dem Gerät ist eine Softwaretastatur aktiviert, unabhängig davon, ob sie sichtbar ist oder nicht.

Wenn Sie keysexposed-Ressourcen, aber keine keyssoft-Ressourcen bereitstellen, verwendet das System die keysexposed-Ressourcen unabhängig davon, ob eine Tastatur sichtbar ist, sofern das System eine Softwaretastatur aktiviert hat.

Das kann sich im Laufe der Lebensdauer Ihrer App ändern, wenn der Nutzer eine Hardwaretastatur öffnet. Informationen dazu, wie sich das auf Ihre App während der Laufzeit auswirkt, finden Sie unter Konfigurationsänderungen verarbeiten.

Sehen Sie sich auch die Konfigurationsfelder hardKeyboardHidden und keyboardHidden an, die die Sichtbarkeit einer Hardwaretastatur bzw. einer beliebigen Tastatur (einschließlich Software) angeben.

Primäre Texteingabemethode nokeys
qwerty
12key
  • nokeys: Das Gerät hat keine Hardwaretasten für die Texteingabe.
  • qwerty: Das Gerät hat eine Hardware-QWERTY-Tastatur, unabhängig davon, ob sie für den Nutzer sichtbar ist.
  • 12key: Das Gerät hat eine Hardwaretastatur mit 12 Tasten, unabhängig davon, ob sie für den Nutzer sichtbar ist.

Sehen Sie sich auch das Konfigurationsfeld keyboard an, das die primäre verfügbare Methode für die Texteingabe angibt.

Plattformversion (API-Level) Beispiele:
v3
v4
v7
usw.

Das vom Gerät unterstützte API-Level. Beispiel: v1 für API-Level 1 (Geräte mit Android 1.0 oder höher) und v4 für API-Level 4 (Geräte mit Android 1.6 oder höher). Weitere Informationen zu diesen Werten finden Sie im Dokument Android API-Levels.

Hinweis:Nicht alle Android-Versionen unterstützen alle Qualifizierer. Wenn Sie einen neuen Qualifier verwenden, wird der Qualifier für die Plattformversion implizit hinzugefügt, damit er von älteren Geräten ignoriert werden kann. Um Probleme zu vermeiden, sollten Sie immer eine Reihe von Standardressourcen (Ressourcen ohne Qualifizierer) angeben. Weitere Informationen finden Sie im Abschnitt Beste Gerätekompatibilität mit Ressourcen bereitstellen.

In Compose-Apps sind keine Konfigurationsqualifizierer für Layout und Dimensionen erforderlich. Solange sie noch vorhanden sind, werden sie aus Tabelle 2 ausgeschlossen. Dazu gehören: Layoutrichtung, kleinste Breite, verfügbare Breite, verfügbare Höhe, Bildschirmgröße, Bildschirmseitenverhältnis, runder Bildschirm und Bildschirmausrichtung. Die vollständige Tabelle der Konfigurationsqualifizierer in der Reihenfolge ihrer Priorität finden Sie unter App-Ressourcen – Übersicht (Ansichten).

Regeln für Namen von Qualifizierern

Hier sind einige Regeln für die Verwendung von Konfigurationsqualifizierernamen:

  • Sie können mehrere Qualifizierer für eine Gruppe von Ressourcen angeben, die durch Bindestriche getrennt sind. drawable-en-rUS-night gilt beispielsweise für Geräte mit US-Englisch im Nachtmodus.
  • Die Qualifizierer müssen in der Reihenfolge aufgeführt sein, die in Tabelle 2 angegeben ist.
    • Falsch: drawable-hdpi-night/
    • Richtig: drawable-night-hdpi/
  • Alternative Ressourcenverzeichnisse können nicht verschachtelt werden. res/drawable/drawable-en/ ist beispielsweise nicht zulässig.
  • Bei den Werten wird die Groß- und Kleinschreibung nicht berücksichtigt. Der Ressourcencompiler konvertiert Verzeichnisnamen vor der Verarbeitung in Kleinbuchstaben, um Probleme in Dateisystemen zu vermeiden, bei denen die Groß-/Kleinschreibung keine Rolle spielt. Die Großschreibung in den Namen dient nur der Lesbarkeit.
  • Es wird nur ein Wert für jeden Qualifizierertyp unterstützt. Wenn Sie beispielsweise dieselben Drawable-Dateien für Spanien und Frankreich verwenden möchten, dürfen Sie kein Verzeichnis mit dem Namen drawable-es-fr/ haben. Stattdessen benötigen Sie zwei Ressourcenverzeichnisse, z. B. drawable-es/ und drawable-fr/, die die entsprechenden Dateien enthalten.

Nachdem Sie alternative Ressourcen in Verzeichnissen mit diesen Qualifizierern gespeichert haben, wendet Android die Ressourcen in Ihrer App automatisch basierend auf der aktuellen Gerätekonfiguration an. Jedes Mal, wenn eine Ressource angefordert wird, sucht Android nach alternativen Ressourcenverzeichnissen, die die angeforderte Ressourcendatei enthalten, und ermittelt dann die am besten passende Ressource.

Wenn es keine alternativen Ressourcen gibt, die einer bestimmten Gerätekonfiguration entsprechen, verwendet Android die entsprechenden Standardressourcen – die Ressourcen für einen bestimmten Ressourcentyp, die keinen Konfigurationsqualifizierer enthalten.

Aliasressourcen erstellen

Wenn Sie eine Ressource haben, die Sie für mehr als eine Gerätekonfiguration verwenden möchten, aber nicht als Standardressource bereitstellen möchten, müssen Sie sie nicht in mehr als einem alternativen Ressourcenverzeichnis ablegen. Stattdessen können Sie eine alternative Ressource erstellen, die als Alias für eine Ressource dient, die in Ihrem Standardressourcenverzeichnis gespeichert ist.

Drawables

Angenommen, Sie haben ein App-Symbol, icon.png, und benötigen eine eindeutige Version davon für verschiedene Sprachen. Für die beiden Gebietsschemas „Englisch (Kanada)“ und „Französisch (Kanada)“ muss jedoch dieselbe Version verwendet werden. Sie müssen dasselbe Bild nicht für Englisch-Kanada und Französisch-Kanada in das Verzeichnis der Ressourcen kopieren. Stattdessen können Sie das Bild, das für beide verwendet wird, unter einem beliebigen Namen außer icon.png speichern, z. B. icon_ca.png, und es in das Standardverzeichnis res/drawable/ einfügen. Erstellen Sie dann in res/drawable-en-rCA/ und res/drawable-fr-rCA/ eine icon.xml-Datei, die mit dem Element <bitmap> auf die icon_ca.png-Ressource verweist.

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

So können Sie nur eine Version der PNG-Datei und zwei kleine XML-Dateien speichern, die darauf verweisen. Anschließend können Sie painterResource(R.drawable.icon) verwenden. Das System wählt dann die entsprechende Datei aus, sobald das Gebietsschema erkannt wird.

Strings und andere einfache Werte

Wenn Sie einen Alias für einen vorhandenen String erstellen möchten, verwenden Sie die Ressourcen-ID des gewünschten Strings als Wert für den neuen String:

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

Die Ressource R.string.hi ist jetzt ein Alias für R.string.hello.

Andere einfache Werte funktionieren auf dieselbe Weise, z. B. Farben:

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

Auf App-Ressourcen zugreifen

Wenn Sie eine Ressource in Ihrer Anwendung bereitgestellt haben, können Sie sie anwenden, indem Sie auf ihre Ressourcen-ID verweisen. Alle Ressourcen-IDs sind in der Klasse R Ihres Projekts definiert, die vom Tool aapt automatisch generiert wird.

Wenn Ihre Anwendung kompiliert wird, generiert aapt die Klasse R, die Ressourcen-IDs für alle Ressourcen in Ihrem res/-Verzeichnis enthält. Für jeden Ressourcentyp gibt es eine R-Unterklasse, z. B. R.drawable für alle Drawables. Für jede Ressource dieses Typs gibt es eine statische Ganzzahl, z. B. R.drawable.icon. Diese Ganzzahl ist die Ressourcen-ID, mit der Sie Ihre Ressource abrufen können.

Obwohl die Ressourcen-IDs in der Klasse R angegeben werden, müssen Sie dort nicht nach einer Ressourcen-ID suchen. Eine Ressourcen-ID besteht immer aus Folgendem:

  • Der Ressourcentyp: Jede Ressource wird in einen „Typ“ gruppiert, z. B. string oder drawable.
  • Der Ressourcenname, also der Dateiname ohne die Erweiterung.

Auf Ressourcen in Compose zugreifen

Jetpack Compose bietet integrierte, composable-fähige Funktionen für den sicheren Zugriff auf Ressourcen.

  • Strings:
    stringResource(id = R.string.hello)
  • Drawables:
    painterResource(id = R.drawable.my_icon)

Auf Ressourcen in Nicht-UI-Code zugreifen

Wenn Sie auf Ressourcen außerhalb Ihrer UI-Hierarchie zugreifen müssen, z. B. in einem ViewModel, einem Repository oder einem System-Service, können Sie sie mit dem Context auflösen.

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

Sie können auch einzelne Ressourcen mit Methoden in Resources abrufen. Eine Instanz davon erhalten Sie mit getResources.

Syntax

So referenzieren Sie eine Ressource im Code:

[<package_name>.]R.<resource_type>.<resource_name>
  • <package_name> ist der Name des Pakets, in dem sich die Ressource befindet. Dies ist nicht erforderlich, wenn Sie auf Ressourcen aus Ihrem eigenen Paket verweisen.
  • <resource_type> ist die R-Unterklasse für den Ressourcentyp.
  • <resource_name> ist entweder der Ressourcen-Dateiname ohne die Erweiterung oder der android:name-Attributwert im XML-Element für einfache Werte.

Weitere Informationen zu den einzelnen Ressourcentypen und dazu, wie Sie darauf verweisen, finden Sie unter Ressourcen in Compose.

Auf Originaldateien zugreifen

Es kann vorkommen, dass Sie auf Ihre Originaldateien und ‑verzeichnisse zugreifen müssen. Wenn das der Fall ist, können Sie Ihre Dateien nicht in res/ speichern, da Ressourcen in res/ nur über die Ressourcen-ID gelesen werden können. Stattdessen können Sie Ihre Ressourcen im Verzeichnis assets/ speichern.

Dateien, die im Verzeichnis assets/ gespeichert sind, erhalten keine Ressourcen-ID. Sie können also nicht über die Klasse R oder über XML-Ressourcen darauf verweisen. Stattdessen können Sie Dateien im Verzeichnis assets/ wie in einem normalen Dateisystem abfragen und Rohdaten mit AssetManager lesen.

Wenn Sie jedoch nur Rohdaten (z. B. eine Video- oder Audiodatei) lesen müssen, speichern Sie die Datei im Verzeichnis res/raw/ und lesen Sie einen Stream von Byte mit openRawResource.

Auf Plattformressourcen zugreifen

Android enthält eine Reihe von Standardressourcen wie Systemstile und ‑designs. Um darauf zuzugreifen, müssen Sie Ihren Ressourcenverweis mit der Paketklasse android qualifizieren. Beispiel: painterResource(android.R.drawable.ic_menu_info_details).

Beste Gerätekompatibilität mit Ressourcen

Damit Ihre App mehrere Gerätekonfigurationen unterstützt, ist es sehr wichtig, dass Sie immer Standardressourcen für jeden Ressourcentyp bereitstellen, den Ihre App verwendet.

Wenn Ihre App beispielsweise mehrere Sprachen unterstützt, fügen Sie immer ein values/-Verzeichnis (in dem Ihre Strings gespeichert sind) ohne Sprach- und Regionsqualifizierer ein. Wenn Sie stattdessen alle Ihre String-Dateien in Verzeichnisse mit einem Sprach- und Regionsqualifizierer einfügen, stürzt Ihre App ab, wenn sie auf einem Gerät ausgeführt wird, das auf eine Sprache eingestellt ist, die von Ihren Strings nicht unterstützt wird.

Solange Sie Standardressourcen für values/ bereitstellen, funktioniert Ihre App ordnungsgemäß, auch wenn der Nutzer die Sprache nicht versteht, in der sie präsentiert wird. Besser als ein Absturz.

Die Bereitstellung von Standardressourcen ist nicht nur wichtig, weil Ihre App möglicherweise in einer Konfiguration ausgeführt wird, die Sie nicht erwartet haben, sondern auch, weil in neuen Android-Versionen manchmal Konfigurationsqualifizierer hinzugefügt werden, die von niedrigeren Versionen nicht unterstützt werden. Wenn Sie einen neuen Ressourcenqualifizierer verwenden, aber die Codekompatibilität mit niedrigeren Android-Versionen beibehalten, stürzt Ihre App ab, wenn sie auf einer niedrigeren Android-Version ausgeführt wird, sofern Sie keine Standardressourcen bereitstellen. Das liegt daran, dass die Ressourcen, die mit dem neuen Qualifizierer benannt sind, nicht verwendet werden können.

Wenn Ihr minSdkVersion beispielsweise auf 4 festgelegt ist und Sie alle Ihre Drawable-Ressourcen mit dem Nachtmodus (night oder notnight, die in API-Level 8 hinzugefügt wurden) qualifizieren, kann ein Gerät mit API-Level 4 nicht auf Ihre Drawable-Ressourcen zugreifen und stürzt ab. In diesem Fall sollten notnight wahrscheinlich Ihre Standardressourcen sein. Schließen Sie diesen Qualifier also aus und legen Sie Ihre Drawableressourcen entweder in drawable/ oder drawable-night/ ab.

Kurz gesagt: Um die beste Gerätekompatibilität zu gewährleisten, sollten Sie immer Standardressourcen für die Ressourcen bereitstellen, die Ihre App für eine ordnungsgemäße Funktion benötigt. Erstellen Sie dann mit Konfigurationsqualifizierern alternative Ressourcen für bestimmte Gerätekonfigurationen.

Es gibt eine Ausnahme von dieser Regel: Wenn die minSdkVersion Ihrer App 4 oder höher ist, benötigen Sie keine Standard-Drawable-Ressourcen, wenn Sie alternative Drawable-Ressourcen mit dem Qualifikator Bildschirmdichte bereitstellen. Auch ohne Standard-Drawable-Ressourcen kann Android die beste Übereinstimmung unter den alternativen Bildschirmdichten finden und die Bitmaps nach Bedarf skalieren. Für eine optimale Darstellung auf allen Gerätetypen sollten Sie jedoch alternative Drawables für alle drei Dichtetypen bereitstellen.

So findet Android die am besten passende Ressource

Wenn Sie eine Ressource anfordern, für die Sie Alternativen angeben, wählt Android zur Laufzeit die zu verwendende alternative Ressource aus, abhängig von der aktuellen Gerätekonfiguration. Um zu veranschaulichen, wie Android eine alternative Ressource auswählt, nehmen wir an, dass die folgenden Drawable-Verzeichnisse jeweils verschiedene Versionen derselben Bilder enthalten:

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

Angenommen, die Gerätekonfiguration ist wie folgt:

Gebietsschema = en-GB
Nachtmodus = night
Pixeldichte des Displays = hdpi
Touchscreen-Typ = notouch
Primäre Methode zur Texteingabe = 12key

Durch den Vergleich der Gerätekonfiguration mit den verfügbaren alternativen Ressourcen wählt Android Drawables aus drawable-en-night aus.

Das System trifft seine Entscheidung darüber, welche Ressourcen verwendet werden sollen, anhand der folgenden Logik:

Abbildung 2: Flussdiagramm, das zeigt, wie Android die am besten passende Ressource findet.

  1. Entfernen Sie Ressourcendateien, die der Gerätekonfiguration widersprechen.

    Das Verzeichnis drawable-fr-rCA/ wird entfernt, da es der Sprache en-GB widerspricht.

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

    Ausnahme:Die Pixeldichte des Displays ist die einzige Qualifizierungsvariable, die nicht aufgrund eines Widerspruchs entfernt wird. Obwohl die Bildschirmdichte des Geräts „hdpi“ ist, wird drawable-night-ldpi/ nicht entfernt, da zu diesem Zeitpunkt jede Bildschirmdichte als Übereinstimmung betrachtet wird. Weitere Informationen finden Sie unter Bildschirmkompatibilität – Übersicht.

  2. Suchen Sie in der Liste (Tabelle 2) nach dem Qualifikator mit der nächsthöheren Priorität. Beginnen Sie mit dem Verwaltungskonto.
  3. Ist dieser Qualifier in einem der Ressourcenverzeichnisse enthalten?
    • Falls nicht, kehren Sie zu Schritt 2 zurück und sehen Sie sich den nächsten Qualifikator an. In diesem Beispiel lautet die Antwort „Nein“, bis der Sprachqualifikator erreicht ist.
    • Wenn ja, fahren Sie mit Schritt 4 fort.
  4. Entfernen Sie Ressourcenverzeichnisse, die diesen Qualifier nicht enthalten. Als Nächstes werden alle Verzeichnisse ohne Sprachqualifizierer entfernt:
    drawable/
    drawable-en/
    drawable-en-night/
    drawable-en-notouch-12key/
    drawable-night-ldpi/
    drawable-night-notouch-12key/
    

    Ausnahme:Wenn der betreffende Qualifier die Pixeldichte des Displays ist, wählt Android die Option aus, die der Displaydichte des Geräts am ehesten entspricht. Im Allgemeinen wird in Android ein größeres Originalbild lieber verkleinert als ein kleineres Originalbild vergrößert. Weitere Informationen finden Sie unter Bildschirmkompatibilität – Übersicht.

  5. Wiederholen Sie die Schritte 2, 3 und 4, bis nur noch ein Verzeichnis übrig ist. In diesem Beispiel ist der Nachtmodus der nächste Qualifikator, für den es Übereinstimmungen gibt. Ressourcen, in denen der Nachtmodus nicht angegeben ist, werden also entfernt:
    drawable-en/
    drawable-en-night/
    drawable-en-notouch-12key/
    

    Das verbleibende Verzeichnis ist drawable-en-night.

Dieses Verfahren wird zwar für jede angeforderte Ressource ausgeführt, das System optimiert jedoch einige Aspekte. Eine solche Optimierung besteht darin, dass alternative Ressourcen, die niemals übereinstimmen können, eliminiert werden, sobald die Gerätekonfiguration bekannt ist. Wenn die Konfigurationssprache beispielsweise Englisch ist, wird jedes Verzeichnis der Ressourcen, für das eine Sprachkennzeichnung auf eine andere Sprache als Englisch festgelegt ist, nie in den Pool der geprüften Ressourcen aufgenommen. Ein Verzeichnis der Ressourcen ohne die Sprachkennzeichnung wird jedoch weiterhin berücksichtigt.

Wenn das System Ressourcen anhand der Qualifizierer für die Bildschirmgröße auswählt, werden Ressourcen verwendet, die für einen kleineren Bildschirm als den aktuellen Bildschirm entwickelt wurden, wenn es keine Ressourcen gibt, die besser passen. Auf einem großen Display werden beispielsweise bei Bedarf Ressourcen für Displays in normaler Größe verwendet.

Wenn die einzigen verfügbaren Ressourcen jedoch größer als der aktuelle Bildschirm sind, werden sie vom System nicht verwendet und Ihre App stürzt ab, wenn keine anderen Ressourcen der Gerätekonfiguration entsprechen. Das ist beispielsweise der Fall, wenn alle Layoutressourcen mit dem Qualifikator xlarge getaggt sind, das Gerät aber einen Bildschirm normaler Größe hat.

Hinweis:Die Priorität des Qualifizierers (in Tabelle 2) ist wichtiger als die Anzahl der Qualifizierer, die genau mit dem Gerät übereinstimmen. Im vorherigen Beispiel enthält die letzte Auswahl in Schritt 4 drei Qualifizierer, die genau mit dem Gerät übereinstimmen (Nachtmodus, Touchscreen-Typ und Eingabemethode), während drawable-en nur einen Parameter hat, der übereinstimmt (Sprache). Die Sprache hat jedoch eine höhere Priorität als diese anderen Qualifizierer, sodass drawable-night-notouch-12key ausgeschlossen wird.

Zusätzliche Ressourcen

Weitere Informationen zu App-Ressourcen finden Sie in den folgenden zusätzlichen Ressourcen:

Dokumentation

Inhalte ansehen