Flutter for OpenHarmony：三方库实战irondash_engine_context 引擎上下文详解

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

---

🎯 前言：为什么需要引擎上下文？

在Flutter插件开发和原生交互中，经常需要访问Flutter引擎的上下文信息。

实际痛点：

• 🔧 插件开发：原生插件需要访问Flutter引擎实例
• 📱 平台通道：需要获取引擎实例进行平台通信
• 🎯 资源访问：访问Flutter资源和配置信息
• 🔄 生命周期：监听和管理引擎生命周期
• 🛠️ 调试工具：开发调试工具需要引擎信息
• 📊 性能监控：监控引擎性能和状态

实际场景需求：

• 场景一：开发原生插件需要获取引擎上下文
• 场景二：实现复杂的原生交互功能
• 场景三：访问平台特定的引擎功能
• 场景四：开发调试和性能分析工具
• 场景五：实现自定义的渲染或输入处理

irondash_engine_context 是解决这些问题的完美方案！它提供了：

• 🎯 统一接口：跨平台统一的引擎上下文访问
• 🔧 简单易用：简洁的API设计
• ⚡ 高性能：轻量级实现，零性能损耗
• 🌐 跨平台：支持多个平台包括OpenHarmony
• 🛡️ 类型安全：强类型API，编译时检查
• 📱 模拟器支持：可在模拟器测试基本功能

🚀 核心能力一览

功能特性	详细说明	OpenHarmony 支持
获取引擎上下文	获取Flutter引擎实例	✅
平台视图访问	访问平台特定视图	✅
资源访问	访问Flutter资源	✅
生命周期监听	监听引擎生命周期	✅
线程安全	线程安全的上下文访问	✅
异步获取	支持异步获取上下文	✅
跨平台一致	统一的API接口	✅

引擎上下文用途说明

用途	说明	适用场景
插件开发	原生插件访问引擎	开发平台插件
平台通道	建立原生通信	原生交互
资源管理	访问应用资源	资源加载
生命周期	监听引擎状态	状态管理
调试工具	开发调试功能	性能分析

📱 如何运行这些示例

运行步骤

1. 创建新项目或使用现有项目
2. 配置依赖（见下方）
3. 复制示例代码到 lib/main.dart
4. 运行应用：flutter run
5. 查看引擎上下文信息

⚠️ 常见问题

• 问题：获取上下文失败

  • 解决：确保在正确的生命周期阶段获取

• 问题：上下文为null

  • 解决：使用异步方式获取，添加null检查

• 问题：模拟器测试

  • 解决：基本功能可在模拟器测试

---

⚙️ 环境准备：两步走

第一步：添加依赖

📄 pubspec.yaml：

dependencies:
  flutter:
    sdk: flutter
  
  # 添加 irondash_engine_context 依赖（OpenHarmony 适配版本）
  irondash_engine_context:
    git:
      url: https://atomgit.com/openharmony-sig/fluttertpc_irondash.git
      path: engine_context/dart
      ref: br_v0.5.5_ohos

执行命令：

flutter pub get

第二步：导入包

在 Dart 文件中导入：

import 'package:flutter/material.dart';
import 'package:irondash_engine_context/irondash_engine_context.dart';

---

📚 基础用法：核心功能

示例1：基础引擎上下文获取

最简单的引擎上下文获取：

class BasicEngineContextDemo extends StatefulWidget {
  const BasicEngineContextDemo({super.key});

  @override
  State<BasicEngineContextDemo> createState() => _BasicEngineContextDemoState();
}

class _BasicEngineContextDemoState extends State<BasicEngineContextDemo> {
  EngineContext? _engineContext;
  String _status = '正在初始化...';
  bool _isLoading = true;

  @override
  void initState() {
    super.initState();
    _initEngineContext();
  }

  Future<void> _initEngineContext() async {
    try {
      // 获取引擎上下文实例
      final context = await EngineContext.instance;
    
      setState(() {
        _engineContext = context;
        _status = '✅ 引擎上下文获取成功';
        _isLoading = false;
      });
    
      print('引擎上下文: $_engineContext');
    } catch (e) {
      setState(() {
        _status = '❌ 获取失败: $e';
        _isLoading = false;
      });
      print('获取引擎上下文失败: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('基础引擎上下文'),
      ),
      body: Center(
        child: Padding(
          padding: const EdgeInsets.all(24),
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              if (_isLoading)
                const CircularProgressIndicator()
              else
                Icon(
                  _engineContext != null ? Icons.check_circle : Icons.error,
                  size: 80,
                  color: _engineContext != null ? Colors.green : Colors.red,
                ),
            
              const SizedBox(height: 24),
            
              Text(
                _status,
                style: const TextStyle(
                  fontSize: 18,
                  fontWeight: FontWeight.bold,
                ),
                textAlign: TextAlign.center,
              ),
            
              const SizedBox(height: 32),
            
              if (_engineContext != null)
                Card(
                  child: Padding(
                    padding: const EdgeInsets.all(16),
                    child: Column(
                      crossAxisAlignment: CrossAxisAlignment.start,
                      children: [
                        const Text(
                          '引擎信息：',
                          style: TextStyle(
                            fontSize: 16,
                            fontWeight: FontWeight.bold,
                          ),
                        ),
                        const SizedBox(height: 8),
                        Text('上下文类型: ${_engineContext.runtimeType}'),
                        const SizedBox(height: 4),
                        const Text('状态: 已连接'),
                      ],
                    ),
                  ),
                ),
            ],
          ),
        ),
      ),
    );
  }
}

核心要点：

• EngineContext.instance 返回 Future，需要 await
• 使用 try-catch 处理可能的异常
• 在 initState 中异步获取上下文

示例2：检查上下文可用性

检查引擎上下文是否可用：

class ContextAvailabilityDemo extends StatefulWidget {
  const ContextAvailabilityDemo({super.key});

  @override
  State<ContextAvailabilityDemo> createState() => _ContextAvailabilityDemoState();
}

class _ContextAvailabilityDemoState extends State<ContextAvailabilityDemo> {
  bool? _isAvailable;
  String _message = '';

  Future<void> _checkAvailability() async {
    setState(() {
      _isAvailable = null;
      _message = '检查中...';
    });

    try {
      final context = await EngineContext.instance;
    
      setState(() {
        _isAvailable = context != null;
        _message = context != null 
          ? '引擎上下文可用' 
          : '引擎上下文不可用';
      });
    } catch (e) {
      setState(() {
        _isAvailable = false;
        _message = '检查失败: $e';
      });
    }
  }

  @override
  void initState() {
    super.initState();
    _checkAvailability();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('上下文可用性'),
      ),
      body: Center(
        child: Padding(
          padding: const EdgeInsets.all(24),
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              if (_isAvailable == null)
                const CircularProgressIndicator()
              else
                Icon(
                  _isAvailable! ? Icons.check_circle : Icons.cancel,
                  size: 100,
                  color: _isAvailable! ? Colors.green : Colors.red,
                ),
            
              const SizedBox(height: 24),
            
              Text(
                _message,
                style: const TextStyle(fontSize: 18),
                textAlign: TextAlign.center,
              ),
            
              const SizedBox(height: 32),
            
              ElevatedButton.icon(
                onPressed: _checkAvailability,
                icon: const Icon(Icons.refresh),
                label: const Text('重新检查'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

示例3：多次获取上下文

演示多次获取引擎上下文：

class MultipleAccessDemo extends StatefulWidget {
  const MultipleAccessDemo({super.key});

  @override
  State<MultipleAccessDemo> createState() => _MultipleAccessDemoState();
}

class _MultipleAccessDemoState extends State<MultipleAccessDemo> {
  int _accessCount = 0;
  final List<String> _accessLog = [];
  bool _isAccessing = false;

  Future<void> _accessContext() async {
    if (_isAccessing) return;
  
    setState(() {
      _isAccessing = true;
    });

    try {
      final startTime = DateTime.now();
      final context = await EngineContext.instance;
      final endTime = DateTime.now();
      final duration = endTime.difference(startTime).inMilliseconds;
    
      setState(() {
        _accessCount++;
        _accessLog.insert(
          0,
          '第$_accessCount次访问 - 耗时: ${duration}ms - ${context != null ? "成功" : "失败"}',
        );
        _isAccessing = false;
      });
    } catch (e) {
      setState(() {
        _accessCount++;
        _accessLog.insert(0, '第$_accessCount次访问 - 失败: $e');
        _isAccessing = false;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('多次访问测试'),
        actions: [
          IconButton(
            icon: const Icon(Icons.delete),
            onPressed: () {
              setState(() {
                _accessLog.clear();
                _accessCount = 0;
              });
            },
          ),
        ],
      ),
      body: Column(
        children: [
          Container(
            padding: const EdgeInsets.all(16),
            color: Colors.blue.shade50,
            child: Column(
              children: [
                Text(
                  '访问次数: $_accessCount',
                  style: const TextStyle(
                    fontSize: 24,
                    fontWeight: FontWeight.bold,
                  ),
                ),
                const SizedBox(height: 16),
                ElevatedButton.icon(
                  onPressed: _isAccessing ? null : _accessContext,
                  icon: _isAccessing 
                    ? const SizedBox(
                        width: 16,
                        height: 16,
                        child: CircularProgressIndicator(strokeWidth: 2),
                      )
                    : const Icon(Icons.play_arrow),
                  label: Text(_isAccessing ? '访问中...' : '访问引擎上下文'),
                ),
              ],
            ),
          ),
          Expanded(
            child: _accessLog.isEmpty
                ? const Center(
                    child: Text('点击按钮开始访问'),
                  )
                : ListView.builder(
                    itemCount: _accessLog.length,
                    itemBuilder: (context, index) {
                      return ListTile(
                        leading: CircleAvatar(
                          child: Text('${_accessLog.length - index}'),
                        ),
                        title: Text(_accessLog[index]),
                        trailing: Icon(
                          _accessLog[index].contains('成功')
                            ? Icons.check_circle
                            : Icons.error,
                          color: _accessLog[index].contains('成功')
                            ? Colors.green
                            : Colors.red,
                        ),
                      );
                    },
                  ),
          ),
        ],
      ),
    );
  }
}

示例4：错误处理

完善的错误处理示例：

class ErrorHandlingDemo extends StatefulWidget {
  const ErrorHandlingDemo({super.key});

  @override
  State<ErrorHandlingDemo> createState() => _ErrorHandlingDemoState();
}

class _ErrorHandlingDemoState extends State<ErrorHandlingDemo> {
  String _result = '';
  bool _isLoading = false;

  Future<void> _safeGetContext() async {
    setState(() {
      _isLoading = true;
      _result = '';
    });

    try {
      // 尝试获取引擎上下文
      final context = await EngineContext.instance.timeout(
        const Duration(seconds: 5),
        onTimeout: () {
          throw TimeoutException('获取引擎上下文超时');
        },
      );
    
      if (context == null) {
        setState(() {
          _result = '⚠️ 引擎上下文为null';
          _isLoading = false;
        });
        return;
      }
    
      setState(() {
        _result = '✅ 成功获取引擎上下文\n类型: ${context.runtimeType}';
        _isLoading = false;
      });
    
    } on TimeoutException catch (e) {
      setState(() {
        _result = '⏱️ 超时错误\n${e.message}';
        _isLoading = false;
      });
    } catch (e, stackTrace) {
      setState(() {
        _result = '❌ 未知错误\n$e\n\n堆栈跟踪:\n${stackTrace.toString().split('\n').take(3).join('\n')}';
        _isLoading = false;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('错误处理'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            ElevatedButton.icon(
              onPressed: _isLoading ? null : _safeGetContext,
              icon: _isLoading
                  ? const SizedBox(
                      width: 16,
                      height: 16,
                      child: CircularProgressIndicator(strokeWidth: 2),
                    )
                  : const Icon(Icons.security),
              label: const Text('安全获取上下文'),
            ),
          
            const SizedBox(height: 24),
          
            if (_result.isNotEmpty)
              Expanded(
                child: Card(
                  child: SingleChildScrollView(
                    padding: const EdgeInsets.all(16),
                    child: Text(
                      _result,
                      style: const TextStyle(fontFamily: 'monospace'),
                    ),
                  ),
                ),
              ),
          ],
        ),
      ),
    );
  }
}

示例5：生命周期集成

在应用生命周期中使用引擎上下文：

class LifecycleIntegrationDemo extends StatefulWidget {
  const LifecycleIntegrationDemo({super.key});

  @override
  State<LifecycleIntegrationDemo> createState() => _LifecycleIntegrationDemoState();
}

class _LifecycleIntegrationDemoState extends State<LifecycleIntegrationDemo> 
    with WidgetsBindingObserver {
  EngineContext? _engineContext;
  final List<String> _lifecycleEvents = [];

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _addEvent('initState: 组件初始化');
    _initEngineContext();
  }

  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    _addEvent('didChangeDependencies: 依赖变化');
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    _addEvent('App生命周期: ${state.name}');
  
    if (state == AppLifecycleState.resumed) {
      _checkEngineContext();
    }
  }

  Future<void> _initEngineContext() async {
    _addEvent('开始获取引擎上下文...');
  
    try {
      final context = await EngineContext.instance;
      setState(() {
        _engineContext = context;
      });
      _addEvent('✅ 引擎上下文获取成功');
    } catch (e) {
      _addEvent('❌ 引擎上下文获取失败: $e');
    }
  }

  Future<void> _checkEngineContext() async {
    if (_engineContext != null) {
      _addEvent('引擎上下文仍然有效');
    } else {
      _addEvent('引擎上下文已失效，重新获取...');
      await _initEngineContext();
    }
  }

  void _addEvent(String event) {
    setState(() {
      _lifecycleEvents.insert(
        0,
        '${DateTime.now().toString().substring(11, 19)} - $event',
      );
    });
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    _addEvent('dispose: 组件销毁');
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('生命周期集成'),
        actions: [
          IconButton(
            icon: const Icon(Icons.delete),
            onPressed: () {
              setState(() {
                _lifecycleEvents.clear();
              });
            },
          ),
        ],
      ),
      body: Column(
        children: [
          Container(
            padding: const EdgeInsets.all(16),
            color: _engineContext != null 
              ? Colors.green.shade50 
              : Colors.grey.shade200,
            child: Row(
              children: [
                Icon(
                  _engineContext != null ? Icons.check_circle : Icons.pending,
                  color: _engineContext != null ? Colors.green : Colors.grey,
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: Text(
                    _engineContext != null 
                      ? '引擎上下文: 已连接' 
                      : '引擎上下文: 未连接',
                    style: const TextStyle(fontWeight: FontWeight.bold),
                  ),
                ),
              ],
            ),
          ),
          Expanded(
            child: ListView.builder(
              itemCount: _lifecycleEvents.length,
              itemBuilder: (context, index) {
                return ListTile(
                  dense: true,
                  leading: const Icon(Icons.circle, size: 8),
                  title: Text(
                    _lifecycleEvents[index],
                    style: const TextStyle(fontSize: 13),
                  ),
                );
              },
            ),
          ),
        ],
      ),
    );
  }
}

---

🎯 完整示例：引擎上下文管理器

下面是一个功能完整的引擎上下文管理应用，展示了所有核心功能：

import 'package:flutter/material.dart';
import 'package:irondash_engine_context/irondash_engine_context.dart';
import 'dart:async';

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

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: '引擎上下文管理器',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
        useMaterial3: true,
      ),
      home: const EngineContextHomePage(),
    );
  }
}

class EngineContextHomePage extends StatelessWidget {
  const EngineContextHomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('引擎上下文管理器'),
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
      ),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          _buildDemoCard(
            context,
            title: '基础获取',
            subtitle: '获取引擎上下文',
            icon: Icons.settings,
            color: Colors.blue,
            onTap: () {
              Navigator.push(
                context,
                MaterialPageRoute(
                  builder: (context) => const BasicEngineContextDemo(),
                ),
              );
            },
          ),
        
          _buildDemoCard(
            context,
            title: '可用性检查',
            subtitle: '检查上下文状态',
            icon: Icons.check_circle,
            color: Colors.green,
            onTap: () {
              Navigator.push(
                context,
                MaterialPageRoute(
                  builder: (context) => const ContextAvailabilityDemo(),
                ),
              );
            },
          ),
        
          _buildDemoCard(
            context,
            title: '多次访问',
            subtitle: '性能测试',
            icon: Icons.repeat,
            color: Colors.orange,
            onTap: () {
              Navigator.push(
                context,
                MaterialPageRoute(
                  builder: (context) => const MultipleAccessDemo(),
                ),
              );
            },
          ),
        
          _buildDemoCard(
            context,
            title: '错误处理',
            subtitle: '异常处理示例',
            icon: Icons.error_outline,
            color: Colors.red,
            onTap: () {
              Navigator.push(
                context,
                MaterialPageRoute(
                  builder: (context) => const ErrorHandlingDemo(),
                ),
              );
            },
          ),
        
          _buildDemoCard(
            context,
            title: '生命周期',
            subtitle: '生命周期集成',
            icon: Icons.timeline,
            color: Colors.purple,
            onTap: () {
              Navigator.push(
                context,
                MaterialPageRoute(
                  builder: (context) => const LifecycleIntegrationDemo(),
                ),
              );
            },
          ),
        ],
      ),
    );
  }

  Widget _buildDemoCard(
    BuildContext context, {
    required String title,
    required String subtitle,
    required IconData icon,
    required Color color,
    required VoidCallback onTap,
  }) {
    return Card(
      margin: const EdgeInsets.only(bottom: 16),
      elevation: 2,
      child: ListTile(
        contentPadding: const EdgeInsets.all(16),
        leading: Container(
          width: 50,
          height: 50,
          decoration: BoxDecoration(
            color: color.withOpacity(0.2),
            borderRadius: BorderRadius.circular(12),
          ),
          child: Icon(icon, color: color, size: 28),
        ),
        title: Text(
          title,
          style: const TextStyle(
            fontSize: 18,
            fontWeight: FontWeight.bold,
          ),
        ),
        subtitle: Text(subtitle),
        trailing: const Icon(Icons.arrow_forward_ios, size: 16),
        onTap: onTap,
      ),
    );
  }
}

完整示例说明：

1. 主页导航：展示所有功能模块
2. 基础获取：演示如何获取引擎上下文
3. 可用性检查：检查上下文是否可用
4. 多次访问：测试多次访问的性能
5. 错误处理：完善的异常处理
6. 生命周期：与应用生命周期集成

---

📊 API 详解

EngineContext 核心方法

class EngineContext {
  // 获取引擎上下文实例（异步）
  static Future<EngineContext> get instance;
  
  // 引擎上下文类型
  Type get runtimeType;
}

使用示例：

// 获取引擎上下文
final context = await EngineContext.instance;

// 检查类型
print('上下文类型: ${context.runtimeType}');

异步获取模式

// 模式1：async/await
Future<void> getContext() async {
  final context = await EngineContext.instance;
  // 使用context
}

// 模式2：then
EngineContext.instance.then((context) {
  // 使用context
});

// 模式3：带超时
final context = await EngineContext.instance.timeout(
  const Duration(seconds: 5),
);

---

💡 最佳实践

1. 异步获取

// ✅ 正确：使用async/await
Future<void> initContext() async {
  try {
    final context = await EngineContext.instance;
    // 使用context
  } catch (e) {
    print('获取失败: $e');
  }
}

// ❌ 错误：同步获取
void initContext() {
  final context = EngineContext.instance;  // 错误！返回Future
}

2. 错误处理

// ✅ 正确：完善的错误处理
Future<EngineContext?> safeGetContext() async {
  try {
    final context = await EngineContext.instance.timeout(
      const Duration(seconds: 5),
    );
    return context;
  } on TimeoutException {
    print('获取超时');
    return null;
  } catch (e) {
    print('获取失败: $e');
    return null;
  }
}

// ❌ 错误：没有错误处理
Future<EngineContext> getContext() async {
  return await EngineContext.instance;  // 可能抛出异常
}

3. 生命周期管理

// ✅ 正确：在合适的生命周期阶段获取
class MyWidget extends StatefulWidget {
  @override
  State<MyWidget> createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  EngineContext? _context;
  
  @override
  void initState() {
    super.initState();
    _initContext();  // 在initState中初始化
  }
  
  Future<void> _initContext() async {
    _context = await EngineContext.instance;
    setState(() {});
  }
  
  @override
  Widget build(BuildContext context) {
    if (_context == null) {
      return const CircularProgressIndicator();
    }
    return Text('上下文已就绪');
  }
}

4. 缓存上下文

// ✅ 正确：缓存引擎上下文
class EngineContextManager {
  static EngineContext? _cachedContext;
  
  static Future<EngineContext> getContext() async {
    if (_cachedContext != null) {
      return _cachedContext!;
    }
  
    _cachedContext = await EngineContext.instance;
    return _cachedContext!;
  }
  
  static void clearCache() {
    _cachedContext = null;
  }
}

// 使用
final context = await EngineContextManager.getContext();

5. 超时控制

// ✅ 正确：添加超时控制
Future<EngineContext?> getContextWithTimeout({
  Duration timeout = const Duration(seconds: 5),
}) async {
  try {
    return await EngineContext.instance.timeout(timeout);
  } on TimeoutException {
    print('获取引擎上下文超时');
    return null;
  }
}

---

🐛 常见问题与解决方案

问题1：获取上下文失败

现象：

• 调用 EngineContext.instance 抛出异常
• 返回null

解决方案：

// 1. 添加错误处理
Future<void> safeInit() async {
  try {
    final context = await EngineContext.instance;
    print('获取成功: $context');
  } catch (e) {
    print('获取失败: $e');
    // 重试逻辑
    await Future.delayed(const Duration(seconds: 1));
    final context = await EngineContext.instance;
  }
}

// 2. 检查生命周期
// 确保在正确的时机获取
@override
void initState() {
  super.initState();
  WidgetsBinding.instance.addPostFrameCallback((_) {
    _initContext();
  });
}

问题2：上下文为null

现象：

• 获取的上下文为null
• 无法使用上下文功能

解决方案：

// ✅ 正确：添加null检查
Future<void> useContext() async {
  final context = await EngineContext.instance;
  
  if (context == null) {
    print('上下文为null');
    return;
  }
  
  // 使用context
  print('上下文可用: $context');
}

// 使用null-safety
Future<void> useContextSafe() async {
  final context = await EngineContext.instance;
  print('上下文类型: ${context?.runtimeType}');
}

问题3：获取超时

现象：

• 获取上下文耗时过长
• 应用卡顿

解决方案：

// ✅ 正确：添加超时和加载提示
class TimeoutHandlingDemo extends StatefulWidget {
  @override
  State<TimeoutHandlingDemo> createState() => _TimeoutHandlingDemoState();
}

class _TimeoutHandlingDemoState extends State<TimeoutHandlingDemo> {
  bool _isLoading = false;
  String _message = '';
  
  Future<void> _getContextWithTimeout() async {
    setState(() {
      _isLoading = true;
      _message = '获取中...';
    });
  
    try {
      final context = await EngineContext.instance.timeout(
        const Duration(seconds: 3),
        onTimeout: () {
          throw TimeoutException('获取超时');
        },
      );
    
      setState(() {
        _isLoading = false;
        _message = '获取成功';
      });
    } on TimeoutException {
      setState(() {
        _isLoading = false;
        _message = '获取超时，请重试';
      });
    }
  }
  
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            if (_isLoading)
              const CircularProgressIndicator(),
            Text(_message),
            ElevatedButton(
              onPressed: _isLoading ? null : _getContextWithTimeout,
              child: const Text('获取上下文'),
            ),
          ],
        ),
      ),
    );
  }
}

问题4：内存泄漏

现象：

• 多次获取上下文导致内存增长
• 应用性能下降

解决方案：

// ✅ 正确：使用单例模式
class EngineContextService {
  static EngineContextService? _instance;
  EngineContext? _context;
  
  EngineContextService._();
  
  static EngineContextService get instance {
    _instance ??= EngineContextService._();
    return _instance!;
  }
  
  Future<EngineContext> getContext() async {
    _context ??= await EngineContext.instance;
    return _context!;
  }
  
  void dispose() {
    _context = null;
  }
}

// 使用
final context = await EngineContextService.instance.getContext();

---

📈 使用场景示例

场景1：插件开发

class MyPlugin {
  EngineContext? _engineContext;
  
  Future<void> initialize() async {
    try {
      _engineContext = await EngineContext.instance;
      print('插件初始化成功');
    } catch (e) {
      print('插件初始化失败: $e');
    }
  }
  
  Future<void> performAction() async {
    if (_engineContext == null) {
      throw StateError('引擎上下文未初始化');
    }
  
    // 使用引擎上下文执行操作
    print('执行插件操作');
  }
}

场景2：调试工具

class DebugTool {
  static Future<Map<String, dynamic>> getEngineInfo() async {
    try {
      final context = await EngineContext.instance;
    
      return {
        'available': context != null,
        'type': context?.runtimeType.toString(),
        'timestamp': DateTime.now().toIso8601String(),
      };
    } catch (e) {
      return {
        'available': false,
        'error': e.toString(),
      };
    }
  }
}

---

🎓 总结

通过本文，你已经掌握了：

✅ irondash_engine_context 的核心概念和优势

✅ 基础引擎上下文获取方法

✅ 上下文可用性检查

✅ 多次访问和性能测试

✅ 完善的错误处理

✅ 生命周期集成

✅ 完整的引擎上下文管理器实现

✅ 最佳实践和常见问题解决方案

irondash_engine_context 为Flutter插件开发提供了统一的引擎上下文访问接口！通过简洁的API和完善的错误处理，可以轻松实现复杂的原生交互功能。

---

🔗 相关资源

• irondash_engine_context 官方文档
• OpenHarmony 仓库
• Flutter插件开发指南

---