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 .
Ниже приведен пример настройки 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 = winrt::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(winrt::Windows::Foundation::Uri(BaseUri().AbsoluteUri(), L"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 . Чтобы избежать исключения, добавьте изображение в визуальное дерево перед установкой свойства Source.
В этом примере возникает исключение, так как он вызывает BaseUri для image перед добавлением образа на страницу. Предполагается, что 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);
Image img;
BitmapImage bitmapImage;
// AN EXCEPTION IS THROWN BECAUSE img.BaseUri IS NULL AT THIS POINT.
Uri uri(img.BaseUri(), L"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;
Image img;
// Add the image to the page.
stackPanel1.Children().Add(img);
BitmapImage bitmapImage;
// img.BaseUri in not null because img has been added to the page.
Uri uri(img.BaseUri(), L"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"));
Image img;
img.Source(BitmapImage(Uri(L"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) можно использовать соглашение об именовании, которое автоматически ссылается на правильный ресурс образа для текущего масштабирования, обнаруженного системой во время выполнения. Особенности контекста именования и дополнительные сведения описываются в разделе Краткое руководство: использование файловых и графических ресурсов.
Дополнительные сведения о проектировании для масштабирования см. в разделах Размеры экрана и точки останова или Примечания на изображении.
Источники образов и квалификаторы ресурсов
Вы можете использовать автоматическую обработку для доступа к неквалифицированным ресурсам с помощью текущих квалификаторов масштабирования и языка и региональных параметров, а также использовать ResourceManager и ResourceMap с квалификаторами для языка и региональных параметров и масштаба, чтобы получить ресурсы напрямую. Дополнительные сведения см. в разделе Система управления ресурсами или Примечания на изображении. Дополнительные сведения о ресурсах приложения и о том, как упаковать источники изображений в приложение, см. в разделе Определение ресурсов приложения.