Flutter App Links 鸿蒙平台使用指南

app_links是一个专为OpenHarmony平台优化的Flutter插件，支持应用链接和深度链接处理。核心功能包括获取初始/最新链接、实时监听链接流，并支持URI和字符串格式。通过Git方式引入依赖后，需在鸿蒙配置文件中声明自定义协议。API提供多种方式获取链接数据，示例展示了如何解析链接实现页面导航。适用于应用跳转、深度导航和营销推广等场景，为鸿蒙应用提供了完整的深度链接解决方案。

fengxinzi_zack

888人浏览 · 2025-12-21 20:02:29

fengxinzi_zack · 2025-12-21 20:02:29 发布

1. 插件介绍

app_links 是一个功能强大的 Flutter 插件，用于处理应用链接（App Links）和深度链接（Deep Links）。该插件为 OpenHarmony（鸿蒙）平台提供了专门的适配版本，使开发者能够在鸿蒙应用中轻松实现从外部链接启动应用并导航到特定页面的功能。

核心功能

支持获取应用启动时的初始链接
支持获取应用运行时收到的最新链接
支持监听链接流，实时处理传入的链接
支持以 URI 或字符串形式处理链接
完全适配鸿蒙平台的链接处理机制

适用场景

实现应用间的相互跳转
支持从浏览器、社交媒体或其他应用启动你的应用
实现应用内的深度导航（如直接打开特定商品页面、文章详情等）
支持营销活动的深度链接推广

2. 安装与配置

2.1 Git 依赖配置

由于这是一个专为鸿蒙平台定制的修改版本，需要通过 Git 形式引入。在项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  app_links_ohos:
    git:
      url: "https://atomgit.com/openharmony-sig/fluttertpc_app_links.git"
      path: "app_links/ohos"

2.2 依赖获取

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

flutter pub get

2.3 鸿蒙平台配置

要在鸿蒙平台上支持深度链接，需要在项目的 entry/src/main/module.json5 文件中配置 skills 标签：

"skills": [
  {
    "uris": [
      {
        "scheme": "sample",
        "host": "open.my.app",
      }
    ]
  }
]

配置说明：

scheme：自定义协议名称，用于标识你的应用
host：协议的主机部分，类似于网址的域名

你可以根据自己的需求修改这些配置。例如，如果你的应用包名为 com.example.myapp，可以配置：

"skills": [
  {
    "uris": [
      {
        "scheme": "myapp",
        "host": "example.com",
      }
    ]
  }
]

3. API 使用

3.1 基本导入

在需要使用该插件的 Dart 文件中导入包：

import 'package:app_links/app_links.dart';

3.2 核心 API

AppLinks 类是该插件的核心类，提供了以下主要方法：

3.2.1 获取初始链接

获取应用启动时的初始链接（如果应用是通过外部链接启动的）：

final appLinks = AppLinks();
final initialLink = await appLinks.getInitialLink();
if (initialLink != null) {
  print('应用通过链接启动: $initialLink');
  // 处理初始链接
}

或者以字符串形式获取：

final initialLinkString = await appLinks.getInitialLinkString();
if (initialLinkString != null) {
  print('应用通过链接启动: $initialLinkString');
  // 处理初始链接
}

3.2.2 获取最新链接

获取应用运行时收到的最新链接：

final latestLink = await appLinks.getLatestLink();
if (latestLink != null) {
  print('最新链接: $latestLink');
  // 处理最新链接
}

或者以字符串形式获取：

final latestLinkString = await appLinks.getLatestLinkString();
if (latestLinkString != null) {
  print('最新链接: $latestLinkString');
  // 处理最新链接
}

3.2.3 监听链接流

监听传入的链接流，实时处理新收到的链接：

StreamSubscription<Uri>? _linkSubscription;

void initDeepLinks() {
  final appLinks = AppLinks();
  _linkSubscription = appLinks.uriLinkStream.listen((uri) {
    print('收到新链接: $uri');
    // 处理链接
  });
}

// 在组件销毁时取消订阅
@override
void dispose() {
  _linkSubscription?.cancel();
  super.dispose();
}

或者监听字符串形式的链接流：

_linkSubscription = appLinks.stringLinkStream.listen((linkString) {
  print('收到新链接: $linkString');
  // 处理链接
});

4. 使用示例

4.1 基本使用示例

以下是一个完整的示例，展示如何在鸿蒙应用中使用 app_links 插件：

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

void main() => runApp(const MyApp());

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

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final _navigatorKey = GlobalKey<NavigatorState>();
  late AppLinks _appLinks;
  StreamSubscription<Uri>? _linkSubscription;

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

  @override
  void dispose() {
    _linkSubscription?.cancel();
    super.dispose();
  }

  Future<void> initDeepLinks() async {
    _appLinks = AppLinks();

    // 处理初始链接
    final initialLink = await _appLinks.getInitialLink();
    if (initialLink != null) {
      print('初始链接: $initialLink');
      openAppLink(initialLink);
    }

    // 监听链接流
    _linkSubscription = _appLinks.uriLinkStream.listen((uri) {
      print('收到新链接: $uri');
      openAppLink(uri);
    });
  }

  void openAppLink(Uri uri) {
    // 从链接中提取导航信息
    // 例如：sample://open.my.app/#/book/hello-world
    // fragment 部分为：/book/hello-world
    _navigatorKey.currentState?.pushNamed(uri.fragment);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: _navigatorKey,
      initialRoute: '/',
      onGenerateRoute: (RouteSettings settings) {
        Widget routeWidget = defaultScreen();

        // 解析路由参数
        final routeName = settings.name;
        if (routeName != null) {
          if (routeName.startsWith('/book/')) {
            // 导航到书籍详情页面
            final bookId = routeName.substring(routeName.indexOf('/book/') + 6);
            routeWidget = bookDetailScreen(bookId);
          } else if (routeName == '/about') {
            // 导航到关于页面
            routeWidget = aboutScreen();
          }
        }

        return MaterialPageRoute(
          builder: (context) => routeWidget,
          settings: settings,
        );
      },
    );
  }

  Widget defaultScreen() {
    return Scaffold(
      appBar: AppBar(title: const Text('首页')),
      body: const Center(
        child: Text('欢迎使用 App Links 示例应用'),
      ),
    );
  }

  Widget bookDetailScreen(String bookId) {
    return Scaffold(
      appBar: AppBar(title: const Text('书籍详情')),
      body: Center(child: Text('书籍 ID: $bookId')),
    );
  }

  Widget aboutScreen() {
    return Scaffold(
      appBar: AppBar(title: const Text('关于')),
      body: const Center(child: Text('App Links 示例应用')),
    );
  }
}