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

,

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

,

Библиотека 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. Выберите конфигурацию, которая требует этой зависимости, или выберите реализацию , если она применима ко всем конфигурациям, затем нажмите OK .

Android Studio Редактирует build.gradle.kts вашего модуля build.gradle

классный

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

Котлин

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

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

Рекомендуемый способ обмена зависимостями (банками и AARS) - с репозиторием Maven, который находится на услуге, такой как Maven Central , или со структурой каталогов на вашем местном диске. Для получения дополнительной информации об использовании хранилища Maven см. Удаленные репозитории .

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

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

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

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

    Добавить библиотечную зависимость в диалог структуры проекта

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

Проверьте файл вашего приложения 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/ Directory вашей библиотеки.

Следующий пример код создает два открытых строковых ресурса с именами 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 ).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    классный

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

    Котлин

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

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

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

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

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

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

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

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