Freigeben über

Laden von Bildern und Ressourcen mit Anpassung an Skalierung, Design, hohen Kontrast usw.

  • Artikel

Ihre App kann Bildressourcendateien (oder andere Ressourcendateien) laden, die auf den Anzeigeskalierungsfaktor, das Design, den hohen Kontrast und andere Laufzeitkontexte zugeschnitten sind. Auf diese Bilder kann aus imperativem Code oder aus XAML-Markup verwiesen werden, z. B. als Source-Eigenschaft eines Bilds. Sie können auch in der Quelldatei des App-Paketmanifests (der Package.appxmanifest Datei) angezeigt werden, z. B. als Wert für das App-Symbol auf der Registerkarte "Visuelle Objekte" des Manifest-Designers von Visual Studio oder auf Ihren Kacheln und Popups. Wenn Sie Qualifizierer in den Dateinamen Ihrer Bilder verwenden und sie optional mithilfe eines ResourceContext dynamisch laden, können Sie dazu führen, dass die am besten geeignete Bilddatei geladen wird, die den Laufzeiteinstellungen des Benutzers für Anzeigeskala, Design, hohen Kontrast, Sprache und andere Kontexte am besten entspricht.

Eine Bildressource ist in einer Bildressourcendatei enthalten. Sie können sich das Bild auch als Ressource und die Datei vorstellen, die es als Objektdatei enthält; und Sie können diese Arten von Ressourcendateien im Ordner "\Assets" Ihres Projekts finden. Hintergrundinformationen zur Verwendung von Qualifizierern in den Namen Ihrer Bildressourcendateien finden Sie unter Anpassen der Ressourcen für Sprache, Skalierung und andere Qualifizierer.

Einige allgemeine Qualifizierer für Bilder sind:

Qualifizieren einer Bildressource für Skalierung, Design und Kontrast

Der Standardwert für den scale Qualifizierer lautet scale-100. Diese beiden Varianten sind also gleichwertig (beide stellen ein Bild im Maßstab 100 oder Skalierungsfaktor 1 bereit).

\Assets\Images\logo.png
\Assets\Images\logo.scale-100.png

Sie können Qualifizierer in Ordnernamen anstelle von Dateinamen verwenden. Dies ist eine bessere Strategie, wenn Sie mehrere Ressourcendateien pro Qualifizierer haben. Zur Veranschaulichung entsprechen diese beiden Varianten den beiden oben genannten Varianten.

\Assets\Images\logo.png
\Assets\Images\scale-100\logo.png

Das nächste Beispiel zeigt, wie Sie Varianten einer Bildressource ( benannt /Assets/Images/logo.png) für unterschiedliche Einstellungen von Anzeigeskala, Design und hohem Kontrast bereitstellen können. In diesem Beispiel wird die Ordnerbenennung verwendet.

\Assets\Images\contrast-standard\theme-dark
    \scale-100\logo.png
    \scale-200\logo.png
\Assets\Images\contrast-standard\theme-light
    \scale-100\logo.png
    \scale-200\logo.png
\Assets\Images\contrast-high
    \scale-100\logo.png
    \scale-200\logo.png

Verweisen auf ein Bild oder eine andere Ressource aus XAML-Markup und Code

Der Name oder Bezeichner einer Bildressource ist sein Pfad und Dateiname mit allen entfernten Qualifizierern. Wenn Sie Ordner und/oder Dateien wie in einem der Beispiele im vorherigen Abschnitt benennen, verfügen Sie über eine einzelne Bildressource und ihren Namen (als absoluter Pfad)./Assets/Images/logo.png Hier erfahren Sie, wie Sie diesen Namen im XAML-Markup verwenden.

<Image x:Name="myXAMLImageElement" Source="ms-appx:///Assets/Images/logo.png"/>

Beachten Sie, dass Sie das ms-appx URI-Schema verwenden, da Sie auf eine Datei verweisen, die aus dem Paket Ihrer App stammt. Siehe URI-Schemas in der UWP-Dokumentation. So verweisen Sie im imperativen Code auf dieselbe Bildressource.

this.myXAMLImageElement.Source = new BitmapImage(new Uri("ms-appx:///Assets/Images/logo.png"));

Sie können ms-appx jede beliebige Datei aus Ihrem App-Paket laden.

var uri = new System.Uri("ms-appx:///Assets/anyAsset.ext");
var storagefile = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

Das ms-appx-web Schema greift auf die gleichen Dateien wie ms-appxim Webfach zu.

<WebView x:Name="myXAMLWebViewElement" Source="ms-appx-web:///Pages/default.html"/>

this.myXAMLWebViewElement.Source = new Uri("ms-appx-web:///Pages/default.html");

Verwenden Sie für eines der in diesen Beispielen gezeigten Szenarien die URI-Konstruktorüberladung , die den UriKind ableiten soll. Geben Sie einen gültigen absoluten URI einschließlich des Schemas und der Autorität an, oder lassen Sie die Autorität einfach wie im obigen Beispiel das App-Paket standardmäßig verwenden.

Beachten Sie, dass in diesen Beispiel-URIs das Schema ("ms-appx" oder "ms-appx-web") von "://" gefolgt wird, auf das ein absoluter Pfad folgt. In einem absoluten Pfad bewirkt das führende "/", dass der Pfad aus dem Stammverzeichnis des Pakets interpretiert wird.

Hinweis

Die ms-resource URI-Schemas (für Zeichenfolgenressourcen) und ms-appx(-web) (für Bilder und andere Ressourcen) führen den automatischen Qualifiziererabgleich aus, um die Ressource zu finden, die für den aktuellen Kontext am besten geeignet ist. Das ms-appdata URI-Schema (das zum Laden von App-Daten verwendet wird) führt keinen solchen automatischen Abgleich durch, Sie können jedoch auf den Inhalt von ResourceContext.QualifierValues reagieren und die entsprechenden Ressourcen explizit aus App-Daten mithilfe ihres vollständigen physischen Dateinamens im URI laden. Informationen zu App-Daten finden Sie unter Store und Abrufen von Einstellungen und anderen App-Daten. Web-URI-Schemas (z http. B. , , httpsund ftp) führen auch keinen automatischen Abgleich durch. Informationen dazu, was in diesem Fall zu tun ist, finden Sie unter Hosting und Laden von Bildern in der Cloud.

Absolute Pfade sind eine gute Wahl, wenn Ihre Bilddateien in der Projektstruktur verbleiben. Wenn Sie in der Lage sein möchten, eine Bilddatei zu verschieben, aber Sie vorsichtig sind, dass sie sich an demselben Speicherort im Verhältnis zu ihrer referenzierenden XAML-Markupdatei befindet, sollten Sie anstelle eines absoluten Pfads einen Pfad verwenden, der relativ zur enthaltenden Markupdatei ist. Wenn Sie dies tun, müssen Sie kein URI-Schema verwenden. In diesem Fall profitieren Sie weiterhin vom automatischen Qualifiziererabgleich, aber nur weil Sie den relativen Pfad im XAML-Markup verwenden.

<Image Source="Assets/Images/logo.png"/>

Siehe auch die Unterstützung von Kacheln und Popups für Sprache, Skalierung und hohen Kontrast.

Verweisen auf ein Bild oder ein anderes Objekt aus einer Klassenbibliothek

Sie können Bilder und andere Ressourcen aus einem Referenzklassenbibliotheksprojekt (WinUI 3 in Desktop) laden, indem Sie auf die Ressource in einem URI verweisen, der das ms-appx Schema verwendet. Der URI sollte den Namen des Klassenbibliotheksprojekts und den Pfad zur Ressource innerhalb des Klassenbibliotheksprojekts enthalten. Wenn Sie z. B. über ein Klassenbibliotheksprojekt mit dem Namen MyClassLibrary eines Bilds in einem Ordner mit dem Namen logo.png Assetsverfügen, können Sie wie folgt auf das Bild in Ihrem App-Projekt verweisen:

<Image Source="ms-appx:///MyClassLibrary/Assets/logo.png"/>

Sie verwenden dieses URI-Format, um auf Ressourcen in einer Klassenbibliothek aus XAML-Markup oder code zu verweisen. Sie können z. B. den folgenden Code verwenden, um das Bild aus Ihrer Klassenbibliothek zu laden und es in ein StorageFile-Objekt einzufügen:

private async Task<DateTimeOffset> GetLogoCreatedDateAsync()
{
    Uri uri = new($"ms-appx:///MyClassLibrary/Assets/logo.png");
    Windows.Storage.StorageFile file =
        await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

    return file.DateCreated;
}

Beachten Sie, dass Sie auf Bilder aus der Klassenbibliothek sowohl aus dem App-Projekt als auch aus dem Klassenbibliotheksprojekt selbst verweisen können.

Qualifizieren einer Bildressource für die Zielgröße

Sie können die scale Und-Qualifizierer targetsize für verschiedene Varianten derselben Bildressource verwenden. Sie können sie jedoch nicht für eine einzelne Variante einer Ressource verwenden. Außerdem müssen Sie mindestens eine Variante ohne targetsize Qualifizierer definieren. Diese Variante muss entweder einen Wert für scale, oder sie standardmäßig definieren scale-100lassen. Daher sind diese beiden Varianten der /Assets/Square44x44Logo.png Ressource gültig.

\Assets\Square44x44Logo.scale-200.png
\Assets\Square44x44Logo.targetsize-24.png

Und diese beiden Varianten sind gültig.

\Assets\Square44x44Logo.png // defaults to scale-100
\Assets\Square44x44Logo.targetsize-24.png

Diese Variante ist jedoch ungültig.

\Assets\Square44x44Logo.scale-200_targetsize-24.png

Verweisen auf eine Bilddatei aus dem App-Paketmanifest

Wenn Sie Ordner und/oder Dateien wie in einem der beiden gültigen Beispiele im vorherigen Abschnitt benennen, verfügen Sie über eine einzelne Bildressource für App-Symbole und deren Namen (als relativer Pfad).Assets\Square44x44Logo.png Verweisen Sie im App-Paketmanifest einfach auf die Ressource anhand des Namens. Es ist nicht erforderlich, ein URI-Schema zu verwenden.

Ressource hinzufügen, Englisch

Das ist alles, was Sie tun müssen, und das Betriebssystem führt automatischen Qualifiziererabgleich aus, um die Ressource zu finden, die für den aktuellen Kontext am besten geeignet ist. Eine Liste aller Elemente im App-Paketmanifest, die Sie lokalisieren oder anderweitig qualifizieren können, finden Sie unter Lokalisierbare Manifestelemente.

Qualifizieren einer Bildressource für layoutdirection

Siehe Spiegelungsbilder.

Laden eines Bilds für eine bestimmte Sprache oder einen anderen Kontext

Weitere Informationen zu einer Werterhöhung Ihrer App durch Lokalisierung finden Sie unter Globalisierung und Lokalisierung.

Der Standardmäßige ResourceContext enthält einen Qualifiziererwert für jeden Qualifizierernamen, der den Standardlaufzeitkontext darstellt (mit anderen Worten die Einstellungen für den aktuellen Benutzer und computer). Bilddateien werden basierend auf den Qualifizierern in ihren Namen anhand der Qualifiziererwerte in diesem Laufzeitkontext abgeglichen.

Es kann jedoch vorkommen, dass Ihre App die Systemeinstellungen außer Kraft setzen und explizit über die Sprache, skalierung oder einen anderen Qualifiziererwert verfügen soll, der verwendet werden soll, wenn Sie nach einem übereinstimmenden Bild suchen, das geladen werden soll. Sie können beispielsweise genau steuern, wann und welche Bilder mit hohem Kontrast geladen werden.

Sie können dies tun, indem Sie einen neuen ResourceContext (anstelle der Standardeinstellung) erstellen, dessen Werte außer Kraft setzen und dann dieses Kontextobjekt in Ihren ResourceMap-Bild-Nachschlagevorgängen mit GetValue oder TryGetValue verwenden.

var resourceManager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
var resourceContext = resourceManager.CreateResourceContext();
resourceContext.QualifierValues["Contrast"] = "high";
var resourceMap = resourceManager.MainResourceMap;
var namedResource = resourceMap.TryGetValue(@"Files/Assets/Logo.png", resourceContext);
var imageFileBytes = namedResource.ValueAsBytes;

using (var ms = new InMemoryRandomAccessStream())
{
    using (var writer = new DataWriter(ms.GetOutputStreamAt(0)))
    {
        writer.WriteBytes(imageFileBytes);
        writer.StoreAsync().GetResults();
    }
    var image = new BitmapImage();
    image.SetSource(ms);
    this.myXAMLImageElement.Source = image;
}

Standardmäßig verwendet die ResourceManager-Klasse den Standardmäßigen ResourceContext.

Wichtige APIs

Die folgenden APIs sind wichtig zu verstehen, wenn Sie mit Bildressourcen arbeiten:

Zugehöriger Inhalt