Создайте библиотеку 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 файлу, затем выберите конфигурацию, к которой применяется зависимость. Если библиотека должна быть доступна для всех конфигураций, выберите конфигурацию реализации .

    Добавить зависимость AAR в структуру проекта Диалоговое окно

    Проверьте файл 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 /> . Это не пометит ничего как общедоступное и сделает все ресурсы приватными.

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

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

При сборке библиотеки плагин 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 также может содержать одну или несколько из следующих необязательных записей: