Ghi chú phát hành trình bổ trợ Android cho Gradle 8.3

Android Studio là một hệ thống xây dựng dựa trên Gradle còn trình bổ trợ Android cho Gradle bổ sung một số tính năng dành riêng cho việc xây dựng ứng dụng Android. Mặc dù trình bổ trợ Android cho Gradle (AGP) thường được cập nhật ở dạng khoá trong Android Studio, nhưng trình bổ trợ này (và phần còn lại của hệ thống Gradle) có thể hoạt động độc lập với Android Studio và được cập nhật riêng.

Trang này giải thích cách cập nhật các công cụ Gradle cũng như nội dung các bản cập nhật gần đây. Để nắm được ghi chú phát hành cho các phiên bản trình bổ trợ Android cho Gradle trước đây, hãy xem ghi chú phát hành trước đây.

Để biết những vấn đề đã được khắc phục trong phiên bản này của trình bổ trợ Android cho Gradle, hãy xem các vấn đề đã xử lý.

Để đọc toàn bộ tóm tắt tổng quan về những thay đổi có thể gây lỗi sắp tới trong trình bổ trợ Android cho Gradle, vui lòng xem lộ trình phát triển trình bổ trợ Android cho Gradle.

Để biết thông tin chi tiết về cách định cấu hình bản dựng Android bằng Gradle, hãy xem các trang sau đây:

• Định cấu hình bản dựng
• Thông tin tham khảo về DSL của trình bổ trợ Android cho Gradle
• Thông tin tham khảo về DSL của Gradle
• Hướng dẫn sử dụng về hiệu suất của Gradle

Để biết thêm thông tin về hệ thống xây dựng Gradle, hãy xem Hướng dẫn sử dụng Gradle.

Cập nhật trình bổ trợ Android cho Gradle

Khi cập nhật Android Studio, bạn có thể nhận được lời nhắc tự động cập nhật trình bổ trợ Android cho Gradle lên phiên bản mới nhất. Bạn có thể chọn chấp nhận bản cập nhật hoặc chỉ định một phiên bản theo cách thủ công dựa trên yêu cầu bản dựng của dự án.

Bạn có thể chỉ định phiên bản trình bổ trợ trong trình đơn File (Tệp) >Project Structure (Cấu trúc dự án) >Project (Dự án) trong Android Studio hoặc tệp build.gradle.kts cấp cao nhất. Phiên bản trình bổ trợ này áp dụng cho mọi mô-đun được tạo trong dự án Android Studio đó. Trong ví dụ sau đây, trình bổ trợ được đặt thành phiên bản 8.3.0 trong tệp build.gradle.kts:

plugins {
    id("com.android.application") version "8.3.0" apply false
    id("com.android.library") version "8.3.0" apply false
    id("org.jetbrains.kotlin.android") version "1.9.23" apply false
}

plugins {
    id 'com.android.application' version '8.3.0' apply false
    id 'com.android.library' version '8.3.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.23' apply false
}

Thận trọng: Bạn không nên sử dụng các phần phụ thuộc động trong số phiên bản, chẳng hạn như 'com.android.tools.build:gradle:8.3.+'. Việc sử dụng tính năng này có thể dẫn đến tình trạng cập nhật phiên bản không mong muốn và khó giải quyết sự khác biệt giữa các phiên bản.

Nếu phiên bản trình bổ trợ đã chỉ định chưa được tải xuống, Gradle sẽ tải phiên bản này xuống vào lần tiếp theo bạn tạo dự án hoặc nhấp vào File (Tệp) >Sync Project with Gradle Files (Đồng bộ hoá dự án với tệp Gradle) qua thanh trình đơn trong Android Studio.

Cập nhật Gradle

Khi cập nhật Android Studio, bạn có thể nhận được lời nhắc cập nhật Gradle lên phiên bản mới nhất. Bạn có thể chọn chấp nhận bản cập nhật hoặc chỉ định một phiên bản theo cách thủ công dựa trên yêu cầu bản dựng của dự án.

Bảng sau đây liệt kê phiên bản Gradle cần thiết cho mỗi phiên bản của trình bổ trợ Android cho Gradle. Để đạt hiệu quả tối đa, bạn nên sử dụng phiên bản mới nhất có thể của cả Gradle và trình bổ trợ.

Bạn có thể chỉ định phiên bản Gradle trên trình đơn File (Tệp) > Project Structure (Cấu trúc dự án) > Project (Dự án) trong Android Studio hoặc bằng cách cập nhật phiên bản Gradle qua dòng lệnh. Bạn nên sử dụng công cụ dòng lệnh Trình bao bọc Gradle để cập nhật tập lệnh gradlew. Ví dụ sau đây sẽ thiết lập phiên bản Gradle thành 8.3 bằng Trình bao bọc Gradle. Lưu ý: Bạn cần chạy lệnh này 2 lần để nâng cấp cả Gradle và chính Trình bao bọc Gradle (để biết thêm thông tin, hãy xem phần Nâng cấp Trình bao bọc Gradle).

gradle wrapper --gradle-version 8.3

Tuy nhiên, có thể không thực hiện được việc này trong một số trường hợp, chẳng hạn như khi bạn vừa cập nhật AGP và AGP đó không còn tuân thủ phiên bản Gradle hiện tại nữa. Trong trường hợp này, bạn cần chỉnh sửa thông tin tham chiếu phân phối Gradle trong tệp gradle/wrapper/gradle-wrapper.properties. Ví dụ sau đây sẽ thiết lập phiên bản Gradle thành 8.3 trong tệp gradle-wrapper.properties.

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.3-bin.zip
...

Trình bổ trợ Android cho Gradle và khả năng tương thích với Android Studio

Android Studio là một hệ thống xây dựng dựa trên Gradle, còn trình bổ trợ Android cho Gradle (AGP) bổ sung một số tính năng dành riêng cho việc xây dựng ứng dụng Android. Bảng sau đây liệt kê yêu cầu về phiên bản AGP cho từng phiên bản Android Studio.

Để biết thông tin về các tính năng mới trong trình bổ trợ Gradle trên Android, hãy xem Ghi chú phát hành của trình bổ trợ Android cho Gradle.

Phiên bản tối thiểu của các công cụ dành cho cấp độ API trên Android

Có các phiên bản Android Studio và AGP tối thiểu hỗ trợ một cấp độ API cụ thể. Việc sử dụng các phiên bản Android Studio hoặc AGP thấp hơn so với yêu cầu của targetSdk hoặc compileSdk của dự án có thể dẫn đến các sự cố không mong muốn. Bạn nên sử dụng phiên bản xem trước mới nhất của Android Studio và AGP để thao tác trong các dự án nhắm đến phiên bản xem trước của hệ điều hành Android. Bạn có thể cài đặt các phiên bản xem trước của Android Studio cùng với một phiên bản ổn định.

Sau đây là các phiên bản Android Studio và AGP tối thiểu:

Thay đổi về phiên bản (tháng 11 năm 2020)

Chúng tôi đang cập nhật cách đánh số phiên bản cho trình bổ trợ Android cho Gradle (AGP) để phù hợp hơn với công cụ bản dựng Gradle cơ bản.

Sau đây là những thay đổi đáng chú ý:

• AGP sẽ sử dụng phiên bản ngữ nghĩa và các thay đổi có thể gây lỗi sẽ dành cho các bản phát hành chính.

• Sẽ có một phiên bản lớn của AGP được phát hành mỗi năm, phù hợp với bản phát hành chính của Gradle.

• Bản phát hành sau AGP 4.2 sẽ là phiên bản 7.0 và yêu cầu phải nâng cấp lên Gradle phiên bản 7.x. Mọi bản phát hành chính của AGP sẽ yêu cầu nâng cấp phiên bản lớn trong công cụ Gradle cơ bản.

• Các API không được sử dụng nữa trước khoảng một năm, đồng thời chức năng thay thế sẽ được ra mắt. API không dùng nữa sẽ bị xoá sau khoảng một năm trong lần cập nhật chính tiếp theo.

Khả năng tương thích

Cấp độ API tối đa mà trình bổ trợ Android cho Gradle 8.3 hỗ trợ là API cấp 34. Sau đây là thông tin khác về khả năng tương thích:

Sau đây là các tính năng mới trong trình bổ trợ Android cho Gradle 8.3.

Bản vá đã phát hành

Dưới đây là danh sách các bản phát hành của bản vá trong Android Studio Iguana và trình bổ trợ Android cho Gradle 8.3.

Android Studio Iguana | 2023.2.1 Bản vá 2 và AGP 8.3.2 (tháng 4 năm 2024)

Bản cập nhật nhỏ này sửa các lỗi này.

Android Studio Iguana | 2023.2.1 Bản vá 1 và AGP 8.3.1 (tháng 3 năm 2024)

Bản cập nhật nhỏ này sửa các lỗi này.

Hỗ trợ Danh mục phiên bản Gradle

Android Studio hỗ trợ Danh mục phiên bản Gradle dựa trên TOML, một tính năng cho phép bạn quản lý các phần phụ thuộc ở một vị trí trung tâm và chia sẻ các phần phụ thuộc trên các mô-đun hoặc dự án. Android Studio giờ đây giúp bạn dễ dàng định cấu hình danh mục phiên bản thông qua các đề xuất của trình chỉnh sửa và tính năng tích hợp với hộp thoại Cấu trúc dự án. Tìm hiểu cách thiết lập và định cấu hình Danh mục phiên bản Gradle hoặc cách di chuyển bản dựng sang danh mục phiên bản.

Hoàn tất và điều hướng mã

Android Studio cung cấp tính năng hoàn thành mã khi bạn đang chỉnh sửa danh mục phiên bản ở định dạng tệp TOML hoặc thêm phần phụ thuộc từ danh mục phiên bản vào tệp bản dựng. Để sử dụng tính năng hoàn thành mã, hãy nhấn tổ hợp phím Ctrl + Phím cách (Command + Phím cách đối với macOS). Ngoài ra, bạn có thể nhanh chóng di chuyển từ một tệp tham chiếu phần phụ thuộc trong tệp build.gradle của ứng dụng đến nơi tệp này được khai báo trong danh mục phiên bản bằng cách nhấn tổ hợp phím Ctrl+b (Command+b đối với macOS).

Tích hợp với hộp thoại Project Structure (Cấu trúc dự án)

Nếu dự án của bạn sử dụng danh mục phiên bản được xác định ở định dạng tệp TOML, thì bạn có thể chỉnh sửa các biến mà bạn đã xác định ở đó thông qua hộp thoại Project Structure (Cấu trúc dự án) chế độ xem Variables (Biến) (File > Project Structure > Variables (Tệp > Cấu trúc dự án > Biến) trong Android Studio). Đối với mỗi danh mục phiên bản, có một trình đơn thả xuống liệt kê các biến từ danh mục đó. Để chỉnh sửa một biến, hãy nhấp vào giá trị của biến đó rồi ghi đè lên giá trị đó. Khi bạn lưu những thay đổi này, tệp TOML sẽ được cập nhật tương ứng.

Bạn cũng có thể cập nhật các phần phụ thuộc trong hộp thoại Project Structure (Cấu trúc dự án) chế độ xem Dependencies (Phần phụ thuộc) (File > Project Structure > Dependencies (Tệp > Cấu trúc dự án > Phần phụ thuộc). Để cập nhật các phiên bản bằng cách sử dụng hộp thoại Project Structure (Cấu trúc dự án), hãy chuyển đến mô-đun và phần phụ thuộc mà bạn muốn chỉnh sửa, sau đó cập nhật trường Requested Version (Phiên bản được yêu cầu). Khi bạn lưu những thay đổi này, tệp TOML sẽ được cập nhật tương ứng. Xin lưu ý rằng nếu phiên bản phần phụ thuộc được xác định bằng một biến, thì việc cập nhật phiên bản trực tiếp theo cách này sẽ thay thế biến bằng một giá trị được cố định giá trị trong mã. Ngoài ra, hãy lưu ý rằng việc xoá phần phụ thuộc khỏi tệp bản dựng (cho dù bạn có sử dụng hộp thoại Project Structure) hay không, phần phụ thuộc đó sẽ không bị xoá khỏi danh mục phiên bản.

Các vấn đề và hạn chế đã biết

Sau đây là các vấn đề hoặc hạn chế đã biết với tính năng hỗ trợ Danh mục phiên bản Gradle trong Android Studio.

• Lỗi khi làm nổi bật các phần khai báo bí danh của trình bổ trợ trong tệp tập lệnh Kotlin: khi bạn thêm phần khai báo trình bổ trợ cho biểu mẫu alias(libs.plugins.example), trình chỉnh sửa sẽ thêm dấu gạch dưới màu đỏ trong phần libs. Đây là vấn đề đã biết trong Gradle phiên bản 8.0 trở xuống và sẽ được giải quyết trong bản phát hành Gradle sau này.

• Android Studio chỉ hỗ trợ danh mục phiên bản ở định dạng TOML: hiện tại, tính năng hoàn tất mã, điều hướng và hộp thoại Cấu trúc dự án trong Android Studio chỉ hoạt động cho danh mục phiên bản được xác định ở định dạng tệp TOML. Tuy nhiên, bạn vẫn có thể thêm danh mục phiên bản ngay trong tệp settings.gradle và sử dụng các phần phụ thuộc của phiên bản đó trong dự án.

• Tính năng điều hướng cho các tệp bản dựng KTS không được hỗ trợ: di chuyển đến một định nghĩa phần phụ thuộc trong danh mục phiên bản bằng cách sử dụng tổ hợp phím Control + nhấp (Command + nhấp trên macOS) chưa được hỗ trợ đối với các tệp bản dựng được viết bằng tập lệnh Kotlin.

• Trợ lý Firebase sẽ thêm các phần phụ thuộc trực tiếp vào tập lệnh bản dựng: Trợ lý Firebase sẽ thêm trực tiếp các phần phụ thuộc vào tập lệnh bản dựng thay vì thông qua danh mục phiên bản.

• Chức năng "Tìm cách sử dụng" không được hỗ trợ: tính năng tìm các trường hợp sử dụng biến danh mục phiên bản trong các tệp bản dựng khác chưa được hỗ trợ, cho dù tệp bản dựng đó nằm trong KTS hay Groovy. Tức là sử dụng tổ hợp phím Control + nhấp (Command + nhấp trên macOS) trên một định nghĩa biến trong danh mục phiên bản sẽ không dẫn đến các tệp bản dựng mà biến được sử dụng.

• Hộp thoại Cấu trúc dự án trong Android Studio cho thấy nhiều tệp danh mục nếu các tệp đó nằm trong thư mục gradle gốc, nhưng không hiển thị danh mục cho bản dựng tổng hợp. Ví dụ: nếu bạn có hai tệp danh mục – một cho ứng dụng và một cho bản dựng kết hợp – thì hộp thoại Cấu trúc dự án chỉ cho thấy tệp danh mục ứng dụng. Bạn có thể sử dụng bản dựng kết hợp nhưng phải chỉnh sửa trực tiếp tệp TOML của bản dựng đó.

Thông tin chi tiết bổ sung về SDK: các vấn đề về chính sách

Android Studio hiện các cảnh báo lỗi mã nguồn trong tệp build.gradle.kts và tệp build.gradle, cũng như trong Hộp thoại cấu trúc dự án cho các SDK công khai có lỗi vi phạm chính sách của Play trong Chỉ mục SDK của Google Play. Bạn nên cập nhật mọi phần phụ thuộc vi phạm chính sách của Play vì những lỗi vi phạm này có thể khiến sau này bạn không thể phát hành ứng dụng lên Google Play Console. Các cảnh báo về lỗi vi phạm chính sách bổ sung cho cảnh báo về phiên bản lỗi thời mà Android Studio hiển thị.

Hỗ trợ phiên bản compileSdk trong Android Studio

Android Studio sẽ hiển thị cảnh báo nếu dự án của bạn sử dụng một compileSdk không được phiên bản Android Studio hiện tại hỗ trợ. Nếu có, bạn cũng nên chuyển sang phiên bản Android Studio có hỗ trợ compileSdk mà dự án của bạn sử dụng. Xin lưu ý rằng việc nâng cấp Android Studio cũng có thể yêu cầu bạn nâng cấp AGP. AGP cũng sẽ hiển thị cảnh báo trong cửa sổ công cụ Build (Tạo) nếu compileSdk mà dự án của bạn sử dụng không được phiên bản AGP hiện tại hỗ trợ.

Thay đổi về hành vi của công cụ tìm lỗi mã nguồn

Kể từ trình bổ trợ Android cho Gradle 8.3.0-alpha02, khi chạy công cụ tìm lỗi mã nguồn trên một mô-đun, các tác vụ phân tích tìm lỗi mã nguồn riêng biệt sẽ được chạy cho các thành phần chính và thành phần kiểm thử của mô-đun. Lý do của sự thay đổi này là để cải thiện hiệu suất. Để quay lại hành vi trước đó, hãy đặt android.experimental.lint.analysisPerComponent=false trong tệp gradle.properties.

Tính năng rút gọn tài nguyên chính xác được bật theo mặc định

Tính năng rút gọn tài nguyên chính xác (xoá các mục nhập không dùng đến khỏi tệp resources.arsc và loại bỏ các tệp tài nguyên không dùng đến) được bật theo mặc định. Khi bạn bật tính năng rút gọn này, bảng tài nguyên của bạn sẽ giảm và chỉ có các mục nhập thư mục res được tham chiếu mới được đưa vào APK.

Để tắt tính năng rút gọn tài nguyên chính xác, hãy đặt android.enableNewResourceShrinker.preciseShrinking thành false trong tệp gradle.properties của dự án.