Flutter Tutorial: ย้ายแอปไปใช้ V2 Android Embedding ล่าสุด

หากคุณกระโดดขึ้นรถ Flutter ในช่วงแรกๆ สביר להניחว่าคุณมีโปรเจกต์หนึ่งหรือสองที่สร้างก่อน version 1.12 ของ Flutter หากเป็นเช่นนั้น คุณอาจเคยเห็นข้อความนี้ทุกครั้งที่รัน Pub get ในโปรเจกต์ของคุณ:

This app is using a deprecated version of the Android embedding.
To avoid unexpected runtime failures, or future build failures, try to migrate this app to the V2 embedding.

Take a look at the docs for migrating an app: https://github.com/flutter/flutter/wiki/Upgrading-pre-1.12-Android-projects

ตอนนี้ เอกสารนั้นมีขั้นตอนที่คุณต้องทำตามเพื่อทำให้คำเตือนนี้หายไป แต่ไม่ได้ชี้แจงเสมอไปว่าต้องเปลี่ยนอะไรและที่ไหน

บทความนี้จะให้คำแนะนำทีละขั้นตอนในการย้ายแอปพลิเคชัน Flutter ไปยัง V2 Embedding เพื่อให้คุณทำให้คำเตือนนั้นหายไปอย่างถาวร

การย้ายอัตโนมัติ – ทางออกที่ง่าย

ต้องบอกก่อนว่าคุณสามารถข้ามกระบวนการย้ายนี้ได้ หากแอปพลิเคชันของคุณสามารถสร้างใหม่ได้ง่าย นั่นหมายความว่าอะไร?

หากโค้ดในแอปพลิเคชันของคุณไม่ซับซ้อน คุณสามารถแค่เซฟไฟล์ในโฟลเดอร์ lib และสร้างโปรเจกต์ใหม่โดยใช้ flutter create ด้วยวิธีนั้น คุณจะได้โปรเจกต์ที่ย้ายไป V2 Embedding แล้ว และแค่ต้อง copy paste โค้ดในโฟลเดอร์ lib

แต่ หากโปรเจกต์ของคุณซับซ้อนกว่านั้น – สมมติว่าเป็น package ที่มี platform-specific code – คุณน่าจะดีกว่าที่ย้ายด้วยมือ

การย้ายด้วยมือ – ปฏิบัติตามขั้นตอนเหล่านี้

1. เปิดไฟล์ MainActivity.kt (หรือ .java) ในแอปพลิเคชันของคุณ
2. คุณต้องลบเนื้อหาทั้งหมดในไฟล์นี้ออก และทิ้งแค่ class declaration (เว้นแต่คุณจะมี logic เฉพาะที่นั่น)
3. ลบ imports ทั้งหมด และตรวจสอบให้แน่ใจว่ามี import เพียงตัวนี้:

import io.flutter.embedding.android.FlutterActivity;

ผลลัพธ์สุดท้ายควรเป็นแบบนี้:

import io.flutter.embedding.android.FlutterActivity;
public class MainActivity extends FlutterActivity {
  // ไม่ควรมีอะไรอยู่ที่นี่
}

1. เปิดไฟล์ AndroidManifest.xml และเปลี่ยน attribute name ใต้ application tag เป็น ${applicationName} – ให้เป็นแบบนี้:

<application android:name="${applicationName}"> .... </application>

1. คุณต้องเพิ่ม meta data ต่อไปนี้ภายใน application tags:

<meta-data android:name="flutterEmbedding" android:value="2" />

1. หากคุณต้องการพฤติกรรม Splash screen เฉพาะ คุณจะต้องลบ meta tag ของ Splash screen:

<meta-data android:name="io.flutter.app.android.SplashScreenUntilFirstFrame" android:value="true" />

1. จากนั้นไปที่ไฟล์ styles.xml และกำหนดค่า LaunchTheme ที่นั่นด้วย drawable ที่คุณชอบ:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="LaunchTheme" parent="@android:style/Theme.Black.NoTitleBar">
    <item name="android:windowBackground">@drawable/launch_background </item>
  </style>
</resources>

AndroidManifest.xml ของคุณจะเป็นประมาณนี้หลังจากการเปลี่ยนแปลงทั้งหมดข้างต้น:

<manifest xmlns:android="https://schemas.android.com/apk/res/android" package="PACKAGE_NAME">
  <application android:name="${applicationName}" android:label="APPLICATION_LABEL" android:icon="@mipmap/ic_launcher">
    <activity android:name=".MainActivity" android:exported="true" android:launchMode="singleTop" android:theme="@style/LaunchTheme" android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode" android:hardwareAccelerated="true" android:windowSoftInputMode="adjustResize">
      <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.LAUNCHER"/>
      </intent-filter>
    </activity>
    <meta-data android:name="flutterEmbedding" android:value="2" />
  </application>
</manifest>

การรองรับ AndroidX

โปรเจกต์ของคุณอาจต้องย้ายไปใช้ AndroidX libraries แทน support libraries เก่า คุณจะได้รับแจ้งเตือนเมื่อ build และรันแอปพลิเคชัน:

Your app isn't using AndroidX. To avoid potential build failures, you can quickly migrate your app by following the steps on https://goo.gl/CP92wY.

การแก้ไขเรื่องนี้ค่อนข้างง่าย เพราะ Android Studio มีการรองรับ built-in สำหรับการย้ายไป AndroidX

เริ่มต้นด้วยการเปิดโฟลเดอร์ Android ของแอปพลิเคชัน Flutter เป็นโปรเจกต์อิสระ (standalone project)

คลิกที่ Refactor → Migrate to AndroidX:

เมนูแบบดรอปดาวน์สำหรับ Migrate to AndroidX

คุณจะได้รับ prompt ให้เซฟสำเนาโปรเจกต์ และหลังจากนั้น กระบวนการย้ายจะเกิดขึ้น

ข้อผิดพลาดที่คุณอาจเจอ

ระหว่างกระบวนการย้ายนี้ คุณอาจเจอข้อผิดพลาดหลายอย่างเมื่อ build แอปพลิเคชัน สิ่งที่โดดเด่นที่สุดคือ:

• Unable to get mutable Windows environment variable map
• cvc-complex-type.2.4.a: Invalid content was found starting with element 'base-extension'. One of '{layoutlib}' is expected
• Warning: This version only understands SDK XML versions up to 2 but an SDK XML file of version 3 was encountered. This can happen if you use versions of Android Studio and the command-line tools that were released at different times

ข้อผิดพลาดสองข้อแรกเกี่ยวข้องกัน และทั้งคู่มาจากสาเหตุรากเหมือนกัน มันเป็นเพราะโปรเจกต์ของคุณตั้งค่าด้วย GradLE version เก่า และจำเป็นต้องอัปเกรดมัน

เพื่อทำเช่นนั้น ปฏิบัติตามขั้นตอนเหล่านี้:

1. เปิดโฟลเดอร์ Android ในแอปพลิเคชัน Flutter เป็นโปรเจกต์อิสระ
2. คลิก File → Project Structure:

เมนูแบบดรอปดาวน์สำหรับเลือก Project Structure

1. เปลี่ยน Gradle version เป็นอะไรที่ใหม่กว่าและตรงกับ Android Studio version ปัจจุบันที่คุณใช้

หน้าจอตั้งค่า AGP และ Gradle

คุณสามารถใช้ AGP Upgrade Assistant ได้ด้วย โดยไปที่ Tools → AGP Upgrade Assistant:

เมนูแบบดรอปดาวน์สำหรับอัปเกรด AGP ด้วย AGP Upgrade Assistant

ปัญหาที่สาม ซึ่งเป็น warning อาจเกิดจากการมี Android SDK Tools version เก่า เพื่อเรียนรู้วิธีทำ คุณสามารถไปที่นี่

โปรเจกต์ของคุณควรย้ายเสร็จสิ้น คอมไพล์และรันได้อย่างราบรื่นแล้ว

หากคุณอยากอ่านบทความอื่นๆ ที่ผมเขียน สามารถดูได้ที่นี่:

เรียนรู้การเขียนโค้ดฟรี หลักสูตรโอเพนซอร์สของ freeCodeCamp ช่วยให้ผู้คนมากกว่า 40,000 คนได้งานเป็นนักพัฒนา เริ่มต้นเลยวันนี้