Contents

在 Flutter 裡使用 Packages

Contents

Flutter 支援使用其他開發者向 Flutter 和 Dart 生態系統貢獻的共享 package，這意味著你可以快速建構應用而不是一切從零開始。

現有的 package 支援許多使用場景，例如，網路請求 (http)，自訂導航/路由處理 (fluro)，整合裝置 API（如 (url_launcher 和 battery，以及使用第三方平台的 SDK（如 Firebase 的 (FlutterFire)。

如果你正打算開發新的 package，請參閱 Flutter Packages 的開發和提交。

如果你想新增資源、圖片或字型，無論是儲存在檔案中還是 package 中，請參閱 新增資源和圖片 這篇文件。

使用 package

下面的內容將為你描述如何使用已經發布了的 packages。

搜尋 package

Package 會被髮布到 pub.dev 網站上。

Pub 網站上的 Flutter 頁面 展示了與 Flutter 相容的 package（即宣告的依賴通常與 Flutter 相容），並且所有已釋出的 package 都支援搜尋。

Pub.dev 上的 Flutter Favorites 頁面列出了一系列編寫應用時可以首先考慮使用的外掛和 package，關於這個專案的更多資訊，請檢視 Flutter Favorites 專案 頁面。

在 pub.dev 網站上同時可以過濾出適合 Android、iOS、 Web、Linux、 Windows 或 macOS 的外掛，也可以透過複選框，過濾出組合結果（適配一個或者多個平台）。

將 package 依賴新增到應用

要將 package ‘css_colors’ 新增到應用：

  1. 新增依賴

    • 開啟應用資料夾下的 pubspec.yaml 檔案，然後在 pubspec.yaml 下新增 css_colors:。

  2. 安裝

    • 在命令列中執行：flutter pub get

    或者

    • 在 Android Studio/IntelliJ 中點選 pubspec.yaml 檔案頂部操作功能區的 Packages get

    • 在 VS Code 中點選位於 pubspec.yaml 檔案頂部操作功能區右側的 Get Packages

  3. 匯入

    • 在 Dart 程式碼中新增相關的 import 陳述式。

  4. 如果有必要，停止並重啟應用

    • 如果 package 內有特定平台的程式碼（Android 的 Java/Kotlin, iOS 的 Swift/Objective-C），程式碼必須內建到你的應用內。熱重載和熱重啟只對 package 的 Dart 程式碼執行此操作，所以你需要完全重啟應用以避免使用 package 時出現 MissingPluginException 錯誤。

使用命令 flutter pub add 新增一個 package 依賴

將 css_colors 這個 package 新增到工程中：

  1. 在專案根目錄執行命令

    • flutter pub add css_colors

  2. 匯入

    • 在 Dart 程式碼中新增相應的 import 陳述式

  3. 如果有必要，停止並重啟應用

    • 如果 package 內有特定平台的程式碼（Android 的 Java/Kotlin, iOS 的 Swift/Objective-C），程式碼必須內建到你的應用內。熱重載和熱重啟只對 package 的 Dart 程式碼執行此操作，所以你需要完全重啟應用以避免使用 package 時出現 MissingPluginException 錯誤。

使用 flutter pub remove 命令移除一個 package 依賴

要將 package ‘css_colors’ 從工程中移除：

  1. 在專案根目錄執行命令

    • flutter pub remove css_colors

對於這些步驟，Pub 上任何 package 頁面的 Installing tab 選項卡都是一個很方便的參考。

完整範例，參閱下面的 css_colors 範例 。

衝突解決

假設你想在應用中使用 some_package 和 other_package，並且它們依賴於不同版本的 url_launcher。於是我們便有了潛在的衝突。避免這種情況的最好方法是 package 的作者在指定依賴項時使用 版本範圍 而非特定版本。

dependencies:
  url_launcher: ^5.4.0    # Good, any version >= 5.4.0 but < 6.0.0
  image_picker: '5.4.3'   # Not so good, only version 5.4.3 works.

如果 some_package 聲明瞭以上依賴，並且 another_package 聲明瞭一個相容的 url_launcher 依賴項，如 '5.4.6' 或 ^5.5.0， pub 能夠自動解決衝突問題。 Gradle modules 和 CocoaPods 也是用類似的方式解決平台依賴的。

即使 some_package 和 another_package 聲明瞭不相容的 url_launcher 版本，它們實際上仍可能以相容的方式使用 url_launcher。在這種情況下，可在 pubspec.yaml 檔案中新增一個依賴覆蓋宣告來強制使用特定版本，從而處理衝突。

為了強制使用版本為 5.4.0 的 url_launcher，你可以對應用的 pubspec.yaml 檔案做如下更改：

dependencies:
  some_package:
  another_package:
dependency_overrides:
  url_launcher: '5.4.0'

如果依賴衝突項不是 package 自身，而是如 guava 這樣特定於 Android 的函式庫，那麼依賴的覆蓋宣告必須新增到 Gradle 的建構邏輯中。

為了強制使用版本為 28.0 的 guava，你可以對 android/build.gradle 檔案做如下更改：

configurations.all {
    resolutionStrategy {
        force 'com.google.guava:guava:28.0-android'
    }
}

CocoaPods 目前尚不提供依賴項覆蓋功能。

開發新的 package

如果某個 package 不適用於你的特定需求，你可以 開發新的自訂 package。

管理 package 的依賴和版本

為了使版本衝突的風險最小化，請在 pubspec.yaml 檔案中指定一個版本範圍。

Package 版本

所有 package 都有一個版本號，在它們的 pubspec.yaml 檔案中指定。當前的 package 版本會在其名稱旁邊顯示當前版本號。（例如，參閱 url_launcher package）以及所有先前版本的列表： url_launcher 版本列表。

當使用簡寫形式 plugin1: 將 package 新增到 pubspec.yaml 時，表明 plugin1 package 的任何版本都可以被使用。為了確保在更新 package 的時候你的應用不會崩潰，我們建議使用以下格式之一來指定版本範圍：

  • 範圍限制：指定一個最小和最大的版本號，例如：

    dependencies:
  url_launcher: '>=5.4.0 <6.0.0'

  • 使用 caret語法 的範圍約束與常規的範圍約束類似：

    dependencies:
  collection: '^5.4.0'

瞭解更詳細的資訊，參閱 Pub 版本管理指南。

更新 package 依賴

當你新增一個 package 後首次執行 flutter pub get（IntelliJ 或 Android Studio 中的 Packages Get）， Flutter 將會儲存在 pubspec.lock lockfile 中找到的具體 package 版本。這將確保當你或者團隊中其他開發者執行 flutter pub get 後能得到相同版本的 package。

如果你想升級到 package 的最新版本，比如使用 package 的最新特性，請執行 flutter packages upgrade （IntelliJ 或 Android Studio 的 Upgrade dependencies 功能）。這將檢索你在 pubspec.yaml 檔案中指定的版本約束所允許的最高可用版本。請注意，flutter upgrade 與 flutter update-packages 是兩個不同的命令，但它們都會更新 Flutter。

依賴未釋出的 package

即使未在 Pub site 上釋出，也可以使用 package。對於不用於公開發布的私有外掛，或者尚未準備好釋出的 package，可以使用其他依賴選項。

Path 依賴
Flutter 應用可以透過檔案系統 path: 依賴而依賴於外掛。路徑可以是相對的，也可以是絕對的。例如，要依賴位於應用相鄰目錄中的外掛 plugin1，可以使用以下語法：

  dependencies:
    plugin1:
      path: ../plugin1/

Git 依賴
你也可以依賴儲存在 Git 儲存庫中的 package，如果 package 位於儲存庫的根目錄，可以使用以下語法：

  dependencies:
    plugin1:
      git:
        url: https://github.com/flutter/plugin1.git

透過 SSH 依賴 Git package
如果你需要透過 SSH 連線私有的儲存庫，你可以用 SSH 連結依賴對應的 package：

  dependencies:
    plugin1:
      git:
        url: git@github.com:flutter/plugin1.git

**Git 依賴於資料夾中的 package **
預設情況下，pub 會預設假定 package 位於 Git 儲存庫的根目錄。如果不是這種情況，你可以使用 path 引數指定位置，例如：

  dependencies:
    package1:
      git:
        url: https://github.com/flutter/packages.git
        path: packages/package1

最後，你可以使用 ref 引數將依賴固定到 git 特定的 commit、branch 或者 tag。更多詳細資訊，請參閱 Package dependencies。

例子

下面的範例將介紹使用 packages 的一些必要步驟。

例子：使用 CSS Colors package

css_colors package 為 CSS 顏色定義顏色常量，允許你在 Flutter 框架中任何需要 Color 型別的地方使用它們。

要使用這個 package：

  1. 建立一個名為 cssdemo 的新專案

  2. 開啟 pubspec.yaml，並新增依賴 css-colors：

    dependencies:
  flutter:
    sdk: flutter

    替換為：

    dependencies:
  flutter:
    sdk: flutter
  css_colors: ^1.0.0

  3. 在命令列中執行 flutter packages get，或者點選 Intellij 中的 Packages get

  4. 開啟 lib/main.dart 並將其全部內容替換為：

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

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

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

   @override
   Widget build(BuildContext context) {
     return const MaterialApp(
       home: DemoPage(),
     );
   }
 }

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

   @override
   Widget build(BuildContext context) {
     return Scaffold(body: Container(color: CSSColors.orange));
   }
 }

  5. 執行應用。當你點選 ‘Show Flutter homepage’ 時，你將看到手機預設瀏覽器開啟並出現 Flutter 主頁。

例子：使用 url_launcher package 來開啟瀏覽器

url_launcher 外掛可以讓你在移動平臺上開啟預設瀏覽器以顯示給定的 URL。它示範了 package 如何也可能包含特定於平台的程式碼我們將這一類包含各平台不同程式碼的 package 稱為 外掛 package 或者 外掛。

要使用這個外掛：

  1. 新建一個名為 lauchdemo 的新專案；

  2. 開啟 pubspec.yaml，然後新增 url_launcher 的依賴：

    dependencies:
  flutter:
    sdk: flutter
  url_launcher: ^5.4.0

  3. 在命令列中執行 flutter packages get，或者點選 Intellij 或 Android Studio 中的 Packages get；

  4. 開啟 lib/main.dart 並將其全部內容替換為：

    import 'package:flutter/material.dart';
 import 'package:path/path.dart' as p;
 import 'package:url_launcher/url_launcher.dart';

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

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

   @override
   Widget build(BuildContext context) {
     return const MaterialApp(
       home: DemoPage(),
     );
   }
 }

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

   launchURL() {
     launchUrl(p.toUri('https://flutter.dev'));
   }

   @override
   Widget build(BuildContext context) {
     return Scaffold(
       body: Center(
         child: ElevatedButton(
           onPressed: launchURL,
           child: const Text('Show Flutter homepage'),
         ),
       ),
     );
   }
 }

  5. 執行應用（如果你的應用在新增外掛之前已經執行，請停止並重啟應用）。當你點選 Show Flutter homepage 時，你將看到手機預設瀏覽器開啟並出現 Flutter 主頁。