เพิ่มการพึ่งพิงบิวด์

ระบบบิลด์ Gradle ใน Android Studio ช่วยให้คุณรวมไบนารีภายนอกหรือโมดูลไลบรารีอื่นๆ ไว้ในบิลด์เป็นทรัพยากร Dependency ได้ ทรัพยากร Dependency อาจอยู่ในเครื่องหรือในที่เก็บระยะไกล และทรัพยากร Dependency แบบทรานซิทีฟที่ประกาศไว้จะรวมอยู่ด้วยโดยอัตโนมัติ หน้านี้อธิบายวิธีใช้ทรัพยากร Dependency กับโปรเจ็กต์ Android รวมถึงรายละเอียดเกี่ยวกับลักษณะการทำงานและการกำหนดค่าที่เฉพาะเจาะจงสำหรับปลั๊กอิน Android Gradle (AGP) ดูคำแนะนำเชิงแนวคิดที่ละเอียดยิ่งขึ้นเกี่ยวกับทรัพยากร Dependency ของ Gradle ได้ที่คู่มือ Gradle สำหรับการจัดการทรัพยากร Dependency แต่อย่าลืมว่าโปรเจ็กต์ Android ต้องใช้เฉพาะการกำหนดค่าทรัพยากร Dependency ที่กำหนดไว้ในหน้านี้เท่านั้น

เพิ่มทรัพยากร Dependency ของไลบรารีหรือปลั๊กอิน

วิธีที่ดีที่สุดในการเพิ่มและจัดการทรัพยากร Dependency ของบิลด์คือการใช้แคตตาล็อกเวอร์ชัน ซึ่งเป็นวิธีที่โปรเจ็กต์ใหม่ใช้โดยค่าเริ่มต้น ส่วนนี้จะครอบคลุมประเภทการกำหนดค่าที่ใช้บ่อยที่สุดสำหรับโปรเจ็กต์ Android โปรดดูตัวเลือกเพิ่มเติมในเอกสารประกอบของ Gradle ดูตัวอย่างแอปที่ใช้แคตตาล็อกเวอร์ชันได้ที่ Now in Android หากคุณตั้งค่าทรัพยากร Dependency ของบิลด์ไว้แล้วโดยไม่มีแคตตาล็อกเวอร์ชันและมีโปรเจ็กต์แบบหลายโมดูล เราขอแนะนำให้ย้ายข้อมูล

ดูคำแนะนำเกี่ยวกับการเพิ่มและจัดการทรัพยากร Dependency แบบเนทีฟ (ไม่พบบ่อย) ได้ที่ทรัพยากร Dependency แบบเนทีฟ

ในตัวอย่างต่อไปนี้ มีการเพิ่มทรัพยากร Dependency แบบไบนารีระยะไกล (ไลบรารี Jetpack Macrobenchmark), ทรัพยากร Dependency ของโมดูลไลบรารีในเครื่อง (myLibrary) และทรัพยากร Dependency ของปลั๊กอิน (ปลั๊กอิน Android Gradle) ลงในโปรเจ็กต์ ขั้นตอนทั่วไปในการเพิ่มทรัพยากร Dependency เหล่านี้ลงในโปรเจ็กต์มีดังนี้

1. เพิ่มชื่อแทนสำหรับเวอร์ชันของทรัพยากร Dependency ที่ต้องการในส่วน [versions] ของไฟล์แคตตาล็อกเวอร์ชันที่ชื่อ libs.versions.toml (ในไดเรกทอรี gradle ในมุมมองโปรเจ็กต์หรือสคริปต์ Gradle ในมุมมอง Android) ดังนี้

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   ชื่อแทนอาจมีขีดกลางหรือขีดล่างได้ ชื่อแทนเหล่านี้จะสร้างค่าที่ซ้อนกันซึ่งคุณสามารถอ้างอิงได้ในสคริปต์บิลด์ การอ้างอิงจะขึ้นต้นด้วยชื่อแคตตาล็อก ซึ่งก็คือส่วน libs ของ libs.versions.toml เมื่อใช้แคตตาล็อกเวอร์ชันเดียว เราขอแนะนำให้คงค่าเริ่มต้นของ "libs" ไว้

2. เพิ่มชื่อแทนสำหรับทรัพยากร Dependency ในส่วน [libraries] (สำหรับไบนารีระยะไกลหรือโมดูลไลบรารีในเครื่อง) หรือ [plugins] (สำหรับปลั๊กอิน) ของไฟล์ libs.versions.toml

   [versions]
   ...
   
   [libraries]
   androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
   my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }
   
   [plugins]
   androidApplication = { id = "com.android.application", version.ref = "agp" }
   

   ไลบรารีบางรายการมีอยู่ใน Bill of Materials (BOM) ที่เผยแพร่ซึ่งจัดกลุ่มตระกูลไลบรารีและเวอร์ชันของไลบรารี คุณสามารถรวม BOM ไว้ในแคตตาล็อกเวอร์ชันและไฟล์บิลด์ แล้วให้ BOM จัดการเวอร์ชันเหล่านั้นให้คุณ ดูรายละเอียดได้ที่การใช้ Bill of Materials

3. เพิ่มการอ้างอิงชื่อแทนของทรัพยากร Dependency ลงในสคริปต์บิลด์ของโมดูลที่ต้องใช้ทรัพยากร Dependency แปลงขีดล่างและขีดกลางของชื่อแทนเป็นจุดเมื่ออ้างอิงจากสคริปต์บิลด์ สคริปต์บิลด์ระดับโมดูลจะมีลักษณะดังนี้

   Kotlin

   plugins {
     alias(libs.plugins.androidApplication)
   }
   
   dependencies {
     implementation(libs.androidx.benchmark.macro)
     implementation(libs.my.library)
   }

   ดึงดูด

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }

   การอ้างอิงปลั๊กอินจะมี plugins ต่อท้ายชื่อแคตตาล็อก และการอ้างอิงเวอร์ชันจะมี versions ต่อท้ายชื่อแคตตาล็อก (การอ้างอิงเวอร์ชันไม่ค่อยพบได้บ่อยนัก โปรดดูตัวอย่างการอ้างอิงเวอร์ชันที่หัวข้อทรัพยากร Dependency ที่มีหมายเลขเวอร์ชันเดียวกัน) ข้อมูลอ้างอิงของคลังไม่มีตัวระบุ libraries ดังนั้นคุณจึงใช้ versions หรือ plugins ที่จุดเริ่มต้นของชื่อแทนของคลังไม่ได้

กำหนดค่าทรัพยากร Dependency

ภายในบล็อก dependencies คุณสามารถประกาศทรัพยากร Dependency ของไลบรารีโดยใช้การกำหนดค่าทรัพยากร Dependency อย่างใดอย่างหนึ่ง (เช่น implementation ที่แสดงไว้ก่อนหน้านี้) การกำหนดค่าทรัพยากร Dependency แต่ละรายการจะให้วิธีการที่แตกต่างกันแก่ Gradle เกี่ยวกับวิธีใช้ทรัพยากร Dependency ตารางต่อไปนี้อธิบายการกำหนดค่าแต่ละรายการที่คุณใช้สำหรับการขึ้นต่อกันในโปรเจ็กต์ Android ได้

dependencies {
  // Executes lint checks from the ":checks" project at build time.
  lintChecks(project(":checks"))
  // Compiles lint checks from the ":checks-to-publish" into a
  // lint.jar file and publishes it to your Android library.
  lintPublish(project(":checks-to-publish"))
}

dependencies {
  // Executes lint checks from the ':checks' project at build time.
  lintChecks project(':checks')
  // Compiles lint checks from the ':checks-to-publish' into a
  // lint.jar file and publishes it to your Android library.
  lintPublish project(':checks-to-publish')
}

กำหนดค่าทรัพยากร Dependency สำหรับตัวแปรบิลด์ที่เฉพาะเจาะจง

การกำหนดค่าก่อนหน้าทั้งหมดจะใช้ทรัพยากร Dependency กับตัวแปรบิลด์ทั้งหมด หากต้องการประกาศทรัพยากร Dependency สำหรับชุดซอร์สตัวแปรบิลด์ที่เฉพาะเจาะจงหรือสำหรับชุดซอร์สการทดสอบแทน คุณต้องใช้อักษรตัวพิมพ์ใหญ่สำหรับชื่อการกำหนดค่าและขึ้นต้นด้วยชื่อตัวแปรบิลด์หรือชุดซอร์สการทดสอบ

เช่น หากต้องการเพิ่มการขึ้นต่อกันของไบนารีระยะไกลลงในเวอร์ชันผลิตภัณฑ์ "ฟรี" เท่านั้นโดยใช้การกำหนดค่า implementation ให้ใช้โค้ดต่อไปนี้

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

อย่างไรก็ตาม หากต้องการเพิ่มทรัพยากร Dependency สำหรับตัวแปรที่รวมเวอร์ชันผลิตภัณฑ์และประเภทบิลด์ คุณต้องเริ่มต้นชื่อการกำหนดค่าดังนี้

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

หากต้องการเพิ่มทรัพยากร Dependency implementation สำหรับการทดสอบในเครื่องและการทดสอบการวัดคุม จะมีลักษณะดังนี้

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
}

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
}

อย่างไรก็ตาม การกำหนดค่าบางอย่างไม่สมเหตุสมผลในสถานการณ์นี้ ตัวอย่างเช่น เนื่องจากโมดูลอื่นๆ ไม่สามารถขึ้นอยู่กับ androidTest คุณจะได้รับคำเตือนต่อไปนี้หากใช้การกำหนดค่า androidTestApi

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

ลำดับการขึ้นต่อกัน

ลำดับที่คุณแสดงรายการทรัพยากร Dependency จะระบุลำดับความสำคัญของแต่ละรายการ เช่น คลังแรกมีลำดับความสำคัญสูงกว่าคลังที่ 2 และคลังที่ 2 มีลำดับความสำคัญสูงกว่าคลังที่ 3 ลำดับนี้มีความสำคัญในกรณีที่มีการผสานทรัพยากรหรือมีการผสานองค์ประกอบไฟล์ Manifest เข้ากับแอปของคุณจากไลบรารี

เช่น หากโปรเจ็กต์ประกาศสิ่งต่อไปนี้

• ขึ้นอยู่กับ LIB_A และ LIB_B (ตามลำดับ)
• และ LIB_A ขึ้นอยู่กับ LIB_C และ LIB_D (ตามลำดับ)
• และ LIB_B ยังจำเป็นต้องใช้ LIB_C ด้วย

จากนั้น ลำดับการขึ้นต่อกันแบบคงที่จะเป็นดังนี้

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

ซึ่งจะช่วยให้ทั้ง LIB_A และ LIB_B ลบล้าง LIB_C ได้ และ LIB_D ยังคงมีลำดับความสำคัญสูงกว่า LIB_B เนื่องจาก LIB_A (ซึ่งขึ้นอยู่กับ ) มีลำดับความสำคัญสูงกว่า LIB_B

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีผสานไฟล์ Manifest จากแหล่งที่มาหรือทรัพยากร Dependency ของโปรเจ็กต์ต่างๆ ได้ที่ผสานไฟล์ Manifest หลายไฟล์

ข้อมูลทรัพยากร Dependency สำหรับ Play Console

เมื่อสร้างแอป AGP จะรวมข้อมูลเมตาที่อธิบายทรัพยากร Dependency ของไลบรารีที่คอมไพล์ลงในแอปของคุณ เมื่ออัปโหลดแอป Play Console จะตรวจสอบข้อมูลเมตานี้เพื่อแจ้งเตือนปัญหาที่ทราบเกี่ยวกับ SDK และทรัพยากร Dependency ที่แอปของคุณใช้ และในบางกรณีจะให้ความคิดเห็นที่นำไปใช้ได้จริงเพื่อแก้ไขปัญหาเหล่านั้น

ข้อมูลจะได้รับการบีบอัด เข้ารหัสโดยคีย์ Signing ของ Google Play และจัดเก็บไว้ในบล็อกการรับรองของแอปรุ่นที่เผยแพร่ เราขอแนะนำให้เก็บไฟล์ทรัพยากร Dependency นี้ไว้เพื่อประสบการณ์ของผู้ใช้ที่ดีและปลอดภัย คุณเลือกไม่ใช้ได้โดยใส่บล็อก dependenciesInfo ต่อไปนี้ในไฟล์ build.gradle.kts ของโมดูล

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

ดูข้อมูลเพิ่มเติมเกี่ยวกับนโยบายและปัญหาที่อาจเกิดขึ้นกับทรัพยากร Dependency ได้ที่หน้าการสนับสนุนเกี่ยวกับการใช้ SDK ของบุคคลที่สามในแอป

ข้อมูลเชิงลึกเกี่ยวกับ SDK

Android Studio จะแสดงคำเตือนของเครื่องมือวิเคราะห์ซอร์สโค้ดในไฟล์แคตตาล็อกเวอร์ชันและกล่องโต้ตอบโครงสร้างโปรเจ็กต์สำหรับ SDK สาธารณะในดัชนี SDK ของ Google Play เมื่อเกิดปัญหาต่อไปนี้

• ผู้เขียน SDK ได้ทำเครื่องหมาย SDK ว่าล้าสมัย
• SDK ละเมิดนโยบายของ Play
• SDK มีช่องโหว่ด้านความปลอดภัยที่ทราบ
• ผู้เขียนเลิกใช้งาน SDK แล้ว

คำเตือนเป็นสัญญาณว่าคุณควรอัปเดตทรัพยากร Dependency เหล่านั้น เนื่องจากการใช้เวอร์ชันที่ล้าสมัยอาจทำให้คุณเผยแพร่ไปยัง Google Play Console ในอนาคตไม่ได้

เพิ่มทรัพยากร Dependency ของบิลด์โดยไม่มีแคตตาล็อกเวอร์ชัน

เราขอแนะนำให้ใช้แคตตาล็อกเวอร์ชันเพื่อเพิ่มและจัดการทรัพยากร Dependency แต่โปรเจ็กต์ง่ายๆ อาจไม่จำเป็นต้องใช้ ต่อไปนี้คือตัวอย่างไฟล์บิลด์ที่ไม่ได้ใช้แคตตาล็อกเวอร์ชัน

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

ไฟล์บิลด์นี้ประกาศทรัพยากร Dependency ในไลบรารี "app-magic" เวอร์ชัน 12.3 ภายในกลุ่มเนมสเปซ "com.example.android" การประกาศการขึ้นต่อกันของไบนารีระยะไกลเป็นรูปแบบย่อของรายการต่อไปนี้

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

ไฟล์บิลด์ยังประกาศทรัพยากร Dependency ในโมดูลไลบรารี Android ชื่อ "mylibrary" ด้วย โดยชื่อนี้ต้องตรงกับชื่อไลบรารีที่กำหนดด้วย include: ในไฟล์ settings.gradle.kts เมื่อคุณสร้างแอป ระบบบิลด์จะคอมไพล์โมดูลไลบรารีและแพ็กเกจเนื้อหาที่คอมไพล์แล้วในแอป

ไฟล์บิลด์ยังประกาศทรัพยากร Dependency ในปลั๊กอิน Android Gradle (com.application.android) ด้วย หากคุณมีหลายโมดูลที่ใช้ปลั๊กอินเดียวกัน คุณจะมีปลั๊กอินได้เพียงเวอร์ชันเดียวใน classpath ของบิลด์ในทุกโมดูล แทนที่จะระบุเวอร์ชันในสคริปต์บิลด์ของแต่ละโมดูล คุณควรใส่ทรัพยากร Dependency ของปลั๊กอินในสคริปต์บิลด์รูทพร้อมกับเวอร์ชัน และระบุว่าไม่ต้องใช้ การเพิ่ม apply false จะบอกให้ Gradle จดบันทึกเวอร์ชันของปลั๊กอิน แต่ไม่ใช้ในบิลด์รูท โดยปกติแล้ว สคริปต์บิลด์ระดับรูทจะว่างเปล่ายกเว้นบล็อก plugins นี้

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

plugins {
    id 'com.android.application' version '8.3.0-rc02' apply false
}

หากมีโปรเจ็กต์โมดูลเดียว คุณสามารถระบุเวอร์ชันอย่างชัดเจนในสคริปต์บิลด์ระดับโมดูลและปล่อยสคริปต์บิลด์ระดับโปรเจ็กต์ว่างไว้ได้ ดังนี้

plugins {
    id("com.android.application") version "8.3.0"
}

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}