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 thành phần bên ngoài tệp nhị phân hoặc mô-đun thư viện khác vào bản dựng dưới dạng 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 trong dự án Android, bao gồm 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, bạn cũng nên 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 trình bổ trợ hoặc thư viện

Cách tốt nhất để thêm và quản lý các phần phụ thuộc của bản dựng là sử dụng danh mục phiên bản, mà các dự án mới sử dụng theo mặc định. Phần này đề cập đến các nguyên tắc phổ biến nhất các loại cấu hình dùng cho các dự án Android; tham chiếu đến Tài liệu về Gradle để có thêm lựa chọn. Để xem 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 phần phụ thuộc của bản dựng 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.

Để xem 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ụ thuộc gốc.

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

1. Thêm bí danh cho phiên bản của 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 Project (Dự án) hoặc Gradle Scripts (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ể bao gồm 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 khảo trong tập lệnh bản dựng. Các tham chiếu bắt đầu bằng tên của danh mục, phần libs của libs.versions.toml. Thời gian khi sử dụng một danh mục phiên bản duy nhất, bạn nên giữ nguyên giá trị mặc định của "libs".

2. Thêm bí danh cho phần phụ thuộc trong [libraries] (cho tệp nhị phân từ xa hoặc mô-đun thư viện cục bộ) hoặc [plugins] (dành cho 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) đã được xuất bản nhóm các họ thư viện và phiên bản của chúng. Bạn có thể thêm Bảng kê khai thành phần trong danh mục phiên bản và tệp bản dựng, đồng thời để Google quản lý các phiên bản đó cho bạn. Xem Sử dụng Bảng kê khai thành phần để biết chi tiết.

3. Thêm mục tham chiếu đến bí danh phần phụ thuộc vào tập lệnh bản dựng của mô-đun yêu cầu phần phụ thuộc. Chuyển đổi bí danh dấu gạch dưới và dấu gạch ngang vào dấu chấm khi bạn tham chiếu mã từ một tập lệnh bản dựng. Tập lệnh bản dựng cấp mô-đun 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
   }
   

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

Đị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 trong số nhiều cấu hình phần phụ thuộc (chẳng hạn như implementation được hiển thị) trước đó). 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ấu hình ở trên đều áp dụng các phần phụ thuộc cho tất cả biến thể bản dựng. Nếu thay vào đó, bạn muốn khai báo phần phụ thuộc chỉ cho một bản dựng cụ thể nhóm tài nguyên biến thể hoặc cho một nguồn thử nghiệm tập hợp, bạn phải viết hoa cấu hình và thêm tiền tố là tên của biến thể bản dựng hoặc nhóm tài nguyên kiểm thử.

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

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 bạn muốn thêm phần phụ thuộc cho một biến thể kết hợp một sản phẩm phiên bản và loại bản dựng, thì 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.5.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.5.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ẽ thêm siêu dữ liệu mô tả thư viện được biên dịch vào ứng dụng của bạn. Khi 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 và trong một số trường hợp, cung cấp thông tin phản hồi thiết thực để 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 giữ lại phần phụ thuộc này để cung cấp trải nghiệm người dùng an toàn và tích cực. Bạn có thể chọn không tham gia bằng cách thêm đang theo dõi dependenciesInfo trong 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 cho thấy các cảnh báo tìm lỗi mã nguồn trong tệp danh mục phiên bản và Project (Dự án) Hộp thoại cấu trúc dành cho các SDK công khai trong phần Chỉ mục SDK của Google Play khi các vấn đề sau xảy ra:

• Tác giả đánh dấu các SDK này là đã lỗi thời.
• Những SDK đó vi phạm các 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, bạn có thể không phát hành được lên Google Play Google Play Console trong tương lai.

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ách làm này đơn giản các dự án có thể không cần đến các mã này. Dưới đây là ví dụ về một 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 phần phụ thuộc trên phiên bản 12.3 của tệp "app-magic" thư viện, bên trong "com.example.android" nhóm không gian tên. Tệp nhị phân từ xa khai báo phần phụ thuộc là cách viết tắt của:

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ô-đun thư viện Android có tên "mylibrary"; tên này phải khớp với tên thư viện được xác định với include: trong tệp settings.gradle.kts. Khi bạn tạo ứng dụng, hệ thống xây dựng biên dịch mô-đun thư viện và đóng gói nội dung kết quả biên dịch trong .

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 bạn có nhiều mô-đun sử dụng cùng một mô-đun trình bổ trợ, bạn chỉ có thể có một phiên bản trình bổ trợ duy nhất 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 mô-đun tập lệnh bản dựng, 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 với phiên bản và chỉ ra rằng không áp dụng phiên bản đó. Việc thêm apply false cho biết Gradle cần lưu ý phiên bản trình bổ trợ nhưng không sử dụng trong bản dựng gốc. Thông thường, tập lệnh bản dựng gốc 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ó dự án một mô-đun, bạn có thể chỉ định rõ phiên bản 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'
}