加入資源和圖片

Flutter 應用程式可以包含程式碼和資源(有時稱為資源)。資源是與應用程式一起打包和部署的檔案,可以在執行階段存取。常見的資源類型包括靜態資料(例如 JSON 檔案)、設定檔、圖示和圖片(JPEG、WebP、GIF、動畫 WebP/GIF、PNG、BMP 和 WBMP)。

指定資源

Flutter 使用位於專案根目錄的 pubspec.yaml 檔案來識別應用程式所需的資源。

以下是範例

flutter:
  assets:
    - assets/my_icon.png
    - assets/background.png

若要包含目錄下的所有資源,請在目錄名稱後面加上 / 字元

flutter:
  assets:
    - directory/
    - directory/subdirectory/

資源打包

flutter 區段的 assets 子區段指定應與應用程式一起包含的檔案。每個資源都由明確路徑(相對於 pubspec.yaml 檔案)來識別,其中放置了資源檔案。宣告資源的順序並不重要。實際使用的目錄名稱(第一個範例中的 assets 或上述範例中的 directory)並不重要。

在建置過程中,Flutter 會將資源放入稱為資源套件的特殊封存檔中,應用程式會在執行階段從中讀取。

載入資源

您的應用程式可透過 AssetBundle 物件存取其資產。

資產組合中的兩個主要方法可讓您載入字串/文字資產 (loadString()) 或影像/二進位資產 (load()),並給予一個邏輯金鑰。邏輯金鑰會對應到在建置時間於 pubspec.yaml 檔案中指定的資產路徑。

載入文字資產

每個 Flutter 應用程式都有 rootBundle 物件,可輕鬆存取主要資產組合。可以使用 package:flutter/services.dart 中的 rootBundle 全域靜態值直接載入資產。

不過,建議使用 DefaultAssetBundle 取得目前 BuildContextAssetBundle,而不是與應用程式一起建置的預設資產組合;此方法讓父小工具可以在執行階段替換不同的 AssetBundle,這對於在地化或測試場景很有用。

通常,您會使用 DefaultAssetBundle.of() 間接從應用程式的執行階段 rootBundle 載入資產,例如 JSON 檔案。

Widget 語境之外,或當無法使用 AssetBundle 處理時,您可以使用 rootBundle 直接載入此類資產。例如

import 'package:flutter/services.dart' show rootBundle;

Future<String> loadAsset() async {
  return await rootBundle.loadString('assets/config.json');
}

載入圖片

若要載入圖片,請在小工具的 build() 方法中使用 AssetImage 類別。

例如,您的應用程式可以從前一個範例的資產宣告中載入背景圖片

return const Image(image: AssetImage('assets/background.png'));

解析度感知的圖片資產

Flutter 可以為目前的 裝置像素比 載入解析度適當的圖片。

AssetImage 會將邏輯請求的資產對應到最符合目前的 裝置像素比 的資產。

為了讓此對應運作,資產應根據特定目錄結構排列

.../image.png
.../Mx/image.png
.../Nx/image.png
...etc.

其中 MN 是數值識別碼,對應於其中所含圖片的名義解析度。換句話說,它們指定圖片的預定裝置像素比。

在此範例中,image.png 被視為 主要資產,而 Mx/image.pngNx/image.png 則被視為 變體

主要資產假設對應於 1.0 的解析度。例如,考慮以下名為 my_icon.png 的圖片的資產配置

.../my_icon.png       (mdpi baseline)
.../1.5x/my_icon.png  (hdpi)
.../2.0x/my_icon.png  (xhdpi)
.../3.0x/my_icon.png  (xxhdpi)
.../4.0x/my_icon.png  (xxxhdpi)

在裝置像素比例為 1.8 的裝置上,會選取資源 .../2.0x/my_icon.png。對於裝置像素比例為 2.7,會選取資源 .../3.0x/my_icon.png

如果未在 Image 小工具上指定已呈現影像的寬度和高度,則會使用名義解析度來縮放資源,使其佔用與主資源相同的螢幕空間,只是解析度較高。亦即,如果 .../my_icon.png 為 72px x 72px,則 .../3.0x/my_icon.png 應為 216px x 216px;但如果未指定寬度和高度,兩者都會呈現為 72px x 72px(以邏輯像素為單位)。

整合解析度感知影像資源

您只需在 pubspec.yamlassets 區段中指定主資源或其父目錄。Flutter 會為您整合變異。除了主資源項目外,每個項目都應對應到一個真實檔案。如果主資源項目未對應到一個真實檔案,則裝置像素比例低於該解析度的裝置會使用解析度最低的資源作為備用。不過,項目仍應包含在 pubspec.yaml 清單中。

使用預設資產套件載入圖片時,會繼承解析度感知功能。(如果您使用較低層級的類別,例如 ImageStreamImageCache,您也會注意到與縮放相關的參數。)

套件相依性中的資產圖片

要從 套件 相依性載入圖片,必須將 package 參數提供給 AssetImage

例如,假設您的應用程式相依於名為 my_icons 的套件,其目錄結構如下

.../pubspec.yaml
.../icons/heart.png
.../icons/1.5x/heart.png
.../icons/2.0x/heart.png
...etc.

要載入圖片,請使用

return const AssetImage('icons/heart.png', package: 'my_icons');

套件本身使用的資產也應使用上述 package 參數擷取。

套件資產的套件

如果在套件的 pubspec.yaml 檔案中指定所需的資產,則會自動與應用程式一起套件。特別是,套件本身使用的資產必須在其 pubspec.yaml 中指定。

套件也可以選擇在其 lib/ 資料夾中放置未在其 pubspec.yaml 檔案中指定的資產。在這種情況下,為了套件這些圖片,應用程式必須在其 pubspec.yaml 中指定要包含哪些圖片。例如,名為 fancy_backgrounds 的套件可以包含以下檔案

.../lib/backgrounds/background1.png
.../lib/backgrounds/background2.png
.../lib/backgrounds/background3.png

例如,要包含第一張圖片,應用程式的 pubspec.yaml 應在 assets 區段中指定

flutter:
  assets:
    - packages/fancy_backgrounds/backgrounds/background1.png

lib/ 是隱含的,因此不應包含在資產路徑中。

如果您正在開發套件,要載入套件中的資產,請在套件的 pubspec.yaml 中指定

flutter:
  assets:
    - assets/images/

若要載入套件中的影像,請使用

return const AssetImage('packages/fancy_backgrounds/backgrounds/background1.png');

與基礎平台共用資源

Flutter 資源可透過 Android 上的 AssetManager 和 iOS 上的 NSBundle,輕鬆提供給平台程式碼使用。

在 Android 中載入 Flutter 資源

在 Android 中,資源可透過 AssetManager API 取得。例如,在 openFd 中使用的查詢金鑰,可從 PluginRegistry.RegistrarFlutterView 上的 lookupKeyForAsset 取得。開發外掛時可使用 PluginRegistry.Registrar,而開發包含平台檢視的應用程式時,則可選擇 FlutterView

舉例來說,假設你在 pubspec.yaml 中指定下列內容

flutter:
  assets:
    - icons/heart.png

這反映了 Flutter 應用程式中的下列結構。

.../pubspec.yaml
.../icons/heart.png
...etc.

若要從 Java 外掛程式碼存取 icons/heart.png,請執行下列動作

AssetManager assetManager = registrar.context().getAssets();
String key = registrar.lookupKeyForAsset("icons/heart.png");
AssetFileDescriptor fd = assetManager.openFd(key);

在 iOS 中載入 Flutter 資源

在 iOS 中,資產可透過 mainBundle 取得。在 pathForResource:ofType: 等方法中使用的查詢金鑰,可從 FlutterPluginRegistrar 上的 lookupKeyForAssetlookupKeyForAsset:fromPackage: 取得,或從 FlutterViewController 上的 lookupKeyForAsset:lookupKeyForAsset:fromPackage: 取得。開發外掛時可以使用 FlutterPluginRegistrar,而開發包含平台檢視的應用程式時,則可以使用 FlutterViewController

例如,假設您有上述的 Flutter 設定。

若要從 Objective-C 外掛程式碼存取 icons/heart.png,請執行下列動作

NSString* key = [registrar lookupKeyForAsset:@"icons/heart.png"];
NSString* path = [[NSBundle mainBundle] pathForResource:key ofType:nil];

若要從 Swift 應用程式存取 icons/heart.png,請執行下列動作

let key = controller.lookupKey(forAsset: "icons/heart.png")
let mainBundle = Bundle.main
let path = mainBundle.path(forResource: key, ofType: nil)

如需更完整的範例,請參閱 pub.dev 上 Flutter video_player 外掛程式 的實作。

pub.dev 上的 ios_platform_images 外掛程式將此邏輯封裝在一個便利的類別中。您可以用下列方式擷取影像

Objective-C

[UIImage flutterImageWithName:@"icons/heart.png"];

Swift

UIImage.flutterImageNamed("icons/heart.png")

在 Flutter 中載入 iOS 影像

在透過 將 Flutter 加入現有的 iOS 應用程式 來實作 Flutter 時,您可能有一些託管在 iOS 中的圖片,而您想要在 Flutter 中使用它們。為達成此目的,請使用 pub.dev 上提供的 ios_platform_images 外掛程式。

平台資源

有其他場合需要直接在平台專案中使用資源。以下是兩個常見的案例,其中資源會在載入並執行 Flutter 架構之前使用。

更新應用程式圖示

更新 Flutter 應用程式的啟動圖示的方式與在原生 Android 或 iOS 應用程式中更新啟動圖示的方式相同。

Launch icon

Android

在您的 Flutter 專案的根目錄中,導覽至 .../android/app/src/main/res。各種位元圖資源資料夾,例如 mipmap-hdpi,已包含命名為 ic_launcher.png 的佔位符圖片。請將它們替換為您想要的資源,並依照 Android 開發人員指南 中所指示的每個螢幕密度的建議圖示大小。

Android icon location

iOS

在 Flutter 專案的根目錄中,導航至 .../ios/RunnerAssets.xcassets/AppIcon.appiconset 目錄已包含 placeholder 圖片。根據 Apple 人機介面指南 中的檔案名稱指示,以適當大小的圖片取代它們。保留原始檔名。

iOS icon location

更新啟動畫面

Launch screen

Flutter 也使用原生平台機制,在 Flutter 框架載入時,為您的 Flutter 應用程式繪製過渡性的啟動畫面。此啟動畫面會持續顯示,直到 Flutter 呈現應用程式的第一個畫面。

Android

若要為您的 Flutter 應用程式新增啟動畫面(也稱為「splash screen」),請導航至 .../android/app/src/main。在 res/drawable/launch_background.xml 中,使用此 圖層清單可繪製資源 XML 來自訂啟動畫面的外觀。現有的範本提供一個範例,說明如何在白色 splash 畫面中間新增圖片(以註解形式提供)。您可以取消註解,或使用其他 可繪製資源 來達成預期的效果。

如需更多詳細資訊,請參閱 為您的 Android 應用程式新增 splash 畫面

iOS

若要將圖片新增至「開機畫面」的中心,請前往 .../ios/Runner。在 Assets.xcassets/LaunchImage.imageset 中,拖放名為 LaunchImage.png[email protected][email protected] 的圖片。如果您使用不同的檔名,請更新同目錄中的 Contents.json 檔案。

您也可以透過開啟 .../ios/Runner.xcworkspace,在 Xcode 中完全自訂您的開機畫面分鏡。在專案瀏覽器中前往 Runner/Runner,並透過開啟 Assets.xcassets 拖放圖片,或使用 LaunchScreen.storyboard 中的介面設計器進行任何自訂。

Adding launch icons in Xcode

如需更多詳細資訊,請參閱 為您的 iOS 應用程式新增開機畫面