Image.Source Eigenschaft

Referenz

Definition

Namespace:: Microsoft.UI.Xaml.Controls

Wichtig

Einige Informationen beziehen sich auf Vorabversionen, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Bearbeiten

Ruft die Quelle für das Bild ab oder legt sie fest.

public:
 property ImageSource ^ Source { ImageSource ^ get(); void set(ImageSource ^ value); };

ImageSource Source();

void Source(ImageSource value);

public ImageSource Source { get; set; }

var imageSource = image.source;
image.source = imageSource;

Public Property Source As ImageSource

<Image Source="uri"/>

Eigenschaftswert

ImageSource

Ein -Objekt, das die Bildquelldatei für das gezeichnete Bild darstellt. In der Regel legen Sie dies mit einem BitmapImage-Objekt fest, das mit dem URI (Uniform Resource Identifier) erstellt wurde, der den Pfad zu einer gültigen Bildquelldatei beschreibt. Alternativ können Sie eine BitmapSource mit einem Stream initialisieren, z. B. mit einem Stream aus einer Speicherdatei.

Hinweise

Das Festlegen der Source-Eigenschaft ist von Natur aus eine asynchrone Aktion. Da es sich um eine Eigenschaft handelt, gibt es keine erwartbare Syntax, aber in den meisten Szenarien müssen Sie nicht mit den asynchronen Aspekten des Ladens von Bildquelldateien interagieren. Das Framework wartet auf die Rückgabe der Bildquelle und führt das Layout erneut aus, wenn die Bildquelldatei verfügbar wird.

Das Festlegen der Quelle auf einen URI-Wert (Uniform Resource Identifier), der nicht in eine gültige Bildquelldatei aufgelöst werden kann, löst keine Ausnahme aus. Stattdessen wird ein ImageFailed-Ereignis ausgelöst . Decodierungsfehler lösen auch ImageFailed aus. Sie können einen ImageFailed-Handler schreiben und an das Image-Objekt anfügen, um dies zu erkennen, und möglicherweise die ErrorMessage in Ereignisdaten verwenden, um die Art des Fehlers zu bestimmen. Wenn Sie außerdem überprüfen möchten, ob eine Bildquelldatei ordnungsgemäß geladen wurde, können Sie das ImageOpened-Ereignis für das Image-Element behandeln.

Festlegen der Quelle in XAML

Sie können die Source-Eigenschaft als Attribut in XAML festlegen. In diesem Fall legen Sie den Source-Attributwert als URI-Zeichenfolge (Uniform Resource Identifier) fest, die den Speicherort der Quellbilddatei beschreibt. Dieses Verhalten basiert auf der zugrunde liegenden Typkonvertierung, die die Zeichenfolge als URI (Uniform Resource Identifier) verarbeitet und die Entsprechung des BitmapImage(Uri)- Konstruktors aufruft. Das Festlegen der Source-Eigenschaft mithilfe einer URI-Zeichenfolge (Uniform Resource Identifier) ist eine von XAML aktivierte Verknüpfung. Beachten Sie, dass der URI (Uniform Resource Identifier) hier ein relativer URI (Uniform Resource Identifier) zu sein scheint. Die Unterstützung des partiellen URI (Uniform Resource Identifier) ist eine weitere XAML-Verknüpfung.

<Image Width="200" Source="Images/myImage.png"/>

Der XAML-Parser interpretiert alle Zeichenfolgen, die einen relativen URI (Uniform Resource Identifier) darstellen, unter Verwendung des Basis-URI (Uniform Resource Identifier) der XAML-Seite, die analysiert wird. Wenn Sie beispielsweise den Wert "Images/myImage.png" in XAML angeben, wird diese Zeichenfolge als relatives Pfadsuffix interpretiert, das an den Basisspeicherort des Uniform Resource Identifier (URI) innerhalb des App-Pakets angefügt wird, in dem die XAML-Seite selbst vorhanden ist. Wenn das vorherige Image-Element einer Seite hinzugefügt wird, die sich im Stammverzeichnis des App-Pakets befindet, wird der URI (Uniform Resource Identifier) als ms-appx:///Images/myImage.png interpretiert. Wenn das Bild einer Seite hinzugefügt wird, die sich in einem Ordner Pages in der App befindet, wird der URI (Uniform Resource Identifier) als ms-appx:///Pages/Images/myImage.png interpretiert.

Wenn das Quellimage nicht Teil des App-Pakets ist, müssen Sie einen absoluten URI (Uniform Resource Identifier) verwenden, um die Source-Eigenschaft in XAML festzulegen. Weitere Informationen finden Sie unter Laden von Dateiressourcen und Beispiele weiter unten in diesem Dokument.

Eine Eigenschaftselementsyntax in XAML ist ebenfalls möglich, wobei ein BitmapImage-Objektelement mit gültiger Quelle als Eigenschaftswert angegeben wird.

Festlegen der Quelle im Code

Um die Image.Source-Eigenschaft im Code festzulegen, ist eine instance bitmapImage (oder BitmapSource) erforderlich, die Sie auch erstellen müssen. Wenn ihre Bildquelle ein Stream ist, verwenden Sie die asynchrone SetSourceAsync-Methode von BitmapImage , um die Bildinformationen aus dem Stream zu definieren.

Wenn ihre Bildquelle eine Datei ist, auf die vom Uniform Resource Identifier (URI) verwiesen wird, legen Sie die BitmapImage.UriSource-Eigenschaft fest, oder verwenden Sie den BitmapImage-Konstruktor , der einen URI-Parameter (Uniform Resource Identifier) annimmt. Die Windows-Runtime erzwingt, dass ein URI (Uniform Resource Identifier) absolut sein muss. Sie können keinen relativen URI (Uniform Resource Identifier) in Windows-Runtime Code verwenden. Wenn Sie einen .NET Framework System.Uri-Wert verwenden und eine Signatur verwenden, die einen UriKind-Wert erfordert, stellen Sie sicher, dass Sie Absolute angeben.

Wenn Sie auf lokalen Inhalt verweisen, müssen Sie das Schema ms-appx: in den absoluten URI (Uniform Resource Identifier) einschließen, den Sie als BitmapImage.UriSource verwenden. Im Code erhalten Sie nicht die Verarbeitungsverknüpfungen für die Kombination relativer URI-Teile (Uniform Resource Identifier) und des Schemas ms-appx: dies geschieht automatisch, wenn Sie Source als XAML-Attribut angeben. Stattdessen müssen Sie explizit einen absoluten URI (Uniform Resource Identifier) mit dem entsprechenden Schema erstellen.

Hier erfahren Sie, wie Sie die Quelle auf ein Bild aus dem App-Paket festlegen.

Image img = new Image();
BitmapImage bitmapImage = new BitmapImage();
Uri uri = new Uri("ms-appx:///Assets/Logo.png");
bitmapImage.UriSource = uri;
img.Source = bitmapImage;

// OR

Image img = new Image();
img.Source = new BitmapImage(new Uri("ms-appx:///Assets/Logo.png"));

Windows::UI::Xaml::Controls::Image img;
Windows::UI::Xaml::Media::Imaging::BitmapImage bitmapImage;
Windows::Foundation::Uri uri{ L"ms-appx:///Assets/LockScreenLogo.png" };
bitmapImage.UriSource(uri);
img.Source(bitmapImage);

// OR

Windows::UI::Xaml::Controls::Image img;
img.Source(Windows::UI::Xaml::Media::Imaging::BitmapImage{ Windows::Foundation::Uri{ L"ms-appx:///Assets/LockScreenLogo.png" } });

auto img = ref new Image();
auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
auto uri = ref new Windows::Foundation::Uri("ms-appx:///Assets/Logo.png");
bitmapImage->UriSource = uri;
img->Source = bitmapImage;

// OR

auto img = ref new Image();
img->Source = ref new BitmapImage(ref new Windows::Foundation::Uri("ms-appx:///Assets/Logo.png"));

Wenn Sie sicherstellen müssen, dass das Image-Steuerelement bereit ist, bevor Sie versuchen, es im Code zu verwenden, behandeln Sie das Loaded-Ereignis , und legen Sie die Source-Eigenschaft im Ereignishandler fest.

Hinweis

Das FrameworkElement.Loaded-Ereignis tritt auf, wenn das Image-Steuerelement in die XAML-Seite geladen wird. Das ImageOpened-Ereignis tritt auf, wenn die Bilddatei im Image-Steuerelement geöffnet wird.

Hier sehen Sie ein Beispiel für das Festlegen von Image.Source im Handler für das Loaded-Ereignis . In diesem Beispiel wurde das Image-Objekt in XAML erstellt, verfügt aber nicht über eine Quelle oder andere Eigenschaftswerte. Stattdessen werden diese Werte zur Laufzeit bereitgestellt, wenn das Image aus XAML geladen wird.

<Image Loaded="Image_Loaded"/>

void Image_Loaded(object sender, RoutedEventArgs e)
{
    Image img = sender as Image;
    if (img != null)
    {
        BitmapImage bitmapImage = new BitmapImage();
        img.Width = bitmapImage.DecodePixelWidth = 280;
        bitmapImage.UriSource = new Uri("ms-appx:///Assets/Logo.png");
        img.Source = bitmapImage;
    }
}

void MainPage::Image_Loaded(winrt::Windows::Foundation::IInspectable const& sender, winrt::Windows::UI::Xaml::RoutedEventArgs const& /* e */)
{
    auto img{ sender.as<Windows::UI::Xaml::Controls::Image>() }; // throws if QI fails, so no need for null-check afterwards.
    Windows::UI::Xaml::Media::Imaging::BitmapImage bitmapImage;
    img.Width(280);
    bitmapImage.DecodePixelWidth(280);
    bitmapImage.UriSource(Windows::Foundation::Uri{ L"ms-appx:///Assets/LockScreenLogo.png" });
    img.Source(bitmapImage);
}

void App1::MainPage::Image_Loaded(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
 auto img = dynamic_cast<Image^>(sender);
 if (img != nullptr)
 {
  auto bitmapImage = ref new BitmapImage();
  img->Width = 280; bitmapImage->DecodePixelWidth = 280;
  bitmapImage->UriSource = ref new Uri("ms-appx:///Assets/Logo.png");
  img->Source = bitmapImage;
 }
}

Sie können das ImageOpened-Ereignis behandeln, wenn beim Abrufen oder Decodieren der Bildquelle Zeitprobleme auftreten, bei denen möglicherweise alternative Inhalte angezeigt werden müssen, bis die Bildquelle verfügbar ist. Beispielcode finden Sie im Beispiel für XAML-Bilder .

Verwenden eines relativen URI im Code

Wir haben zuvor gesehen, dass der XAML-Parser einen relativen URI (Uniform Resource Identifier) mithilfe des Basis-URI (Uniform Resource Identifier) der XAML-Seite interpretiert, die analysiert wird. Um das gleiche Ergebnis im Code zu erzielen, können Sie einen URI mit einem der Konstruktoren erstellen, der einen URI (Uniform Resource Identifier) erstellt, indem Sie eine absolute Basis und dann einen relativen Pfad innerhalb dieses Speicherorts kombinieren. Rufen Sie für den ersten Parameter BaseUri auf Seite auf, an der das Image geladen wird. (Sie können baseUri auch für die Image-instance aufrufen, in der Sie die Quelle festlegen, oder ein anderes Element auf der Seite. Weitere Informationen finden Sie unter "Vorsicht".) Dadurch wird ein URI (Uniform Resource Identifier) mit dem Schema ms-appx: erstellt und der Pfad hinzugefügt, der Teil des Speicherorts der XAML-Seite ist. Übergeben Sie für den zweiten Parameter die relative ZEICHENFOLGE (Uniform Resource Identifier, URI), die den Speicherort des Quellbilds beschreibt.

In C# oder Microsoft Visual Basic wird der URI-Typ als System.Uri projiziert. Verwenden Sie daher den System.Uri(Uri, String)- Konstruktor, der eine Zeichenfolge als zweiten Parameter verwendet. Verwenden Sie in Visual C++-Komponentenerweiterungen (C++/CX) Uri(String,String).

<Image x:Name="capturedPhoto"/>

BitmapImage bitmapImage = new BitmapImage();
// Call BaseUri on the root Page element and combine it with a relative path
// to consruct an absolute URI.
bitmapImage.UriSource = new Uri(this.BaseUri, "Assets/placeholder.png");
capturedPhoto.Source = bitmapImage;

auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
// Call BaseUri on the root Page element and combine it with a relative path
// to consruct an absolute URI.
bitmapImage->UriSource = ref new Windows::Foundation::Uri(BaseUri->AbsoluteUri, "Assets/placeholder.png");
capturedPhoto->Source = bitmapImage;

Hinweis

Wenn Sie ein neues Image im Code instanziieren, ist die BaseUri-EigenschaftNULL , bis das Image der visuellen Struktur einer Seite hinzugefügt wird. Der folgende Code löst beispielsweise eine ArgumentNull-Ausnahme aus. Um die Ausnahme zu vermeiden, fügen Sie das Image der visuellen Struktur hinzu, bevor Sie die Source-Eigenschaft festlegen.

In diesem Beispiel wird eine Ausnahme ausgelöst, da BaseUri für das Image aufgerufen wird, bevor das Image der Seite hinzugefügt wird. Es wird angenommen, dass "stackPanel1" ein in XAML deklariertes StackPanel-Element ist.

Image img = new Image();
BitmapImage bitmapImage = new BitmapImage();

// AN EXCEPTION IS THROWN BECAUSE img.BaseUri IS NULL AT THIS POINT.
Uri uri = new Uri(img.BaseUri, "Assets/Logo.png");

bitmapImage.UriSource = uri;
img.Source = bitmapImage;
stackPanel1.Children.Add(img);

auto img = ref new Image();
auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();

// AN EXCEPTION IS THROWN BECAUSE img->BaseUri IS NULL AT THIS POINT.
auto uri = ref new Windows::Foundation::Uri(img->BaseUri->AbsoluteUri, "Assets/Logo.png");

bitmapImage->UriSource = uri;
img->Source = bitmapImage;
stackPanel1->Children->Append(img);

Um diesen Fehler zu vermeiden, können Sie BaseUri auf der Seite selbst aufrufen, wie zuvor gezeigt, oder das Image der Seite hinzufügen, bevor Sie BaseUri aufrufen, wie hier gezeigt.

In diesem Beispiel wird das Image der Seite vor dem Aufruf von BaseUri hinzugefügt, sodass BaseUri nicht NULL ist. Es wird angenommen, dass "stackPanel1" ein in XAML deklariertes StackPanel-Element ist.

Image img = new Image();
// Add the image to the page.
stackPanel1.Children.Add(img);

BitmapImage bitmapImage = new BitmapImage();
// img.BaseUri in not null because img has been added to the page.
Uri uri = new Uri(img.BaseUri, "Assets/Logo.png");
bitmapImage.UriSource = uri;
img.Source = bitmapImage;

auto img = ref new Image();
// Add the image to the page.
stackPanel1->Children->Append(img);

auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
// img->BaseUri in not null because img has been added to the page.
auto uri = ref new Windows::Foundation::Uri(img->BaseUri->AbsoluteUri, "Assets/Logo.png");
bitmapImage->UriSource = uri;
img->Source = bitmapImage;

Verwenden von Dateien aus einem Netzwerk

Um eine Datei von einem Netzwerkspeicherort als Bildquelle zu verwenden, verwenden Sie die Schemas http: oder https: wie hier gezeigt. Geben Sie den absoluten URI (Uniform Resource Identifier) an. Weitere Informationen finden Sie unter Laden von Dateiressourcen.

<Image Source="http://www.contoso.com/images/logo.png"/>

Image img = new Image();
img.Source = new BitmapImage(new Uri("http://www.contoso.com/images/logo.png"));

auto img = ref new Image();
img->Source = ref new BitmapImage(ref new Windows::Foundation::Uri("http://www.contoso.com/images/logo.png"));

Verwenden von Dateien aus lokalem Speicher

Um Dateien zu verwenden, die sich im lokalen Speicher Ihrer App als Bildquelle befinden, verwenden Sie das Schema ms-appdata: wie hier gezeigt. Geben Sie den absoluten URI (Uniform Resource Identifier) an. Weitere Informationen finden Sie unter Laden von Dateiressourcen.

<!-- Access an image file stored in the local folder -->
<Image Source="ms-appdata:///local/images/logo.png"/>

<!-- Access an image file stored in the roaming folder -->
<Image Source="ms-appdata:///roaming/images/logo.png"/>

<!-- Access an image file stored in the temp folder -->
<Image Source="ms-appdata:///temp/images/logo.png"/>

var uri = new System.Uri("ms-appdata:///local/images/logo.png");
var file = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

Image img = new Image();
img.Source = file;

Verwenden einer Streamquelle zum Anzeigen von Bildern aus der Bildbibliothek

Eine typische Verwendung von Bildelementen in einer App besteht darin, Bilder aus der Bildbibliothek des Benutzers anzuzeigen. Auf diese Bilder kann programmgesteuert oder über einen FileOpenPicker zugegriffen werden. In beiden Fällen kann das storageFile-Objekt , das Sie erhalten, als Stream geöffnet werden, stellt jedoch keinen URI-Verweis (Uniform Resource Identifier) auf die Bilddatei bereit. Um einen Stream als Bildquelle zu verwenden, müssen Sie Code schreiben, der die Image-instance für die Verwendung des Datenstroms festlegt. Dies kann nicht allein in XAML erfolgen.

Verwenden Sie zum Anzeigen eines einzelnen Bilds die StorageFile-Objekte aus dem Auflisten der Bibliothek, und rufen Sie OpenAsync auf, um einen Stream abzurufen. Verwenden Sie diesen Stream, um die Bildquelle festzulegen, indem Sie ein neues BitmapImage erstellen, dann SetSourceAsync aufrufen und den Stream übergeben, der als streamSource-Parameter verwendet werden soll.

In diesem Beispiel wird gezeigt, wie Sie mit einem FileOpenPicker über die Bildbibliothek auf eine Bilddatei zugreifen und sie als Quelle eines Image-Steuerelements festlegen. Der Code kann bereits erwartet werden, da er darauf wartet, dass der Benutzer eine Datei auswählt und erst danach ausgeführt wird. Der zu verwendende Stream stammt aus StorageFile.OpenAsync, nachdem ein StorageFile-instance von den asynchronen Auswahlaktionen zurückgegeben wurde. Weitere Informationen zur Verwendung von Dateiauswahlen finden Sie unter Öffnen von Dateien und Ordnern mit einer Auswahl.

<Button Content="Get photo" Click="GetPhotoButton_Click"/>

<Image x:Name="image1" Width="300"/>

private async void GetPhotoButton_Click(object sender, RoutedEventArgs e)
{
    // Set up the file picker.
    Windows.Storage.Pickers.FileOpenPicker openPicker = 
        new Windows.Storage.Pickers.FileOpenPicker();
    openPicker.SuggestedStartLocation = 
        Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
    openPicker.ViewMode = 
        Windows.Storage.Pickers.PickerViewMode.Thumbnail;

    // Filter to include a sample subset of file types.
    openPicker.FileTypeFilter.Clear();
    openPicker.FileTypeFilter.Add(".bmp");
    openPicker.FileTypeFilter.Add(".png");
    openPicker.FileTypeFilter.Add(".jpeg");
    openPicker.FileTypeFilter.Add(".jpg");

    // Open the file picker.
    Windows.Storage.StorageFile file = 
        await openPicker.PickSingleFileAsync();

    // 'file' is null if user cancels the file picker.
    if (file != null)
    {
        // Open a stream for the selected file.
        // The 'using' block ensures the stream is disposed
        // after the image is loaded.
        using (Windows.Storage.Streams.IRandomAccessStream fileStream =
            await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
        {
            // Set the image source to the selected bitmap.
            Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage =
                new Windows.UI.Xaml.Media.Imaging.BitmapImage();

            bitmapImage.SetSource(fileStream);
            image1.Source = bitmapImage;
        }
    }
}

In diesem Beispiel wird gezeigt, wie Sie programmgesteuert auf eine Bilddatei aus der Bildbibliothek zugreifen und sie als Quelle eines Bildsteuerelements festlegen. Um programmgesteuert auf den Inhalt der Bildbibliothek zuzugreifen, rufen Sie StorageFolder.GetFilesAsync auf. Denken Sie daran, dass Sie eine Funktion für den programmgesteuerten Zugriff auf die Bildbibliothek angeben müssen.

protected async override void OnNavigatedTo(NavigationEventArgs e)
{
    // Get the Pictures library
    Windows.Storage.StorageFolder picturesFolder = 
        Windows.Storage.KnownFolders.PicturesLibrary;
    IReadOnlyList<StorageFolder> folders = 
        await picturesFolder.GetFoldersAsync();

    // Process file folders
    foreach (StorageFolder folder in folders)
    {
        // Get and process files in folder
        IReadOnlyList<StorageFile> fileList = await folder.GetFilesAsync();
        foreach (StorageFile file in fileList)
        {
            Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage = 
                new Windows.UI.Xaml.Media.Imaging.BitmapImage();

            // Open a stream for the selected file.
            // The 'using' block ensures the stream is disposed
            // after the image is loaded.
            using (Windows.Storage.Streams.IRandomAccessStream fileStream = 
                await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
            {
                // Set the image source to the selected bitmap.
                Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage =
                    new Windows.UI.Xaml.Media.Imaging.BitmapImage();
                bitmapImage.SetSource(fileStream);

                // Create an Image control.  
                Image img = new Image();
                img.Height = 50;
                img.Source = bitmapImage;

                // Add the Image control to the UI. 'imageGrid' is a
                // VariableSizedWrapGrid declared in the XAML page.
                imageGrid.Children.Add(img);
            }
        }
    }
}

Bildquellen und Skalierung

Wenn Sie auf Bilder verweisen, die in Ihrer App verpackt sind, sollten Sie Ihre Bildquellen in mehreren empfohlenen Größen erstellen, um sicherzustellen, dass Ihre App gut aussieht, wenn die Windows-Runtime skaliert wird. Wenn Sie eine Quelle für ein Image als URI (Uniform Resource Identifier) angeben, können Sie eine Benennungskonvention verwenden, die automatisch auf die richtige Bildressource für die aktuelle Skalierung verweist, wie sie vom System zur Laufzeit erkannt wurde. Einzelheiten zur Namenskonvention sowie weiterführende Informationen findest du unter Schnellstart: Verwenden von Datei- oder Bildressourcen.

Weitere Informationen zum Entwerfen für die Skalierung finden Sie unter Responsive Design 101 für oder Hinweise in Image.

Bildquellen und Ressourcenqualifizierer

Sie können die automatische Behandlung für den Zugriff auf nicht qualifizierte Ressourcen mit aktuellen Skalierungs- und Kulturqualifizierern verwenden, oder Sie können ResourceManager und ResourceMap mit Qualifizierern für Kultur und Skalierung verwenden, um die Ressourcen direkt abzurufen. Weitere Informationen finden Sie unter Ressourcenverwaltungssystem oder Hinweise in Image. Weitere Informationen zu App-Ressourcen und zum Verpacken von Bildquellen in einer App finden Sie unter Definieren von App-Ressourcen.

Gilt für:

Freigeben über