Thêm phần phụ thuộc của bản dựng

Hệ thống xây dựng Gradle trong Android Studio cho phép bạn đưa các tệp nhị phân bên ngoài hoặc các mô-đun thư viện khác vào bản dựng dưới dạng các phần phụ thuộc. Các phần phụ thuộc có thể nằm trên máy hoặc trong một kho lưu trữ từ xa, đồng thời các phần phụ thuộc bắc cầu mà các phần phụ thuộc đó khai báo cũng tự động được đưa vào. Trang này mô tả cách sử dụng các phần phụ thuộc với dự án Android, bao gồm thông tin chi tiết về các hành vi và cấu hình dành riêng cho trình bổ trợ Android cho Gradle (AGP). Để được hướng dẫn khái niệm chuyên sâu hơn về phần phụ thuộc Gradle, hãy xem Hướng dẫn quản lý phần phụ thuộc Gradle, nhưng hãy nhớ rằng dự án Android của bạn chỉ được sử dụng các cấu hình phần phụ thuộc được xác định trên trang này.

Thêm phần phụ thuộc thư viện hoặc trình bổ trợ

Cách tốt nhất để thêm và quản lý các phần phụ thuộc bản dựng là sử dụng danh mục phiên bản, phương thức mà các dự án mới sử dụng theo mặc định. Phần này trình bày các loại cấu hình phổ biến nhất được dùng cho các dự án Android; hãy tham khảo tài liệu về Gradle để biết thêm các tuỳ chọn. Để biết ví dụ về một ứng dụng sử dụng danh mục phiên bản, hãy xem Now in Android. Nếu bạn đã thiết lập các phần phụ thuộc bản dựng mà không có danh mục phiên bản và có một dự án nhiều mô-đun, bạn nên di chuyển.

Để biết hướng dẫn về cách thêm và quản lý các phần phụ thuộc gốc (không phổ biến), hãy xem phần Phần phụ thuộc gốc.

Trong ví dụ sau, chúng ta thêm phần phụ thuộc nhị phân từ xa (thư viện Macrobenchmark của Jetpack), phần phụ thuộc mô-đun thư viện cục bộ (myLibrary) và phần phụ thuộc trình bổ trợ (trình bổ trợ Android cho Gradle) vào dự án. Dưới đây là các bước chung để thêm các phần phụ thuộc này vào dự án:

1. Thêm bí danh cho phiên bản phần phụ thuộc mà bạn muốn trong phần [versions] của tệp danh mục phiên bản, có tên là libs.versions.toml (trong thư mục gradle trong chế độ xem Dự án hoặc Tập lệnh Gradle trong chế độ xem Android):

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

   Bí danh có thể chứa dấu gạch ngang hoặc dấu gạch dưới. Các bí danh này tạo ra các giá trị lồng nhau mà bạn có thể tham chiếu trong tập lệnh bản dựng. Các tệp tham chiếu bắt đầu bằng tên của danh mục, phần libs của libs.versions.toml. Khi sử dụng một danh mục phiên bản, bạn nên giữ nguyên giá trị mặc định là "libs".

2. Thêm bí danh cho phần phụ thuộc trong phần [libraries] (đối với các tệp nhị phân từ xa hoặc mô-đun thư viện cục bộ) hoặc [plugins] (đối với trình bổ trợ) của tệp 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" }
   

   Một số thư viện có trong Bảng kê khai thành phần (BOM) đã xuất bản, trong đó nhóm các gia đình thư viện và phiên bản của các thư viện đó. Bạn có thể đưa Bảng kê khai thành phần vào danh mục phiên bản và tệp bản dựng, đồng thời để bảng kê khai này quản lý các phiên bản đó cho bạn. Hãy xem phần Sử dụng Bảng kê khai thành phần để biết thông tin chi tiết.

3. Thêm tệp tham chiếu đến bí danh phần phụ thuộc vào tập lệnh bản dựng của(các) mô-đun yêu cầu phần phụ thuộc đó. Chuyển đổi dấu gạch dưới và dấu gạch ngang của bí danh thành dấu chấm khi bạn tham chiếu bí danh đó từ tập lệnh bản dựng. Tập lệnh bản dựng cấp mô-đun của chúng ta sẽ có dạng như sau:

   Kotlin

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

   Groovy

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

   Tham chiếu trình bổ trợ bao gồm plugins sau tên danh mục và tham chiếu phiên bản bao gồm versions sau tên danh mục (tham chiếu phiên bản không phổ biến; hãy xem Phần phụ thuộc có cùng số phiên bản để biết ví dụ về tham chiếu phiên bản.) Tham chiếu thư viện không bao gồm bộ hạn định libraries, vì vậy, bạn không thể sử dụng versions hoặc plugins ở đầu bí danh thư viện.

Định cấu hình phần phụ thuộc

Bên trong khối dependencies, bạn có thể khai báo phần phụ thuộc thư viện bằng cách sử dụng một trong nhiều cấu hình phần phụ thuộc (chẳng hạn như implementation hiển thị ở trên). Mỗi cấu hình phần phụ thuộc cung cấp cho Gradle các hướng dẫn khác nhau về cách sử dụng phần phụ thuộc. Bảng sau đây mô tả từng cấu hình phần phụ thuộc có thể sử dụng trong dự án 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')
}

Định cấu hình phần phụ thuộc cho một biến thể bản dựng cụ thể

Tất cả các cấu hình trước đó đều áp dụng các phần phụ thuộc cho tất cả biến thể bản dựng. Thay vào đó, nếu bạn chỉ muốn khai báo một phần phụ thuộc dành riêng cho một nhóm tài nguyên biến thể bản dựng cụ thể hoặc dành cho một nhóm tài nguyên kiểm thử, bạn phải viết hoa tên cấu hình và thêm tiền tố là tên của biến thể bản dựng hoặc tên của nhóm tài nguyên kiểm thử.

Ví dụ: để chỉ thêm một phần phụ thuộc nhị phân từ xa vào phiên bản sản phẩm "miễn phí" của bạn bằng cách sử dụng cấu hình implementation, hãy sử dụng đoạn mã sau:

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

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

Tuy nhiên, nếu muốn thêm phần phụ thuộc cho một biến thể kết hợp một phiên bản sản phẩm và một kiểu bản dựng, bạn phải khởi tạo tên cấu hình:

// 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")
}

Để thêm các phần phụ thuộc implementation cho quy trình kiểm thử cục bộ và quy trình kiểm thử đo lường, bạn có thể xem đoạn mã sau:

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'
}

Tuy nhiên, một số cấu hình nhất định không có ý nghĩa trong trường hợp này. Chẳng hạn, vì các mô-đun khác không thể phụ thuộc vào androidTest, nên bạn sẽ nhận được cảnh báo sau nếu sử dụng cấu hình androidTestApi:

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

Thứ tự phần phụ thuộc

Thứ tự liệt kê các phần phụ thuộc của bạn phản ánh rõ mức độ ưu tiên: thư viện đầu tiên có mức độ ưu tiên cao hơn thư viện thứ hai, thư viện thứ hai có mức độ ưu tiên cao hơn thư viện thứ ba, v.v. Thứ tự này rất quan trọng trong trường hợp tài nguyên được hợp nhất hoặc các phần tử tệp kê khai được hợp nhất vào trong ứng dụng từ thư viện.

Ví dụ: nếu dự án của bạn khai báo như sau:

• Phần phụ thuộc trên LIB_A và LIB_B (theo thứ tự đó)
• Và LIB_A phụ thuộc vào LIB_C và LIB_D (theo thứ tự đó)
• Và LIB_B cũng phụ thuộc vào LIB_C

Khi đó, thứ tự phần phụ thuộc cố định sẽ như sau:

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

Điều này đảm bảo rằng cả LIB_A và LIB_B đều có thể ghi đè LIB_C; và LIB_D vẫn sẽ có mức độ ưu tiên cao hơn LIB_B vì LIB_A (phụ thuộc vào LIB_D) có mức độ ưu tiên cao hơn LIB_B.

Để biết thêm thông tin về cách hợp nhất các tệp kê khai từ nhiều nguồn/phần phụ thuộc của các dự án khác nhau, hãy xem Hợp nhất nhiều tệp kê khai.

Thông tin phần phụ thuộc dành cho Play Console

Khi xây dựng ứng dụng, AGP sẽ bao gồm siêu dữ liệu mô tả các phần phụ thuộc thư viện được biên dịch thành ứng dụng. Khi bạn tải ứng dụng lên, Play Console sẽ kiểm tra siêu dữ liệu này để đưa ra cảnh báo về các vấn đề đã biết liên quan đến SDK và các phần phụ thuộc mà ứng dụng của bạn sử dụng. Trong một số trường hợp, Play Console sẽ đưa ra ý kiến phản hồi hữu ích để giải quyết các vấn đề đó.

Dữ liệu được một khoá ký Google Play nén, mã hoá và lưu trữ trong khối ký của ứng dụng phát hành. Bạn nên lưu giữ tệp phần phụ thuộc này để mang đến trải nghiệm an toàn và tích cực cho người dùng. Bạn có thể chọn không thực hiện bằng cách thêm khối dependenciesInfo sau đây vào tệp build.gradle.kts của mô-đun.

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

Để biết thêm thông tin về các chính sách cũng như vấn đề tiềm ẩn về phần phụ thuộc, hãy xem trang hỗ trợ của chúng tôi về Sử dụng SDK của bên thứ ba trong ứng dụng của bạn.

Thông tin chi tiết về SDK

Android Studio hiển thị các cảnh báo lỗi mã nguồn (lint) trong tệp danh mục phiên bản và Hộp thoại cấu trúc dự án cho các SDK công khai trong Chỉ mục SDK của Google Play khi các vấn đề sau đây xảy ra:

• Các SDK này được tác giả đánh dấu là đã lỗi thời.
• SDK vi phạm chính sách của Play.

Cảnh báo là tín hiệu cho biết bạn nên cập nhật các phần phụ thuộc đó, vì nếu dùng phiên bản lỗi thời thì sau này, bạn sẽ không thể phát hành ứng dụng lên Google Play Console.

Thêm phần phụ thuộc của bản dựng mà không cần danh mục phiên bản

Bạn nên sử dụng danh mục phiên bản để thêm và quản lý các phần phụ thuộc, nhưng các dự án đơn giản có thể không cần đến các danh mục này. Dưới đây là ví dụ về tệp bản dựng không sử dụng danh mục phiên bản:

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')
}

Tệp bản dựng này khai báo một phần phụ thuộc trên phiên bản 12.3 của thư viện "app-magic", trong nhóm không gian tên "com.example.android". Nội dung khai báo phần phụ thuộc nhị phân từ xa là viết tắt của nội dung sau:

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

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

Tệp bản dựng cũng khai báo phần phụ thuộc trên một mô-đun thư viện Android có tên là "mylibrary"; tên này phải khớp với tên thư viện được khai báo bằng include: trong tệp settings.gradle.kts. Khi bạn tạo ứng dụng, hệ thống xây dựng sẽ biên dịch mô-đun thư viện và đóng gói nội dung kết quả biên dịch trong ứng dụng.

Tệp bản dựng cũng khai báo phần phụ thuộc trên trình bổ trợ Android cho Gradle (com.application.android). Nếu có nhiều mô-đun sử dụng cùng một trình bổ trợ, bạn chỉ có thể có một phiên bản trình bổ trợ trên đường dẫn lớp bản dựng trên tất cả các mô-đun. Thay vì chỉ định phiên bản trong mỗi tập lệnh bản dựng mô-đun, bạn nên đưa phần phụ thuộc trình bổ trợ vào tập lệnh bản dựng gốc cùng với phiên bản và cho biết không áp dụng phần phụ thuộc đó. Việc thêm apply false sẽ yêu cầu Gradle ghi lại phiên bản của trình bổ trợ nhưng không sử dụng trình bổ trợ đó trong bản dựng gốc. Thông thường, tập lệnh bản dựng gốc sẽ trống ngoại trừ khối plugins này.

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

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

Nếu có một dự án mô-đun duy nhất, bạn có thể chỉ định phiên bản một cách rõ ràng trong tập lệnh bản dựng cấp mô-đun và để trống tập lệnh bản dựng cấp dự án:

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

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