Image.Source Eigenschaft

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

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 Uniform Resource Identifier (URI) erstellt wurde, der den Pfad zu einer gültigen Bildquelldatei beschreibt. Oder Sie können eine BitmapSource mit einem Datenstrom initialisieren, z. B. einen Datenstrom aus einer Speicherdatei.

Hinweise

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

Wenn Sie die Quelle auf einen URI-Wert (Uniform Resource Identifier) festlegen, der nicht in eine gültige Bildquelldatei aufgelöst werden kann, wird keine Ausnahme ausgelöst. Stattdessen wird ein ImageFailed-Ereignis ausgelöst . Decodierungsfehler werden auch imageFailed ausgelöst. 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 Quellattributwert 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 Uniform Resource Identifier (URI) verarbeitet, und ruft das Äquivalent des BitmapImage(Uri) -Konstruktors auf. Das Festlegen der Source-Eigenschaft mithilfe einer URI-Zeichenfolge (Uniform Resource Identifier) ist eine verknüpfung, die von XAML aktiviert ist. Beachten Sie, dass hier der URI (Uniform Resource Identifier) als relativer URI (Uniform Resource Identifier) angezeigt wird; Unterstützung partieller Uniform Resource Identifier (URI) 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, mithilfe des Basis-URI (Uniform Resource Identifier) der XAML-Seite, die analysiert wird. Wenn Sie beispielsweise einen Wert "Images/myImage.png" in XAML angeben, wird diese Zeichenfolge als relatives Pfadsuffix interpretiert, das an den Basisspeicherort für den URI (Uniform Resource Identifier) innerhalb des App-Pakets angefügt wird, in dem die XAML-Seite selbst vorhanden ist. Wenn das vorherige Image-Element zu einer Seite hinzugefügt wird, die sich im Stammverzeichnis des App-Pakets befindet, wird der URI (Uniform Resource Identifier) als ms-appx:///Images/myImage.pnginterpretiert. Wenn das Bild zu einer Seite hinzugefügt wird, die sich in einem Ordner "Seiten" in der App befindet, wird der URI (Uniform Resource Identifier) als ms-appx:///Pages/Images/myImage.pnginterpretiert.

Wenn das Quellbild 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 Beispielen 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

Zum Festlegen der Image.Source-Eigenschaft im Code ist eine Instanz von BitmapImage (oder BitmapSource) erforderlich, die Sie auch erstellen müssen. Wenn ihre Bildquelle ein Datenstrom ist, verwenden Sie die asynchrone SetSourceAsync-Methode von BitmapImage , um die Bildinformationen aus dem Datenstrom zu definieren.

Wenn die Bildquelle eine Datei ist, auf die durch 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) verwendet. Die Windows-Runtime erzwingt, dass ein URI (Uniform Resource Identifier) absolut sein muss. Sie können keinen relativen URI (Uniform Resource Identifier) im 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 Absolute angegeben wird.

Wenn Sie auf lokale Inhalte 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 keine Verarbeitungsverknüpfungen zum Kombinieren relativer URI-Teile (Uniform Resource Identifier) und des ms-appx:- Schemas, das automatisch auftritt, 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 aus dem App-Paket auf ein Bild 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 es im Code verwenden möchten, behandeln Sie das Loaded-Ereignis , und legen Sie die Source-Eigenschaft im Ereignishandler fest.

Hier ist 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 jedoch nicht über eine Quelle oder andere Eigenschaftswerte. Stattdessen werden diese Werte zur Laufzeit bereitgestellt, wenn das Bild 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 Probleme auftreten, bei denen Sie möglicherweise alternative Inhalte benötigen, um anzuzeigen, bis die Bildquelle verfügbar ist. Beispiel für XAML-Bilder finden Sie unter Beispielcode.

Verwenden eines relativen URI im Code

Wir haben zuvor gesehen, dass der XAML-Parser einen relativen URI (Uniform Resource Identifier) mit dem Basis-URI (Uniform Resource Identifier) der XAML-Seite interpretiert, die analysiert wird. Um dasselbe Ergebnis im Code zu erzielen, können Sie einen URI mithilfe eines der Konstruktoren erstellen, die einen URI (Uniform Resource Identifier) erstellen, indem Sie eine absolute Basis und dann einen relativen Pfad innerhalb dieses Speicherorts kombinieren. Rufen Sie für den ersten Parameter "BaseUri " auf "Page " auf, auf dem das Bild geladen wird. (Sie können " BaseUri " auch für die Image-Instanz aufrufen, in der Sie die Quelle oder ein anderes Element auf der Seite festlegen. Siehe die Nachstehende Vorsicht.) Dadurch wird ein URI (Uniform Resource Identifier) mit dem Ms-appx:- Schema erstellt und der Pfad hinzugefügt, der Teil des Speicherorts der XAML-Seite ist. Übergeben Sie für den zweiten Parameter die relative URI-Zeichenfolge (Uniform Resource Identifier), die den Quellbildspeicherort beschreibt.

In C# 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 C++ Uri(Zeichenfolge,Zeichenfolge).

<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;

In diesem Beispiel wird eine Ausnahme ausgelöst, da sie BaseUri für das Image aufruft, bevor das Bild der Seite hinzugefügt wird. Es wird angenommen, dass " stackPanel1" ein stackPanel-Element ist, das in XAML deklariert 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 vor dem Aufrufen von BaseUri das Bild zur Seite hinzufügen, wie hier gezeigt.

In diesem Beispiel wird das Bild vor dem Aufruf von BaseUri der Seite hinzugefügt, sodass BaseUri nicht NULL ist. Es wird angenommen, dass " stackPanel1" ein stackPanel-Element ist, das in XAML deklariert 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

Wenn Sie eine Datei von einem Netzwerkspeicherort als Bildquelle verwenden möchten, 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 dem lokalen Speicher

Wenn Sie Dateien verwenden möchten, die im lokalen Speicher Ihrer App als Bildquelle platziert werden, 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 ein FileOpenPicker zugegriffen werden. In beiden Fällen kann das von Ihnen abgerufene StorageFile-Objekt als Datenstrom geöffnet werden, stellt jedoch keinen URI -Verweis (Uniform Resource Identifier) auf die Bilddatei bereit. Um einen Datenstrom als Bildquelle zu verwenden, müssen Sie Code schreiben, der die Image-Instanz so festlegt, dass der Datenstrom verwendet wird. Dies kann nicht allein in XAML erfolgen.

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

In diesem Beispiel wird gezeigt, wie Sie mithilfe eines FileOpenPicker-Steuerelements auf eine Bilddatei aus der Bildbibliothek zugreifen und als Quelle eines Bildsteuerelements festlegen. Der Code ist bereits wartend, da er darauf wartet, dass der Benutzer eine Datei auswählt und erst danach ausgeführt wird. Der zu verwendende Datenstrom stammt aus StorageFile.OpenAsync , nachdem eine StorageFile-Instanz von den asynchronen Auswahlaktionen zurückgegeben wird. Weitere Informationen zur Verwendung der Dateiauswahl 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 über die Bildbibliothek auf eine Bilddatei zugreifen und sie als Quelle eines Bildsteuerelements festlegen. Rufen Sie "StorageFolder.GetFilesAsync" auf, um programmgesteuert auf den Inhalt der Bildbibliothek zuzugreifen. Denken Sie daran, dass Sie eine Funktion angeben müssen, um programmgesteuert auf die Bildbibliothek zuzugreifen.

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 mit mehreren empfohlenen Größen erstellen, um sicherzustellen, dass Ihre App gut aussieht, wenn die Windows-Runtime skaliert. Wenn Sie eine Quelle für ein Bild 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 wird. Einzelheiten zur Benennungskonvention und weitere Informationen finden Sie in der Schnellstartanleitung: Verwenden von Datei- oder Bildressourcen.

Weitere Informationen zum Entwerfen der Skalierung finden Sie unter "Dynamisches Design 101" 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.

Weitere Informationen

• ImageFailed
• ImageOpened
• BitmapSource
• Image und ImageBrush
• Beispiel für XAML-Bilder