Image.Source Свойство

Определение

Возвращает или задает источник для изображения.

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"/>

Значение свойства

Объект , представляющий исходный файл изображения для нарисованного изображения. Обычно для этого используется объект BitmapImage , созданный с помощью универсального кода ресурса (URI), который описывает путь к допустимому исходному файлу изображения. Или можно инициализировать BitmapSource с помощью потока, возможно, потока из файла хранилища.

Комментарии

Установка свойства Source по сути является асинхронным действием. Поскольку это свойство, нет ожидаемого синтаксиса, но в большинстве сценариев вам не нужно взаимодействовать с асинхронными аспектами загрузки исходного файла изображения. Платформа будет ожидать возвращения источника образа и повторно запустить макет, когда исходный файл образа станет доступным.

Установка для источника значения универсального кода ресурса (URI), которое не может быть разрешено в допустимый исходный файл образа, не вызывает исключения. Вместо этого вызывается событие ImageFailed . Ошибки декодирования также запускают ImageFailed. Вы можете написать обработчик ImageFailed и присоединить его к объекту Image , чтобы обнаружить это, и, возможно, использовать ErrorMessage в данных события для определения характера сбоя. Кроме того, если вы хотите убедиться, что исходный файл изображения загружен правильно, можно обработать событие ImageOpened в элементе Image .

Задание источника в XAML

Свойство Source можно задать в качестве атрибута в XAML. В этом случае значение атрибута Source задается как строка универсального кода ресурса (URI), описывающая расположение файла исходного образа. Это поведение основано на преобразовании базового типа, которое обрабатывает строку как универсальный код ресурса (URI) и вызывает эквивалент конструктора BitmapImage(Uri). Задание свойства Source с помощью строки универсального кода ресурса (URI) является ярлыком, включенным XAML. Обратите внимание, что универсальный код ресурса (URI) здесь представляет собой относительный универсальный код ресурса (URI). Поддержка частичного универсального кода ресурса (URI) — еще один ярлык XAML.

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

Средство синтаксического анализа XAML интерпретирует любые строки, представляющие относительный универсальный код ресурса (URI), используя базовый универсальный код ресурса (URI) анализируемой страницы XAML. Например, если указать значение Images/myImage.png в XAML, эта строка интерпретируется как относительный суффикс пути, который добавляется к базовому расположению универсального кода ресурса (URI) в пакете приложения, где существует сама страница XAML. Если предыдущий элемент Image добавляется на страницу, которая находится в корне пакета приложения, универсальный код ресурса (URI) интерпретируется как ms-appx:///Images/myImage.png. Если изображение добавляется на страницу, которая находится в папке Pages в приложении, универсальный код ресурса (URI) интерпретируется как ms-appx:///Pages/Images/myImage.png.

Если исходный образ не является частью пакета приложения, необходимо использовать абсолютный универсальный код ресурса (URI), чтобы задать свойство Source в XAML. Дополнительные сведения см. в разделе Загрузка файловых ресурсов и примеры далее в этом документе.

Также можно использовать синтаксис элемента свойства в XAML, указав объектный элемент BitmapImage с допустимым источником в качестве значения свойства.

Задание источника в коде

Чтобы задать свойство Image.Source в коде, требуется экземпляр BitmapImage (или BitmapSource), который также необходимо создать. Если источником изображения является поток, используйте асинхронный метод SetSourceAsyncbitmapImage , чтобы определить сведения об изображении из потока.

Если источником изображения является файл, на который ссылается универсальный код ресурса (URI), задайте свойство BitmapImage.UriSource или используйте конструктор BitmapImage , который принимает параметр URI. Среда выполнения Windows принудительно указывает, что универсальный код ресурса (URI) должен быть абсолютным; нельзя использовать относительный универсальный код ресурса (URI) в среда выполнения Windows коде. Если вы используете платформа .NET Framework значение System.Uri и используете сигнатуру, для которых требуется значение UriKind, обязательно укажите Значение Absolute.

При ссылке на локальное содержимое необходимо включить схему ms-appx: в абсолютный универсальный код ресурса (URI), который используется в качестве BitmapImage.UriSource. В коде вы не получаете ярлыки обработки для объединения относительных частей универсального кода ресурса (URI) и схемы ms-appx:, которая происходит автоматически, если указать Source в качестве атрибута XAML. Вместо этого необходимо явно создать абсолютный универсальный код ресурса (URI) с соответствующей схемой.

Ниже описано, как задать источник изображения из пакета приложения.

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

Если необходимо убедиться, что элемент управления Image готов, прежде чем пытаться использовать его в коде, обработайте событие Loaded и задайте свойство Source в обработчике событий.

Примечание

Событие FrameworkElement.Loaded возникает при загрузке элемента управления Image на страницу XAML. Событие ImageOpened возникает при открытии файла изображения в элементе управления Изображение .

Ниже приведен пример настройки Image.Source в обработчике события Loaded . В этом примере объект Image был создан в XAML, но не имеет источника или других значений свойств. Вместо этого эти значения предоставляются во время выполнения при загрузке образа из XAML.

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

Событие ImageOpened можно обработать при возникновении проблем со временем при извлечении или декодировании источника изображения, где может потребоваться дополнительное содержимое для отображения до тех пор, пока источник изображения не будет доступен. Пример кода см . в разделе Пример изображений XAML .

Использование относительного URI в коде

Ранее мы видели, что средство синтаксического анализа XAML интерпретирует относительный универсальный код ресурса (URI) с помощью базового универсального кода ресурса (URI) анализируемой страницы XAML. Для достижения того же результата в коде можно создать универсальный код ресурса (URI ) с помощью одного из конструкторов, создающих универсальный код ресурса (URI), объединяя абсолютный базовый и относительный путь в этом расположении. Для первого параметра вызовите BaseUri на странице , на которую загружается изображение . (Вы также можете вызвать BaseUri в экземпляре Image , где вы задаете источник, или другой элемент на странице. См. предупреждение ниже.) При этом создается универсальный код ресурса (URI) со схемой ms-appx: и добавляется путь, который является частью расположения страницы XAML. Для второго параметра передайте относительную строку универсального кода ресурса (URI), которая описывает расположение исходного образа.

В C# или Microsoft Visual Basic тип URI проецируется как System.Uri, поэтому используйте конструктор System.Uri(Uri, String), который принимает строку в качестве второго параметра. В расширениях компонентов Visual C++ (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;

Примечание

При создании экземпляра нового изображения в коде свойство BaseUri будет иметь значение NULL , пока изображение не будет добавлено в визуальное дерево страницы. Например, следующий код вызывает исключение ArgumentNull . Чтобы избежать исключения, добавьте image в визуальное дерево перед заданием свойства Source.

В этом примере создается исключение, так как он вызывает BaseUri для образа перед добавлением образа на страницу. Предполагается, что stackPanel1 — это элемент StackPanel, объявленный в XAML.

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

Чтобы избежать этой ошибки, можно вызвать BaseUri на самой странице , как показано выше, или добавить изображение на страницу перед вызовом BaseUri, как показано ниже.

В этом примере изображение добавляется на страницу перед вызовом BaseUri, поэтому BaseUri не имеет значения NULL. Предполагается, что stackPanel1 — это элемент StackPanel, объявленный в XAML.

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;

Использование файлов из сети

Чтобы использовать файл из сетевого расположения в качестве источника образа, используйте схемы http: или https: , как показано ниже. Укажите абсолютный универсальный код ресурса (URI). Дополнительные сведения см. в разделе Загрузка файлового ресурса.

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

Использование файлов из локального хранилища

Чтобы использовать файлы, размещенные в локальном хранилище приложения в качестве источника изображений, используйте схему ms-appdata: , как показано ниже. Укажите абсолютный универсальный код ресурса (URI). Дополнительные сведения см. в разделе Загрузка файлового ресурса.

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

Использование источника потока для отображения изображений из библиотеки изображений

Обычно элементы Image в приложении используются для отображения изображений из библиотеки изображений пользователя. Доступ к этим изображениям можно получить программным способом или с помощью FileOpenPicker. В любом случае объект StorageFile , который вы получаете, можно открыть в виде потока, но не предоставляет ссылку на универсальный код ресурса (URI) на файл изображения. Чтобы использовать поток в качестве источника изображения, необходимо написать код, который задает экземпляр Image для использования потока. Это невозможно сделать только в XAML.

Чтобы отобразить отдельное изображение, используйте объекты StorageFile из перечисления библиотеки и вызовите OpenAsync для получения потока. Используйте этот поток для задания источника изображения, создав новый Объект BitmapImage, а затем вызвав SetSourceAsync и передав поток для использования в качестве параметра streamSource .

В этом примере показано, как использовать FileOpenPicker для доступа к файлу изображения из библиотеки изображений и задать его в качестве источника элемента управления Image . Код уже доступен для ожидания, так как он ожидает, когда пользователь выберет файл, и выполняется только после этого. Используемый поток поступает из StorageFile.OpenAsync после возврата экземпляра StorageFile из действий асинхронного средства выбора. Дополнительные сведения об использовании средств выбора файлов см. в разделе Открытие файлов и папок с помощью средства выбора.

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

В этом примере показано, как программным способом получить доступ к файлу изображения из библиотеки изображений и задать его в качестве источника элемента управления Image . Чтобы получить доступ к содержимому библиотеки изображений программным способом, вызовите StorageFolder.GetFilesAsync. Помните, что необходимо указать возможность программного доступа к библиотеке изображений.

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

Исходные изображения и масштабирование

Если вы ссылаетесь на изображения, упакованные в приложение, следует создать источники изображений в нескольких рекомендуемых размерах, чтобы приложение выглядело отлично при масштабировании среда выполнения Windows. При указании источника для образа в качестве универсального кода ресурса (URI) можно использовать соглашение об именовании, которое автоматически ссылается на правильный ресурс образа для текущего масштабирования, обнаруженного системой во время выполнения. Особенности контекста именования и дополнительные сведения описываются в разделе Краткое руководство: использование файловых и графических ресурсов.

Дополнительные сведения о проектировании для масштабирования см. в разделе Адаптивный дизайн 101 для или Примечания на изображении.

Источники образов и квалификаторы ресурсов

Вы можете использовать автоматическую обработку для доступа к неквалифицированным ресурсам с помощью текущих квалификаторов масштабирования и языка и региональных параметров или ResourceManager и ResourceMap с квалификаторами для языка и региональных параметров и масштаба, чтобы получить ресурсы напрямую. Дополнительные сведения см. в разделе Система управления ресурсами или Примечания на изображении. Дополнительные сведения о ресурсах приложения и о том, как упаковать источники изображений в приложение, см. в разделе Определение ресурсов приложения.

Применяется к

См. также раздел