共用方式為

MediaElement

  • 發行項

MediaElement 是播放視訊和音訊的控件。 基礎平台支援的媒體可以從下列來源播放：

  • Web，使用 URI（HTTP 或 HTTPS）。
  • 使用 embed:// URI 配置內嵌在平臺應用程式中的資源。
  • 使用 filesystem:// URI 設定來自應用程式本機檔案系統的檔案。

MediaElement 可以使用稱為傳輸控制件的平臺播放控制件。 不過，預設會停用它們，而且可以取代為您自己的傳輸控件。 下列螢幕快照顯示 MediaElement 使用平臺傳輸控制播放影片：

在Android和iOS上播放影片的 MediaElement 螢幕快照。

注意

MediaElement 適用於 iOS、Android、Windows、macOS 和 Tizen。

會 MediaElement 使用下列平台實作。

平台 平台媒體播放機實作
Android ExoPlayer，非常感謝 Android 函式庫 維護人員！
iOS/macOS AVPlayer
Windows MediaPlayer

開始使用

若要使用 MediaElement .NET MAUI Community Toolkit 的功能，需要下列步驟。

安裝 NuGet 套件

在應用程式內使用MediaElement之前，您必須安裝 CommunityToolkit.Maui.MediaElement NuGet 套件，並在MauiProgram.cs中新增初始化行。 如下：

套件名稱：CommunityToolkit.Maui.MediaElement

套件 URL：https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement

初始化封裝

首先，using 語句必須新增至MauiProgram.cs檔案的頂端

using CommunityToolkit.Maui.MediaElement;

若要正確使用 方法MediaElement，UseMauiCommunityToolkitMediaElement在啟動載入應用程式時，必須在 類別上MauiAppBuilder呼叫 方法MauiProgram.cs檔案。 下列範例示範如何執行此動作。

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

如需如何執行這項操作的詳細資訊，請參閱 開始使用 頁面。

平臺特定初始化

若要存取 MediaElement 此功能，需要下列平臺特定的設定。

使用 MediaElement 時，必須執行下列步驟：

1.將 和 ResizableActivity 新增Launchmode至活動

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

2.將下列內容新增至 AndroidManifest.xml 標記內 <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.更新最低 Android API 版本

在專案的 .csproj 檔案中，將 android API 的最低版本更新為 26。

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

4.將下列許可權新增至 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" />

以下是 中必要設定的範例 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"/>

注意

對 Android 指令清單的這項修改可在播放影片時啟用元數據顯示。 它提供通知的支持，對於通知在所有相關 API 之間運作至關重要。 此變更引進服務，並授與必要的許可權。

如需應用程式中包含的這個方法的完整範例，請參閱 .NET MAUI 社群工具組範例應用程式

支援的格式

每個平台支援的多媒體格式可能不同。 在某些情況下，它甚至可以取決於哪些譯碼器可用，或安裝在執行應用程式時所使用的操作系統上。 如需每個平台上支援哪些格式的詳細資訊，請參閱下列連結。

平台 連結 備註
Android ExoPlayer 支援的格式
iOS/macOS iOS/macOS 支援的格式 沒有官方檔存在
Windows Windows 支援的格式 在 Windows 上，支援的格式非常相依於使用者電腦上安裝的編解碼器
Tizen Tizen 支援的格式

重要

如果使用者使用 Windows N 版本，則預設不支援任何視訊播放。 Windows N 版本沒有依設計安裝的視訊播放格式。

常見案例

下列各節涵蓋的 MediaElement常見使用案例。

播放遠程媒體

MediaElement可以使用 HTTP 和 HTTPS URI 配置來播放遠端媒體檔案。 這可藉由將 Source 屬性設定為媒體檔案的 URI 來完成：

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

重要

從 HTTP 端點播放遠端來源時，您可能需要停用作業系統安全性措施，以防止存取不安全的 Web 端點。 這至少適用於 iOS 和 Android。

根據預設，屬性所 Source 定義的媒體不會在媒體開啟之後立即開始播放。 若要啟用自動媒體播放，請將 ShouldAutoPlay 屬性設定為 true。

默認會啟用平臺提供的媒體播放控制件，而且可以藉由將 ShouldShowPlaybackControls 屬性設定為 false來停用。

使用中繼資料

MediaElement可以使用、 MediaElement.MetadataTitle 和 MediaElement.MetadataArtist的MediaElement.MetadataArtworkUrl元數據。 您可以設定標題或藝術家，以顯示目前在 Windows、Mac Catalyst、iOS 和 Android 的鎖定畫面控制件上播放的內容。 您可以使用鎖定畫面的圖稿來設定本機或遠端 URL。 至少應為 1080P，才能顯示最佳品質。 它必須是URL且為 .jpg 或 .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";

重要

您可以在 XAML 或程式碼後置中設定元數據。 如果您要在程式代碼後置中設定它，則必須在程式碼後置中設定原始程式碼。 來源應該最後設定。 如果您在 XAML 或建構函式中設定元數據，則可以安全地忽略此附注。

播放本機媒體

您可以從下列來源播放本機媒體：

  • 使用 embed:// URI 配置內嵌在平臺應用程式中的資源。
  • 使用 filesystem:// URI 設定來自應用程式本機檔案系統的檔案。

注意

速記 embed:// ，只能 filesystem:// 從 XAML 運作。 在程式代碼中，請分別使用 MediaSource.FromResource() 和 MediaSource.FromFile() 。 使用這些方法，您可以省略 embed:// 和 filesystem:// 前置詞。 路徑的其餘部分應該相同。

播放內嵌在應用程式套件中的媒體

MediaElement可以使用 URI 配置，embed://播放內嵌在應用程式套件中的媒體檔案。 媒體檔案會內嵌在應用程式套件中，方法是將它們放在平台專案中。

若要啟用媒體檔案，以便從本機資源播放，請將檔案新增至 .NET MAUI 專案的 Resources/Raw 資料夾。 在根目錄中新增檔案時，URI 會是 embed://MyFile.mp4。

您也可以將檔案放在子資料夾中。 如果 MyFile.mp4 位於 中 Resources/Raw/MyVideos ，則要使用的 MediaElement URI 會是 embed://MyVideos/MyFile.mp4。

以下是如何在 XAML 中使用此語法的範例。

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

瞭解 MediaSource 類型

MediaElement可藉由將其 Source 屬性設定為遠端或本機媒體檔案，以播放媒體。 屬性 Source 的類型為 MediaSource，而這個類別會定義三個靜態方法：

  • FromFile，會從FileMediaSource自變數傳string回 實例。
  • FromUri，會從UriMediaSource自變數傳Uri回 實例。
  • FromResource，會從ResourceMediaSource自變數傳string回 實例。

此外，類別MediaSource也有隱含運算符，可從和 MediaSource 自變數傳回string實例Uri。

注意

Source在 XAML 中設定 屬性時，會叫用型別轉換器，以從 MediaSource 或string傳回 Uri 實例。

類別 MediaSource 也有這些衍生類別：

  • FileMediaSource，用來從 string指定本機媒體檔案。 這個類別的屬性 Path 可以設定為 string。 此外，這個類別具有隱含運算元，可將轉換成 物件，並將 string 對象轉換成 FileMediaSourceFileMediaSource。string
  • UriMediaSource，用來從 URI 指定遠端媒體檔案。 這個類別的屬性 Uri 可以設定為 Uri。
  • ResourceMediaSource，用來指定透過應用程式資源檔提供的內嵌檔案。 這個類別的屬性 Path 可以設定為 string。

注意

FileMediaSource在 XAML 中建立 物件時，會叫用型別轉換器，以從 FileMediaSource傳回 string 實例。

變更視訊外觀比例

屬性 Aspect 會決定如何調整視訊媒體以符合顯示區域。 根據預設，這個屬性會設定為 AspectFit 列舉成員，但可以設定為任何 Aspect 列舉成員：

  • AspectFit 表示視訊會視需要放入顯示區域，同時保留外觀比例。
  • AspectFill 表示影片會裁剪，使其填滿顯示區域，同時保留外觀比例。
  • Fill 表示將延展視訊以填滿顯示區域。

判斷 MediaElement 狀態

類別 MediaElement 會定義名為 CurrentState的唯讀可系結屬性，類型為 MediaElementState。 這個屬性表示控制件的目前狀態，例如媒體正在播放或暫停，或者它尚未準備好播放媒體。

MediaElementState 列舉會定義下列成員：

  • None 表示 MediaElement 不包含任何媒體。
  • Opening 表示 MediaElement 正在驗證並嘗試載入指定的來源。
  • Buffering MediaElement表示 正在載入要播放的媒體。 其 Position 屬性不會在這個狀態期間前進。 MediaElement如果 正在播放視訊，它會繼續顯示最後一個顯示的畫面。
  • Playing MediaElement表示 正在播放媒體來源。
  • Paused MediaElement表示 不會推進其 Position 屬性。 MediaElement如果 正在播放視訊，它會繼續顯示目前的畫面。
  • Stopped 表示 MediaElement 包含媒體，但未播放或暫停。 其 Position 屬性會重設為 0，而且不會前進。
  • Failed MediaElement表示無法載入或播放媒體。 嘗試載入新的媒體專案、嘗試播放媒體專案或因失敗而中斷媒體播放時，可能會發生這種情況。 MediaFailed使用 事件來擷取其他詳細數據。

使用CurrentState傳輸控制項時，通常不需要檢查 MediaElement 屬性。 不過，實作您自己的傳輸控件時，這個屬性會變得很重要。

實作自定義傳輸控制件

媒體播放機的傳輸控制件包括執行 播放、 暫停和 停止功能的按鈕。 這些按鈕通常會以熟悉的圖示而非文字呈現，且 [播放] 及 [暫停] 功能常會合併為一個按鈕。

根據預設， MediaElement 播放控件會停用。 這可讓您以程式設計方式控制 MediaElement ，或藉由提供您自己的傳輸控制件。 支援這項功能， MediaElement 包括 Play、 Pause和 Stop 方法。

下列 XAML 範例顯示包含 MediaElement 和 自訂傳輸控制器的頁面：

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

在此範例中，自定義傳輸控件會定義為 Button 物件。 不過，只有兩 Button 個物件，第一個 Button 代表 Play 和 Pause，第二 Button 個代表 Stop。 DataTrigger對象可用來啟用和停用按鈕，以及切換播放和暫停之間的第一個按鈕。 如需數據觸發程式的詳細資訊，請參閱 .NET MAUI 觸發程式。

程式代碼後置檔案具有事件的處理程式 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();
}

一旦啟用 [播放] 按鈕，即可按下 [播放] 按鈕，開始播放。 按下 [ 暫停] 按鈕會導致播放暫停。 按下 [ 停止] 按鈕會停止播放，並將媒體檔案的位置傳回至開頭。

實作自定義磁碟區控件

每個平臺所實作的媒體播放控件都包含磁碟區列。 此列類似於滑桿，並顯示媒體的音量。 此外，您可以操作磁碟區列來增加或減少磁碟區。

您可以使用 實 Slider作自訂磁碟區列，如下列範例所示：

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

在此範例中 Slider ，數據會將其 Value 屬性系結至 Volume 的 MediaElement屬性。 這是可能的，因為 Volume 屬性使用系 TwoWay 結。 因此，變更 Value 屬性會導致 Volume 屬性變更。

注意

屬性 Volume 具有驗證回呼，可確保其值大於或等於0.0，且小於或等於1.0。

如需使用 Slider 的詳細資訊， 請參閱 .NET MAUI 滑桿

清除 MediaElement 資源

若要防止記憶體流失，您必須釋放的資源 MediaElement。 這可以透過中斷處理程式的連線來完成。 您需要執行此動作的位置取決於您在應用程式中使用 MediaElement 的位置和方式，但通常如果您在單一頁面上有 MediaElement ，而且不會在背景播放媒體，則當使用者離開頁面時，您想要釋放資源。

您可以在下方找到示範如何執行此動作的範例程式代碼段。 首先，請務必在頁面上連結 Unloaded 事件。

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

然後在程序代碼後置中，呼叫 方法來中斷處理程式的連線。

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

若要深入瞭解處理程式，請參閱有關處理程式的 .NET MAUI 檔。

屬性

屬性 類型​ 描述 預設值
層面 層面 決定目前載入之 （visual） 媒體的縮放模式。 這是可繫結屬性。 Aspect.AspectFit
CurrentState MediaElementState 指出控件的目前狀態。 這是唯讀的可系結屬性。 MediaElementState.None
期間 TimeSpan 表示目前開啟媒體的持續時間。 這是唯讀的可系結屬性。 TimeSpan.Zero
Position TimeSpan 描述媒體播放時間的目前進度。 這是唯讀的可系結屬性。 如果您想要設定 Position ， SeekTo() 請使用 方法。 TimeSpan.Zero
ShouldAutoPlay bool 指出設定 屬性時 Source ，媒體播放是否會自動開始。 這是可繫結屬性。 false
ShouldLoopPlayback bool 描述目前載入的媒體來源是否應該在到達結束之後從頭繼續播放。 這是可繫結屬性。 false
ShouldKeepScreenOn bool 判斷裝置畫面是否應該在媒體播放期間保持開啟。 這是可繫結屬性。 false
ShouldMute bool 判斷音訊目前是否為靜音。 這是可繫結屬性。 false
ShouldShowPlaybackControls bool 判斷是否顯示平臺播放控制件。 這是可繫結屬性。 請注意，在 iOS 和 Windows 上，控件只會在與畫面互動後短暫顯示。 無法隨時讓控件保持可見。 true
來源 MediaSource? 載入控件之媒體的來源。 null
速度 double 決定媒體的播放速度。 這是可系結的屬性 1
MediaHeight int 以像素為單位載入媒體的高度。 這是唯讀的可系結屬性。 未針對非視覺媒體回報，而且可能不一定會在iOS/macOS上填入即時串流內容。 0
MediaWidth int 載入媒體的寬度，以像素為單位。 這是唯讀的可系結屬性。 未針對非視覺媒體回報，而且可能不一定會在iOS/macOS上填入即時串流內容。 0
體積 double 決定媒體的磁碟區，其以介於 0 到 1 之間的線性刻度表示。 這是可繫結屬性。 1

事件

活動 描述
MediaOpened 發生於已驗證並開啟媒體數據流時。
MediaEnded 發生於 完成播放其媒體時 MediaElement 。
MediaFailed 發生於與媒體來源相關聯的錯誤時。
PositionChanged 發生於 Position 屬性值變更時。
SeekCompleted 發生於要求搜尋作業的搜尋點準備好播放時。

方法

活動 描述
Play 開始播放載入的媒體。
暫停 暫停目前媒體的播放。
停止 停止播放並重設目前媒體的位置。
SeekTo TimeSpan接受值以將 屬性設定Position為 ，並接受 CancellationToken 以取消 Task。

範例

您可以在 .NET MAUI Community Toolkit 範例應用程式中找到此控件作用中的範例。

API

您可以在 .NET MAUI Community Toolkit GitHub 存放庫MediaElement找到 的原始程式碼。