MediaElement
MediaElement
è un controllo per la riproduzione di video e audio. I supporti supportati dalla piattaforma sottostante possono essere riprodotti dalle origini seguenti:
- Il Web, usando un URI (HTTP o HTTPS).
- Una risorsa incorporata nell'applicazione della piattaforma, usando lo
embed://
schema URI. - File provenienti dal file system locale dell'app, usando lo
filesystem://
schema URI.
MediaElement
può usare i controlli di riproduzione della piattaforma, detti controlli di trasporto. Tuttavia, sono disabilitati per impostazione predefinita e possono essere sostituiti con i propri controlli di trasporto. Gli screenshot seguenti mostrano MediaElement
la riproduzione di un video con i controlli di trasporto della piattaforma:
Nota
MediaElement
è disponibile in iOS, Android, Windows, macOS e Tizen.
MediaElement
usa le implementazioni della piattaforma seguenti.
Piattaforma | Implementazione del lettore multimediale della piattaforma |
---|---|
Android | exoPlayer, grazie ai gestori librerie Android di! |
iOS/macOS | AVPlayer |
Finestre | MediaPlayer |
Introduzione
Per usare la MediaElement
funzionalità di .NET MAUI Community Toolkit, sono necessari i passaggi seguenti.
Installare il pacchetto NuGet
Prima di poter usare MediaElement
all'interno dell'applicazione, è necessario installare il CommunityToolkit.Maui.MediaElement
pacchetto NuGet e aggiungere una riga di inizializzazione nel MauiProgram.cs. Come indicato di seguito:
Nome pacchetto: CommunityToolkit.Maui.MediaElement
URL pacchetto:https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement
Inizializzazione del pacchetto
Prima di tutto l'istruzione using deve essere aggiunta all'inizio del file MauiProgram.cs
using CommunityToolkit.Maui.MediaElement;
Per usare correttamente il MediaElement
UseMauiCommunityToolkitMediaElement
metodo deve essere chiamato sulla classe durante il MauiAppBuilder
bootstrap di un'applicazione il file MauiProgram.cs . Nell'esempio seguente viene illustrato come eseguire questa operazione.
var builder = MauiApp.CreateBuilder();
builder
.UseMauiApp<App>()
.UseMauiCommunityToolkitMediaElement()
Per altre informazioni su come eseguire questa operazione, vedere la pagina Attività iniziali .
Inizializzazione specifica della piattaforma
Per accedere alla MediaElement
funzionalità, è necessaria la configurazione specifica della piattaforma seguente.
Quando si usa MediaElement
è essenziale eseguire i passaggi seguenti:
1. Aggiungere ResizableActivity
e Launchmode
all'attività
[Activity(Theme = "@style/Maui.SplashTheme", ResizeableActivity = true, MainLauncher = true, LaunchMode = LaunchMode.SingleTask)]
public class MainActivity : MauiAppCompatActivity
{
}
2. Aggiungere quanto segue all'interno AndroidManifest.xml
del <application>
tag.
<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. Aggiornare la versione minima dell'API Android
Nel file .csproj
del progetto aggiornare la versione minima dell'API Android alla versione 26.
<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">26.0</SupportedOSPlatformVersion>
4. Aggiungere le autorizzazioni seguenti per 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" />
Di seguito è riportato un esempio di impostazioni obbligatorie in 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"/>
Nota
Questa modifica al manifesto Android abilita la visualizzazione dei metadati durante la riproduzione di un video. Fornisce supporto per le notifiche ed è essenziale per il funzionamento delle notifiche in tutte le API pertinenti. La modifica introduce un servizio e concede le autorizzazioni necessarie.
Per un esempio completo di questo metodo incluso in un'applicazione, vedere l'applicazione di esempio .NET MAUI Community Toolkit
Formati supportati:
I formati multimediali supportati possono essere diversi per ogni piattaforma. In alcuni casi può anche dipendere da quali decodificatori sono disponibili o installati nel sistema operativo usato durante l'esecuzione dell'app. Per informazioni più dettagliate sui formati supportati in ogni piattaforma, vedere i collegamenti seguenti.
Piattaforma | Collega | Note |
---|---|---|
Android | Formati supportati da ExoPlayer | |
iOS/macOS | Formati supportati per iOS/macOS | Nessuna documentazione ufficiale su questo esiste |
Finestre | Formati supportati da Windows | In Windows i formati supportati dipendono molto dai codec installati nel computer dell'utente |
Tizen | Formati supportati da Tizen |
Importante
Se l'utente usa un'edizione di Windows N, per impostazione predefinita non è supportata alcuna riproduzione video. Le edizioni di Windows N non hanno formati di riproduzione video installati dalla progettazione.
Scenari comuni
Le sezioni seguenti illustrano gli scenari di utilizzo comuni per .MediaElement
Riprodurre supporti remoti
Un MediaElement
oggetto può riprodurre file multimediali remoti usando gli schemi URI HTTP e HTTPS. Questa operazione viene eseguita impostando la Source
proprietà sull'URI del file multimediale:
<toolkit:MediaElement Source="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
ShouldShowPlaybackControls="True" />
Importante
Quando si giocano origini remote da endpoint HTTP, è probabile che sia necessario disabilitare le misure di sicurezza del sistema operativo che impediscono l'accesso agli endpoint Web non sicuri. Questo vale per almeno iOS e Android.
Per impostazione predefinita, il supporto definito dalla Source
proprietà non inizia immediatamente la riproduzione dopo l'apertura del supporto. Per abilitare la riproduzione automatica dei contenuti multimediali, impostare la ShouldAutoPlay
proprietà su true
.
I controlli di riproduzione multimediale forniti dalla piattaforma sono abilitati per impostazione predefinita e possono essere disabilitati impostando la ShouldShowPlaybackControls
proprietà su false
.
Uso di metadati
Un MediaElement
oggetto può usare i metadati per MediaElement.MetadataTitle
e MediaElement.MetadataArtist
MediaElement.MetadataArtworkUrl
. Puoi impostare il titolo o l'artista per mostrare cosa sta attualmente riproducendo nei controlli lockscreen per Windows, Mac Catalyst, iOS e Android. È possibile impostare un URL locale o remoto con la grafica per la schermata di blocco. Deve essere almeno 1080P per la migliore qualità da visualizzare. Deve essere un URL e essere .jpg
o .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";
Importante
È possibile impostare i metadati in XAML o code-behind. Se la si imposta nel code-behind, è necessario impostare l'origine nel code-behind. L'origine deve essere impostata per ultima. Se imposti i metadati in XAML o nel costruttore, questa nota può essere ignorata in modo sicuro.
Riprodurre elementi multimediali locali
I supporti locali possono essere riprodotti dalle origini seguenti:
- Una risorsa incorporata nell'applicazione della piattaforma, usando lo
embed://
schema URI. - File provenienti dal file system locale dell'app, usando lo
filesystem://
schema URI.
Nota
La sintassi abbreviata embed://
e filesystem://
funziona solo da XAML. Nel codice usare MediaSource.FromResource()
e MediaSource.FromFile()
rispettivamente. Usando questi metodi, è possibile omettere i embed://
prefissi e filesystem://
. Il resto del percorso deve essere lo stesso.
Riprodurre elementi multimediali incorporati nel pacchetto dell'app
Un MediaElement
oggetto può riprodurre file multimediali incorporati nel pacchetto dell'app, usando lo embed://
schema URI. I file multimediali vengono incorporati nel pacchetto dell'app inserendoli nel progetto della piattaforma.
Per abilitare un file multimediale per la riproduzione dalle risorse locali, aggiungere il file alla Resources/Raw
cartella del progetto MAUI .NET. Quando un file viene aggiunto nella radice, l'URI sarà embed://MyFile.mp4
.
È anche possibile inserire file nelle sottocartelle. Se MyFile.mp4
si trova in Resources/Raw/MyVideos
, l'URI da usare con MediaElement
sarebbe embed://MyVideos/MyFile.mp4
.
Di seguito è riportato un esempio di come usare questa sintassi in XAML.
<toolkit:MediaElement Source="embed://MyFile.mp4"
ShouldShowPlaybackControls="True" />
Informazioni sui tipi MediaSource
Un MediaElement
oggetto può riprodurre elementi multimediali impostandone la Source
proprietà su un file multimediale remoto o locale. La Source
proprietà è di tipo MediaSource
e questa classe definisce tre metodi statici:
-
FromFile
, restituisce un'istanzaFileMediaSource
di da unstring
argomento . -
FromUri
, restituisce un'istanzaUriMediaSource
di da unUri
argomento . -
FromResource
, restituisce un'istanzaResourceMediaSource
di da unstring
argomento .
Inoltre, la MediaSource
classe dispone anche di operatori impliciti che restituiscono MediaSource
istanze da string
e Uri
argomenti.
Nota
Quando la Source
proprietà è impostata in XAML, viene richiamato un convertitore di tipi per restituire un'istanza MediaSource
da un string
oggetto o Uri
.
La MediaSource
classe include anche queste classi derivate:
-
FileMediaSource
, usato per specificare un file multimediale locale da un oggettostring
. Questa classe ha unaPath
proprietà che può essere impostata su .string
Inoltre, questa classe include operatori impliciti per convertire un oggettostring
in unFileMediaSource
oggetto e unFileMediaSource
oggetto in un oggettostring
. -
UriMediaSource
, usato per specificare un file multimediale remoto da un URI. Questa classe ha unaUri
proprietà che può essere impostata su .Uri
-
ResourceMediaSource
, usato per specificare un file incorporato fornito tramite i file di risorse dell'app. Questa classe ha unaPath
proprietà che può essere impostata su .string
Nota
Quando un FileMediaSource
oggetto viene creato in XAML, viene richiamato un convertitore di tipi per restituire un'istanza FileMediaSource
da un oggetto string
.
Modificare le proporzioni video
La Aspect
proprietà determina il modo in cui i supporti video verranno ridimensionati per adattarsi all'area di visualizzazione. Per impostazione predefinita, questa proprietà è impostata sul AspectFit
membro di enumerazione, ma può essere impostata su uno dei membri dell'enumerazione Aspect
:
-
AspectFit
indica che il video verrà sottoposto a letterboxing, se necessario, per adattarsi all'area di visualizzazione, mantenendo al tempo stesso le proporzioni. -
AspectFill
indica che il video verrà ritagliato in modo che riempia l'area di visualizzazione, mantenendo al tempo stesso le proporzioni. -
Fill
indica che il video verrà esteso per riempire l'area di visualizzazione.
Determinare MediaElement
lo stato
La MediaElement
classe definisce una proprietà associabile di sola lettura denominata CurrentState
, di tipo MediaElementState
. Questa proprietà indica lo stato corrente del controllo, ad esempio se il supporto è in riproduzione o in pausa o se non è ancora pronto per riprodurre il supporto.
L'enumerazione MediaElementState
definisce i membri seguenti:
-
None
indica che l'oggettoMediaElement
non contiene supporti. -
Opening
indica che staMediaElement
convalidando e tentando di caricare l'origine specificata. -
Buffering
indica che staMediaElement
caricando il supporto per la riproduzione. La proprietàPosition
non avanza durante questo stato. Se ilMediaElement
video è in riproduzione, continua a visualizzare l'ultimo fotogramma visualizzato. -
Playing
indica che staMediaElement
riproducendo l'origine multimediale. -
Paused
indica che l'oggettoMediaElement
non avanza la relativaPosition
proprietà. Se ilMediaElement
video è in riproduzione, continua a visualizzare il fotogramma corrente. -
Stopped
indica che contieneMediaElement
supporti, ma non viene riprodotto o sospeso. La proprietàPosition
viene reimpostata su 0 e non avanza. -
Failed
indica che l'oggettoMediaElement
non è riuscito a caricare o riprodurre il supporto. Ciò può verificarsi durante il tentativo di caricare un nuovo elemento multimediale quando si tenta di riprodurre l'elemento multimediale o quando la riproduzione multimediale viene interrotta a causa di un errore. Usare l'eventoMediaFailed
per recuperare dettagli aggiuntivi.
In genere non è necessario esaminare la CurrentState
proprietà quando si usano i controlli di MediaElement
trasporto. Tuttavia, questa proprietà diventa importante quando si implementano controlli di trasporto personalizzati.
Implementare controlli di trasporto personalizzati
I controlli di trasporto di un lettore multimediale includono i pulsanti che eseguono le funzioni Play, Pause e Stop. Questi pulsanti sono identificati in genere con icone note anziché testo e le funzioni di riproduzione e pausa sono in genere unite in un unico pulsante.
Per impostazione predefinita, i MediaElement
controlli di riproduzione sono disabilitati. Ciò consente di controllare l'oggetto a MediaElement
livello di codice o fornendo controlli di trasporto personalizzati. A supporto di questo, include MediaElement
i Play
metodi , Pause
e Stop
.
L'esempio XAML seguente mostra una pagina che contiene controlli MediaElement
di trasporto personalizzati e :
<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>
In questo esempio i controlli di trasporto personalizzati vengono definiti come Button
oggetti . Esistono tuttavia solo due Button
oggetti, con il primo Button
che rappresenta Play e Pause e il secondo Button
che rappresenta Stop.
DataTrigger
gli oggetti vengono usati per abilitare e disabilitare i pulsanti e per cambiare il primo pulsante tra Play e Pause. Per altre informazioni sui trigger di dati, vedere Trigger MAUI .NET.
Il file code-behind include i gestori per gli Clicked
eventi:
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();
}
Il pulsante Riproduci può essere premuto, una volta abilitato, per avviare la riproduzione. Premendo il pulsante Sospendi si ottiene la sospensione della riproduzione. Premendo il pulsante Arresta la riproduzione viene arrestata e viene restituita la posizione del file multimediale all'inizio.
Implementare un controllo volume personalizzato
I controlli di riproduzione multimediale implementati da ogni piattaforma includono una barra del volume. Questa barra è simile a un dispositivo di scorrimento e mostra il volume dei supporti. Inoltre, è possibile modificare la barra del volume per aumentare o diminuire il volume.
È possibile implementare una barra del volume personalizzata usando un Slider
oggetto , come illustrato nell'esempio seguente:
<StackLayout>
<toolkit:MediaElement ShouldAutoPlay="False"
Source="{StaticResource AdvancedAsync}" />
<Slider Maximum="1.0"
Minimum="0.0"
Value="{Binding Volume}"
Rotation="270"
WidthRequest="100" />
</StackLayout>
In questo esempio, i dati associano la Slider
relativa proprietà alla Value
proprietà dell'oggetto Volume
MediaElement
. Ciò è possibile perché la Volume
proprietà utilizza un'associazione TwoWay
. Pertanto, la modifica della Value
proprietà comporterà la modifica della Volume
proprietà.
Nota
La Volume
proprietà dispone di un callback di convalida che garantisce che il relativo valore sia maggiore o uguale a 0,0 e minore o uguale a 1,0.
Per altre informazioni sull'uso di un dispositivo di Slider
scorrimento MAUI di .NET, vedere .NET MAUI Slider
Pulire le MediaElement
risorse
Per evitare perdite di memoria, è necessario liberare le risorse di MediaElement
. Questa operazione può essere eseguita disconnettendo il gestore.
Dove è necessario eseguire questa operazione dipende da dove e come si usa MediaElement
nell'app, ma in genere se si dispone di un MediaElement
oggetto in una singola pagina e non si riproduce elementi multimediali in background, si vogliono liberare le risorse quando l'utente si sposta dalla pagina.
Di seguito è riportato un frammento di codice di esempio che illustra come eseguire questa operazione. Prima di tutto, assicurarsi di associare l'evento Unloaded
nella pagina.
<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>
Quindi nel code-behind chiamare il metodo per disconnettere il gestore.
public partial class FreeResourcesPage : ContentPage
{
void ContentPage_Unloaded(object? sender, EventArgs e)
{
// Stop and cleanup MediaElement when we navigate away
mediaElement.Handler?.DisconnectHandler();
}
}
Per altre informazioni sui gestori, vedere la documentazione di .NET MAUI sui gestori.
Proprietà
Proprietà | Type | Descrizione | Valore predefinito |
---|---|---|---|
Aspetto | Aspetto | Determina la modalità di ridimensionamento per il supporto (visivo) attualmente caricato. Si tratta di una proprietà associabile. | Aspect.AspectFit |
CurrentState | MediaElementState |
Indica lo stato corrente del controllo. Si tratta di una proprietà associabile di sola lettura. | MediaElementState.None |
Durata | TimeSpan |
Indica la durata del supporto attualmente aperto. Si tratta di una proprietà associabile di sola lettura. | TimeSpan.Zero |
Posizione | TimeSpan |
Descrive lo stato di avanzamento corrente attraverso il tempo di riproduzione del supporto. Si tratta di una proprietà associabile di sola lettura. Se si desidera impostare l'oggetto Position utilizzando il SeekTo() metodo . |
TimeSpan.Zero |
ShouldAutoPlay | bool |
Indica se la riproduzione multimediale inizierà automaticamente quando la Source proprietà è impostata. Si tratta di una proprietà associabile. |
false |
ShouldLoopPlayback | bool |
Descrive se l'origine multimediale attualmente caricata deve riprendere la riproduzione dall'inizio dopo aver raggiunto la fine. Si tratta di una proprietà associabile. | false |
ShouldKeepScreenOn | bool |
Determina se la schermata del dispositivo deve rimanere attiva durante la riproduzione multimediale. Si tratta di una proprietà associabile. | false |
ShouldMute | bool |
Determina se l'audio è attualmente disattivato. Si tratta di una proprietà associabile. | false |
ShouldShowPlaybackControls | bool |
Determina se vengono visualizzati i controlli di riproduzione delle piattaforme. Si tratta di una proprietà associabile. Si noti che in iOS e Windows i controlli vengono visualizzati solo per un breve periodo dopo l'interazione con la schermata. Non è possibile mantenere sempre visibili i controlli. | true |
Origine | MediaSource? |
Origine del supporto caricato nel controllo. | null |
Velocità | double |
Determina la velocità di riproduzione del supporto. Si tratta di una proprietà associabile | 1 |
MediaHeight | int |
Altezza del supporto caricato in pixel. Si tratta di una proprietà associabile di sola lettura. Non segnalato per i supporti non visivi e potrebbe non essere sempre popolato in iOS/macOS per contenuti in streaming live. | 0 |
MediaWidth | int |
Larghezza del supporto caricato in pixel. Si tratta di una proprietà associabile di sola lettura. Non segnalato per i supporti non visivi e potrebbe non essere sempre popolato in iOS/macOS per contenuti in streaming live. | 0 |
Volume | double |
Determina il volume del supporto, rappresentato su una scala lineare compresa tra 0 e 1. Si tratta di una proprietà associabile. | 1 |
Eventi
Evento | Descrizione |
---|---|
MediaOpened | Si verifica quando il flusso multimediale è stato convalidato e aperto. |
MediaEnded | Si verifica al termine della MediaElement riproduzione dei supporti. |
MediaFailed | Si verifica quando si verifica un errore associato all'origine multimediale. |
PositionChanged | Si verifica quando viene modificato il valore della proprietà Position . |
SeekCompleted | Si verifica quando il punto di ricerca di un'operazione di ricerca richiesta è pronto per la riproduzione. |
Metodi
Evento | Descrizione |
---|---|
Riproduci | Avvia la riproduzione dei supporti caricati. |
Sospendi | Sospende la riproduzione dei supporti correnti. |
Arresta | Arresta la riproduzione e reimposta la posizione del supporto corrente. |
SeekTo | Accetta un TimeSpan valore per impostare la Position proprietà su e accetta un CancellationToken oggetto per annullare l'oggetto Task . |
Esempi
È possibile trovare esempi di questo controllo in azione nell'applicazione di esempio .NET MAUI Community Toolkit.
API
È possibile trovare il codice sorgente per MediaElement
over nel repository GitHub di .NET MAUI Community Toolkit.
Collegamenti correlati
.NET MAUI Community Toolkit