Медіаплеєри
Відтворення медіафайлів передбачає перегляд і прослуховування відео та аудіо через вкладений (вбудований у сторінку чи групу інших елементів керування) або спеціальний повноекранний режим.
Користувачі очікують базового набору елементів керування, таких як відтворення/пауза, перемотування назад, перемотування вперед, які можна змінювати за потреби (включно з кнопками медіаплеєра, фоном панелі керування, розташуванням елементів керування або макетом).
Чи правильний цей елемент керування?
Використовуйте медіаплеєр, якщо ви хочете відтворити аудіо або відео у своєму додатку. Щоб відобразити колекцію зображень, використовуйте режим перегортання.
Рекомендації
Медіаплеєр підтримує як світлі, так і темні теми, але темна тема забезпечує краще сприйняття для більшості розважальних сценаріїв. Темний фон забезпечує кращу контрастність, особливо в умовах слабкого освітлення, і обмежує втручання панелі керування в перегляд.
Під час відтворення відеоконтенту заохочуйте спеціальний режим перегляду, надаючи перевагу повноекранному режиму над вбудованим. Повноекранний режим є оптимальним для перегляду, а у вбудованому режимі можливості обмежені.
Якщо у вас є вільний простір на екрані, використовуйте дворядкову розмітку. Вона забезпечує більше місця для елементів керування, ніж компактна однорядкова, і в ній легше орієнтуватися за допомогою різноманітних вводів.
Елементи керування оптимізовано для відтворення медіафайлів за замовчуванням, проте ви можете додати до медіаплеєра власні параметри, які вам потрібні, щоб забезпечити кращу роботу з вашим додатком. Щоб дізнатися більше про додавання власних елементів керування, відвідайте розділ Створення власних елементів керування навігацією.
UWP та WinUI 2
Важливо: Інформація та приклади в цій статті оптимізовані для програм, які використовують Windows App SDK та WinUI 3, але загалом застосовуються до програм UWP, які використовують WinUI 2. Для отримання інформації та прикладів для конкретної платформи див. довідник UWP API.
Цей розділ містить інформацію, необхідну для використання елемента керування у програмі UWP або WinUI 2.
API для цього елемента управління існують у просторі імен Windows.UI.Xaml.Controls.
UWP APIs: клас MediaPlayerElement, клас MediaTransportControls
Відкрийте додаток WinUI 2 Gallery і подивіться на MediaPlayerElement в дії. Додаток WinUI 2 Gallery містить інтерактивні приклади більшості елементів керування, функцій і можливостей WinUI 2. Завантажте додаток з Microsoft Store або отримайте вихідний код на GitHub.
Ми рекомендуємо використовувати останню версію WinUI 2, щоб отримати найновіші стилі та шаблони для елементів керування. WinUI 2.2 або наступні версії містять новий шаблон для цього елемента керування, який використовує закруглені кути. Докладні відомості див. у розділі Радіус кута.
Для розробки “10-футового досвіду” краще використовувати дворядну розкладку. Вона забезпечує більше місця для елементів керування, ніж компактна однорядна, і на ній легше орієнтуватися за допомогою джойстика на відстані 10 футів. Додаткову інформацію про оптимізацію програми для “10-футового досвіду” див. у статті “Проєктування для Xbox та TV”.
MediaPlayerElement доступний лише для Windows 10, версії 1607 та наступних. Якщо ви розробляєте додаток для попередньої версії Windows 10, вам слід використовувати елементи керування MediaElement. Усі наведені тут рекомендації також стосуються MediaElement.
Створення медіаплеєра
Важливі API: Клас MediaPlayerElement, клас MediaTransportControls.
Відкрийте додаток WinUI 3 Gallery and подивіться на MediaPlayerElement у дії.
Додаток WinUI 3 Gallery містить інтерактивні приклади більшості елементів керування, функцій та можливостей WinUI 3. Завантажте додаток з Microsoft Store або отримайте вихідний код на GitHub
Додайте медіа до свого додатка, створивши об’єкт MediaPlayerElement у XAML and налаштувавши його Source значення на MediaSource, що вказує на аудіо- або відеофайл.
Цей XAML створює MediaPlayerElement і налаштовує його значення Source на URI відеофайлу, який є локальним для додатка. MediaPlayerElement починає відтворюватися, коли сторінка завантажується. Щоб запобігти миттєвому запуску мультимедіа, ви можете встановити властивість AutoPlay у значення false.
XAML
x:Name=“mediaPlayerElement”
Source=“ms-appx:///Videos/video1.mp4”
Width=“400” AutoPlay=“True”/>
Цей XAML створює MediaPlayerElement з увімкненими вбудованими елементами керування переміщенням і властивістю AutoPlay встановленою в значенні false.
XAML
x:Name=“mediaPlayerElement”
Source=“ms-appx:///Videos/video1.mp4”
Width=“400”
AutoPlay=“False”
AreTransportControlsEnabled=“True”/>
Важливо: Налаштування MediaPlayerElement.Source на відносний URI (ms-appx/ms-resource) працює лише у програмі, укомплектованій за допомогою Windows Application Packaging Project. Якщо ваш додаток не використовує Windows Application Packaging Project, рекомендується перетворити відповідний ms-appx:/// URI на повністю розширений file:/// URI. Дивіться також розділи Налаштування джерела медіафайлів і Відкриття локальних медіафайлів далі у цій статті.
Елементи керування переміщенням медіафайлів
MediaPlayerElement має вбудовані елементи керування переміщенням, які керують відтворенням, зупинкою, паузою, гучністю, вимкненням звуку, пошуком/програванням, субтитрами та вибором звукової доріжки. Щоб увімкнути ці елементи керування, налаштуйте AreTransportControlsEnabled у значення true. Щоб вимкнути їх, налаштуйте AreTransportControlsEnabled у значення false. Елементи керування переміщенням представлені класом MediaTransportControls. Ви можете використовувати елементи керування переміщенням у звичайному стані або налаштувати їх у різний спосіб. Для отримання додаткової інформації див. посилання на клас MediaTransportControls та Створення власних елементів керування переміщенням.
Елементи керування переміщенням підтримують одно- та дворядні розмітки. Перший приклад тут – однорядний, з кнопкою відтворення/паузи, розташованою ліворуч від часової шкали медіа. Така розмітка найкраще підходить для вбудованого відтворення мультимедіа та компактних екранів.
Дворядне розташування елементів керування (показано нижче) рекомендується для більшості випадків використання, особливо на великих екранах. Така розмітка забезпечує більше місця для елементів керування та полегшує роботу користувача зі шкалою часу.
Керування системою переміщення медіаданих
MediaPlayerElement автоматично інтегрується з системними елементами керування переміщенням медіафайлів. Елементи керування переміщенням медіа у системі — це елементи керування, які з’являються після натискання апаратних медіакнопок, як-от медіакнопки на клавіатурі. Докладну інформацію можна знайти на сторінці SystemMediaTransportControls..
Налаштування джерела медіафайлів
Щоб відтворювати файли з мережі або файли, вбудовані в програму, встановіть для параметра Source значення MediaSource із зазначенням шляху до файлу.
Підказка: Щоб відкрити файли з інтернету, вам потрібно визначити можливість доступу до інтернету (Client) у маніфесті програми (Package.appxmanifest). Для отримання додаткової інформації про визначення можливостей див. статтю Визначення можливостей додатка.
Цей код спробує налаштувати параметр Source елемента MediaPlayerElement, визначеного у XAML на шляху до файлу, введеного у TextBox.
XAML
x:Name=“txtFilePath” Width=“400”
FontSize=“20”
KeyUp=“TxtFilePath_KeyUp”
Header=“File path”
PlaceholderText=“Enter file path”/>
C#
private void TxtFilePath_KeyUp(object sender, KeyRoutedEventArgs e)
{
if (e.Key == Windows.System.VirtualKey.Enter)
{
TextBox tbPath = sender as TextBox;
if (tbPath != null)
{
LoadMediaFromString(tbPath.Text);
}
}
}
private void LoadMediaFromString(string path)
{
try
{
Uri pathUri = new Uri(path);
mediaPlayerElement.Source = MediaSource.CreateFromUri(pathUri);
}
catch (Exception ex)
{
if (ex is FormatException)
{
// handle exception.
// For example: Log error or notify user problem with file
}
}
}
Щоб налаштувати джерело медіафайлу на вбудований у програму медіафайл, ініціалізуйте Uri за допомогою шляху з префіксом ms-appx:///, створіть MediaSource з цим Uri, а потім налаштуйте Source для Uri. Наприклад, для файлу з назвою video1.mp4, який розташований у підпапці Videos, шлях матиме такий вигляд: ms-appx:///Videos/video1.mp4.
Важливо: Налаштування MediaPlayerElement.Source на відносну URI (ms-appx/ms-resource) працює лише у додатку, запакованому за допомогою Windows Application Packaging Project.
Цей код налаштовує властивість Source елемента MediaPlayerElement визначеного раніше в XAML у значення ms-appx:///Videos/video1.mp4.
C#
private void LoadEmbeddedAppFile()
{
try
{
Uri pathUri = new Uri(“ms-appx:///Videos/video1.mp4”);
mediaPlayerElement.Source = MediaSource.CreateFromUri(pathUri);
}
catch (Exception ex)
{
if (ex is FormatException)
{
// handle exception.
// For example: Log error or notify user problem with file
}
}
}
Відкриття локальних медіафайлів
Щоб відкрити файли у локальній системі або зі сховища OneDrive, ви можете скористатися перемикачем FileOpenPicker, щоб отримати файл і параметром Source, щоб задати джерело медіафайлу, або отримати програмний доступ до користувацьких медіатек.
Якщо вашому додатку потрібен доступ без участі користувача до тек Музики або Відео, наприклад, якщо ви перераховуєте всі музичні або відеофайли з колекції користувача і відображаєте їх у вашому додатку, то вам потрібно визначити можливості Музичної бібліотеки й Відеобібліотеки. Для отримання додаткової інформації див. розділ Файли і теки у бібліотеках “Музика”, “Зображення” і “Відео”.
FileOpenPicker не потребує спеціальних можливостей для доступу до файлів у локальній файловій системі, таких як теки “Музика” або “Відео” користувача, оскільки користувач має повний контроль над тим, до якого файлу він отримує доступ. З точки зору безпеки та конфіденційності краще мінімізувати кількість можливостей, які використовує ваш додаток.
Щоб відкрити локальний медіафайл за допомогою FileOpenPicker:
1. Виберіть FileOpenPicker, щоб дозволити користувачеві обрати медіафайл.
Використайте клас FileOpenPicker для вибору медіафайлу. Встановіть FileTypeFilter, щоб вказати, які типи файлів відображатиме FileOpenPicker. Виберіть PickSingleFileAsync, щоб запустити програму вибору й отримати файл. to launch the file picker and get the file.
XAML
<MediaPlayerElement x:Name=“mediaPlayerElement”/> … <Button Content=“Choose file” Click=“Button_Click”/>
C#
private async void Button_Click(object sender, RoutedEventArgs e)
{
await SetLocalMedia();
}
async private System.Threading.Tasks.Task SetLocalMedia()
{
var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
WinRT.Interop.InitializeWithWindow.Initialize(openPicker, WinRT.Interop.WindowNative.GetWindowHandle(this));
openPicker.FileTypeFilter.Add(“.wmv”);
openPicker.FileTypeFilter.Add(“.mp4”);
openPicker.FileTypeFilter.Add(“.wma”);
openPicker.FileTypeFilter.Add(“.mp3”);
var file = await openPicker.PickSingleFileAsync();
// mediaPlayerElement is a MediaPlayerElement control defined in XAML
if (file != null)
{
mediaPlayerElement.Source = MediaSource.CreateFromStorageFile(file);
mediaPlayerElement.MediaPlayer.Play();
}
}
Налаштування джерела постера
Ви можете використовувати властивість PosterSource, щоб надати вашому MediaPlayerElement візуальне подання перед завантаженням медіафайлу. PosterSource – це зображення, наприклад, знімок екрана, постер фільму або обкладинка альбому, яке відображається замість медіафайлу. PosterSource відображається у таких ситуаціях:
1. Коли не вказано дійсне джерело. Наприклад, Source не задано, Source налаштоване на null, або джерело є недійсним (як у випадку, коли сталася помилка: MediaFailed.
2. Під час завантаження медіафайлу. Наприклад, вказано дійсне джерело, але ще не відбулася зміна MediaOpened.
3. Під час потокового передавання даних на інший пристрій.
4. Коли мультимедіа містить лише звук.
Ось MediaPlayerElement зі значенням Source, налаштованим на доріжку альбому, і PosterSource, налаштованим на зображення обкладинки альбому.
XAML
Source=“ms-appx:///Media/Track1.mp4” PosterSource=“ms-appx:///Media/AlbumCover.png”/>
Тримайте екран пристрою активним
Зазвичай пристрій приглушує екран (і зрештою вимикає його), щоб заощадити заряд акумулятора, коли користувач відсутній, але відеопрограмам потрібно тримати екран увімкненим, щоб користувач міг бачити відео. Щоб запобігти вимкненню дисплея, коли дії користувача більше не виявлено, наприклад, коли програма відтворює відео, ви можете використати DisplayRequest.RequestActive. Клас DisplayRequest дає змогу вказати Windows тримати дисплей увімкненим, щоб користувач міг бачити відео.
Для економії енергії та заряду акумулятора слід використовувати DisplayRequest.RequestRelease, щоб вимкнути запит на відображення, коли він більше не потрібен. Windows автоматично деактивує активні запити вашого додатка на відображення, коли ваш додаток зникає з екрана, і знову активує їх, коли ваш додаток повертається на передній план.
Нижче наведено кілька ситуацій, коли вам слід вимкнути запит на відображення:
- Відтворення відео призупиняється, наприклад, через дії користувача, буферизацію або налаштування через обмежену пропускну здатність.
- Відтворення зупиняється. Наприклад, відео завершено або презентацію закінчено.
- Виникла помилка відтворення. Наприклад, проблеми з підключенням до мережі або пошкоджений файл.
Щоб екран залишався активним:
C#
private DisplayRequest appDisplayRequest = null;
2. Виберіть RequestActive, щоб повідомити Windows про те, що програма вимагає, щоб екран залишався увімкненим.
3. Виберіть RequestRelease, щоб зняти запит на екран щоразу, коли відтворення відео зупинено, поставлено на паузу або перервано помилкою відтворення. Коли ваша програма більше не має активних запитів на екран, Windows заощаджує заряд акумулятора, зменшуючи яскравість екрана (і, зрештою, вимикаючи його), коли пристрій не використовується.
x:Name=“mediaPlayerElement” Source=“ms-appx:///Videos/video1.mp4”/>
C#
public sealed partial class MainWindow : Window
{
public DisplayRequest appDisplayRequest = null;
// using Microsoft.UI.Dispatching;
private DispatcherQueue dispatcherQueue = DispatcherQueue.GetForCurrentThread();
public MainWindow()
{
this.InitializeComponent();
mediaPlayerElement.MediaPlayer.PlaybackSession.PlaybackStateChanged +=
PlaybackSession_PlaybackStateChanged;
}
private void PlaybackSession_PlaybackStateChanged(MediaPlaybackSession sender, object args)
{
MediaPlaybackSession playbackSession = sender as MediaPlaybackSession;
if (playbackSession != null && playbackSession.NaturalVideoHeight != 0)
{
if (playbackSession.PlaybackState == MediaPlaybackState.Playing)
{
if (appDisplayRequest is null)
{
dispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
{
appDisplayRequest = new DisplayRequest();
appDisplayRequest.RequestActive();
});
}
}
else // PlaybackState is Buffering, None, Opening, or Paused.
{
if (appDisplayRequest is not null)
{
appDisplayRequest.RequestRelease();
appDisplayRequest = null;
}
}
}
}
}
Програмне керування медіаплеєром
Розширені сценарії відтворення медіафайлів
Зміна розміру та розширення відео
Використовуйте властивість Stretch, щоб змінювати те, як відеоконтент та/або PosterSource заповнює контейнер, в якому він знаходиться. За допомогою цієї властивості можна змінювати розмір і розтягувати відео залежно від значення Stretch. Стани Stretch подібні до налаштувань розміру зображення на багатьох телевізорах. Ви можете підключити цей параметр до кнопки й дозволити користувачеві вибирати, якому налаштуванню він віддає перевагу.
1. None не відображає власну роздільну здатність вмісту в його оригінальному розмірі. Це може призвести до обрізання частини відео або появи чорних смуг по краях відео.
2. Uniform рівномірно заповнює якомога більше простору зі збереженням співвідношення сторін і відеоконтенту. Це може призвести до появи горизонтальних або вертикальних чорних смуг по краях відео. Це схоже на широкоекранні режими.
3. UniformToFill заповнює весь простір зі збереженням співвідношення сторін. Це може призвести до обрізання частини відео. Це схоже на повноекранний режим.
4. Fill заповнює весь простір, але не зберігає співвідношення сторін. Відео не обрізається, але може відбутися розтягування. Це схоже на режими розтягування.
Тут використовується кнопка AppBarButton для перегляду параметрів розтягування (Stretch). Оператор switch перевіряє поточний стан властивості Stretch і встановлює його на наступне значення у переліку Stretch.Це дозволяє користувачеві циклічно перебирати різні стани розтягування.
XAML
Icon=“Trim”
Label=“Resize Video”
Click=“PictureSize_Click” />
C#
private void PictureSize_Click(object sender, RoutedEventArgs e)
{
switch (mediaPlayerElement.Stretch)
{
case Stretch.Fill:
mediaPlayerElement.Stretch = Stretch.None;
break;
case Stretch.None:
mediaPlayerElement.Stretch = Stretch.Uniform;
break;
case Stretch.Uniform:
mediaPlayerElement.Stretch = Stretch.UniformToFill;
break;
case Stretch.UniformToFill:
mediaPlayerElement.Stretch = Stretch.Fill;
break;
default:
break;
}
}
Увімкнення відтворення з невеликою затримкою
Налаштуйте властивість RealTimePlayback у значення true для елемента MediaPlayerElement.MediaPlayer, щоб дозволити елементу медіаплеєра зменшити початкову затримку при відтворенні. Це важливо для програм двосторонньої комунікації, а іноді може застосовуватися у деяких ігрових сценаріях. Зверніть увагу, що цей режим є більш ресурсомістким і менш енергоефективним.
У цьому прикладі створюється елемент MediaPlayerElement і налаштовується значення RealTimePlayback у true.
C#
MediaPlayerElement mediaPlayerElement = new MediaPlayerElement();
mediaPlayerElement.MediaPlayer.RealTimePlayback = true;
Схожі статті
Основи проєктування Windows-додатків.
Основні принципи оформлення вмісту для Windows додатків.