MediaElement

MediaElement to kontrolka do odtwarzania wideo i dźwięku. Nośniki obsługiwane przez platformę podstawową można odtwarzać z następujących źródeł:

• Sieć przy użyciu adresu URI (HTTP lub HTTPS).
• Zasób osadzony w aplikacji platformy przy użyciu schematu identyfikatora embed:// URI.
• Pliki pochodzące z lokalnego systemu plików aplikacji, korzystające ze schematu identyfikatora URI filesystem://.

MediaElement może używać kontrolek odtwarzania platformy, nazywanych kontrolkami transportu. Są one jednak domyślnie wyłączone i można je zastąpić własnymi mechanizmami kontroli transportu. Na poniższych zrzutach ekranu przedstawiono MediaElement odtwarzanie wideo za pomocą kontrolek transportu platformy:

Uwaga

MediaElement Jest dostępny w systemach iOS, Android, Windows, macOS i Tizen.

MediaElement używa następujących implementacji platformy.

Platforma	Implementacja odtwarzacza multimediów platformy
Android	ExoPlayer, wielkie podziękowania dla bibliotek systemu Android!
iOS/macOS	AVPlayer
Windows	Odtwarzacz multimedialny

Wprowadzenie

Aby korzystać z MediaElement funkcji zestawu narzędzi .NET MAUI Community Toolkit, wymagane są następujące kroki.

Instalowanie pakietu NuGet

Zanim będzie można używać MediaElement wewnątrz aplikacji, musisz zainstalować CommunityToolkit.Maui.MediaElement pakiet NuGet i dodać wiersz inicjowania w MauiProgram.cs. Jak następuje:

Nazwa pakietu: CommunityToolkit.Maui.MediaElement

Adres URL pakietu:https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement

Inicjowanie pakietu

Najpierw należy dodać instrukcję using na górze pliku MauiProgram.cs

using CommunityToolkit.Maui.MediaElement;

Aby poprawnie użyć MediaElement, metoda UseMauiCommunityToolkitMediaElement musi zostać wywołana na klasie MauiAppBuilder podczas uruchamiania aplikacji w pliku MauiProgram.cs. W poniższym przykładzie pokazano, jak to zrobić.

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMediaElement()

Aby uzyskać więcej informacji na temat tego, jak to zrobić, zapoznaj się ze stroną Wprowadzenie .

Inicjowanie specyficzne dla platformy

Aby uzyskać dostęp do MediaElement funkcji, wymagana jest następująca konfiguracja specyficzna dla platformy.

Android

Podczas używania MediaElement konieczne jest wykonanie następujących kroków:

Dodaj ResizableActivity i Launchmode do działania

[Activity(Theme = "@style/Maui.SplashTheme", ResizeableActivity = true, MainLauncher = true, LaunchMode = LaunchMode.SingleTask)]
public class MainActivity : MauiAppCompatActivity
{
}

Pełny przykład tej metody zawartej w aplikacji można znaleźć w przykładowej aplikacji .NET MAUI Community Toolkit

Katalizator mac

Edytuj Info.plist dla MacCatalyst i dodaj następujące klucze.

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
    <string>audio</string>
</array>
<key>NSLocalNetworkUsageDescription</key>
<string></string>

Ios

Edytuj Info.plist dla iOS i dodaj następujące klucze.

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

Windows

Nie jest wymagana żadna konfiguracja.

Tizen

Nie jest wymagana żadna konfiguracja.

Obsługiwane formaty

Obsługiwane formaty multimedialne mogą być różne dla poszczególnych platform. W niektórych przypadkach może to być nawet zależne od dostępnych dekodatorów lub zainstalowanych w systemie operacyjnym używanym podczas uruchamiania aplikacji. Aby uzyskać bardziej szczegółowe informacje na temat obsługiwanych formatów na każdej platformie, zapoznaj się z poniższymi linkami.

Platforma	Odnośnik	Uwagi
Android	Formaty obsługiwane przez program ExoPlayer
iOS/macOS	Obsługiwane formaty systemu iOS/macOS	Nie ma oficjalnej dokumentacji dotyczącej tego problemu
Windows	Formaty obsługiwane przez system Windows	W systemie Windows obsługiwane formaty są bardzo zależne od tego, jakie kodecze są instalowane na komputerze użytkownika
Tizen	Formaty obsługiwane przez tizen

Ważne

Jeśli użytkownik korzysta z wersji Windows N, domyślnie nie jest obsługiwane odtwarzanie wideo. Wersje Systemu Windows N nie mają zainstalowanych formatów odtwarzania wideo zgodnie z projektem.

Typowe scenariusze

W poniższych sekcjach opisano typowe scenariusze użycia dla programu MediaElement.

Odtwarzaj zdalne media

Obiekt MediaElement może odtwarzać pliki multimediów zdalnych przy użyciu schematów identyfikatorów URI HTTP i HTTPS. Można to zrobić, ustawiając właściwość Source na URI pliku multimedialnego.

<toolkit:MediaElement Source="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
              ShouldShowPlaybackControls="True" />

Ważne

Podczas odtwarzania źródeł zdalnych z punktów końcowych HTTP prawdopodobnie trzeba będzie wyłączyć środki zabezpieczeń systemu operacyjnego, które uniemożliwiają dostęp do niezabezpieczonych punktów końcowych sieci Web. Dotyczy to co najmniej systemów iOS i Android.

Domyślnie multimedia zdefiniowane przez właściwość Source nie są uruchamiane od razu po ich otwarciu. Aby włączyć automatyczne odtwarzanie multimediów, ustaw ShouldAutoPlay właściwość na true.

Kontrolki odtwarzania multimediów udostępniane przez platformę są domyślnie włączone i można je wyłączyć, ustawiając właściwość ShouldShowPlaybackControls na false.

Używanie metadanych

Element MediaElement może używać metadanych dla parametrów MediaElement.MetadataTitlei MediaElement.MetadataArtistMediaElement.MetadataArtworkUrl. Możesz ustawić tytuł lub artystę, aby pokazać, co jest obecnie odtwarzane na kontrolkach ekranu blokady dla systemu Windows, Mac Catalyst, iOS i Android. Możesz ustawić lokalny lub zdalny adres URL z grafiką na ekranie blokady. Aby uzyskać najlepszą jakość wyświetlania, powinno być co najmniej 1080P. Musi to być adres URL i musi być albo .jpg, albo .png

<toolkit:MediaElement 
    MetadataTitle="Title"
    MetadataArtist="Artist"
    MetadataArtworkUrl="http://www.myownpersonaldomain.com/image.jpg" />

    MediaElement.MetadataTitle="Title";
    MediaElement.MetadataArtist="Artist";
    MediaElement.MetadataArtworkUrl="http://www.myownpersonaldomain.com/image.jpg";

Ważne

Metadane można ustawić w kodzie XAML lub za nim. Jeśli ustawiasz to w kodzie, musisz ustawić źródło także w kodzie. Źródło powinno być ustawione jako ostatnie. Jeśli ustawisz metadane w języku XAML lub konstruktorze, tę notatkę można bezpiecznie zignorować.

Korzystanie z elementu TextureView

Element MediaElement może być używany TextureView na platformie Android. Domyślnym zachowaniem platformy jest użycie elementu SurfaceView. Użycie widoku tekstury dodaje możliwość obsługi przezroczystości i innych efektów. Ustawienie to dokonywane jest poprzez zmianę sposobu użycia konstruktora.

.UseMauiCommunityToolkitMediaElement(static options => 
{
				options.SetDefaultAndroidViewType(AndroidViewType.TextureView);
})

Można również ustawić TextureView dla każdego używanego elementu multimediów. Można to ustawić w XAML oraz w kodzie zaplecza. Użycie go w ten sposób spowoduje zastąpienie polecenia .UseMauiCommunityToolkitMediaElement() buildera.

var mediaElement = new MediaElement
{
    AndroidViewType = AndroidViewType.TextureView
}

<toolkit:MediaElement AndroidViewType="TextureView" />

Ważne

Nie zalecamy używania elementu TextureView, chyba że jest to konieczne. Jeśli ta opcja jest włączona i jest zalecana tylko dla tych, którzy potrzebują transparencji i innych zaawansowanych funkcji, mogą wystąpić problemy związane z wydajnością.

Odtwarzanie lokalnych multimediów

Nośniki lokalne można odtwarzać z następujących źródeł:

• Zasób osadzony w aplikacji platformy przy użyciu schematu identyfikatora embed:// URI.
• Pliki pochodzące z lokalnego systemu plików aplikacji, korzystające ze schematu identyfikatora URI filesystem://.

Uwaga

Skrót embed:// i filesystem:// działa tylko z języka XAML. W kodzie użyj odpowiednio poleceń MediaSource.FromResource() i MediaSource.FromFile() . Przy użyciu tych metod można pominąć prefiksy embed:// oraz filesystem://. Pozostała część ścieżki powinna być taka sama.

Odtwarzanie multimediów osadzonych w pakiecie aplikacji

Obiekt MediaElement może odtwarzać pliki multimedialne osadzone w pakiecie aplikacji przy użyciu schematu identyfikatora embed:// URI. Pliki multimedialne są osadzone w pakiecie aplikacji, umieszczając je w projekcie platformy.

Aby włączyć plik multimedialny do odtwarzania z zasobów lokalnych, dodaj plik do folderu Resources/Raw projektu .NET MAUI. Po dodaniu pliku w katalogu głównym, identyfikator URI będzie miał postać embed://MyFile.mp4.

Możesz również umieścić pliki w podfolderach. Gdyby MyFile.mp4 znajdował się w Resources/Raw/MyVideos, URI do użycia z MediaElement byłby embed://MyVideos/MyFile.mp4.

Poniżej przedstawiono przykład użycia tej składni w języku XAML.

<toolkit:MediaElement Source="embed://MyFile.mp4"
              ShouldShowPlaybackControls="True" />

Informacje o typach usługi MediaSource

Element MediaElement może odtwarzać media, ustawiając właściwość Source na zdalny lub lokalny plik multimedialny. Właściwość Source jest typu MediaSource, a ta klasa definiuje trzy metody statyczne:

• FromFile, zwraca FileMediaSource instancję na podstawie argumentu string.
• FromUri, zwraca UriMediaSource instancję na podstawie argumentu Uri.
• FromResource, zwraca ResourceMediaSource instancję na podstawie argumentu string.

Ponadto klasa MediaSource ma również operatory niejawne, które zwracają instancje MediaSource z argumentów string oraz Uri.

Uwaga

Gdy właściwość Source jest ustawiona w języku XAML, wywoływany jest konwerter typów, aby zwrócić wystąpienie MediaSource z klasy string lub Uri.

Klasa MediaSource ma również następujące klasy pochodne:

• FileMediaSource, który służy do określania lokalnego pliku multimedialnego z pliku string. Ta klasa ma Path właściwość, którą można ustawić na string. Ponadto ta klasa ma niejawne operatory do konwertowania string obiektu na FileMediaSource obiekt i FileMediaSource obiektu na stringobiekt .
• UriMediaSource, który jest używany do określania zdalnego pliku multimedialnego z URI. Ta klasa ma Uri właściwość, którą można ustawić na Uri.
• ResourceMediaSource, który służy do określania pliku osadzonego udostępnianego za pośrednictwem plików zasobów aplikacji. Ta klasa ma Path właściwość, którą można ustawić na string.

Uwaga

Po utworzeniu obiektu FileMediaSource w XAML wywoływany jest konwerter typów, który zwraca wystąpienie FileMediaSource z string.

Zmiana proporcji obrazu wideo

Właściwość Aspect określa sposób skalowania multimediów wideo w celu dopasowania do obszaru wyświetlania. Domyślnie ta właściwość jest ustawiona na element AspectFit członkowski wyliczenia, ale można ją ustawić na dowolny z Aspect elementów członkowskich wyliczenia:

• AspectFit wskazuje, że wideo zostanie w razie potrzeby wyświetlone w formacie z czarnymi pasami, aby dopasować je do obszaru wyświetlania, zachowując proporcje obrazu.
• AspectFill wskazuje, że klip wideo zostanie obcięty tak, aby wypełniał obszar wyświetlania, zachowując współczynnik proporcji.
• Fill wskazuje, że wideo zostanie rozciągnięte, aby wypełnić obszar wyświetlania.

Określanie MediaElement stanu

Klasa MediaElement definiuje właściwość powiązaną tylko do odczytu o nazwie CurrentState, typu MediaElementState. Ta właściwość wskazuje bieżący stan kontrolki, na przykład to, czy nośnik jest odtwarzany, czy wstrzymany, czy nie jest jeszcze gotowy do odtwarzania multimediów.

Wyliczenie MediaElementState definiuje następujących członków:

• None wskazuje, że obiekt nie zawiera nośnika MediaElement .
• Opening wskazuje, że MediaElement jest weryfikowany i podejmuje próbę załadowania określonego źródła.
• Buffering wskazuje, że MediaElement nośnik jest ładowany do odtwarzania. Jej Position właściwość nie posuwa się naprzód w tym stanie. Jeśli MediaElement odtwarzał film wideo, będzie nadal wyświetlać ostatnią klatkę.
• Playing wskazuje, że MediaElement odtwarza źródło multimediów.
• Paused wskazuje, że MediaElement nie rozwija swojej właściwości Position. Jeśli MediaElement odtwarzał wideo, to nadal wyświetla bieżącą klatkę.
• Stopped wskazuje, że MediaElement zawiera media, ale nie jest odtwarzany ani wstrzymany. Jego Position właściwość jest resetowana do wartości 0 i nie ulega przesunięciu.
• Failed wskazuje, że MediaElement nie można załadować lub odtworzyć nośnika. Taka sytuacja może wystąpić podczas próby załadowania nowego elementu nośnika podczas próby odtworzenia elementu nośnika lub przerwania odtwarzania multimediów z powodu awarii. Użyj zdarzenia MediaFailed, aby pobrać dodatkowe szczegóły.

Zazwyczaj nie jest konieczne przeglądanie właściwości CurrentState podczas korzystania z funkcji sterowania transportem MediaElement. Jednak ta właściwość staje się ważna podczas implementowania własnych mechanizmów kontroli transportu.

Implementowanie niestandardowych kontrolek transportu

Kontrolki transportu odtwarzacza multimedialnego obejmują przyciski, które wykonują funkcje Play, Pause i Stop. Te przyciski są zwykle identyfikowane ze znanymi ikonami, a nie tekstem, a funkcje Odtwarzania i wstrzymywania są zwykle łączone w jeden przycisk.

Domyślnie kontrolki odtwarzania MediaElement są wyłączone. Dzięki temu można kontrolować MediaElement programowo lub dostarczając własne mechanizmy kontroli transportu. W tym celu MediaElement obejmuje metody Play, Pause oraz Stop.

Poniższy przykład XAML przedstawia stronę zawierającą MediaElement oraz niestandardowe kontrolki transportu:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MediaElementDemos.CustomTransportPage"
             Title="Custom transport">
    <Grid>
        ...
        <toolkit:MediaElement x:Name="mediaElement"
                      ShouldAutoPlay="False"
                      ... />
        <HorizontalStackLayout BindingContext="{x:Reference mediaElement}"
                     ...>
            <Button Text="Play"
                    HorizontalOptions="Center"
                    Clicked="OnPlayPauseButtonClicked">
                <Button.Triggers>
                    <DataTrigger TargetType="Button"
                                 Binding="{Binding CurrentState}"
                                 Value="{x:Static toolkit:MediaElementState.Playing}">
                        <Setter Property="Text"
                                Value="Pause" />
                    </DataTrigger>
                    <DataTrigger TargetType="Button"
                                 Binding="{Binding CurrentState}"
                                 Value="{x:Static toolkit:MediaElementState.Buffering}">
                        <Setter Property="IsEnabled"
                                Value="False" />
                    </DataTrigger>
                </Button.Triggers>
            </Button>
            <Button Text="Stop"
                    HorizontalOptions="Center"
                    Clicked="OnStopButtonClicked">
                <Button.Triggers>
                    <DataTrigger TargetType="Button"
                                 Binding="{Binding CurrentState}"
                                 Value="{x:Static toolkit:MediaElementState.Stopped}">
                        <Setter Property="IsEnabled"
                                Value="False" />
                    </DataTrigger>
                </Button.Triggers>
            </Button>
        </HorizontalStackLayout>
    </Grid>
</ContentPage>

W tym przykładzie niestandardowe kontrolki transportu są definiowane jako obiekty Button. Jednak istnieją tylko dwa Button obiekty, z pierwszym Button reprezentującym odtwarzanie i wstrzymywanie, a drugi Button reprezentujący zatrzymanie. DataTriggerobiekty są używane do włączania i wyłączania przycisków oraz do przełączania pierwszego przycisku między odtwarzaniem i wstrzymaniem. Aby uzyskać więcej informacji na temat wyzwalaczy danych, zobacz Wyzwalacze .NET MAUI.

Plik code-behind zawiera obsługujące zdarzenia Clicked:

void OnPlayPauseButtonClicked(object sender, EventArgs args)
{
    if (mediaElement.CurrentState == MediaElementState.Stopped ||
        mediaElement.CurrentState == MediaElementState.Paused)
    {
        mediaElement.Play();
    }
    else if (mediaElement.CurrentState == MediaElementState.Playing)
    {
        mediaElement.Pause();
    }
}

void OnStopButtonClicked(object sender, EventArgs args)
{
    mediaElement.Stop();
}

Przycisk Odtwarzania można nacisnąć, gdy zostanie włączony, aby rozpocząć odtwarzanie. Naciśnięcie przycisku Wstrzymaj powoduje wstrzymanie odtwarzania. Naciśnięcie przycisku Zatrzymaj zatrzymuje odtwarzanie i zwraca położenie pliku multimedialnego na początku.

Zaimplementować niestandardowe sterowanie głośnością

Kontrolki odtwarzania multimediów implementowane przez każdą platformę zawierają pasek głośności. Ten pasek przypomina suwak i pokazuje głośność materiału. Ponadto można manipulować paskiem woluminu, aby zwiększyć lub zmniejszyć wolumin.

Niestandardowy pasek woluminu można zaimplementować przy użyciu elementu Slider, jak pokazano w poniższym przykładzie:

<StackLayout>
    <toolkit:MediaElement ShouldAutoPlay="False"
                          Source="{StaticResource AdvancedAsync}" />
    <Slider Maximum="1.0"
            Minimum="0.0"
            Value="{Binding Volume}"
            Rotation="270"
            WidthRequest="100" />
</StackLayout>

W tym przykładzie dane Slider wiążą swoją właściwość Value z właściwością VolumeMediaElement. Jest to możliwe, ponieważ Volume właściwość używa TwoWay powiązania. Zatem zmiana właściwości Value spowoduje zmianę właściwości Volume.

Uwaga

Właściwość Volume ma wywołanie zwrotne weryfikacji, które gwarantuje, że jego wartość jest większa lub równa 0,0 i mniejsza niż lub równa 1,0.

Aby uzyskać więcej informacji na temat korzystania z elementu Slider, zobacz .NET MAUI Slider (Suwak MAUI platformy .NET)

Właściwości

Nieruchomość	Typ	Opis	Wartość domyślna
Aspekt	Aspekt	Określa tryb skalowania dla aktualnie załadowanego nośnika wizualnego. Jest to właściwość powiązywalna.	Aspect.AspectFit
AktualnyStan	MediaElementState	Wskazuje bieżący stan kontrolki. Jest to właściwość tylko do odczytu, możliwa do powiązania.	MediaElementState.None
Czas trwania	TimeSpan	Wskazuje czas trwania aktualnie otwartego pliku multimedialnego. Jest to właściwość tylko do odczytu, możliwa do powiązania.	TimeSpan.Zero
Pozycja	TimeSpan	Opisuje bieżący postęp w czasie odtwarzania materiału. Jest to właściwość tylko do odczytu, możliwa do powiązania. Jeśli chcesz ustawić Position, użyj metody SeekTo().	TimeSpan.Zero
PowinnoOdtwarzaćAutomatycznie	bool	Wskazuje, czy odtwarzanie multimediów rozpocznie się automatycznie po ustawieniu Source właściwości. Jest to właściwość powiązywalna.	false
ShouldLoopPlayback	bool	Opisuje, czy aktualnie załadowane źródło multimediów powinno wznowić odtwarzanie od początku po osiągnięciu końca. Jest to właściwość powiązywalna.	false
PowinnoUtrzymywaćEkranWłączony	bool	Określa, czy ekran urządzenia powinien pozostać włączony podczas odtwarzania multimediów. Jest to właściwość powiązywalna.	false
Powinien wyciszyć	bool	Określa, czy dźwięk jest obecnie wyciszony. Jest to właściwość powiązywalna.	false
CzyPokazaćKontrolkiOdtwarzania	bool	Określa, czy wyświetlane są elementy sterujące odtwarzaniem platformy. Jest to właściwość powiązywalna. Należy pamiętać, że w systemach iOS i Windows kontrolki są wyświetlane tylko przez krótki okres po interakcji z ekranem. Nie ma możliwości, aby kontrolki były widoczne przez cały czas.	true
Źródło	MediaSource?	Źródło nośnika wczytanego do kontroli.	null
Szybkość	double	Określa szybkość odtwarzania mediów. Jest to właściwość, która jest powiązana	1
MediaHeight	int	Wysokość załadowanego nośnika w pikselach. Jest to właściwość tylko do odczytu, możliwa do powiązania. Nie są zgłaszane dla multimediów innych niż wizualizacje i nie zawsze mogą być wypełniane w systemie iOS/macOS dla zawartości przesyłanej strumieniowo na żywo.	0
MediaWidth	int	Szerokość załadowanego nośnika w pikselach. Jest to właściwość tylko do odczytu, możliwa do powiązania. Nie są zgłaszane dla multimediów innych niż wizualizacje i nie zawsze mogą być wypełniane w systemie iOS/macOS dla zawartości przesyłanej strumieniowo na żywo.	0
Objętość	double	Określa wolumin nośnika, który jest reprezentowany w skali liniowej z zakresu od 0 do 1. Jest to właściwość powiązywalna.	1

Zdarzenia

Wydarzenie	Opis
MediaOpened	Występuje po zweryfikowaniu i otwarciu strumienia multimediów.
Koniec odtwarzania	Występuje, gdy MediaElement zakończy odtwarzanie swojej zawartości multimedialnej.
Niepowodzenie Mediów	Występuje, gdy występuje błąd skojarzony ze źródłem multimediów.
ZmianaPozycji	Występuje, gdy Position wartość właściwości uległa zmianie.
SzukajZakończono	Występuje, gdy punkt docelowy żądanej operacji wyszukiwania jest gotowy do odtwarzania.

Metody

Wydarzenie	Opis
Odtwórz	Rozpoczyna odtwarzanie załadowanych multimediów.
Wstrzymanie	Wstrzymuje odtwarzanie aktualnego medium.
Zatrzymaj	Zatrzymuje odtwarzanie i resetuje położenie bieżącego nośnika.
SeekTo	Przyjmuje wartość TimeSpan, aby ustawić właściwość Position i wartość CancellationToken, aby anulować Task.

Przykłady

Przykłady tej kontrolki można znaleźć w akcji w przykładowej aplikacji zestawu narzędzi .NET MAUI Community Toolkit.

interfejs API

Kod źródłowy można MediaElement znaleźć w repozytorium GitHub zestawu narzędzi .NET MAUI Community Toolkit.

Pokrewne łącza

• Wyzwalacze .NET MAUI
• .NET MAUI Suwak
• Android ExoPlayer: obsługiwane formaty multimediów
• iOS: obsługiwane formaty multimediów
• Windows: obsługiwane koderie
• Powiązania programu Android ExoPlayer