Tạo một thư viện Android

Thư viện Android có cấu trúc giống như một mô-đun ứng dụng Android. Trong thư viện Android có mọi thứ cần thiết để xây dựng một ứng dụng, bao gồm cả mã nguồn, tệp tài nguyên và tệp kê khai của Android. Tuy nhiên, thay vì biên dịch thành một APK chạy trên thiết bị, thì thư viện Android sẽ biên dịch thành một tệp Android Archive (AAR) mà bạn có thể sử dụng làm phần phụ thuộc cho mô-đun ứng dụng Android. Không giống như tệp JAR, tệp AAR cung cấp chức năng sau đây cho các ứng dụng Android:

  • Các tệp AAR có thể chứa các tài nguyên Android và một tệp kê khai, cho phép bạn gói các tài nguyên được chia sẻ như bố cục và các đối tượng có thể vẽ bên cạnh các lớp và phương thức trong Java.
  • Tệp AAR có thể chứa thư viện C/C++ để sử dụng mã C/C++ của mô-đun ứng dụng.

Mô-đun thư viện hữu ích trong các trường hợp sau:

  • Khi bạn xây dựng nhiều ứng dụng sử dụng một số thành phần giống nhau, chẳng hạn như hoạt động, dịch vụ hoặc bố cục của giao diện người dùng.
  • Khi bạn xây dựng một ứng dụng tồn tại ở nhiều biến thể APK, chẳng hạn như một phiên bản miễn phí và một phiên bản trả phí, đồng thời bạn cần có các thành phần cốt lõi giống nhau ở cả hai phiên bản.

Trong cả hai trường hợp, bạn chỉ cần di chuyển các tệp mà mình muốn sử dụng lại vào mô-đun thư viện, sau đó thêm thư viện làm phần phụ thuộc cho mỗi mô-đun ứng dụng. Trang này sẽ hướng dẫn bạn cách xử lý cả hai trường hợp này.

Tạo mô-đun thư viện

Để tạo một mô-đun thư viện mới trong dự án của bạn, hãy tiến hành như sau:

  1. Nhấp vào File > New > New Module (Tệp > Mới > Mô-đun mới).
  2. Trong cửa sổ Tạo mô-đun mới xuất hiện, nhấp vào Thư viện Android, rồi nhấp vào Tiếp theo.

    Ngoài ra, bạn cũng có thể tạo Thư viện Java để xây dựng một tệp JAR truyền thống. Mặc dù tệp JAR hữu ích cho nhiều dự án — đặc biệt là khi bạn muốn chia sẻ mã với các nền tảng khác, nhưng tệp không cho phép bạn đưa tài nguyên Android hoặc tệp kê khai, điều mà rất hữu ích cho việc sử dụng lại mã trong các dự án Android. Vì vậy, hướng dẫn này tập trung vào quy trình tạo thư viện Android.

  3. Đặt tên cho thư viện và chọn một phiên bản SDK tối thiểu cho mã trong thư viện, rồi nhấp vào Hoàn tất.

Sau khi quá trình đồng bộ hóa dự án Gradle hoàn tất, mô-đun thư viện sẽ xuất hiện trong bảng điều khiển Dự án ở bên trái. Nếu bạn không thấy thư mục mô-đun mới, hãy đảm bảo thư mục đó đang hiển thị chế độ xem Android.

Chuyển đổi mô-đun ứng dụng thành mô-đun thư viện

Nếu đã có một mô-đun ứng dụng có toàn bộ mã mà bạn muốn sử dụng lại, bạn có thể chuyển mô-đun đó thành một mô-đun thư viện như sau:

  1. Mở tệp build.gradle ở cấp mô-đun.
  2. Xóa dòng cho applicationId. Chỉ một mô-đun ứng dụng Android mới có thể xác định điều này.
  3. Ở đầu tệp, bạn sẽ thấy các thông tin sau:

    Groovy

      plugins {
        id 'com.android.application'
      }
      

    Kotlin

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

    Hãy thay đổi thành như sau:

    Groovy

      plugins {
          id 'com.android.library'
      }
      

    Kotlin

      plugins {
          id("com.android.library")
      }
      
  4. Lưu tệp và nhấp vào File > Sync Project with Gradle Files (Tệp > Đồng bộ hóa dự án với Gradle Files).

Vậy là xong. Toàn bộ cấu trúc của mô-đun vẫn giữ nguyên, nhưng giờ đây, mô-đun này hoạt động như một thư viện Android và bản dựng sẽ tạo một tệp AAR thay vì APK.

Khi bạn muốn xây dựng tệp AAR, hãy chọn mô-đun thư viện trong cửa sổ Dự án rồi nhấp vào Build > Build APK(Xây dựng > Xây dựng APK).

Thêm phần phụ thuộc bằng hộp thoại Cấu trúc dự án

Sử dụng thư viện của bạn từ cùng một dự án

Để sử dụng mã của thư viện Android mới trong một ứng dụng hoặc mô-đun thư viện khác trong cùng một dự án, hãy thêm phần phụ thuộc cấp dự án:

  1. Điều hướng tới File > Project Structure > Dependencies (Tệp > Cấu trúc dự án > Phần phụ thuộc).
  2. Chọn Mô-đun mà bạn sẽ sử dụng thư viện trong mô-đun đó.
  3. Trong thẻ Phần phụ thuộc đã khai báo, nhấp vào rồi chọn Phần phụ thuộc của mô-đun trong trình đơn thả xuống.

  4. Trong hộp thoại Thêm phần phụ thuộc của mô-đun, hãy chọn mô-đun thư viện của bạn.

    Thêm phần phụ thuộc của mô-đun vào hộp thoại Cấu trúc dự án

  5. Chọn cấu hình yêu cầu phần phụ thuộc này hoặc chọn "triển khai" nếu phần phụ thuộc đó áp dụng cho tất cả các cấu hình và nhấp vào OK.

Studio sẽ chỉnh sửa tệp build.gradle của mô-đun để thêm phần phụ thuộc của biểu mẫu:

implementation(project(path: ":example-library"))

Sử dụng thư viện của bạn trong các dự án khác

Cách thức đề xuất để chia sẻ các phần phụ thuộc (JAR và AAR) là với một kho lưu trữ Maven, được lưu trữ trên một dịch vụ chẳng hạn như Maven Central hoặc với cấu trúc thư mục trên ổ đĩa cục bộ của bạn. Để biết thêm thông tin về cách sử dụng kho lưu trữ Maven, hãy xem Kho lưu trữ từ xa.

Khi một thư viện Android được phát hành lên một kho lưu trữ Maven, siêu dữ liệu sẽ được đưa vào để các phần phụ thuộc của thư viện được đưa vào bản dựng đang sử dụng, cho phép thư viện tự động loại bỏ trùng lặp nếu thư viện đó được sử dụng ở nhiều vị trí.

Để sử dụng mã của thư viện Android trong một mô-đun ứng dụng khác, hãy tiến hành như sau:

  1. Điều hướng tới File > Project Structure > Dependencies (Tệp > Cấu trúc dự án > Phần phụ thuộc).
  2. Trong thẻ Phần phụ thuộc đã khai báo, nhấp vào rồi chọn Phần phụ thuộc của thư viện trong trình đơn thả xuống.

  3. Trong hộp thoại Thêm phần phụ thuộc của thư viện, sử dụng hộp tìm kiếm để tìm thư viện mà bạn muốn thêm. Biểu mẫu này tìm kiếm những kho lưu trữ được chỉ định trong khối dependencyResolutionManagement { repositories {...}} trong tệp settings.gradle.

    Thêm phần phụ thuộc của thư viện vào hộp thoại Cấu trúc dự án

  4. Chọn cấu hình yêu cầu phần phụ thuộc này hoặc chọn "triển khai" nếu phần phụ thuộc đó áp dụng cho tất cả các cấu hình.

  5. Kiểm tra tệp build.gradle của ứng dụng để xác nhận nội dung khai báo tương tự như sau (tùy thuộc vào cấu hình bản dựng bạn đã chọn):

    implementation 'com.example:examplelibrary:1.0.0'

Thêm AAR hoặc JAR làm phần phụ thuộc

Để sử dụng mã của thư viện Android trong một mô-đun ứng dụng khác, hãy tiến hành như sau:

  1. Điều hướng tới File > Project Structure > Dependencies (Tệp > Cấu trúc dự án > Phần phụ thuộc).
  2. Trong thẻ Phần phụ thuộc đã khai báo, nhấp vào rồi chọn Phần phụ thuộc Jar trong trình đơn thả xuống.

  3. Trong hộp thoại Thêm phần phụ thuộc Jar/Aar, trước tiên, nhập đường dẫn đến tệp .aar hoặc .jar của bạn, rồi chọn cấu hình mà phần phụ thuộc này sẽ áp dụng. Nếu thư viện đã được cung cấp cho tất cả các cấu hình, hãy chọn cấu hình "triển khai".

    Thêm phần phụ thuộc AAR vào hộp thoại Cấu trúc dự án

  4. Kiểm tra tệp build.gradle của ứng dụng để xác nhận nội dung khai báo tương tự như sau (tùy thuộc vào cấu hình bản dựng bạn đã chọn):

      implementation files('my_path/my_lib.aar')
    

Ngoài ra, nếu đang chạy các bản dựng Gradle bên ngoài Android Studio, bạn có thể nhập một phần phụ thuộc bằng cách thêm đường dẫn vào phần phụ thuộc đó trong tệp build.gradle của ứng dụng. Ví dụ:

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
    ...
}

Để biết thêm về cách thêm các phần phụ thuộc Gradle, hãy xem phần Thêm các phần phụ thuộc cho bản dựng.

Chọn tài nguyên để công khai

Tất cả tài nguyên trong thư viện đều mặc định ở chế độ công khai. Để đặt tất cả các tài nguyên ở chế độ riêng tư ngầm, bạn phải xác định ít nhất một thuộc tính cụ thể là công khai. Các tài nguyên bao gồm tất cả các tệp trong thư mục res/ của dự án, chẳng hạn như các hình ảnh. Để ngăn người dùng thư viện của bạn truy cập vào các tài nguyên chỉ dùng cho nội bộ, bạn nên sử dụng cơ chế chỉ định riêng tư tự động này bằng cách khai báo một hoặc nhiều tài nguyên công khai. Ngoài ra, bạn có thể đặt tất cả tài nguyên ở chế độ riêng tư bằng cách thêm thẻ <public /> trống, thẻ này sẽ không đánh dấu nội dung nào là công khai, điều này sẽ đặt mọi nội dung khác (tất cả tài nguyên) ở chế độ riêng tư.

Để khai báo tài nguyên công khai, thêm khai báo <public> vào tệp public.xml của thư viện. Nếu trước đó chưa từng thêm tài nguyên công khai thì bạn cần tạo tệp public.xml trong thư mục res/values/ của thư viện.

Mã ví dụ sau đây sẽ tạo hai tài nguyên chuỗi công khai có tên mylib_app_namemylib_public_string:

<resources>
    <public name="mylib_app_name" type="string"/>
    <public name="mylib_public_string" type="string"/>
</resources>

Bạn nên hiển thị công khai mọi tài nguyên mà bạn muốn các nhà phát triển vẫn xem được bằng cách sử dụng thư viện của bạn.

Ngầm ẩn các thuộc tính ở chế độ riêng tư không chỉ ngăn người dùng thư viện của bạn thử nghiệm các đề xuất hoàn thành mã từ tài nguyên thư viện nội bộ mà còn cho phép bạn đổi tên hoặc gỡ bỏ các tài nguyên riêng tư mà không làm hỏng ứng dụng của thư viện. Các tài nguyên riêng tư được lọc ra khỏi quá trình hoàn thành mã và Lint sẽ nhắc nhở bạn khi bạn cố gắng tham chiếu một tài nguyên riêng tư.

Khi xây dựng một thư viện, trình bổ trợ Android cho Gradle sẽ lấy các định nghĩa tài nguyên công khai và trích xuất các định nghĩa đó vào tệp public.txt, sau đó gói các tệp này bên trong tệp AAR.

Những điểm cần lưu ý khi phát triển mô-đun thư viện

Khi bạn phát triển các mô-đun thư viện và ứng dụng phụ thuộc, hãy lưu ý đến các hành vi và giới hạn sau.

Sau khi thêm tệp đối chiếu vào các mô-đun thư viện vào mô-đun của ứng dụng Android, bạn có thể đặt mức độ ưu tiên tương đối cho các mô-đun đó. Tại thời điểm xây dựng, các thư viện sẽ được hợp nhất với từng ứng dụng một, bắt đầu từ mức ưu tiên thấp nhất đến mức cao nhất.

  • Xung đột trong hợp nhất tài nguyên

    Các công cụ xây dựng hợp nhất tài nguyên từ một mô-đun thư viện với các tài nguyên của một mô-đun ứng dụng độc lập. Nếu một mã tài nguyên nhất định được xác định trong cả hai mô-đun, thì tài nguyên từ ứng dụng sẽ được sử dụng.

    Nếu xảy ra xung đột giữa nhiều thư viện AAR, thì sẽ sử dụng tài nguyên từ thư viện được liệt kê đầu tiên trong danh sách phần phụ thuộc (ở đầu khối dependencies).

    Để tránh xung đột tài nguyên cho các mã tài nguyên phổ biến, hãy cân nhắc sử dụng một tiền tố hoặc lược đồ đặt tên nhất quán khác dành riêng cho mô-đun (hoặc là duy nhất trong tất cả các mô-đun dự án).

  • Trong các bản dựng có nhiều mô-đun, các phần phụ thuộc JAR sẽ được coi là phần phụ thuộc bắc cầu

    Khi bạn thêm phần phụ thuộc JAR vào một dự án thư viện mà sẽ tạo ra AAR, thì JAR này sẽ được mô-đun thư viện xử lý và đóng gói với AAR của mô-đun đó.

    Tuy nhiên, nếu dự án của bạn bao gồm một mô-đun thư viện mà được một mô-đun ứng dụng sử dụng, thì mô-đun ứng dụng đó sẽ xem phần phụ thuộc JAR cục bộ của thư viện là một phần phụ thuộc bắc cầu. Trong trường hợp này, JAR cục bộ sẽ được xử lý bởi mô-đun ứng dụng sử dụng mô-đun đó, chứ không phải bằng mô-đun thư viện. Điều này giúp tăng tốc độ cho các bản dựng do các thay đổi mã của thư viện gây ra.

    Bạn cần phải giải quyết mọi xung đột tài nguyên Java do các phần phụ thuộc JAR cục bộ gây ra trong mô-đun ứng dụng mà sử dụng thư viện.

  • Một mô-đun thư viện có thể phụ thuộc vào một thư viện JAR bên ngoài

    Bạn có thể phát triển một mô-đun thư viện phụ thuộc vào thư viện bên ngoài. (ví dụ: thư viện bên ngoài của Maps). Trong trường hợp này, ứng dụng phụ thuộc phải xây dựng dựa vào một mục tiêu có bao gồm thư viện bên ngoài (ví dụ: Tiện ích bổ sung API của Google). Ngoài ra, hãy lưu ý rằng cả mô-đun thư viện và ứng dụng phụ thuộc đều phải khai báo thư viện bên ngoài trong tệp kê khai của cả mô-đun thư viện và ứng dụng phụ thuộc đó, trong phần tử <uses-library>.

  • minSdkVersion của mô-đun ứng dụng phải bằng hoặc hơn phiên bản do thư viện xác định

    Thư viện được biên dịch như một phần của mô-đun ứng dụng phụ thuộc, vì vậy, các API dùng trong mô-đun thư viện phải tương thích với phiên bản nền tảng mà mô-đun ứng dụng hỗ trợ.

  • Mỗi mô-đun thư viện tạo ra lớp R riêng

    Khi bạn xây dựng các mô-đun ứng dụng phụ thuộc, các mô-đun thư viện sẽ được biên dịch vào tệp AAR rồi thêm vào mô-đun ứng dụng. Do đó, mỗi thư viện có lớp R riêng và được đặt tên theo tên gói của thư viện. Lớp R được tạo từ mô-đun chính và mô-đun thư viện được tạo trong tất cả các gói cần thiết, bao gồm cả gói của mô-đun chính và các gói của thư viện.

  • Một mô-đun thư viện có thể bao gồm tệp cấu hình ProGuard riêng

    Nếu có dự án thư viện mà bạn sử dụng để xây dựng và phát hành AAR, bạn có thể thêm tệp cấu hình ProGuard vào cấu hình xây dựng của thư viện và trình bổ trợ Android cho Gradle sẽ áp dụng các quy tắc ProGuard mà bạn đã chỉ định. Các công cụ xây dựng sẽ nhúng tệp này trong tệp AAR được tạo cho mô-đun thư viện. Khi bạn thêm thư viện vào một mô-đun ứng dụng, tệp ProGuard của thư viện sẽ được thêm vào tệp cấu hình ProGuard (proguard.txt) của mô-đun ứng dụng.

    Bằng cách nhúng tệp ProGuard vào mô-đun thư viện, bạn đảm bảo rằng các mô-đun ứng dụng phụ thuộc vào thư viện không phải cập nhật các tệp ProGuard theo cách thủ công để sử dụng thư viện của bạn. Khi hệ thống xây dựng Android Studio xây dựng ứng dụng của bạn, hệ thống sẽ sử dụng các lệnh từ cả mô-đun ứng dụng và thư viện. Vì vậy, bạn không cần phải chạy trình thu gọn mã trên thư viện bằng một bước riêng biệt.

    Để thêm các quy tắc ProGuard vào dự án thư viện, bạn phải chỉ định tên tệp bằng thuộc tính consumerProguardFiles, bên trong khối defaultConfig của tệp build.gradle trong thư viện. Ví dụ, đoạn mã sau đây sẽ đặt lib-proguard-rules.txt làm tệp cấu hình ProGuard của thư viện:

    Groovy

    android {
        defaultConfig {
            consumerProguardFiles 'lib-proguard-rules.txt'
        }
        ...
    }

    Kotlin

    android {
        defaultConfig {
            consumerProguardFiles("lib-proguard-rules.txt")
        }
        ...
    }

    Tuy nhiên, nếu mô-đun thư viện của bạn là một phần của bản dựng nhiều mô-đun mà biên dịch thành APK và không tạo AAR, thì bạn chỉ nên thu gọn mã trên mô-đun ứng dụng mà sử dụng thư viện. Để tìm hiểu thêm về các quy tắc ProGuard và cách sử dụng các quy tắc đó, hãy đọc Thu gọn, làm rối mã nguồn và tối ưu hóa ứng dụng của bạn.

  • Quá trình thử nghiệm mô-đun thư viện cũng giống như quá trình thử nghiệm ứng dụng

    Điểm khác biệt chính là thư viện và các phần phụ thuộc của thư viện đó sẽ được tự động thêm vào dưới dạng phần phụ thuộc của APK thử nghiệm. Điều này có nghĩa là APK thử nghiệm không chỉ bao gồm mã riêng của APK đó mà còn chứa AAR của thư viện và mọi phần phụ thuộc của APK đó. Do không có "ứng dụng riêng biệt nào đang thử nghiệm, nên nhiệm vụ của androidTest sẽ cài đặt (và gỡ cài đặt) chỉ APK thử nghiệm.

    Khi hợp nhất nhiều tệp kê khai, Gradle sẽ thực hiện theo thứ tự ưu tiên mặc định và hợp nhất tệp kê khai của thư viện đó vào tệp kê khai chính của tệp APK thử nghiệm.

Phân tích thành phần của tệp AAR

Đuôi tệp của tệp AAR là .aar và loại cấu phần mềm Maven cũng phải là aar. Bản thân tệp này là tệp zip. Mục nhập bắt buộc duy nhất là /AndroidManifest.xml.

Ngoài ra, tệp AAR có thể bao gồm một hoặc nhiều mục nhập tùy chọn sau đây: