@ohos-cpf/3rdloop 0.0.12 → 0.0.13

package/vendor/Server/Skills/flutter-demo-code-generator/references/EXAMPLES.md

@@ -0,0 +1,629 @@
+# 示例：flutter_video_player Demo 代码生成
+
+本文档展示使用 `flutter-demo-code-generator` 技能，基于 `flutter_video_player` 库的测试 Demo 描述文档，生成实际 Dart 页面代码的完整示例（节选 Demo 001 和 Demo 002）。
+
+---
+
+## 输入：Demo 描述文档片段
+
+| 序号 | 测试 Demo 名称 | 对应函数接口 |
+|-----|--------------|------------|
+| 1 | 环境检测与版本查询 Demo | `isHardwareDecodingSupported(): bool`、`getSDKVersion(): String` |
+| 2 | 控制器初始化与资源释放 Demo | `VideoPlayerController(config)`、`initialize(): Future<void>`、`dispose(): Future<void>` |
+
+---
+
+## 输出示例一：Demo 001 页面代码
+
+**文件路径**：`lib/pages/001_check_support/check_support_page.dart`
+
+```dart
+/// Demo 001: Check Support And SDK Version
+///
+/// 功能说明：展示如何在使用播放器前检测当前设备是否支持硬件解码，
+///           并查询 SDK 版本号，帮助开发者了解使用前置条件检查的标准流程。
+/// 对应接口：
+///   - isHardwareDecodingSupported(): bool
+///   - getSDKVersion(): String
+
+import 'dart:developer' as dev;
+
+import 'package:flutter/material.dart';
+import 'package:flutter_video_player/flutter_video_player.dart';
+
+// ─── 日志 Tag ────────────────────────────────────────────────────────────
+const String _kTag = 'FlutterVideoPlayer_CheckSupportPage';
+
+/// CheckSupportPage - 环境检测与版本查询示例
+///
+/// 展示 flutter_video_player 的设备能力检测和版本查询流程。
+class CheckSupportPage extends StatefulWidget {
+  const CheckSupportPage({super.key});
+
+  @override
+  State<CheckSupportPage> createState() => _CheckSupportPageState();
+}
+
+class _CheckSupportPageState extends State<CheckSupportPage> {
+  // ─── 状态变量 ─────────────────────────────────────────────────────────
+  String _hwDecodeResult = '';
+  String _sdkVersionResult = '';
+
+  @override
+  void initState() {
+    super.initState();
+    dev.log('Page appeared', name: _kTag);
+  }
+
+  @override
+  void dispose() {
+    dev.log('Page disposed', name: _kTag);
+    super.dispose();
+  }
+
+  // ─── 核心功能方法 ──────────────────────────────────────────────────────
+
+  /// 检测当前设备是否支持硬件解码。
+  ///
+  /// 调用 [isHardwareDecodingSupported] 并将结果展示在页面上。
+  void _checkHardwareDecoding() {
+    dev.log('_checkHardwareDecoding called', name: _kTag);
+    try {
+      // 调用库接口：同步返回布尔值
+      final bool supported = isHardwareDecodingSupported();
+      dev.log('_checkHardwareDecoding result: $supported', name: _kTag);
+      setState(() {
+        _hwDecodeResult = supported
+            ? '当前设备支持硬件解码 ✅'
+            : '当前设备不支持硬件解码 ❌';
+      });
+    } catch (e, stack) {
+      dev.log(
+        '_checkHardwareDecoding failed',
+        name: _kTag,
+        error: e,
+        stackTrace: stack,
+      );
+      setState(() => _hwDecodeResult = '检测失败：$e');
+    }
+  }
+
+  /// 查询 SDK 版本号。
+  ///
+  /// 调用 [getSDKVersion] 并将版本号字符串展示在页面上。
+  void _querySdkVersion() {
+    dev.log('_querySdkVersion called', name: _kTag);
+    try {
+      final String version = getSDKVersion();
+      dev.log('_querySdkVersion result: $version', name: _kTag);
+      setState(() => _sdkVersionResult = 'SDK 版本: $version');
+    } catch (e, stack) {
+      dev.log(
+        '_querySdkVersion failed',
+        name: _kTag,
+        error: e,
+        stackTrace: stack,
+      );
+      setState(() => _sdkVersionResult = '查询失败：$e');
+    }
+  }
+
+  // ─── UI 构建 ─────────────────────────────────────────────────────────
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('[001] 环境检测与版本查询'),
+      ),
+      body: SingleChildScrollView(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.stretch,
+          children: [
+            // 说明卡片
+            Card(
+              child: Padding(
+                padding: const EdgeInsets.all(12),
+                child: Text(
+                  '在使用播放器前，可通过以下接口检测设备能力和 SDK 版本。'
+                  '这些信息有助于开发者根据设备环境做出适当的适配决策。',
+                  style: Theme.of(context).textTheme.bodyMedium,
+                ),
+              ),
+            ),
+            const SizedBox(height: 16),
+
+            // 硬件解码检测区域
+            const Text(
+              '硬件解码能力检测',
+              style: TextStyle(fontWeight: FontWeight.bold),
+            ),
+            const SizedBox(height: 8),
+            ElevatedButton(
+              onPressed: _checkHardwareDecoding,
+              child: const Text('检测硬件解码支持'),
+            ),
+            const SizedBox(height: 8),
+            _buildResultBox(_hwDecodeResult, '（点击上方按钮检测）'),
+            const SizedBox(height: 24),
+
+            // SDK 版本查询区域
+            const Text(
+              'SDK 版本查询',
+              style: TextStyle(fontWeight: FontWeight.bold),
+            ),
+            const SizedBox(height: 8),
+            ElevatedButton(
+              onPressed: _querySdkVersion,
+              child: const Text('查询 SDK 版本号'),
+            ),
+            const SizedBox(height: 8),
+            _buildResultBox(_sdkVersionResult, '（点击上方按钮查询）'),
+          ],
+        ),
+      ),
+    );
+  }
+
+  /// 构建结果展示框
+  Widget _buildResultBox(String result, String placeholder) {
+    return Container(
+      width: double.infinity,
+      padding: const EdgeInsets.all(12),
+      decoration: BoxDecoration(
+        color: Colors.grey[100],
+        borderRadius: BorderRadius.circular(8),
+        border: Border.all(color: Colors.grey[300]!),
+      ),
+      child: Text(result.isEmpty ? placeholder : result),
+    );
+  }
+}
+```
+
+---
+
+## 输出示例二：Demo 002 页面代码
+
+**文件路径**：`lib/pages/002_controller_lifecycle/controller_lifecycle_page.dart`
+
+```dart
+/// Demo 002: Controller Lifecycle Management
+///
+/// 功能说明：展示 VideoPlayerController 的完整生命周期管理流程，包括
+///           使用 PlayerConfig 构造实例、调用 initialize() 异步加载资源
+///           以及最终调用 dispose() 释放资源。
+/// 对应接口：
+///   - VideoPlayerController(config: PlayerConfig)
+///   - PlayerConfig({required url, autoPlay, initialVolume})
+///   - initialize(): Future<void>
+///   - dispose(): Future<void>
+
+import 'dart:developer' as dev;
+
+import 'package:flutter/material.dart';
+import 'package:flutter_video_player/flutter_video_player.dart';
+
+// ─── 日志 Tag ────────────────────────────────────────────────────────────
+const String _kTag = 'FlutterVideoPlayer_ControllerLifecyclePage';
+
+/// 控制器状态枚举
+enum _ControllerStatus { idle, loading, ready, disposed }
+
+/// ControllerLifecyclePage - 控制器初始化与资源释放示例
+///
+/// 展示 flutter_video_player 的 VideoPlayerController 从创建到销毁的
+/// 完整生命周期，以及异步 initialize() 的正确使用姿势。
+class ControllerLifecyclePage extends StatefulWidget {
+  const ControllerLifecyclePage({super.key});
+
+  @override
+  State<ControllerLifecyclePage> createState() =>
+      _ControllerLifecyclePageState();
+}
+
+class _ControllerLifecyclePageState extends State<ControllerLifecyclePage> {
+  // ─── 状态变量 ─────────────────────────────────────────────────────────
+  _ControllerStatus _status = _ControllerStatus.idle;
+  String _statusText = '未初始化';
+  String _logText = '';
+
+  /// 双计数器（诊断异步链路）
+  int _initCallCount = 0;
+  int _initDoneCount = 0;
+
+  // ─── 输入控制器 ────────────────────────────────────────────────────────
+  final TextEditingController _urlController = TextEditingController(
+    text: 'https://example.com/sample.mp4',
+  );
+
+  // ─── 非响应式：库实例 ───────────────────────────────────────────────────
+  VideoPlayerController? _controller;
+
+  @override
+  void initState() {
+    super.initState();
+    dev.log('Page appeared', name: _kTag);
+  }
+
+  @override
+  void dispose() {
+    dev.log('Page disposed, releasing resources', name: _kTag);
+    // 释放库控制器资源（若页面销毁时控制器仍存在）
+    _controller?.dispose();
+    _controller = null;
+    // 释放 TextField 控制器
+    _urlController.dispose();
+    super.dispose();
+  }
+
+  // ─── 核心功能方法 ──────────────────────────────────────────────────────
+
+  /// 初始化 VideoPlayerController。
+  ///
+  /// 构造 [PlayerConfig] 并传入 [VideoPlayerController]，
+  /// 调用 [initialize()] 异步加载视频资源，完成后更新 UI 状态。
+  Future<void> _initController() async {
+    dev.log('_initController called, url: ${_urlController.text}', name: _kTag);
+    setState(() {
+      _initCallCount++;
+      _status = _ControllerStatus.loading;
+      _statusText = '加载中...';
+    });
+    try {
+      final config = PlayerConfig(
+        url: _urlController.text.trim(),
+        autoPlay: false,
+        initialVolume: 1.0,
+      );
+      final controller = VideoPlayerController(config);
+      await controller.initialize();
+      dev.log('_initController succeeded', name: _kTag);
+      if (!mounted) return;
+      setState(() {
+        _controller = controller;
+        _initDoneCount++;
+        _status = _ControllerStatus.ready;
+        _statusText = '已就绪';
+        _logText = '✅ 控制器初始化成功\n'
+            '  URL: ${_urlController.text.trim()}';
+      });
+    } catch (e, stack) {
+      dev.log('_initController failed', name: _kTag, error: e, stackTrace: stack);
+      if (!mounted) return;
+      setState(() {
+        _status = _ControllerStatus.idle;
+        _statusText = '初始化失败';
+        _logText = '❌ 初始化失败：$e';
+      });
+    }
+  }
+
+  /// 释放 VideoPlayerController 资源。
+  ///
+  /// 调用 [dispose()] 释放底层资源，将控制器引用置空，更新 UI 状态。
+  Future<void> _disposeController() async {
+    dev.log('_disposeController called', name: _kTag);
+    if (_controller == null) {
+      dev.log('_disposeController skipped: controller is null', name: _kTag);
+      return;
+    }
+    try {
+      await _controller!.dispose();
+      dev.log('_disposeController succeeded', name: _kTag);
+      if (!mounted) return;
+      setState(() {
+        _controller = null;
+        _status = _ControllerStatus.disposed;
+        _statusText = '已释放';
+        _logText = '✅ 控制器资源已释放';
+      });
+    } catch (e, stack) {
+      dev.log(
+        '_disposeController failed',
+        name: _kTag,
+        error: e,
+        stackTrace: stack,
+      );
+      if (!mounted) return;
+      setState(() => _logText = '❌ 释放失败：$e');
+    }
+  }
+
+  // ─── UI 构建 ─────────────────────────────────────────────────────────
+
+  @override
+  Widget build(BuildContext context) {
+    final bool isIdle = _status == _ControllerStatus.idle ||
+        _status == _ControllerStatus.disposed;
+    final bool isLoading = _status == _ControllerStatus.loading;
+    final bool isReady = _status == _ControllerStatus.ready;
+
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('[002] 控制器初始化与资源释放'),
+      ),
+      body: SingleChildScrollView(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.stretch,
+          children: [
+            // 说明卡片
+            Card(
+              child: Padding(
+                padding: const EdgeInsets.all(12),
+                child: Text(
+                  '展示 VideoPlayerController 的完整生命周期：'
+                  '构造配置 → 异步初始化 → 释放资源。'
+                  '通过双计数器验证异步链路的完整性。',
+                  style: Theme.of(context).textTheme.bodyMedium,
+                ),
+              ),
+            ),
+            const SizedBox(height: 16),
+
+            // URL 输入框
+            TextField(
+              controller: _urlController,
+              decoration: const InputDecoration(
+                labelText: '视频 URL',
+                border: OutlineInputBorder(),
+                hintText: 'https://example.com/video.mp4',
+              ),
+              enabled: isIdle,
+            ),
+            const SizedBox(height: 12),
+
+            // 操作按钮行
+            Row(
+              children: [
+                Expanded(
+                  child: ElevatedButton(
+                    onPressed: isIdle ? _initController : null,
+                    child: const Text('初始化控制器'),
+                  ),
+                ),
+                const SizedBox(width: 12),
+                Expanded(
+                  child: ElevatedButton(
+                    onPressed: isReady ? _disposeController : null,
+                    style: ElevatedButton.styleFrom(
+                      backgroundColor: Colors.red[400],
+                      foregroundColor: Colors.white,
+                    ),
+                    child: const Text('释放控制器'),
+                  ),
+                ),
+              ],
+            ),
+            const SizedBox(height: 16),
+
+            // Loading 指示器
+            if (isLoading)
+              const Center(
+                child: Padding(
+                  padding: EdgeInsets.all(8),
+                  child: CircularProgressIndicator(),
+                ),
+              ),
+
+            // 当前状态展示
+            _buildStatusRow('当前状态', _statusText),
+            const SizedBox(height: 8),
+
+            // 双计数器诊断区域
+            Card(
+              child: Padding(
+                padding: const EdgeInsets.all(12),
+                child: Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  children: [
+                    const Text(
+                      '异步链路诊断',
+                      style: TextStyle(fontWeight: FontWeight.bold),
+                    ),
+                    const SizedBox(height: 8),
+                    Text('初始化调用次数: $_initCallCount'),
+                    Text('初始化完成次数: $_initDoneCount'),
+                    const SizedBox(height: 4),
+                    if (_initCallCount > 0 && _initDoneCount == 0 && !isLoading)
+                      const Text(
+                        '⚠️ 调用了但未完成，可能初始化出错',
+                        style: TextStyle(color: Colors.orange),
+                      ),
+                    if (_initDoneCount > 0 && _initCallCount == _initDoneCount)
+                      const Text(
+                        '✅ 异步链路正常',
+                        style: TextStyle(color: Colors.green),
+                      ),
+                  ],
+                ),
+              ),
+            ),
+            const SizedBox(height: 8),
+
+            // 日志输出区域
+            if (_logText.isNotEmpty)
+              Container(
+                width: double.infinity,
+                padding: const EdgeInsets.all(12),
+                decoration: BoxDecoration(
+                  color: Colors.grey[100],
+                  borderRadius: BorderRadius.circular(8),
+                  border: Border.all(color: Colors.grey[300]!),
+                ),
+                child: SelectableText(
+                  _logText,
+                  style: const TextStyle(fontFamily: 'monospace', fontSize: 13),
+                ),
+              ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  /// 构建状态行
+  Widget _buildStatusRow(String label, String value) {
+    return Row(
+      children: [
+        Text('$label：', style: const TextStyle(fontWeight: FontWeight.w500)),
+        const SizedBox(width: 8),
+        Expanded(child: Text(value)),
+      ],
+    );
+  }
+}
+```
+
+---
+
+## 输出示例三：主导航页面代码
+
+**文件路径**：`lib/pages/demo_home_page.dart`
+
+```dart
+/// flutter_video_player Demo 主导航页面
+///
+/// 展示所有可用的 Demo 列表，点击后跳转到对应 Demo 页面。
+
+import 'dart:developer' as dev;
+
+import 'package:flutter/material.dart';
+
+import '001_check_support/check_support_page.dart';
+import '002_controller_lifecycle/controller_lifecycle_page.dart';
+import '003_playback_control/playback_control_page.dart';
+import '004_volume_control/volume_control_page.dart';
+
+const String _kTag = 'FlutterVideoPlayer_DemoHome';
+
+class _DemoEntry {
+  const _DemoEntry({
+    required this.id,
+    required this.title,
+    required this.description,
+    required this.builder,
+  });
+
+  final String id;
+  final String title;
+  final String description;
+  final WidgetBuilder builder;
+}
+
+final List<_DemoEntry> _demoList = [
+  _DemoEntry(
+    id: '001',
+    title: '环境检测与版本查询',
+    description: '检测设备硬件解码支持情况，查询 SDK 版本号',
+    builder: (_) => const CheckSupportPage(),
+  ),
+  _DemoEntry(
+    id: '002',
+    title: '控制器初始化与资源释放',
+    description: '展示 VideoPlayerController 完整生命周期：初始化 → 就绪 → 释放',
+    builder: (_) => const ControllerLifecyclePage(),
+  ),
+  _DemoEntry(
+    id: '003',
+    title: '播放控制与进度管理',
+    description: '展示 play/pause/seekTo 及进度监听的完整使用流程',
+    builder: (_) => const PlaybackControlPage(),
+  ),
+  _DemoEntry(
+    id: '004',
+    title: '音量控制',
+    description: '通过 setVolume/volume 调节并读取当前播放音量',
+    builder: (_) => const VolumeControlPage(),
+  ),
+];
+
+/// DemoHomePage - flutter_video_player Demo 示例主导航页
+class DemoHomePage extends StatelessWidget {
+  const DemoHomePage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('flutter_video_player Demo 示例'),
+        centerTitle: true,
+      ),
+      body: ListView.separated(
+        padding: const EdgeInsets.all(16),
+        itemCount: _demoList.length,
+        separatorBuilder: (_, __) => const SizedBox(height: 8),
+        itemBuilder: (context, index) {
+          final demo = _demoList[index];
+          return _DemoCard(
+            demo: demo,
+            onTap: () {
+              dev.log(
+                'Navigate to demo: ${demo.id} - ${demo.title}',
+                name: _kTag,
+              );
+              Navigator.push(
+                context,
+                MaterialPageRoute(builder: demo.builder),
+              );
+            },
+          );
+        },
+      ),
+    );
+  }
+}
+
+class _DemoCard extends StatelessWidget {
+  const _DemoCard({required this.demo, required this.onTap});
+
+  final _DemoEntry demo;
+  final VoidCallback onTap;
+
+  @override
+  Widget build(BuildContext context) {
+    return Card(
+      child: ListTile(
+        leading: CircleAvatar(
+          child: Text(demo.id, style: const TextStyle(fontSize: 12)),
+        ),
+        title: Text(
+          '[${demo.id}] ${demo.title}',
+          style: const TextStyle(fontWeight: FontWeight.w500),
+        ),
+        subtitle: Text(
+          demo.description,
+          maxLines: 2,
+          overflow: TextOverflow.ellipsis,
+        ),
+        trailing: const Icon(Icons.arrow_forward_ios, size: 16),
+        onTap: onTap,
+      ),
+    );
+  }
+}
+```
+
+---
+
+## 关键生成规则说明
+
+上述示例展示了以下技能规则的应用：
+
+1. **文件命名**：目录名 `001_check_support`、文件名 `check_support_page.dart`、类名 `CheckSupportPage`，全部遵循 Dart 命名规范。
+
+2. **日志常量**：每个文件顶部声明 `const String _kTag = 'FlutterVideoPlayer_XxxPage'`，所有 `dev.log` 调用均使用该常量。
+
+3. **双计数器诊断**：`_initCallCount`（调用次数）和 `_initDoneCount`（完成次数）均通过 `setState()` 更新，确保 UI 实时反映异步状态，同时在 UI 中展示诊断信息。
+
+4. **mounted 检查**：在所有 `async` 方法的 `await` 后、调用 `setState()` 前，均有 `if (!mounted) return` 检查，防止页面销毁后触发 setState 导致的内存错误。
+
+5. **资源释放**：`dispose()` 中释放了库控制器（`_controller?.dispose()`）和 TextField 控制器（`_urlController.dispose()`），并置空引用防止悬挂指针。
+
+6. **const 优化**：所有静态 Widget（标题 Text、SizedBox、Card 内的固定 Text 等）均使用 `const` 修饰，减少不必要重建。
+
+7. **错误处理**：所有异步调用均包裹在 `try/catch (e, stack)` 中，`dev.log` 同时传递 `error` 和 `stackTrace` 参数，方便调试定位。
+
+8. **接口真实性**：生成前应通过 `script_flutter_extract_interfaces` 提取 `flutter_video_player` 的接口规格，确认 `isHardwareDecodingSupported`、`VideoPlayerController`、`PlayerConfig` 等签名与源码一致后再编码。