Создайте библиотеку Android

Библиотека Android структурно аналогична модулю приложения Android. Она включает в себя всё необходимое для создания приложения, включая исходный код, файлы ресурсов и манифест Android.

Однако вместо компиляции в APK-файл, запускаемый на устройстве, библиотека Android компилируется в файл Android Archive (AAR), который можно использовать в качестве зависимости для модуля приложения Android. В отличие от JAR-файлов, AAR-файлы предлагают следующие функции для приложений Android:

• Файлы AAR могут содержать ресурсы Android и файл манифеста, что позволяет объединять общие ресурсы, такие как макеты и чертежи, в дополнение к классам и методам Kotlin или Java.
• Файлы AAR могут содержать библиотеки C/C++ для использования кодом C/C++ модуля приложения.

Библиотечный модуль полезен в следующих ситуациях:

• При создании нескольких приложений, которые используют одни и те же компоненты, такие как действия, службы или макеты пользовательского интерфейса
• При создании приложения, которое существует в нескольких вариантах APK, например, в бесплатной и платной версии, которые имеют общие основные компоненты

В любом случае переместите файлы, которые вы хотите использовать повторно, в модуль библиотеки, а затем добавьте библиотеку в качестве зависимости для каждого модуля приложения.

На этой странице объясняется, как создать и использовать модуль библиотеки Android. Инструкции по публикации библиотеки см. в разделе «Публикация библиотеки».

Создать библиотечный модуль

Чтобы создать новый библиотечный модуль в вашем проекте, выполните следующие действия:

1. Нажмите Файл > Создать > Новый модуль .
2. В открывшемся диалоговом окне «Создать новый модуль» нажмите «Библиотека Android» , затем нажмите «Далее» .

   Также можно создать библиотеку Kotlin или Java, которая создаст традиционный JAR-файл. JAR-файл полезен для многих проектов, особенно если вы хотите использовать код на других платформах, но он не позволяет включать ресурсы Android или файлы манифестов, что очень полезно для повторного использования кода в проектах Android. Данное руководство посвящено созданию библиотек Android.

3. Дайте вашей библиотеке имя и выберите минимальную версию SDK для кода в библиотеке, затем нажмите Готово .

После завершения синхронизации проекта Gradle модуль библиотеки появится на панели «Проект» . Если вы не видите новую папку модуля, убедитесь, что на панели отображается представление Android .

Преобразовать модуль приложения в модуль библиотеки

Если у вас есть существующий модуль приложения с кодом, который вы хотите использовать повторно, вы можете превратить его в модуль библиотеки следующим образом:

1. Откройте файл build.gradle на уровне модуля, если вы используете Groovy, или файл build.gradle.kts , если вы используете скрипт Kotlin.
2. Удалите строку для applicationId . Его может определить только модуль приложения Android.
3. Найдите блок `plugins` в верхней части файла, который выглядит следующим образом:

   Круто

     plugins {
         id 'com.android.application'
     }
     

   Котлин

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

   Измените его на следующее:

   Круто

     plugins {
         id 'com.android.library'
     }
     

   Котлин

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

4. Сохраните файл и нажмите Файл > Синхронизировать проект с файлами Gradle .

Структура модуля осталась прежней, но теперь он работает как библиотека Android. Сборка создаёт AAR-файл вместо APK.

Если вы хотите собрать файл AAR, выберите модуль библиотеки в окне проекта и нажмите «Сборка» > «Сборка APK» .

Добавьте зависимости с помощью диалогового окна «Структура проекта»

Вы можете использовать диалоговое окно «Структура проекта» для добавления зависимостей в свой проект. В следующих разделах описано, как использовать диалоговое окно для добавления зависимостей.

Используйте свою библиотеку из того же проекта

Чтобы использовать код новой библиотеки Android в другом приложении или модуле библиотеки в том же проекте, добавьте зависимость на уровне проекта:

1. Перейдите в Файл > Структура проекта > Зависимости .
2. Выберите модуль, к которому вы хотите добавить библиотеку.
3. На вкладке «Объявленные зависимости» нажмите и выберите в меню пункт Зависимость модуля .
   
   

4. В диалоговом окне «Добавить зависимость модуля» выберите модуль библиотеки.

   

5. Выберите конфигурацию, для которой требуется эта зависимость, или выберите реализацию, если она применяется ко всем конфигурациям, затем нажмите кнопку ОК .

Android Studio редактирует файл build.gradle или build.gradle.kts вашего модуля, чтобы добавить зависимость, в следующей форме:

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

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

Используйте вашу библиотеку в других проектах

Рекомендуемый способ совместного использования зависимостей (JAR- и AAR-файлов) — использование репозитория Maven, размещённого на сервисе, например, Maven Central , или структуры каталогов на локальном диске. Подробнее об использовании репозиториев Maven см. в разделе Удалённые репозитории .

При публикации библиотеки Android в репозитории Maven добавляются метаданные, чтобы зависимости библиотеки были включены в сборку-потребитель. Это позволяет автоматически дедуплицировать библиотеку, если она используется в нескольких местах.

Чтобы использовать код вашей библиотеки Android в другом модуле приложения в другом проекте, выполните следующие действия:

1. Перейдите в Файл > Структура проекта > Зависимости .
2. На вкладке «Объявленные зависимости» нажмите и выберите в меню пункт Зависимость библиотеки .
   
   

3. В диалоговом окне «Добавить зависимость библиотеки» воспользуйтесь полем поиска, чтобы найти нужную библиотеку. Эта форма выполняет поиск в репозиториях, указанных в блоке dependencyResolutionManagement { repositories {...}} в файле settings.gradle или settings.gradle.kts .

   

4. Выберите конфигурацию, для которой требуется эта зависимость, или выберите реализацию, если она применяется ко всем конфигурациям, затем нажмите кнопку ОК .

Проверьте файл build.gradle или build.gradle.kts вашего приложения, чтобы убедиться, что в нем отображается объявление, похожее на следующее (в зависимости от выбранной вами конфигурации сборки):

  implementation 'com.example:examplelibrary:1.0.0'

  implementation("com.example:examplelibrary:1.0.0")

Добавьте ваш AAR или JAR как зависимость

Чтобы использовать код вашей библиотеки Android в другом модуле приложения, выполните следующие действия:

1. Перейдите в Файл > Структура проекта > Зависимости .
2. На вкладке «Объявленные зависимости» нажмите и выберите в меню пункт Jar Dependency .
   
   

3. В диалоговом окне «Добавить зависимость Jar/Aar» введите путь к файлу AAR или JAR, а затем выберите конфигурацию, к которой применяется эта зависимость. Если библиотека должна быть доступна для всех конфигураций, выберите конфигурацию реализации .

   

   Проверьте файл build.gradle или build.gradle.kts вашего приложения, чтобы убедиться, что в нем отображается объявление, похожее на следующее (в зависимости от выбранной вами конфигурации сборки):

   Круто

     implementation files('my_path/my_lib.aar')

   Котлин

     implementation(files("my_path/my_lib.aar"))

Чтобы импортировать зависимость от сборки Gradle, запущенной вне Android Studio, добавьте путь к зависимости в файл build.gradle или build.gradle.kts вашего приложения. Например:

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

dependencies {
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar", "*.aar"))))
}

Дополнительную информацию о добавлении зависимостей Gradle см. в разделе Добавление зависимостей сборки .

Объявить публичный ресурс

Ресурсы включают все файлы в каталоге res/ вашего проекта, например, изображения. Все ресурсы в библиотеке по умолчанию являются публичными. Чтобы сделать все ресурсы неявно приватными, необходимо определить хотя бы один атрибут как публичный.

Чтобы объявить публичный ресурс, добавьте объявление <public> в файл public.xml вашей библиотеки. Если вы ещё не добавляли публичные ресурсы, создайте файл public.xml в каталоге res/values/ вашей библиотеки.

В следующем примере кода создаются два публичных строковых ресурса с именами mylib_app_name и mylib_public_string :

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

Чтобы запретить пользователям вашей библиотеки доступ к ресурсам, предназначенным только для внутреннего использования, используйте этот механизм автоматического назначения ресурсов частными, объявив один или несколько общедоступных ресурсов. Вы также можете сделать все ресурсы частными, добавив пустой тег <public /> . Это пометит ничего как общедоступное и сделает все ресурсы частными.

Любые ресурсы, которые вы хотите оставить видимыми для разработчиков, использующих вашу библиотеку, должны быть сделаны общедоступными.

Неявное указание атрибутов как закрытых предотвращает получение пользователями вашей библиотеки предложений по автодополнению кода из внутренних ресурсов библиотеки и позволяет переименовывать или удалять закрытые ресурсы, не нарушая работу клиентов вашей библиотеки. Закрытые ресурсы отфильтровываются при автодополнении кода, а инструмент lint выдает предупреждение при попытке сослаться на закрытый ресурс.

При сборке библиотеки плагин Android Gradle получает определения публичных ресурсов и извлекает их в файл public.txt , который затем упаковывается в файл AAR.

Рекомендации по разработке библиотечных модулей

При разработке библиотечных модулей и зависимых приложений учитывайте следующие особенности поведения и ограничения.

• Библиотеки объединяются в порядке приоритета.

  После добавления ссылок на модули библиотек в модуль вашего приложения Android вы можете задать их относительный приоритет. Во время сборки библиотеки добавляются в приложение по одной, начиная с самого низкого приоритета и заканчивая самым высоким.

  Ссылки на ресурсы в библиотеке будут ссылаться на объединённый ресурс, а не обязательно на ресурс библиотеки. Модуль библиотеки не может принудительно использовать свои ресурсы вместо ресурсов приложения или других библиотек, если существуют ресурсы с одинаковыми именами.

• Избегайте конфликтов при слиянии ресурсов.

  Инструменты сборки объединяют ресурсы из модуля библиотеки с ресурсами зависимого модуля приложения. Если заданное имя ресурса определено в обоих модулях, используется ресурс из приложения.

  Если возникают конфликты между несколькими библиотеками AAR, то используется ресурс из библиотеки, указанной первой в списке зависимостей (ближайшей к началу блока dependencies ).

  Чтобы избежать конфликтов ресурсов, рассмотрите возможность использования префикса или другой последовательной схемы именования, уникальной для модуля (или уникальной для всех модулей проекта).

• В многомодульных сборках зависимости JAR рассматриваются как транзитивные зависимости.

  При добавлении зависимости JAR к библиотечному проекту, который выводит AAR, JAR обрабатывается библиотечным модулем и упаковывается вместе с его AAR.

  Однако если ваш проект включает в себя модуль библиотеки, используемый модулем приложения, модуль приложения рассматривает локальную зависимость JAR-файла библиотеки как транзитивную. В этом случае локальный JAR-файл обрабатывается модулем приложения, который его использует, а не модулем библиотеки. Это ускоряет инкрементальные сборки, вызванные изменениями в коде библиотеки.

  Любые конфликты ресурсов Java, вызванные локальными зависимостями JAR, должны быть разрешены в модуле приложения, который использует библиотеку.

• Модуль библиотеки может зависеть от внешней библиотеки JAR.

  Вы можете разработать библиотечный модуль, зависящий от внешней библиотеки. В этом случае зависимый модуль должен быть построен на основе целевой платформы, включающей внешнюю библиотеку.

  Обратите внимание, что как модуль библиотеки, так и зависимое приложение должны объявить внешнюю библиотеку в своих файлах манифеста в элементе <uses-library> .

• minSdkVersion модуля приложения должно быть равно или превышать версию, определенную библиотекой.

  Библиотека компилируется как часть зависимого модуля приложения, поэтому API, используемые в модуле библиотеки, должны быть совместимы с версией платформы, которую поддерживает модуль приложения.

• Каждый модуль библиотеки создает свой собственный класс R

  При сборке зависимых модулей приложения модули библиотеки компилируются в AAR-файл, а затем добавляются в модуль приложения. Таким образом, каждая библиотека имеет свой собственный класс R , названный в соответствии с именем пакета библиотеки.

  Класс R , сгенерированный из основного модуля и библиотечного модуля, создается во всех необходимых пакетах, включая пакет основного модуля и пакеты библиотек.

• Модуль библиотеки может включать собственный файл конфигурации ProGuard.

  Если у вас есть проект библиотеки, который вы используете для сборки и публикации AAR, вы можете добавить файл конфигурации ProGuard в конфигурацию сборки вашей библиотеки. В этом случае плагин Android Gradle применит заданные вами правила ProGuard. Инструменты сборки встраивают этот файл в сгенерированный AAR-файл для модуля библиотеки. При добавлении библиотеки в модуль приложения файл ProGuard библиотеки добавляется к файлу конфигурации ProGuard ( proguard.txt ) модуля приложения.

  Встраивая файл ProGuard в модуль библиотеки, вы избавляете модули приложения, зависящие от вашей библиотеки, от необходимости вручную обновлять файлы ProGuard для использования вашей библиотеки. Когда система сборки Android Studio собирает ваше приложение, она использует директивы как из модуля приложения, так и из библиотеки. Поэтому нет необходимости запускать функцию сжатия кода для библиотеки на отдельном этапе.

  Чтобы добавить правила ProGuard в проект вашей библиотеки, укажите имя файла с помощью свойства consumerProguardFiles внутри блока defaultConfig файла build.gradle или build.gradle.kts вашей библиотеки.

  Например, следующий фрагмент устанавливает lib-proguard-rules.txt в качестве файла конфигурации библиотеки ProGuard:

  Круто

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

  Котлин

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

  Однако, если ваш модуль библиотеки является частью многомодульной сборки, которая компилируется в APK и не генерирует AAR, выполните сжатие кода только для модуля приложения, использующего библиотеку. Чтобы узнать больше о правилах ProGuard и их применении, ознакомьтесь со статьей «Сжатие, обфускация и оптимизация вашего приложения» .

• Тестирование библиотечного модуля практически аналогично тестированию приложения.

  Главное отличие заключается в том, что библиотека и её зависимости автоматически включаются в зависимости тестового APK. Это означает, что тестовый APK включает не только собственный код, но и AAR-файл библиотеки со всеми его зависимостями. Поскольку отдельного тестируемого приложения нет, задача androidTest устанавливает (и удаляет) только тестовый APK.

  При объединении нескольких файлов манифеста Gradle следует порядку приоритетов по умолчанию и объединяет манифест библиотеки с основным манифестом тестового APK.

Анатомия AAR-файла

Расширение файла AAR — .aar , а тип артефакта Maven — aar . Сам файл представляет собой ZIP-архив. Единственный обязательный параметр — /AndroidManifest.xml .

Файл AAR также может включать одну или несколько из следующих необязательных записей:

• /classes.jar
• /res/
• /R.txt
• /public.txt
• /assets/
• /libs/ name .jar
• /jni/ abi_name / name .so (где abi_name — один из поддерживаемых Android ABI )
• /proguard.txt
• /lint.jar
• /api.jar
• /prefab/ для экспорта собственных библиотек