使用包

Flutter 支援使用由其他開發者為 Flutter 和 Dart 生態系統貢獻的共享包。這使得開發者能夠快速構建應用，而無需從頭開發所有內容。

現有的包支援許多用例——例如，進行網路請求（http）、導航/路由處理（go_router）、與裝置 API 整合（url_launcher 和 battery_plus），以及使用第三方平臺 SDK（如 Firebase，即 FlutterFire）。

要編寫一個新包，請參閱開發包。要新增資產、影像或字型（無論儲存在檔案還是包中），請參閱新增資產和影像。

以下部分介紹瞭如何使用現有的已釋出包。

包被髮布到 pub.dev。

pub.dev 上的 Flutter 著陸頁展示了與 Flutter 相容的熱門包（即聲明瞭與 Flutter 通用相容的依賴項的包），並支援在所有已釋出的包中進行搜尋。

pub.dev 上的 Flutter 推薦包 (Flutter Favorites) 頁面列出了被認定為你在編寫應用時應優先考慮使用的外掛和包。有關成為 Flutter 推薦包意味著什麼的更多資訊，請參閱 Flutter 推薦包計劃。

你還可以透過過濾 Android、iOS、Web、Linux、Windows、macOS 或它們的任何組合，來瀏覽 pub.dev 上的包。

要將 english_words 包新增到應用中

1. 在專案目錄內使用 pub add 命令

   • flutter pub add english_words

2. 匯入它

   • 在 Dart 程式碼中新增相應的 import 語句。

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

   • 如果包引入了特定於平臺的程式碼（Android 使用 Kotlin/Java，iOS 使用 Swift/Objective-C），則必須將該程式碼構建到你的應用中。熱過載和熱重啟僅更新 Dart 程式碼，因此可能需要完全重啟應用，以避免在使用該包時出現 MissingPluginException 等錯誤。

要將 english_words 包新增到應用中

1. 依賴它

   • 開啟應用資料夾內的 pubspec.yaml 檔案，在 dependencies 下新增 english_words: ^4.0.0。

2. 安裝它

   • 從終端執行：flutter pub get。
     或者
   • 在 VS Code 中：點選 pubspec.yaml 頂部操作功能區右側的“下載”圖示（Get Packages）。
   • 在 Android Studio/IntelliJ 中：點選 pubspec.yaml 頂部操作功能區中的 Pub get。

3. 匯入它

   • 在 Dart 程式碼中新增相應的 import 語句。

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

   • 如果包引入了特定於平臺的程式碼（Android 使用 Kotlin/Java，iOS 使用 Swift/Objective-C），則必須將該程式碼構建到你的應用中。熱過載和熱重啟僅更新 Dart 程式碼，因此可能需要完全重啟應用，以避免在使用該包時出現 MissingPluginException 等錯誤。

要從應用中移除 english_words 包

1. 在專案目錄內使用 pub remove 命令
   • flutter pub remove english_words

pub.dev 上每個包頁面提供的安裝 (Installing) 選項卡是這些步驟的便捷參考。

有關完整示例，請參閱下方的 english_words 示例。

假設你希望在應用中使用 some_package 和 another_package，並且它們都依賴於 url_launcher，但版本不同。這會導致潛在的衝突。避免這種情況的最佳方法是包作者在指定依賴項時使用版本範圍，而不是特定版本。

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 模組和/或 CocoaPods 的平臺特定依賴項也會以類似方式解決。

即使 some_package 和 another_package 為 url_launcher 聲明瞭不相容的版本，它們實際上也可能以相容的方式使用 url_launcher。在這種情況下，可以透過在應用的 pubspec.yaml 檔案中新增依賴項覆蓋（dependency override）宣告來解決衝突，強制使用特定版本。

例如，要強制使用 url_launcher 版本 5.4.0，請對應用的 pubspec.yaml 檔案進行以下更改

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

如果衝突的依賴項本身不是包，而是像 guava 這樣的 Android 特定庫，則必須改為在 Gradle 構建邏輯中新增依賴項覆蓋宣告。

要強制使用 guava 版本 28.0，請對應用的 android/build.gradle 檔案進行以下更改

configurations.all {
    resolutionStrategy {
        force("com.google.guava:guava:28.0-android")
    }
}

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

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

如果針對你的特定用例不存在現成的包，你可以編寫一個自定義包。

為了降低版本衝突的風險，請在 pubspec.yaml 檔案中指定版本範圍。

所有包都有一個版本號，在包的 pubspec.yaml 檔案中指定。包的當前版本顯示在其名稱旁邊（例如，參見 url_launcher 包），此外還有所有先前版本的列表（參見 url_launcher 版本）。

為確保在更新包時應用不會崩潰，請使用以下格式之一指定版本範圍。

• 範圍約束：指定最小和最大版本。

  yaml

  dependencies:
    url_launcher: '>=5.4.0 <6.0.0'
  

  content_copy

• 使用 插入符號 (caret) 語法的範圍約束：指定作為包含性最小版本的版本。這涵蓋了從該版本到下一個主版本的所有版本。

  yaml

  dependencies:
    collection: '^5.4.0'
  

  content_copy

  此語法與第一個要點中提到的語法含義相同。

要了解更多資訊，請查閱 包版本控制指南。

首次新增包後執行 flutter pub get 時，Flutter 會儲存 pubspec.lock 鎖檔案中找到的具體包版本。這確保瞭如果你或團隊中的其他開發者執行 flutter pub get，都能獲得相同的版本。

要升級到包的新版本（例如使用該包中的新功能），請執行 flutter pub upgrade 以檢索 pubspec.yaml 中指定版本約束所允許的最高可用包版本。請注意，這與 flutter upgrade 或 flutter update-packages 不同，後者是用於更新 Flutter 本身的。

即使包未釋出在 pub.dev 上，也可以使用它們。對於私有包，或尚未準備好釋出的包，可以使用其他依賴項選項

路徑依賴

Flutter 應用可以使用檔案系統 path: 依賴項來依賴某個包。路徑可以是相對路徑或絕對路徑。相對路徑是相對於包含 pubspec.yaml 的目錄進行評估的。例如，要依賴於位於應用所在目錄旁邊的目錄中的 packageA，請使用以下語法

yaml

  dependencies:
  packageA:
    path: ../packageA/

content_copy

Git 依賴

你還可以依賴儲存在 Git 倉庫中的包。如果包位於倉庫的根目錄，請使用以下語法

yaml

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

content_copy

使用 SSH 的 Git 依賴

如果倉庫是私有的且可以透過 SSH 連線，請使用該倉庫的 SSH URL 來依賴該包

yaml

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

content_copy

對資料夾中包的 Git 依賴

Pub 預設包位於 Git 倉庫的根目錄。如果並非如此，請使用 path 引數指定位置。例如

yaml

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

content_copy

最後，使用 ref 引數將依賴項固定到特定的 Git 提交、分支或標籤。有關更多詳細資訊，請參閱 包依賴項。

以下示例展示了使用包的必要步驟。

english_words 包包含數千個最常用的英語單詞以及一些實用函式。

要使用此包

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

2. 執行 dart pub add english_words 以新增依賴。

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

   dart

   import 'package:english_words/english_words.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: Center(child: Text(generateWordPairs().first.asPascalCase)),
       );
     }
   }
   

   content_copy

4. 執行應用。應用文字應顯示一個隨機的英語單詞對。

url_launcher 外掛包支援在移動平臺上開啟預設瀏覽器以顯示給定 URL，並支援 Android、iOS、Web、Windows、Linux 和 macOS。此包是一種稱為外掛包（或外掛）的特殊 Dart 包，它包含特定於平臺的程式碼。

要使用此外掛

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

2. 開啟 pubspec.yaml 並新增 url_launcher 依賴

   yaml

   dependencies:
     flutter:
       sdk: flutter
     url_launcher: ^5.4.0
   

   content_copy

3. 在終端執行 flutter pub get，或在 VS Code 中點選 Get Packages。

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

   dart

   import 'package:flutter/material.dart';
   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});
   ​
     void launchURL() {
       launchUrl(Uri.parse('https://flutter.club.tw'));
     }
   ​
     @override
     Widget build(BuildContext context) {
       return Scaffold(
         body: Center(
           child: ElevatedButton(
             onPressed: launchURL,
             child: const Text('Show Flutter homepage'),
           ),
         ),
       );
     }
   }
   

   content_copy

5. 執行應用（如果新增外掛前已在執行，則需停止並重啟）。點選 Show Flutter homepage。你應該會看到裝置上的預設瀏覽器開啟並顯示 flutter.dev 的主頁。