Создайте библиотеку 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. При сборке вместо APK создается файл AAR.

Если вы хотите создать файл 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 .

  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 ).

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

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