MediaElement
MediaElement
är en kontroll för att spela upp video och ljud. Media som stöds av den underliggande plattformen kan spelas upp från följande källor:
- Webben, med hjälp av en URI (HTTP eller HTTPS).
- En resurs som är inbäddad i plattformsprogrammet med hjälp av
embed://
URI-schema. - Filer som kommer från appens lokala filsystem med hjälp av
filesystem://
URI-schema.
MediaElement
kan använda plattformsuppspelningskontrollerna, som kallas transportkontroller. De är dock inaktiverade som standard och kan ersättas med dina egna transportkontroller. Följande skärmbilder visar MediaElement
spela upp en video med plattformstransportkontrollerna:
Not
MediaElement
finns på iOS, Android, Windows, macOS och Tizen.
MediaElement
använder följande plattformsimplementationer.
Plattform | Implementering av plattformsmediespelare |
---|---|
Android | ExoPlayer, stort tack till Android-biblioteken ansvariga! |
iOS/macOS | AVPlayer |
Windows | MediaPlayer |
Komma igång
Om du vill använda funktionen MediaElement
i .NET MAUI Community Toolkit krävs följande steg.
Installera NuGet-paketet
Innan du kan använda MediaElement
i ditt program måste du installera CommunityToolkit.Maui.MediaElement
NuGet-paketet och lägga till en initieringsrad i din MauiProgram.cs. På följande sätt:
Paketnamn:CommunityToolkit.Maui.MediaElement
url för -paket:https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement
Initiera paketet
Först måste using-satsen läggas till överst i din MauiProgram.cs-fil
using CommunityToolkit.Maui.MediaElement;
För att kunna använda MediaElement
korrekt måste UseMauiCommunityToolkitMediaElement
-metoden anropas på MauiAppBuilder
-klassen vid start av ett program MauiProgram.cs filen. I följande exempel visas hur du utför detta.
var builder = MauiApp.CreateBuilder();
builder
.UseMauiApp<App>()
.UseMauiCommunityToolkitMediaElement()
Mer information om hur du gör detta finns på sidan Komma igång.
Plattformsspecifik initiering
För att få åtkomst till MediaElement
funktioner krävs följande plattformsspecifika installation.
När du använder MediaElement
är det viktigt att utföra följande steg:
1. Lägg till ResizableActivity
och Launchmode
till aktivitet
[Activity(Theme = "@style/Maui.SplashTheme", ResizeableActivity = true, MainLauncher = true, LaunchMode = LaunchMode.SingleTask)]
public class MainActivity : MauiAppCompatActivity
{
}
2. Lägg till följande i AndroidManifest.xml
inuti taggen <application>
.
<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>
3. Uppdatera den lägsta android-API-versionen
I projektets .csproj
-fil uppdaterar du den lägsta android-API-versionen till 26.
<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">26.0</SupportedOSPlatformVersion>
4. Lägg till följande behörigheter i AndroidManifest.xml
<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" />
Här är ett exempel på obligatoriska inställningar i AndroidManifest.xml
<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"/>
Not
Den här ändringen av Android-manifestet aktiverar metadatavisning när en video spelas upp. Det ger stöd för meddelanden och är viktigt för att meddelanden ska fungera i alla relevanta API:er. Ändringen introducerar en tjänst och ger nödvändiga behörigheter.
Ett fullständigt exempel på den här metoden som ingår i ett program finns i .NET MAUI Community Toolkit Sample Application
Format som stöds
Multimedieformat som stöds kan vara olika per plattform. I vissa fall kan det till och med vara beroende av vilka avkodare som är tillgängliga eller installerade på operativsystemet som används när du kör appen. Mer detaljerad information om vilka format som stöds på varje plattform finns i länkarna nedan.
Plattform | Länk | Anteckningar |
---|---|---|
Android | ExoPlayer-format som stöds | |
iOS/macOS | format som stöds av iOS/macOS | Det finns ingen officiell dokumentation om detta |
Windows | Windows-format som stöds | I Windows är de format som stöds mycket beroende av vilka codecs som är installerade på användarens dator |
Tizen | Tizen-format som stöds |
Viktig
Om användaren använder en Windows N-utgåva stöds ingen videouppspelning som standard. Windows N-utgåvor har inga videouppspelningsformat installerade avsiktligt.
Vanliga scenarier
Följande avsnitt beskriver vanliga användningsscenarier för MediaElement
.
Spela upp fjärrmedia
En MediaElement
kan spela upp fjärranslutna mediefiler med hjälp av HTTP- och HTTPS-URI-scheman. Detta uppnås genom att ange egenskapen Source
till mediefilens URI:
<toolkit:MediaElement Source="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
ShouldShowPlaybackControls="True" />
Viktig
När du spelar upp fjärrkällor från HTTP-slutpunkter måste du förmodligen inaktivera operativsystemets säkerhetsåtgärder som förhindrar åtkomst till osäkra webbslutpunkter. Detta gäller för minst iOS och Android.
Media som definieras av egenskapen Source
börjar som standard inte spelas upp direkt när mediet har öppnats. Om du vill aktivera automatisk medieuppspelning anger du egenskapen ShouldAutoPlay
till true
.
Plattformsbaserade medieuppspelningskontroller är aktiverade som standard och kan inaktiveras genom att ange egenskapen ShouldShowPlaybackControls
till false
.
Använda metadata
En MediaElement
kan använda metadata för MediaElement.MetadataTitle
, MediaElement.MetadataArtist
och MediaElement.MetadataArtworkUrl
. Du kan ange rubriken eller artisten så att den visar vad som för närvarande spelas upp på låsskärmskontroller för Windows, Mac Catalyst, iOS och Android. Du kan ange en lokal url eller fjärr-URL med konstverk för låsskärmen. Det bör vara minst 1080P för bästa kvalitet som ska visas. Det måste vara en URL och vara antingen .jpg
eller .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";
Viktig
Du kan ange metadata i XAML eller bakom koden. Om du ställer in det i den bakomliggande koden måste du ange källan i den bakomliggande koden. Källan ska anges sist. Om du anger metadata i XAML eller konstruktor kan den här anteckningen ignoreras på ett säkert sätt.
Spela upp lokala mediafiler
Lokala medier kan spelas upp från följande källor:
- En resurs som är inbäddad i plattformsprogrammet med hjälp av
embed://
URI-schema. - Filer som kommer från appens lokala filsystem med hjälp av
filesystem://
URI-schema.
Notera
Förkortningarna embed://
och filesystem://
fungerar bara från XAML. Använd MediaSource.FromResource()
respektive MediaSource.FromFile()
i kod. Med dessa metoder kan du utelämna prefixen embed://
och filesystem://
. Resten av sökvägen bör vara densamma.
Spela upp mediet inbäddat i apppaketet
En MediaElement
kan spela upp mediefiler som är inbäddade i apppaketet med hjälp av embed://
URI-schema. Mediefiler bäddas in i apppaketet genom att de placeras i plattformsprojektet.
Om du vill aktivera en mediefil för uppspelning från de lokala resurserna lägger du till filen i mappen Resources/Raw
för ditt .NET MAUI-projekt. När en fil läggs till i roten blir URI:n embed://MyFile.mp4
.
Du kan också placera filer i undermappar. Om MyFile.mp4
skulle finnas i Resources/Raw/MyVideos
skulle URI:n för att använda den med MediaElement
vara embed://MyVideos/MyFile.mp4
.
Nedan visas ett exempel på hur du använder den här syntaxen i XAML.
<toolkit:MediaElement Source="embed://MyFile.mp4"
ShouldShowPlaybackControls="True" />
Förstå MediaSource-typer
En MediaElement
kan spela upp media genom att ange egenskapen Source
till en fjärr- eller lokal mediefil. Egenskapen Source
är av typen MediaSource
och den här klassen definierar tre statiska metoder:
-
FromFile
returnerar enFileMediaSource
instans från ettstring
argument. -
FromUri
returnerar enUriMediaSource
instans från ettUri
argument. -
FromResource
returnerar enResourceMediaSource
instans från ettstring
argument.
Dessutom har klassen MediaSource
implicita operatorer som returnerar MediaSource
instanser från string
och Uri
argument.
Anmärkning
När egenskapen Source
anges i XAML anropas en typkonverterare för att returnera en MediaSource
instans från en string
eller Uri
.
Klassen MediaSource
har också följande härledda klasser:
-
FileMediaSource
, som används för att ange en lokal mediefil från enstring
. Den här klassen har enPath
egenskap som kan anges till enstring
. Dessutom har den här klassen implicita operatorer för att konvertera enstring
till ettFileMediaSource
-objekt och ettFileMediaSource
-objekt till enstring
. -
UriMediaSource
, som används för att ange en fjärrmediefil från en URI. Den här klassen har enUri
egenskap som kan anges till enUri
. -
ResourceMediaSource
, som används för att ange en inbäddad fil som tillhandahålls via appens resursfiler. Den här klassen har enPath
egenskap som kan anges till enstring
.
Notera
När ett FileMediaSource
objekt skapas i XAML anropas en typkonverterare för att returnera en FileMediaSource
-instans från en string
.
Ändra bildproportionsgrad
Egenskapen Aspect
avgör hur videomedia ska skalas för att passa visningsområdet. Som standard är den här egenskapen inställd på AspectFit
uppräkningsmedlem, men den kan anges till någon av Aspect
uppräkningsmedlemmar:
-
AspectFit
anger att videon kommer att infogas med letterbox, om det behövs, för att passa in i visnings-området, samtidigt som bildförhållandet bevaras. -
AspectFill
anger att videon kommer att klippas så att den fyller visningsområdet, samtidigt som bildförhållandet bevaras. -
Fill
anger att videon kommer att sträckas ut för att fylla visningsområdet.
Fastställa status för MediaElement
Klassen MediaElement
definierar en skrivskyddad bindbar egenskap med namnet CurrentState
, av typen MediaElementState
. Den här egenskapen anger kontrollens aktuella status, till exempel om mediet spelas upp eller pausas eller om det ännu inte är redo att spela upp media.
Uppräkningen MediaElementState
definierar följande medlemmar:
-
None
anger attMediaElement
inte innehåller något media. -
Opening
anger attMediaElement
verifierar och försöker läsa in den angivna källan. -
Buffering
anger attMediaElement
läser in mediet för uppspelning. DessPosition
egenskap avancerar inte under det här tillståndet. OmMediaElement
spelar upp video fortsätter den att visa den senast visade bildrutan. -
Playing
anger attMediaElement
spelar upp mediekällan. -
Paused
anger attMediaElement
inte framskrider med sittPosition
-attribut. OmMediaElement
spelade upp video fortsätter den att visa den aktuella bildrutan. -
Stopped
anger attMediaElement
innehåller media men att det varken spelas upp eller pausas. EgenskapenPosition
återställs till 0 och går inte vidare. -
Failed
anger attMediaElement
inte kunde läsa in eller spela upp mediet. Detta kan inträffa när du försöker läsa in ett nytt medieobjekt, när du försöker spela upp medieobjektet eller när medieuppspelningen avbryts på grund av ett fel. Använd händelsenMediaFailed
för att hämta ytterligare information.
Det är vanligtvis inte nödvändigt att undersöka egenskapen CurrentState
när du använder MediaElement
transportkontroller. Den här egenskapen blir dock viktig när du implementerar dina egna transportkontroller.
Implementera anpassade transportkontroller
Transportkontrollerna för en mediaspelare innehåller knapparna som utför funktionerna Play, Pauseoch Stop. Dessa knappar identifieras vanligtvis med välbekanta ikoner snarare än text, och funktionerna Play och Pausa kombineras vanligtvis till en knapp.
Som standard är MediaElement
uppspelningskontroller inaktiverade. På så sätt kan du styra MediaElement
programmatiskt eller genom att ange egna transportkontroller. Till stöd för detta inkluderar MediaElement
metoderna Play
, Pause
och Stop
.
I följande XAML-exempel visas en sida som innehåller en MediaElement
och anpassade transportkontroller:
<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>
I det här exemplet definieras de anpassade transportkontrollerna som Button
objekt. Det finns dock bara två Button
objekt, där den första Button
representerar Play och Pauseoch den andra Button
som representerar Stop.
DataTrigger
objekt används för att aktivera och inaktivera knapparna och för att växla den första knappen mellan Spela upp och Pausa. Mer information om datautlösare finns i .NET MAUI-utlösare.
Bakomliggande kodfil har hanterare för Clicked
händelser:
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();
}
Knappen Spela upp kan tryckas ned, när den har aktiverats, för att starta uppspelningen. Om du trycker på knappen Pausa pausas uppspelningen. Om du trycker på knappen Stoppa stoppas uppspelningen och mediefilens position returneras till början.
Implementera en anpassad volymkontroll
Medieuppspelningskontroller som implementeras av varje plattform innehåller ett volymfält. Det här fältet liknar ett skjutreglage och visar medievolymen. Dessutom kan du ändra volymfältet för att öka eller minska volymen.
Ett anpassat volymfält kan implementeras med hjälp av en Slider
, som du ser i följande exempel:
<StackLayout>
<toolkit:MediaElement ShouldAutoPlay="False"
Source="{StaticResource AdvancedAsync}" />
<Slider Maximum="1.0"
Minimum="0.0"
Value="{Binding Volume}"
Rotation="270"
WidthRequest="100" />
</StackLayout>
I det här exemplet binder Slider
-data sin egenskap Value
till egenskapen Volume
för MediaElement
. Detta är möjligt eftersom egenskapen Volume
använder en TwoWay
bindning. Om du ändrar egenskapen Value
ändras därför egenskapen Volume
.
Notera
Egenskapen Volume
har ett valideringsåteranrop som säkerställer att dess värde är större än eller lika med 0,0 och mindre än eller lika med 1.0.
Mer information om hur du använder en Slider
finns i .NET MAUI Slider
Rensa MediaElement
resurser
För att förhindra minnesläckor måste du frigöra resurserna för MediaElement
. Detta kan göras genom att koppla från hanteraren.
Var du behöver göra detta beror på var och hur du använder MediaElement
i din app, men vanligtvis om du har en MediaElement
på en enda sida och inte spelar upp media i bakgrunden, vill du frigöra resurserna när användaren navigerar bort från sidan.
Nedan hittar du ett kodfragment med exempelkod som visar hur du gör detta. Först, se till att koppla in händelsen Unloaded
på din sida.
<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>
I koden bakom anropar du sedan metoden för att koppla från hanteraren.
public partial class FreeResourcesPage : ContentPage
{
void ContentPage_Unloaded(object? sender, EventArgs e)
{
// Stop and cleanup MediaElement when we navigate away
mediaElement.Handler?.DisconnectHandler();
}
}
Mer information om hanterare finns i .NET MAUI-dokumentationen om -hanterare.
Egenskaper
Egenskap | Typ | Beskrivning | Standardvärde |
---|---|---|---|
Aspekt | Aspekt | Avgör skalningsläget för de (visuella) media som för närvarande läses in. Det här är en bindbar egenskap. | Aspect.AspectFit |
Nuvarande tillstånd | MediaElementState |
Visar aktuell status för kontrollen. Det här är en skrivskyddad, bindbar egenskap. | MediaElementState.None |
Varaktighet | TimeSpan |
Anger varaktigheten för den mediafil som är öppnad nu. Det här är en skrivskyddad, bindbar egenskap. | TimeSpan.Zero |
Position | TimeSpan |
Beskriver det aktuella förloppet genom mediets uppspelningstid. Det här är en skrivskyddad, bindbar egenskap. Om du vill ange Position använder du metoden SeekTo() . |
TimeSpan.Zero |
ShouldAutoPlay | bool |
Anger om medieuppspelningen startar automatiskt när egenskapen Source har angetts. Det här är en bindbar egenskap. |
false |
ShouldLoopPlayback | bool |
Beskriver om den aktuella inlästa mediekällan ska återuppta uppspelningen från början när den har nått sitt slut. Det här är en bindbar egenskap. | false |
SkaHållaSkärmenPå | bool |
Avgör om enhetens skärm ska vara på under medieuppspelning. Det här är en bindbar egenskap. | false |
ShouldMute | bool |
Avgör om ljudet för närvarande är avstängt. Det här är en bindbar egenskap. | false |
SkaVisaUppspelningskontroller | bool |
Avgör om uppspelningskontrollerna för plattformar visas. Det här är en bindbar egenskap. Observera att kontrollerna i iOS och Windows endast visas under en kort period efter att de har interagerat med skärmen. Det går inte att hålla kontrollerna synliga hela tiden. | true |
Källa | MediaSource? |
Källan för mediet som lästs in i kontrollen. | null |
Hastighet | double |
Avgör uppspelningshastigheten för mediet. Det här är en bindbar egenskap | 1 |
MediaHeight | int |
Höjden på det inlästa mediet i bildpunkter. Det här är en skrivskyddad, bindbar egenskap. Rapporteras inte för icke-visuella medier och kanske inte alltid fylls i i iOS/macOS för liveuppspelat innehåll. | 0 |
MediaWidth | int |
Bredden på det inlästa mediet i bildpunkter. Det här är en skrivskyddad, bindbar egenskap. Rapporteras inte för icke-visuella medier och kanske inte alltid fylls i i iOS/macOS för liveuppspelat innehåll. | 0 |
Volym | double |
Avgör medievolymen, som representeras på en linjär skala mellan 0 och 1. Det här är en bindbar egenskap. | 1 |
Evenemang
Händelse | Beskrivning |
---|---|
MediaOpened | Inträffar när medieströmmen har verifierats och öppnats. |
Media avslutat | Inträffar när MediaElement har spelat upp media. |
MediaFailed | Inträffar när det finns ett fel som är associerat med mediekällan. |
PositionÄndrad | Inträffar när Position -egenskapsvärdet har ändrats. |
Sökning slutförd | Inträffar när sökpunkten för en begärd sökåtgärd är redo för uppspelning. |
Metoder
Händelse | Beskrivning |
---|---|
Leka | Börjar spela upp det inlästa mediet. |
Paus | Pausar uppspelningen av det aktuella mediet. |
Stopp | Stoppar uppspelningen och återställer positionen för det aktuella mediet. |
SeekTo | Tar ett TimeSpan -värde för att ställa in egenskapen Position till ett visst värde och använder en CancellationToken för att avbryta Task . |
Exempel
Du hittar exempel på den här kontrollen i praktiken i .NET MAUI Community Toolkit Sample Application.
API
Du hittar källkoden för MediaElement
på github-lagringsplatsen .NET MAUI Community Toolkit.
Relaterade länkar
.NET MAUI Community Toolkit