ApsaraVideo VOD：Flutter播放器含UI整合方案

aliplayer_widget 已經開源並提供多種下載方式。如果您需要對組件進行自訂修改，您可以使用源碼依賴的方式，直接擷取並修改源碼。完整源碼可通過以下方式擷取：

下載包的內容包括：

• 核心組件：AliPlayerWidget 和 AliPlayerWidgetController 的完整實現。

• 樣本工程：aliplayer_widget_example 提供點播、直播、列表播放等情境的程式碼範例，協助開發人員快速整合和使用。

• 文檔與注釋：源碼包含詳細注釋和開發指南，便於二次開發與定製。

整合方式

手動添加依賴

在您的 pubspec.yaml 檔案中添加以下依賴：

dependencies:
  aliplayer_widget: ^x.y.z

使用命令列工具

如果您更傾向於使用命令列，可以直接運行以下命令來添加依賴：

flutter pub add aliplayer_widget

該命令會自動更新您的 pubspec.yaml 檔案。

無論您選擇哪種方式，完成依賴添加後，請在終端中運行以下命令以安裝依賴：

flutter pub get

通過上述步驟，AliPlayerWidget 就已成功整合到您的專案中，您可以開始使用它了！

實現視頻播放

以下是一個完整的樣本，展示如何在頁面中嵌入視頻播放器。只需幾行代碼即可完成視頻播放功能。

import 'package:flutter/material.dart';
import 'package:aliplayer_widget/aliplayer_widget_lib.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: VideoPlayerPage(),
    );
  }
}

class VideoPlayerPage extends StatefulWidget {
  @override
  _VideoPlayerPageState createState() => _VideoPlayerPageState();
}

class _VideoPlayerPageState extends State<VideoPlayerPage> {
  late AliPlayerWidgetController _controller;

  @override
  void initState() {
    super.initState();
    // 初始化播放器組件控制器
    _controller = AliPlayerWidgetController(context);
    // 配置播放器組件資料
    final data = AliPlayerWidgetData(
      videoUrl: "https://example.com/video.mp4", // 替換為實際視頻地址
      coverUrl: "https://example.com/cover.jpg", // 替換為實際封面圖地址
      videoTitle: "Sample Video",
    );
    _controller.configure(data); // 設定自動播放
  }

  @override
  void dispose() {
    // 銷毀播放器執行個體，釋放資源
    _controller.destroy();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: AliPlayerWidget(
          _controller,
        ),
      ),
    );
  }
}

更多情境支援

上述樣本展示了點播情境的基本用法。如需瞭解更複雜的情境（如直播、列表播放等），請參考 aliplayer_widget_example 樣本工程，其中包含了詳細的代碼和使用說明。

編譯與運行

樣本說明

aliplayer_widget_example 工程涵蓋了多個典型情境，展示了 AliPlayerWidget 的核心功能及其在不同情境中的實際應用。無論是基礎的點播播放頁面，還是複雜的直播播放頁面和短視頻列表播放頁面，開發人員都可以通過本樣本工程快速掌握整合和使用方法，並根據需求進行定製化開發。

@override
void initState() {
  super.initState();
  _controller = AliPlayerWidgetController(context);
  final data = AliPlayerWidgetData(
    videoUrl: "https://example.com/sample-video.mp4",
    coverUrl: "https://example.com/sample-cover.jpg",
    videoTitle: "Sample Video Title",
  );
  _controller.configure(data);
}

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: AliPlayerWidget(_controller),
  );
}

@override
void initState() {
  super.initState();
  _controller = AliPlayerWidgetController(context);
  final data = AliPlayerWidgetData(
    videoUrl: "https://example.com/live-stream.m3u8",
    sceneType: SceneType.live,
  );
  _controller.configure(data);
}

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: Column(
      children: [
        Expanded(child: AliPlayerWidget(_controller)),
        _buildChatArea(),
        _buildMessageInput(),
      ],
    ),
  );
}

短視頻列表操作用法請參見整合微短劇方案-Flutter。

AliPlayerWidget

AliPlayerWidget 是核心的播放器組件，用於嵌入到 Flutter 應用中並播放視頻。

建構函式

AliPlayerWidget(
  AliPlayerWidgetController controller, {
  Key? key,
  List<Widget> overlays = const [],
});

樣本如下

AliPlayerWidget(
  _controller,
  overlays: [
    Positioned(
      right: 16,
      bottom: 80,
      child: Column(
        children: [
          IconButton(icon: Icon(Icons.favorite), onPressed: () {}),
          IconButton(icon: Icon(Icons.share), onPressed: () {}),
        ],
      ),
    ),
  ],
);

AliPlayerWidgetController

AliPlayerWidgetController 是播放器組件的核心控制器，用於管理播放器組件的初始化、播放、銷毀等邏輯。

方法說明

樣本如下

// 初始化播放器組件控制器
final controller = AliPlayerWidgetController(context);

// 設定播放器組件資料
AliPlayerWidgetData data = AliPlayerWidgetData(
  videoUrl: "https://example.com/video.mp4",
);
controller.configure(data);

// 銷毀播放器
controller.destroy();

AliPlayerWidgetData

AliPlayerWidgetData 是播放器組件所需的資料模型，包含視頻地址、封面圖、標題等資訊。

屬性說明

樣本如下

AliPlayerWidgetData(
  videoUrl: "https://example.com/video.mp4",
  coverUrl: "https://example.com/cover.jpg",
  videoTitle: "Sample Video",
  sceneType: SceneType.vod,
);

SceneType屬性

樣本如下：

_controller = AliPlayerWidgetController(context);
// 設定播放器組件資料
final data = AliPlayerWidgetData(
  sceneType: SceneType.vod
);
_controller.configure(data);

浮層組件

通過 overlays 參數，您可以輕鬆地在播放器上疊加自訂 UI 組件。例如，添加點贊、評論、分享按鈕等。

AliPlayerWidget(
  _controller,
  overlays: [
    Positioned(
      right: 16,
      bottom: 80,
      child: Column(
        children: [
          IconButton(icon: Icon(Icons.favorite), onPressed: () {}),
          IconButton(icon: Icon(Icons.comment), onPressed: () {}),
          IconButton(icon: Icon(Icons.share), onPressed: () {}),
        ],
      ),
    ),
  ],
);

常用介面

AliPlayerWidget 提供了一系列對外介面，方便開發人員直接控制播放器的行為。這些介面通過 AliPlayerWidgetController 暴露，支援播放控制、狀態查詢、資料更新等功能。以下是一些常用的對外介面及其使用情境：

配置與初始化

播放控制

播放屬性設定

其它設定

插槽（Slot）系統

概述
AliPlayerWidget提供靈活的插槽系統，支援對播放器介面進行細粒度定製。開發人員可自由組合或替換各UI組件，實現品牌化、情境化或極簡風格的播放體驗。

插槽類型
內建以下核心互動地區插槽：

使用預設介面

不配置插槽構建器時，預設載入完整UI，適用於標準播放情境。

Widget _buildPlayWidget() {
  return AliPlayerWidget(_controller);
}

自訂部分插槽

按需覆蓋指定組件，其餘保持預設，可以減少維護成本。

AliPlayerWidget(
  controller,
  slotBuilders: {
    SlotType.topBar: (context) => MyAppTopBar(title: '我的視訊'),
    SlotType.bottomBar: (context) => MyCustomControls(),
  },
)

完全自訂插槽

AliPlayerWidget(
  controller,
  slotBuilders: {
    SlotType.topBar: (context) => CustomTop(),
    SlotType.bottomBar: (context) => CustomBottom(),
    SlotType.playControl: (context) => GestureHandler(),
    SlotType.coverImage: (context) => BrandCover(),
    SlotType.playState: (context) => ErrorOverlay(),
    SlotType.centerDisplay: (context) => VolumeIndicator(),
    SlotType.seekThumbnail: (context) => PreviewThumb(),
    SlotType.subtitle: (context) => SubtitleView(),
    SlotType.settingMenu: (context) => MySettings(),
    SlotType.overlays: (context) => [AdBanner(), Watermark()],
  },
)

隱藏特定插槽

將插槽值置為null即可隱藏對應地區。

AliPlayerWidget(
  controller,
  slotBuilders: {
    SlotType.topBar: null,        // 隱藏頂部欄
    SlotType.settingMenu: null,   // 隱藏設定菜單
    SlotType.centerDisplay: null, // 禁用手勢反饋提示
  },
)

完整樣本如下：

// Hide top and bottom bars for a clean look
// 隱藏頂部和底部欄，使介面更簡潔
AliPlayerWidget(controller, slotBuilders: {
  SlotType.topBar: null,
  SlotType.bottomBar: null,
});

// Add custom business overlay
// 添加自訂商業疊加層
AliPlayerWidget(controller, slotBuilders: {
  SlotType.overlays: (context) => MyLikeShareButtons(),
});

// Fully branded UI
// 完全品牌化的使用者介面
AliPlayerWidget(controller, slotBuilders: {
  SlotType.topBar: (context) => MyAppTopBar(),
  SlotType.bottomBar: (context) => MyAppBottomBar(),
  SlotType.settingMenu: null, // hide settings
});

多情境適配

支援點播、直播、列表播放及全屏播放等多種情境。

豐富的功能集

• 基礎功能：提供播放控制、設定面板、封面圖顯示、清晰度切換等核心功能，滿足常規視頻播放需求。

• 手勢控制：支援亮度、音量和播放進度的手勢調節，操作直觀便捷，提升使用者體驗。

靈活的 UI 定製

• 浮層支援：支援自訂浮層組件，擴充性強，允許開發人員實現如廣告、彈幕等複雜功能。

• 模組化設計：內建頂部欄、底部欄、設定面板等可複用的 UI 組件，方便開發人員按需定製。

• 全屏適配：自動適配橫豎屏切換，確保在不同裝置上的最佳顯示效果。

事件與狀態管理

• 即時狀態監控：提供播放狀態、視頻尺寸、緩衝進度等即時資料更新，便於開發人員實現動態互動。

• 事件回調機制：提供全面的播放器事件監聽，包括播放開始、暫停、完成等狀態管理，方便開發人員處理各種播放情境。

• 日誌與調試支援：內建詳細的日誌系統，便於問題排查和效能最佳化。

簡單易用

通過簡單的 API 呼叫即可實現複雜的視頻播放功能，快速整合到 Flutter 專案中。

靈活可擴充

• 模組化設計，支援多種自訂選項，方便開發人員根據需求進行定製。

• 自動適配不同螢幕尺寸和解析度，確保一致的使用者體驗。

高效能與穩定性

• 基於阿里雲播放器 SDK，提供低延遲、高穩定性的視頻播放體驗。

• 最佳化的架構設計，通過輕量化組件、非同步載入和事件驅動模型，確保高效運行與流暢使用者體驗。

跨平台支援

充分利用 Flutter 的跨平台特性，支援 Android 和 iOS 平台，一次開發即可實現雙端運行。