1. 插件介绍

Quick Actions 是一个 Flutter 插件，允许开发者管理和与应用的主屏幕快捷操作进行交互。快捷操作是一种允许用户从主屏幕快速访问应用特定功能的机制，在 iOS 上对应 “Quick Actions” 概念，在 Android 上对应 “App Shortcuts” API。

主要特性

• 支持在应用主屏幕上添加快捷操作
• 允许用户通过快捷操作快速启动应用并执行特定功能
• 支持自定义快捷操作的图标、标题和类型
• 提供初始化回调，用于处理用户通过快捷操作启动应用的事件
• 支持动态设置和清除快捷操作
• 跨平台支持（iOS、Android）
• 鸿蒙平台兼容性

鸿蒙平台支持

Quick Actions 包通过 Flutter 的平台接口机制提供了对鸿蒙平台的支持潜力。虽然当前没有专门针对鸿蒙平台的实现，但开发者可以通过扩展平台接口为鸿蒙平台添加特定实现，利用鸿蒙系统的快捷操作功能。

2. 依赖配置

由于需要使用自定义修改版本，我们将通过 Git 形式引入依赖。

2.1 配置 pubspec.yaml

在 Flutter 项目的 pubspec.yaml 文件中，添加以下依赖配置：

dependencies:
  flutter:
    sdk: flutter
  quick_actions:
    git:
      url: "https://gitcode.com/openharmony-tpc/flutter_packages.git"
      path: "packages/quick_actions/quick_actions"
  quick_actions_ohos:
    git:
      url: "https://gitcode.com/openharmony-tpc/flutter_packages.git"
      path: "packages/quick_actions/quick_actions_ohos"

2.2 安装依赖

添加依赖后，执行以下命令获取包：

flutter pub get

3. API 调用

Quick Actions 包提供了简单易用的 API，用于管理应用的快捷操作。以下是主要 API 的使用示例：

3.1 初始化快捷操作

在应用生命周期的早期初始化 Quick Actions 插件，并提供一个回调函数，用于处理用户通过快捷操作启动应用的事件：

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

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

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Quick Actions Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({Key? key}) : super(key: key);

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final QuickActions quickActions = const QuickActions();
  String _lastAction = 'No action yet';

  @override
  void initState() {
    super.initState();
    // 初始化快捷操作
    _initQuickActions();
    // 设置快捷操作项
    _setupQuickActions();
  }

  // 初始化快捷操作并设置回调
  void _initQuickActions() {
    quickActions.initialize((shortcutType) {
      setState(() {
        _lastAction = 'Launched via shortcut: $shortcutType';
      });
      
      // 根据快捷操作类型执行不同的功能
      if (shortcutType == 'action_search') {
        _navigateToSearch();
      } else if (shortcutType == 'action_new_note') {
        _createNewNote();
      } else if (shortcutType == 'action_settings') {
        _openSettings();
      }
    });
  }

  // 设置快捷操作项
  void _setupQuickActions() {
    quickActions.setShortcutItems(const <ShortcutItem>[
      ShortcutItem(
        type: 'action_search',
        localizedTitle: 'Search',
        icon: 'search_icon',
      ),
      ShortcutItem(
        type: 'action_new_note',
        localizedTitle: 'New Note',
        icon: 'note_icon',
      ),
      ShortcutItem(
        type: 'action_settings',
        localizedTitle: 'Settings',
        icon: 'settings_icon',
      ),
    ]);
  }

  // 导航到搜索页面
  void _navigateToSearch() {
    // 实现导航逻辑
    print('Navigating to search page');
  }

  // 创建新笔记
  void _createNewNote() {
    // 实现创建新笔记逻辑
    print('Creating new note');
  }

  // 打开设置页面
  void _openSettings() {
    // 实现打开设置逻辑
    print('Opening settings');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Quick Actions Demo'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              _lastAction,
              style: const TextStyle(fontSize: 18),
              textAlign: TextAlign.center,
            ),
            const SizedBox(height: 20),
            const Text(
              'Try long-pressing the app icon to see quick actions!',
              textAlign: TextAlign.center,
              style: TextStyle(color: Colors.grey),
            ),
          ],
        ),
      ),
    );
  }
}

3.2 设置快捷操作项

使用 setShortcutItems 方法设置应用的快捷操作项：

quickActions.setShortcutItems(const <ShortcutItem>[
  ShortcutItem(
    type: 'action_main',
    localizedTitle: 'Main View',
    icon: 'icon_main',
  ),
  ShortcutItem(
    type: 'action_profile',
    localizedTitle: 'My Profile',
    icon: 'icon_profile',
  ),
  ShortcutItem(
    type: 'action_favorites',
    localizedTitle: 'Favorites',
    icon: 'icon_favorites',
  ),
]);

每个 ShortcutItem 包含以下属性：

• type: 快捷操作的唯一标识符，用于在回调中识别不同的快捷操作
• localizedTitle: 快捷操作的本地化标题
• icon: 快捷操作的图标名称（原生资源，不是 Flutter 资源）

3.3 清除快捷操作项

使用 clearShortcutItems 方法清除所有已设置的快捷操作项：

// 清除所有快捷操作项
quickActions.clearShortcutItems();

4. 完整示例

以下是一个完整的示例，展示了如何在鸿蒙平台上使用 Quick Actions 包：

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

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

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Quick Actions Complete Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      initialRoute: '/',
      routes: {
        '/': (context) => const HomePage(),
        '/search': (context) => const SearchPage(),
        '/new_note': (context) => const NewNotePage(),
        '/settings': (context) => const SettingsPage(),
      },
    );
  }
}

class HomePage extends StatefulWidget {
  const HomePage({Key? key}) : super(key: key);

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  final QuickActions quickActions = const QuickActions();
  String _lastAction = 'No action yet';

  @override
  void initState() {
    super.initState();
    _initQuickActions();
    _setupQuickActions();
  }

  void _initQuickActions() {
    quickActions.initialize((shortcutType) {
      setState(() {
        _lastAction = 'Launched via shortcut: $shortcutType';
      });

      // 根据快捷操作类型导航到不同页面
      switch (shortcutType) {
        case 'action_search':
          Navigator.pushNamed(context, '/search');
          break;
        case 'action_new_note':
          Navigator.pushNamed(context, '/new_note');
          break;
        case 'action_settings':
          Navigator.pushNamed(context, '/settings');
          break;
        default:
          break;
      }
    });
  }

  void _setupQuickActions() {
    quickActions.setShortcutItems(const <ShortcutItem>[
      ShortcutItem(
        type: 'action_search',
        localizedTitle: 'Search',
        icon: 'search_icon',
      ),
      ShortcutItem(
        type: 'action_new_note',
        localizedTitle: 'New Note',
        icon: 'note_icon',
      ),
      ShortcutItem(
        type: 'action_settings',
        localizedTitle: 'Settings',
        icon: 'settings_icon',
      ),
    ]);
  }

  void _clearQuickActions() {
    quickActions.clearShortcutItems();
    setState(() {
      _lastAction = 'All quick actions cleared';
    });
  }

  void _restoreQuickActions() {
    _setupQuickActions();
    setState(() {
      _lastAction = 'Quick actions restored';
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Quick Actions Demo'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(20),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              _lastAction,
              style: const TextStyle(fontSize: 20, fontWeight: FontWeight.bold),
              textAlign: TextAlign.center,
            ),
            const SizedBox(height: 30),
            const Text(
              'Try these actions:',
              style: TextStyle(fontSize: 18),
            ),
            const SizedBox(height: 10),
            ListTile(
              leading: const Icon(Icons.search),
              title: const Text('Search'),
              onTap: () {
                Navigator.pushNamed(context, '/search');
              },
            ),
            ListTile(
              leading: const Icon(Icons.note_add),
              title: const Text('New Note'),
              onTap: () {
                Navigator.pushNamed(context, '/new_note');
              },
            ),
            ListTile(
              leading: const Icon(Icons.settings),
              title: const Text('Settings'),
              onTap: () {
                Navigator.pushNamed(context, '/settings');
              },
            ),
            const SizedBox(height: 30),
            const Divider(),
            const SizedBox(height: 20),
            const Text(
              'Manage Quick Actions:',
              style: TextStyle(fontSize: 18),
            ),
            const SizedBox(height: 10),
            Row(
              mainAxisAlignment: MainAxisAlignment.spaceEvenly,
              children: [
                ElevatedButton(
                  onPressed: _clearQuickActions,
                  child: const Text('Clear Quick Actions'),
                ),
                ElevatedButton(
                  onPressed: _restoreQuickActions,
                  child: const Text('Restore Quick Actions'),
                ),
              ],
            ),
            const SizedBox(height: 20),
            const Text(
              'Note: On HarmonyOS, you may need to long-press the app icon to see quick actions.',
              textAlign: TextAlign.center,
              style: TextStyle(fontSize: 12, color: Colors.grey),
            ),
          ],
        ),
      ),
    );
  }
}

// 搜索页面
class SearchPage extends StatelessWidget {
  const SearchPage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Search Page'),
      ),
      body: const Center(
        child: Text('Search functionality would be implemented here.'),
      ),
    );
  }
}

// 新建笔记页面
class NewNotePage extends StatelessWidget {
  const NewNotePage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('New Note'),
      ),
      body: const Center(
        child: Text('New note creation functionality would be implemented here.'),
      ),
    );
  }
}

// 设置页面
class SettingsPage extends StatelessWidget {
  const SettingsPage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Settings'),
      ),
      body: const Center(
        child: Text('Settings functionality would be implemented here.'),
      ),
    );
  }
}

5. 注意事项

5.1 鸿蒙平台特定考虑

1. 图标资源：快捷操作的图标必须是原生资源，而不是 Flutter 资源。在鸿蒙平台上，需要将图标添加到原生资源目录中。

2. 快捷操作类型：确保每个快捷操作的 type 属性在应用内是唯一的，以便正确识别用户的操作。

3. 初始化时机：建议在应用启动时尽早初始化 Quick Actions 插件，以确保能够捕获所有通过快捷操作启动应用的事件。

4. 用户体验：快捷操作的标题应该简洁明了，准确描述快捷操作的功能。

5.2 最佳实践

1. 合理设置快捷操作：只添加最常用的功能作为快捷操作，避免过多的快捷操作导致用户选择困难。

2. 本地化支持：为快捷操作的标题提供本地化支持，以适应不同语言的用户。

3. 动态更新：根据用户的使用习惯或应用状态动态更新快捷操作。

4. 错误处理：虽然当前 API 没有返回错误信息，但在实现鸿蒙平台特定代码时，应该添加适当的错误处理。

5.3 性能考虑

• 设置快捷操作的操作是异步的，不会阻塞 UI 线程。
• 避免频繁调用 setShortcutItems 方法，这可能会影响应用性能。
• 建议在应用启动时或用户明确要求时更新快捷操作。

6. 总结

Quick Actions 是一个功能强大的 Flutter 插件，允许开发者为应用添加主屏幕快捷操作，提高用户体验。虽然当前没有专门针对鸿蒙平台的实现，但通过平台接口机制，可以为鸿蒙平台添加特定实现。

主要优势

1. 提高用户体验：允许用户快速访问应用的常用功能，减少操作步骤。

2. 跨平台支持：支持 iOS、Android 和鸿蒙等多个平台。

3. 简单易用的 API：提供简洁直观的 API，便于开发者集成和使用。

4. 灵活配置：支持动态设置和清除快捷操作，适应不同的应用场景。

适用场景

Quick Actions 包适用于以下场景：

1. 常用功能快速访问：为应用的核心功能提供快捷访问方式，如搜索、新建笔记、查看收藏等。

2. 个性化体验：根据用户的使用习惯提供个性化的快捷操作。

3. 提高用户参与度：通过快捷操作鼓励用户使用应用的更多功能。

4. 专业应用：为专业应用提供快速访问高级功能的方式。

通过使用 Quick Actions 包，开发者可以为鸿蒙平台的 Flutter 应用添加便捷的主屏幕快捷操作，提高应用的可用性和用户体验。