MediaElement

MediaElement a video- és hanglejátszás vezérlője. Az alapul szolgáló platform által támogatott médiatartalmak a következő forrásokból játszhatók le:

• A weben, URI használatával (HTTP vagy HTTPS).
• A platformalkalmazásba beágyazott erőforrás, amely a embed:// URI-sémát használja.
• Az alkalmazás helyi fájlrendszeréből származó fájlok az filesystem:// URI-sémával.

MediaElement használhatja a platformlejátszási vezérlőket, amelyeket átviteli vezérlőknek neveznek. Alapértelmezés szerint azonban le vannak tiltva, és lecserélhetők a saját átviteli vezérlőire. Az alábbi képernyőképek mutatják a MediaElement videó lejátszását a platform lejátszási vezérlőivel.

A MediaElement a következő platformmegvalósításokat használja.

Első lépések

A .NET MAUI közösségi eszközkészlet MediaElement funkciójának használatához az alábbi lépések szükségesek.

NuGet-csomag telepítése

Mielőtt a MediaElement-t használni tudja az alkalmazásában, telepítenie kell a CommunityToolkit.Maui.MediaElement NuGet-csomagot, és hozzá kell adnia egy inicializációs sort a MauiProgram.csfájlhoz. Következőképpen:

csomag neve:CommunityToolkit.Maui.MediaElement

Csomag URL-címe:https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement

A csomag inicializálása

Először hozzá kell adni a felhasználói utasítást a MauiProgram.cs fájl elejéhez

using CommunityToolkit.Maui.MediaElement;

A MediaElement helyes használatához a UseMauiCommunityToolkitMediaElement metódust az MauiAppBuilder osztályban kell meghívni az alkalmazás MauiProgram.cs fájljának indításakor. Az alábbi példa bemutatja, hogyan hajthatja végre ezt.

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

Ennek módjáról további információt a Első lépések oldalon talál.

Platformspecifikus inicializálás

A MediaElement funkció eléréséhez a következő platformspecifikus beállítás szükséges.

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

 <service android:name="communityToolkit.maui.media.services" android:stopWithTask="true" android:exported="false" android:enabled="true" android:foregroundServiceType="mediaPlayback">
   <intent-filter>
     <action android:name="androidx.media3.session.MediaSessionService"/>
   </intent-filter>
 </service>

<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">26.0</SupportedOSPlatformVersion>

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.MEDIA_CONTENT_CONTROL" />

<service android:name="communityToolkit.maui.media.services" android:stopWithTask="true" android:exported="false" android:enabled="true" android:foregroundServiceType="mediaPlayback">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaSessionService"/>
    </intent-filter>
</service>
</application>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"/>
<uses-permission android:name="android.permission.MEDIA_CONTENT_CONTROL"/>

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

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

Támogatott formátumok

A támogatott multimédiás formátumok platformonként eltérőek lehetnek. Bizonyos esetekben akár attól is függ, hogy milyen dekóderek érhetők el vagy telepíthetők az alkalmazás futtatásakor használt operációs rendszeren. Az egyes platformokon támogatott formátumokról további információt az alábbi hivatkozásokon talál.

Gyakori forgatókönyvek

Az alábbi szakaszok a MediaElementgyakori használati forgatókönyveit ismertetik.

Távoli média lejátszása

A MediaElement a HTTP- és HTTPS URI-sémák használatával le tudja játszani a távoli médiafájlokat. Ez úgy érhető el, hogy a Source tulajdonságot a médiafájl URI-jára állítja:

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

Alapértelmezés szerint a Source tulajdonság által definiált média nem indul el azonnal a média megnyitása után. Az automatikus médialejátszás engedélyezéséhez állítsa a ShouldAutoPlay tulajdonságot true.

A platform által biztosított médialejátszási vezérlők alapértelmezés szerint engedélyezve vannak, és a ShouldShowPlaybackControls tulajdonság falsebeállításával letilthatók.

Metaadatok használata

A MediaElement metaadatokat használhat MediaElement.MetadataTitle, MediaElement.MetadataArtist és MediaElement.MetadataArtworkUrl. Beállíthatja a címet vagy az előadót, hogy megjelenítse, mi játszik jelenleg a Windows, a Mac Catalyst, az iOS és az Android zárolási vezérlőiben. Beállíthat egy helyi vagy távoli URL-címet a zárolási képernyőhöz tartozó grafikával. A legjobb minőség megjelenítéséhez legalább 1080P-nek kell lennie. Url-címnek kell lennie, és .jpg vagy .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";

Helyi média lejátszása

A helyi média a következő forrásokból játszható le:

• A platformalkalmazásba beágyazott erőforrás, amely a embed:// URI-sémát használja.
• Az alkalmazás helyi fájlrendszeréből származó fájlok az filesystem:// URI-sémával.

Az alkalmazáscsomagba beágyazott média lejátszása

A MediaElement lejátszhatják az alkalmazáscsomagba beágyazott médiafájlokat az embed:// URI-sémával. A médiafájlok beágyazódnak az alkalmazáscsomagba azáltal, hogy a platformprojektbe helyezik őket.

Ha engedélyezni szeretné egy médiafájl lejátszását a helyi erőforrásokból, adja hozzá a fájlt a .NET MAUI-projekt Resources/Raw mappájához. Ha hozzáad egy fájlt a gyökérfájlhoz, az URI embed://MyFile.mp4lesz.

A fájlokat almappákba is elhelyezheti. Ha MyFile.mp4 a Resources/Raw/MyVideos-ben lenne, akkor az URI, amit a MediaElement-vel használnánk, a embed://MyVideos/MyFile.mp4lenne.

Ennek a szintaxisnak az XAML-ben való használatára az alábbiakban talál példát.

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

A MediaSource típusainak ismertetése

A MediaElement a Source tulajdonságának távoli vagy helyi médiafájlra állításával játszhat le adathordozót. A Source tulajdonság MediaSourcetípusú, és ez az osztály három statikus metódust határoz meg:

• FromFileegy FileMediaSource példányt ad vissza egy string argumentumból.
• FromUriegy UriMediaSource példányt ad vissza egy Uri argumentumból.
• FromResourceegy ResourceMediaSource példányt ad vissza egy string argumentumból.

Emellett a MediaSource osztály implicit operátorokkal is rendelkezik, amelyek MediaSource példányokat ad vissza string és Uri argumentumokból.

A MediaSource osztály az alábbi származtatott osztályokkal is rendelkezik:

• FileMediaSource, amely egy helyi médiafájl megadására szolgál egy string. Ennek az osztálynak van egy Path tulajdonsága, amelyet be lehet állítani string-re. Ezen kívül ez az osztály implicit operátorokkal rendelkezik, amelyek egy string objektumot FileMediaSource objektummá konvertálnak, illetve egy FileMediaSource objektumot string-má.
• UriMediaSource, amely egy távoli médiafájl URI-ból való megadására szolgál. Ennek az osztálynak van egy Uri tulajdonsága, amelyet be lehet állítani Uri-re.
• ResourceMediaSource, amely egy beágyazott fájl megadására szolgál, amelyet az alkalmazás erőforrásfájljai biztosítanak. Ennek az osztálynak van egy Path tulajdonsága, amelyet be lehet állítani string-re.

Videó méretarányának módosítása

A Aspect tulajdonság határozza meg, hogy a videó adathordozója hogyan lesz skálázva a megjelenítési területnek megfelelően. Ez a tulajdonság alapértelmezés szerint az AspectFit enumerálási tagra van állítva, de a Aspect enumerálási tagok bármelyikére beállítható:

• AspectFit azt jelzi, hogy szükség esetén a videó betűboxba kerül, hogy elférjen a megjelenítési területen, miközben megőrzi az oldalarányt.
• AspectFill azt jelzi, hogy a videó úgy lesz kivágva, hogy kitöltse a megjelenítési területet, miközben megőrzi az oldalarányt.
• Fill azt jelzi, hogy a videó ki lesz nyújtva, hogy kitöltse a megjelenítési területet.

MediaElement állapotának meghatározása

A MediaElement osztály egy CurrentStatenevű írásvédett, MediaElementStatetípusú kötési tulajdonságot határoz meg. Ez a tulajdonság a vezérlő aktuális állapotát jelzi, például azt, hogy a média lejátszás vagy szüneteltetés alatt van, vagy még nem áll készen a média lejátszására.

A MediaElementState enumerálás a következő tagokat határozza meg:

• None azt jelzi, hogy a MediaElement nem tartalmaz adathordozót.
• Opening azt jelzi, hogy a MediaElement ellenőrzi és megpróbálja betölteni a megadott forrást.
• Buffering azt jelzi, hogy a MediaElement betölti az adathordozót lejátszásra. A Position tulajdonsága ebben az állapotban nem fejlődik tovább. Ha a MediaElement lejátszott egy videót, az továbbra is az utolsó megjelenített keretet jeleníti meg.
• Playing azt jelzi, hogy a MediaElement a médiaforrást játssza.
• Paused azt jelzi, hogy a MediaElement nem lépi túl a Position tulajdonságát. Ha a MediaElement videoképet játszott le, az továbbra is megjeleníti az aktuális keretet.
• Stopped azt jelzi, hogy a MediaElement médiatartalmat tartalmaz, de nincs lejátszva vagy szüneteltetve. A Position tulajdonsága 0-ra alaphelyzetbe áll, és nem halad előre.
• Failed azt jelzi, hogy a MediaElement nem tudta betölteni vagy lejátszani az adathordozót. Ez akkor fordulhat elő, ha egy új médiaelemet próbál betölteni, amikor megpróbálja lejátszani a médiaelemet, vagy ha a médialejátszás megszakad egy hiba miatt. A MediaFailed esemény használatával további részleteket is lekérhet.

A CurrentState átviteli vezérlők használatakor általában nem szükséges megvizsgálni a MediaElement tulajdonságot. Ez a tulajdonság azonban fontossá válik a saját átviteli vezérlők megvalósításakor.

Egyéni átviteli vezérlők implementálása

A médialejátszó átviteli vezérlői közé tartoznak a Lejátszás, Szüneteltetésés Leállításparancsot végrehajtó gombok. Ezek a gombok általában ismerős ikonokkal vannak azonosítva a szöveg helyett, és a Lejátszás és Szüneteltetés függvények általában egyetlen gombba vannak kombinálva.

Alapértelmezés szerint a MediaElement lejátszási vezérlők le vannak tiltva. Ez lehetővé teszi, hogy a MediaElement-t programozási úton vagy saját vezérlőelemekkel vezérelje. Ezt támogatva MediaElementPlay, Pauseés Stop metódusokat is tartalmaz.

Az alábbi XAML-példa egy MediaElement és egyéni átviteli vezérlőt tartalmazó oldalt mutat be:

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

Ebben a példában az egyéni átviteli vezérlők Button objektumokként vannak definiálva. Azonban csak két Button objektum van, az első Button a Lejátszás és a Szüneteltetés, a második Button pedig a Stop. DataTrigger objektumokat használnak a gombok engedélyezésére és letiltására, valamint az első gomb Lejátszás és Szüneteltetésközötti kapcsolására. Az adatindítókkal kapcsolatos további információkért lásd .NET MAUI-eseményindítók.

A kód-mögötti fájl tartalmazza a Clicked események kezelőit.

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

A Lejátszás gomb megnyomható, amint engedélyezve van, a lejátszás elkezdéséhez. A Szüneteltetés gomb lenyomása a lejátszás szünetelését eredményezi. A Leállítás gomb lenyomásával leáll a lejátszás, és visszaadja a médiafájl pozícióját az elejére.

Egyéni hangerő-vezérlés implementálása

Az egyes platformok által implementált médialejátszási vezérlők közé tartozik egy hangerőszabályzó. Ez a sáv egy csúszkára emlékeztet, és megjeleníti a média hangerőt. Emellett a hangerő növeléséhez vagy csökkentéséhez módosíthatja a hangerősávot.

Az egyéni kötetsáv egy Sliderhasználatával implementálható, ahogyan az alábbi példában látható.

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

Ebben a példában a Slider adat a Value tulajdonságát a VolumeMediaElement tulajdonságához köti. Ez azért lehetséges, mert a Volume tulajdonság egy TwoWay kötést használ. Ezért a Value tulajdonság módosítása a Volume tulajdonság megváltoztatását eredményezi.

További információért a Slider használatával kapcsolatban, lásd: .NET MAUI csúszka

MediaElement erőforrások törlése

A memóriavesztés elkerülése érdekében fel kell szabadítanod a MediaElementerőforrásait. Ez a kezelő leválasztásával valósítható meg. Ha ezt meg kell tennie, az attól függ, hogy hol és hogyan használja a MediaElement az alkalmazásban, de általában ha egy MediaElement van egy oldalon, és nem játszik médiatartalmat a háttérben, akkor szeretné felszabadítani az erőforrásokat, amikor a felhasználó eligazodik az oldaltól.

Az alábbiakban egy mintakódrészletet talál, amely bemutatja ennek módját. Először állítsa be az Unloaded eseményt az oldalán.

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

Ezután a mögöttes kódban hívja meg a metódust a kezelő leválasztásához.

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

A kezelőkkel kapcsolatos további információkért tekintse meg a .NET MAUI dokumentációját Kezelők.

Tulajdonságok

Események

Módszerek

Példák

A .NET MAUI Community Toolkit mintaalkalmazásbantalálhat példákat erre a vezérlőre működés közben.

API

A MediaElement forráskódját a .NET MAUI Community Toolkit GitHub-adattártalálhatja meg.

Kapcsolódó hivatkozások

• .NET MAUI-eseményindítók
• .NET MAUI csúszka
• Android ExoPlayer: Támogatott médiaformátumok
• iOS: Támogatott médiaformátumok
• Windows: Támogatott kodekek
• Android ExoPlayer-kötések