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ć Web przy użyciu identyfikatora 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 przy użyciu schematu identyfikatora filesystem:// URI.

MediaElement może używać kontrolek odtwarzania platformy, które są określane jako kontrolki 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.

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

Platforma	Implementacja odtwarzacza multimediów platformy
Android	ExoPlayer, wielkie podziękowania dla exoPlayerXamarin opiekunów!
iOS/macOS	AVPlayer
Windows	Mediaplayer

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. Następujący sposób:

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 początku pliku MauiProgram.cs

using CommunityToolkit.Maui.MediaElement;

Aby można było użyć MediaElement poprawnie UseMauiCommunityToolkitMediaElement metody, należy wywołać metodę MauiAppBuilder w klasie 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

Aby zainicjować aplikację MediaElement w systemie Android, LaunchModeActivity musi być ustawiona LaunchMode.SingleTask wartość i należy dodać ResizableActivity=true ją zgodnie z poniższym przykładem

[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 systemu iOS/Mac

Nie jest wymagana żadna konfiguracja.

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	Link	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.

Pomijanie przełącznika dyskretnego systemu iOS

W systemie iOS dźwięk odtwarzania elementu MediaElement jest domyślnie wyciszony, gdy użytkownik wyłączył przełącznik sprzętowy w trybie dyskretnym.

Aby obejść przełącznik dyskretny sprzętu w systemie iOS, dodaj następujące wiersze kodu do polecenia MauiProgram.cs. Dzięki temu dźwięk odtwarzania elementu MediaElement będzie zawsze słyszalny dla użytkownika niezależnie od sprzętowego przełącznika dyskretnego urządzenia.

public static class MauiProgram
{
    // ... Additonal Code Not Shown ... //

    public static MauiApp CreateMauiApp()
    {
        // ... Additonal Code Not Shown ... //
#if IOS
        AVAudioSession.SharedInstance().SetActive(true);
        AVAudioSession.SharedInstance().SetCategory(AVAudioSessionCategory.Playback);
#endif
        // ... Additonal Code Not Shown ... //
    }
}

Odtwarzanie nośników zdalnych

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 Source właściwość na identyfikator 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 nośnik zdefiniowany przez Source właściwość nie rozpoczyna się natychmiast po otwarciu nośnika. 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 ShouldShowPlaybackControls właściwość na falsewartość .

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 przy użyciu schematu identyfikatora filesystem:// URI.

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ąć embed:// prefiksy i 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 Resources/Raw folderu projektu .NET MAUI. Po dodaniu pliku w katalogu głównym identyfikator URI będzie .embed://MyFile.mp4

Możesz również umieścić pliki w podfolderach. Jeśli MyFile.mp4 identyfikator URI będzie znajdować się w Resources/Raw/MyVideos identyfikatorze URI, który będzie używany z elementem MediaElement , będzie to 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

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

• FromFile, zwraca FileMediaSource wystąpienie z argumentu string .
• FromUri, zwraca UriMediaSource wystąpienie z argumentu Uri .
• FromResource, zwraca ResourceMediaSource wystąpienie z argumentu string .

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

Uwaga

Gdy właściwość jest ustawiona Source w języku XAML, konwerter typów jest wywoływany w celu zwrócenia MediaSource wystąpienia 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 służy do określania pliku zdalnego nośnika z identyfikatora 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 FileMediaSource obiektu w języku XAML wywoływany jest konwerter typów w celu zwrócenia FileMediaSource wystąpienia z klasy string.

Zmiana współczynnika proporcji 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 film wideo zostanie w razie potrzeby dopasowany do obszaru wyświetlania, zachowując współczynnik proporcji.
• 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ące elementy członkowskie:

• None wskazuje, że obiekt nie zawiera nośnika MediaElement .
• Opening wskazuje, że MediaElement element jest weryfikowany i próbuje załadować określone źródło.
• Buffering wskazuje, że MediaElement nośnik jest ładowany do odtwarzania. Jego Position właściwość nie przechodzi w tym stanie. MediaElement Jeśli odtwarzany film wideo, będzie nadal wyświetlać ostatnią wyświetloną ramkę.
• Playing wskazuje, że MediaElement obiekt odtwarza źródło multimediów.
• Paused wskazuje, że MediaElement właściwość nie jest rozwijana Position . MediaElement Jeśli odtwarzany film wideo, nadal wyświetla bieżącą ramkę.
• Stopped wskazuje, że nośnik MediaElement zawiera, ale nie jest odtwarzany ani wstrzymany. Jego Position właściwość jest resetowany do wartości 0 i nie przechodzi.
• 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. MediaFailed Użyj zdarzenia, aby pobrać dodatkowe szczegóły.

Zazwyczaj nie jest konieczne zbadanie CurrentState właściwości podczas korzystania z MediaElement kontroli transportu. 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 Playmetody , Pausei Stop .

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

<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 Button obiekty. 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 .NET MAUI Triggers (Wyzwalacze MAUI platformy .NET).

Plik związany z kodem zawiera programy obsługi zdarzeń 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.

Implementowanie niestandardowej kontrolki woluminu

Kontrolki odtwarzania multimediów implementowane przez każdą platformę zawierają pasek głośności. Ten pasek przypomina suwak i pokazuje głośność nośnika. 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 Slider dane wiążą jego Value właściwość z właściwością VolumeMediaElement. Jest to możliwe, ponieważ Volume właściwość używa TwoWay powiązania. W związku z Value tym zmiana właściwości spowoduje zmianę Volume właściwości.

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)

MediaElement Czyszczenie zasobów

Aby zapobiec wyciekom pamięci, należy zwolnić zasoby programu MediaElement. Można to zrobić, odłączając program obsługi. Jeśli musisz to zrobić, zależy od tego, gdzie i jak używasz MediaElement aplikacji, ale zazwyczaj jeśli masz na MediaElement jednej stronie i nie odtwarzasz multimediów w tle, chcesz zwolnić zasoby, gdy użytkownik przechodzi z dala od strony.

Poniżej znajduje się fragment przykładowego kodu, który pokazuje, jak to zrobić. Najpierw pamiętaj, aby podłączyć Unloaded zdarzenie na stronie.

<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.FreeResourcesPage"
             Title="Free Resources"
             Unloaded="ContentPage_Unloaded">
    
    <toolkit:MediaElement x:Name="mediaElement"
                          ShouldAutoPlay="False"
                          ... />
</ContentPage>

Następnie w kodzie wywołaj metodę , aby odłączyć procedurę obsługi.

public partial class FreeResourcesPage : ContentPage
{
    void ContentPage_Unloaded(object? sender, EventArgs e)
    {
        // Stop and cleanup MediaElement when we navigate away
        mediaElement.Handler?.DisconnectHandler();
    }
}

Aby dowiedzieć się więcej na temat procedur obsługi, zobacz dokumentację programu .NET MAUI dotyczącą programów obsługi.

Właściwości

Właściwości	Type	Opis	Wartość domyślna
Aspekt	Aspekt	Określa tryb skalowania dla aktualnie załadowanego nośnika (wizualizacji). Jest to właściwość, która jest powiązana.	Aspect.AspectFit
CurrentState	MediaElementState	Wskazuje bieżący stan kontrolki. Jest to właściwość tylko do odczytu, powiązana.	MediaElementState.None
Czas trwania	TimeSpan	Wskazuje czas trwania aktualnie otwartego nośnika. Jest to właściwość tylko do odczytu, powiązana.	TimeSpan.Zero
Position	TimeSpan	Opisuje bieżący postęp przez czas odtwarzania nośnika. Jest to właściwość tylko do odczytu, powiązana. Jeśli chcesz ustawić metodę PositionSeekTo() , użyj metody .	TimeSpan.Zero
ShouldAutoPlay	bool	Wskazuje, czy odtwarzanie multimediów rozpocznie się automatycznie po ustawieniu Source właściwości. Jest to właściwość, która jest powiązana.	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ść, która jest powiązana.	false
ShouldKeepScreenOn	bool	Określa, czy ekran urządzenia powinien pozostać włączony podczas odtwarzania multimediów. Jest to właściwość, która jest powiązana.	false
Powinienmute	bool	Określa, czy dźwięk jest obecnie wyciszony. Jest to właściwość, która jest powiązana.	false
ShouldShowPlaybackControls	bool	Określa, czy są wyświetlane kontrolki odtwarzania platform. Jest to właściwość, która jest powiązana. 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 załadowanego do kontrolki.	null
Szybkość	double	Określa szybkość odtwarzania nośnika. 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, powiązana.	0
MediaWidth	int	Szerokość załadowanego nośnika w pikselach. Jest to właściwość tylko do odczytu, powiązana.	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ść, która jest powiązana.	1

Zdarzenia

Wydarzenie	opis
MediaOpened	Występuje po zweryfikowaniu i otwarciu strumienia multimediów.
MediaEnded	Występuje po zakończeniu odtwarzania MediaElement multimediów.
MediaFailed	Występuje, gdy występuje błąd skojarzony ze źródłem multimediów.
Positionchanged	Występuje, gdy Position wartość właściwości uległa zmianie.
SeekCompleted	Występuje, gdy punkt wyszukiwania żądanej operacji wyszukiwania jest gotowy do odtwarzania.

Metody

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

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 MAUI platformy .NET
• Suwak MAUI platformy .NET
• Android ExoPlayer: obsługiwane formaty multimediów
• iOS: obsługiwane formaty multimediów
• Windows: obsługiwane koderie
• Powiązania programu Android ExoPlayer