Dart Defines trong Flutter và sức mạnh của nó

Chào mừng bạn đến với Fx Studio. Chúng ta đã cùng nhau phiêu lưu trong thế giới Flutter với Flavor. Tuy nhiên, bạn sẽ phải tốn kha khá các thao tác để đạt được mục đích.  Do đó, chủ đề bài viết này sẽ hướng dẫn cho các bạn 1 cách khác để config, nó sẽ giúp mình giảm được vô số bước. Đó là Dart Defines.

Tác giả bài viết là bạn Hồng Vân. Mọi người có thể theo dõi thêm các bài viết từ GitHub chính chủ của bạn nhóe!

Còn nếu mọi việc đã ổn rồi, thì …

Bắt đầu thôi!

Chuẩn bị

Về mặt kiến thức, bạn cần thông thạo Flutter cơ bản trước nhóe. Còn về mặt tools & versions, mình sẽ sử dụng các công cụ như sau:

• IDE:

  • Visual Studio Code version 1.67.0

  • Android Studio Chipmunk 2021.2.1

  • XCode version 13.3.1

• Flutter SDK version 2.10.5

Ngoài ra, đây cũng là phần tiếp theo của 3 bài viết liên quan tới Flavor trong Flutter. Nên nếu bạn chưa đọc qua nó, thì có thể tham khảo ở link sau:

• Guide to flavoring a Flutter app

• Guild to customize Run and Debug in flutter using VSCode

• Write code for specific platform by MethodChannel.

Dart Defines

Dart defines là các biến được tạo ra trong khoảng thời gian biên dịch chương trình (compile-time variables). Nếu bạn đang tìm kiếm những biến tương tự biến môi trường (environtment variables), thì Dart defines là những gì bạn cần! Và chúng được tạo ra bởi --dart-define.

Vậy --dart-define là gì?

Nó là một tham số để truyền vào (pass) vào câu lệnh flutter build hoặc flutter run. Nó sẽ giúp chúng ta chuyển tiếp các biến môi trường. Điều đó có nghĩa là bạn có thể custom code của mình với bất kỳ giá trị nào bạn truyền qua tham số này.

Quá là hay phải không nào? Điều này khiến mình ngay lập tức nghĩ đến việc define các biến khác nhau cho flavor thay vì config khùng điên như ở bài trước của mình.

Ahihi!

Cú pháp

Trước khi đi vào ứng dụng cho flavor, mình sẽ demo nhỏ nhỏ để các bạn nắm được cách làm việc với --dart-define nha!

• Bước 1: Chúng ta sẽ xây dựng 1 ứng dụng có UI đơn giản như sau:

• Bước 2: Các bạn define lớp EnvironmentConfig:

class EnvironmentConfig {
  static const APP_NAME =
      String.fromEnvironment('APP_NAME', defaultValue: 'awesomeApp');
  static const APP_SUFFIX = String.fromEnvironment('APP_SUFFIX');
}

Giải thích 1 chút:

• Chúng ta có thể truy cập các biến dart define thông qua hàm fromEnvirontment(name, defaultValue). name sẽ là tên biến được define sau câu lệnh --dart-define= , nếu như fromEnvirontment không thể tìm thấy biến nào như vậy thì nó sẽ trả về defaultValue.

• Bạn sẽ bắt buộc phải khai báo biến là const, bởi vì hàm fromEnvironment chỉ đảm bảo hoạt động khi các biến đó là hằng số.

Còn vì sao có thêm static phía trước? Bạn chỉ cần gõ const không thôi là hiểu rõ! Ahihi!

• Bước 3: Sử dụng lớp EnviromentConfig:

Tới đây, mình sẽ gán 2 biến APP_NAME và APP_SUFIX vào trên UI:

Text(
   'APP_NAME: ${EnvironmentConfig.APP_NAME}',
    style: Theme.of(context).textTheme.subtitle1,
),
Text(
   'APP_SUFFIX: ${EnvironmentConfig.APP_SUFFIX}',
    style: Theme.of(context).textTheme.subtitle1,
),

• Bước 4: Run và xem kết quả thôi nào!

Câu lệnh run như sau:

flutter run --dart-define=APP_NAME=demo --dart-define=APP_SUFFIX=.dev

(Kết quả thực thi nhóe!)

Ứng dụng vào Flutter Flavor

Nếu chưa biết Flutter Flavor là gì, bạn có thể tham khảo qua bài viết này của mình.

Còn đã biết rồi, thì bắt tay vào công việc thôi nào! Ý tưởng ở đây là mình sẽ config app có name và suffix khác nhau cho mỗi flavor nhé!

Cấu hình cho Android

• Bước 1: Định nghĩa và đọc các biến dart define:

Bạn vào file android/app/build.gradle và thêm đoạn code này vào:

// 1
def dartEnvironmentVariables = [
    APP_NAME: 'awesomeApp',
    APP_SUFFIX: null
];
// 2
if (project.hasProperty('dart-defines')) {
    // 3    
    dartEnvironmentVariables = dartEnvironmentVariables + project.property('dart-defines')
            .split(',')
            .collectEntries { entry ->
                // 4
                def pair = new String(entry.decodeBase64(), 'UTF-8').split('=')
                [(pair.first()): pair.last()]
            }
}

Giải thích code:

1. Chúng ta define các biến dart define theo dạng key-value. Key này sẽ giống nhau ở cả iOS, Android và Flutter. Còn value định nghĩa các giá trị default.

2. Flutter sẽ pass các biến dart define trong các thuộc tính của project với key là dart-defines

3. Chuyển đổi string từ dart-defines thành Map.

4. Flutter Tool sẽ pass tất cả các Dart Defines như 1 string với dấu phẩy, ví dụ:

   • Ở Flutter 1.17: APP_NAME=awesomeApp1,APP_SUFFIX=.dev

   • Ở Flutter 1.20: APP_NAME%3Dawesome1,APP_SUFFIX%3D.dev

   • Ở Flutter 2.2: REVGSU5FRVhBTVBMRV9BUFBfTkFNRT1hd2Vzb21lMg==,REVGSU5FRVhBTVBMRV9BUFBfU1VGRklYPS5kZXY=

   Ở mỗi version, có cách mã hoá khác nhau, ở đây vì mình sử dụng Flutter 2.16 mã hoá base64 như ở Flutter 2.2, nên mình sẽ phải giải mã base64 ngược lại.

• Bước 2: Thay đổi app name và application id suffix
  • Bạn tiếp tục vào file android/app/build.gradle và sửa ở phần defaultConfig như sau:

defaultConfig {
        // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html).
        applicationId "com.example.demo_dart_define"
        minSdkVersion flutter.minSdkVersion
        targetSdkVersion flutter.targetSdkVersion
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
        // NOTE: ADD THESE LINES
        applicationIdSuffix dartEnvironmentVariables.APP_SUFFIX
        resValue "string", "app_name", dartEnvironmentVariables.APP_NAME
}

• • Bạn vào android/app/src/main/AndroidManifest.xml để gán app_name vào application label

<application
        android:label="@string/app_name"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">

Bây giờ run và xem kết quả thôi. Câu lệnh như trên nhé!

flutter run --dart-define=APP_NAME=demo --dart-define=APP_SUFFIX=.dev

App name đã được thay đổi!

Cấu hình cho iOS

Bạn vẫn phải thực hiện trên XCode nha!

• Bước 1: Bạn tạo file Define-defaults.xcconfig để define các cặp key-value tương tự như ở bước 1 của Android.

  • Click chuột phải vào Runner/Flutter chọn New File, nhập “con“” vào ô filter chọn Next và đặt tên tương ứng.

• • Bạn định nghĩa vào đó như sau:

APP_NAME=awesomeApp
APP_SUFFIX=

• Bước 2: import file đó vào Debug.xcconfig và Release.xcconfig

#include "Generated.xcconfig"
#include "Define-defaults.xcconfig"
#include "Define.xcconfig"

Giải thích: Define-defaults.xcconfig là file bạn đã tạo ở bước 1 còn Define.xcconfig để ghi các biến dart define sẽ là file được tạo ra trong quá trình biên dịch.

• Bước 3: Thay đổi app name và app bundle identifier trong file Info.plist

• Bước 4: Chỉnh sửa scheme để đọc các biến dart define và ghi vào file Define.xcconfig
  • Click vào Scheme Runner -> Edit Scheme. Sau đó dưới tab Build chọn Pre-actions -> click dấu + chọn New Run Script Action

• • Tiếp theo, chúng ta sẽ viết đoạn code thực hiện việc đọc các biến dart define và ghi vào file Define.xcconfig. Đoạn code này sẽ được biên dịch trước khi XCode build app. Tương tự như Android là vẫn phải giải mã base64 nha:

function entry_decode() { echo "${*}" | base64 --decode; }

IFS=',' read -r -a define_items <<< "$DART_DEFINES"

for index in "${!define_items[@]}"
do
    define_items[$index]=$(entry_decode "${define_items[$index]}");
done

printf "%s\n" "${define_items[@]}"|grep '^APP_' > ${SRCROOT}/Flutter/Define.xcconfig

• • Nhớ chọn Provide build settings from là Runner nhoé! Nếu không thì các bạn sẽ gặp lỗi đấy.

flutter run --dart-define=APP_NAME=demo --dart-define=APP_SUFFIX=.dev

{
     "name": "dev",
     "request": "launch",
     "type": "dart",
     "args": ["--dart-define", "APP_NAME=[dev]demo", "--dart-define", "APP_SUFFIX=.dev"]
},
{
     "name": "staging",
     "request": "launch",
     "type": "dart",
     "args": ["--dart-define", "APP_NAME=[stg]demo", "--dart-define", "APP_SUFFIX=.stg"]
},
{
     "name": "prod",
     "request": "launch",
     "type": "dart",
     "args": ["--dart-define", "APP_NAME=demo"]
},

• Follow me more:

  • Facebook: https://www.facebook.com/van.may.750/
  • Email : lehongvan.develop@gmail.com
  • LinkedIn: https://www.linkedin.com/in/le-van-935231150/

Cảm ơn bạn đã đọc bài viết này!

Written by Hồng Vân Lê