Ограничения и порядок применения модификаторов

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

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

Модификаторы в дереве интерфейса

Чтобы понять, как модификаторы влияют друг на друга, полезно визуализировать, как они появляются в дереве пользовательского интерфейса, которое генерируется на этапе композиции. Подробную информацию вы найдете в разделе Состав.

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

Код для composable-функций и модификаторов, а также их визуальное представление в виде дерева интерфейса.
Рисунок 1. Модификаторы, которые оборачивают узлы макета в дереве интерфейса.

Добавление нескольких модификаторов к composable-функции создает цепочку модификаторов. Когда вы связываете несколько модификаторов, каждый узел модификатора оборачивает остальную часть цепочки и узел макета внутри. Например, если вы объедините модификаторы clip и size, узел модификатора clip будет содержать узел модификатора size, который, в свою очередь, будет содержать узел макета Image.

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

Как показано на рисунке 2, реализация composable-функций Image и Text состоит из цепочки модификаторов, которые оборачивают один узел макета.

Реализации Row и Column – это узлы макета, которые описывают, как размещать дочерние элементы.

Древовидная структура, как и раньше, но теперь каждый узел представляет собой простой макет с множеством узлов-оберток модификаторов вокруг него.
Рисунок 2. Та же древовидная структура, что и на рисунке 1, но с composable-функциями в дереве интерфейса, визуализированными в виде цепочек модификаторов.

Подведем итоги:

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

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

Ограничения на этапе макета

Этап макета следует алгоритму из трех шагов, чтобы определить ширину, высоту и координаты X и Y каждого узла макета:

  1. Измерение дочерних элементов. Узел измеряет свои дочерние элементы, если они есть.
  2. Определение собственного размера. На основе этих измерений узел определяет свой размер.
  3. Разместить дочерние элементы. Каждый дочерний узел размещается относительно положения узла.

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

Типы ограничений

Ограничение может быть одним из следующих:

  • Ограниченный. Узел имеет максимальную и минимальную ширину и высоту.
Ограничения разных размеров в контейнере.
Рисунок 3. Ограничения.
  • Unbounded (Без ограничений). Размер узла не ограничен. Максимальные значения ширины и высоты не ограничены.
Неограниченные ограничения, ширина и высота которых установлены на бесконечность. Ограничения выходят за пределы контейнера.
Рисунок 4. Неограниченные ограничения.
  • Точный. Узел должен соответствовать точному требованию к размеру. Минимальное и максимальное значения равны.
Точные ограничения, которые соответствуют требованиям к размеру в контейнере.
Рисунок 5. Точные ограничения.
  • Комбинированное ограничение. Узел следует комбинации предыдущих типов ограничений. Например, можно ограничить ширину, но не высоту, или задать точную ширину и ограничить высоту.
Два контейнера, которые показывают комбинации ограниченных и неограниченных ограничений, а также точную ширину и высоту.
Рисунок 6. Комбинации ограниченных и неограниченных ограничений, а также точных значений ширины и высоты.

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

Как ограничения передаются от родительского элемента к дочернему

На первом шаге алгоритма, описанного в разделе Ограничения на этапе макета, ограничения передаются от родительского элемента к дочернему в дереве пользовательского интерфейса.

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

В общих чертах алгоритм работает следующим образом:

  1. Чтобы определить размер, который он на самом деле хочет занять, корневой узел в дереве пользовательского интерфейса измеряет свои дочерние элементы и пересылает те же ограничения своему первому дочернему элементу.
  2. Если дочерний элемент является модификатором, который не влияет на измерение, он пересылает ограничения следующему модификатору. Ограничения передаются по цепочке модификаторов как есть, пока не будет достигнут модификатор, влияющий на измерение. Ограничения будут изменены соответствующим образом.
  3. Когда узел достигает точки, в которой у него нет дочерних элементов (так называемый "листовой узел"), он определяет свой размер на основе переданных ограничений и возвращает этот разрешенный размер своему родительскому элементу.
  4. Родительский виджет адаптирует свои ограничения на основе размеров этого дочернего виджета и вызывает следующий дочерний виджет с этими скорректированными ограничениями.
  5. После того как все дочерние элементы родительского элемента будут измерены, родительский узел определяет свой собственный размер и сообщает об этом своему родительскому элементу.
  6. Таким образом, все дерево обходится в глубину. В конце концов все узлы определились со своими размерами, и этап измерения завершен.

Подробный пример смотрите в видео Ограничения и порядок модификаторов.

Модификаторы, влияющие на ограничения

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

Модификатор size

Модификатор size объявляет предпочтительный размер контента.

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

Часть дерева интерфейса с модификатором размера, который оборачивает узел макета, и представление ограниченных ограничений, заданных модификатором размера в контейнере.
Рисунок 7. Ограниченные ограничения в дереве пользовательского интерфейса и его представление в контейнере.

Модификатор size адаптирует входящие ограничения в соответствии с переданным ему значением. В этом примере значение равно 150dp:

То же, что и на рисунке 7, за исключением того, что модификатор размера адаптирует входящие ограничения в соответствии с переданным ему значением.
Рисунок 8. Модификатор size корректирует ограничения до 150dp.

Если ширина и высота меньше наименьшей границы ограничения или больше наибольшей границы ограничения, модификатор максимально точно соответствует переданным ограничениям, при этом соблюдая переданные ограничения:

Два дерева пользовательского интерфейса и соответствующие им представления в контейнерах. В первом случае модификатор размера принимает входящие ограничения, а во втором – адаптируется к слишком большим ограничениям, насколько это возможно, в результате чего ограничения заполняют контейнер.
Рисунок 9. Модификатор size, который максимально точно соответствует переданному ограничению.

Обратите внимание, что объединять несколько модификаторов size нельзя. Первый модификатор size задает фиксированное значение для минимального и максимального ограничений. Даже если второй модификатор размера запрашивает меньший или больший размер, он все равно должен придерживаться точных переданных границ, поэтому он не будет переопределять эти значения:

Цепочка из двух модификаторов размера в дереве интерфейса и ее представление в контейнере, которое является результатом первого переданного значения, а не второго.
Рисунок 10. Цепочка из двух модификаторов size, в которой второе переданное значение (50dp) не переопределяет первое (100dp).

Модификатор requiredSize

Если вам нужно, чтобы узел переопределял входящие ограничения, используйте модификатор requiredSize вместо size. Модификатор requiredSize заменяет входящие ограничения и передает указанный вами размер в качестве точных границ.

Если переданный вами размер выходит за рамки входящих ограничений, узел сообщает размер, который им соответствует, когда размер передается обратно по дереву, и его содержимое центрируется в этом пространстве по каждой оси, где два размера различаются. Контент, размер которого превышает ограничения, выходит за их пределы. На рисунке 11 requiredSize(50) меньше, чем 100dp, переданный size, поэтому контент 50dp центрируется в пространстве 100dp:

Модификаторы size и requiredSize, связанные в дереве интерфейса, и соответствующее представление в контейнере. Ограничения модификатора requiredSize переопределяют ограничения модификатора size.
Рисунок 11. Модификатор requiredSize переопределяет ограничения, заданные модификатором size.

Модификаторы width и height

Модификатор size адаптирует как ширину, так и высоту ограничений. С помощью модификатора width можно задать фиксированную ширину, но оставить высоту неопределенной. Аналогично с помощью модификатора height можно задать фиксированную высоту, но оставить ширину неопределенной:

Два дерева пользовательского интерфейса: одно с модификатором ширины и представлением его контейнера, а другое с модификатором высоты и его представлением.
Рисунок 12. Модификаторы width и height, задающие фиксированную ширину и высоту соответственно.

Чтобы задать ширину или высоту, которая переопределяет входящие ограничения, используйте requiredWidth или requiredHeight. Как и requiredSize, каждый из них заменяет входящие ограничения, но только по своей оси: requiredWidth сохраняет входящие ограничения по высоте, а requiredHeight сохраняет входящие ограничения по ширине.

Модификатор sizeIn

Модификатор sizeIn позволяет задавать минимальные и максимальные ограничения для ширины и высоты в рамках входящих ограничений. Если входящие ограничения строже, они имеют приоритет. Если вам нужен точный контроль над ограничениями, используйте модификатор sizeIn. Модификаторы widthIn и heightIn делают то же самое по одной оси, оставляя ограничения другой оси без изменений. Каждый из них принимает минимальное, максимальное или оба значения.

Дерево пользовательского интерфейса с модификатором sizeIn с установленными минимальной и максимальной шириной и высотой,
  и его представление внутри контейнера.
Рисунок 13. Модификатор sizeIn с заданными значениями minWidth, maxWidth, minHeight и maxHeight.

Чтобы задать диапазон, который переопределяет входящие ограничения, используйте requiredSizeIn или requiredWidthIn и requiredHeightIn для одной оси. Они связаны с sizeIn, widthIn и heightIn так же, как requiredSize с size.

Примеры

В этом разделе показаны и объяснены результаты нескольких фрагментов кода с цепочками модификаторов.

Image(
    painterResource(R.drawable.hero),
    contentDescription = null,
    Modifier
        .fillMaxSize()
        .size(50.dp)
)

Этот фрагмент кода дает следующий результат:

Синий квадрат, который заполняет родительский контейнер.
Рисунок 14. В результате применения цепочки модификаторов Image заполняет максимальный размер.
  • Модификатор fillMaxSize изменяет ограничения, устанавливая минимальную ширину и высоту на максимальное значение – 300dp по ширине и 200dp по высоте.
  • Хотя модификатор size хочет использовать размер 50dp, он все равно должен придерживаться входящих минимальных ограничений. Поэтому модификатор size также выведет точные границы ограничений 300 на 200, фактически игнорируя значение, указанное в модификаторе size.
  • Image следует этим границам и сообщает размер 300 на 200, который передается вверх по дереву.

Image(
    painterResource(R.drawable.hero),
    contentDescription = null,
    Modifier
        .fillMaxSize()
        .wrapContentSize()
        .size(50.dp)
)

Этот фрагмент кода дает следующий результат:

Небольшой синий квадрат, расположенный по центру родительского контейнера.
Рисунок 15. Image центрируется и масштабируется до размера 50dp.
  • Модификатор fillMaxSize адаптирует ограничения, чтобы установить минимальную ширину и высоту на максимальное значение – 300dp по ширине и 200dp по высоте.
  • Модификатор wrapContentSize сбрасывает минимальные ограничения. Таким образом, если fillMaxSize приводит к фиксированным ограничениям, то wrapContentSize возвращает ограниченные. Следующий узел может снова занять все пространство или быть меньше всего пространства.
  • Модификатор size задает ограничения для минимального и максимального значения 50.
  • Image определяет размер 50 на 50, а модификатор size передает его дальше.
  • Модификатор wrapContentSize имеет особое свойство. Он берет дочерний элемент и помещает его в центр доступных минимальных границ, которые были ему переданы. Размер, который он передает своим родителям, равен минимальным границам, которые были в него переданы.

Объединив всего три модификатора, вы можете определить размер composable-функции и центрировать ее в родительском элементе.

Image(
    painterResource(R.drawable.hero),
    contentDescription = null,
    Modifier
        .clip(CircleShape)
        .padding(10.dp)
        .size(100.dp)
)

Этот фрагмент кода дает следующий результат:

Круглая фигура, которая неправильно обрезана из-за порядка модификаторов.
Рисунок 16. Неправильно обрезанная фигура из-за порядка модификаторов.
  • Модификатор clip не меняет ограничения.
  • Модификатор padding снижает максимальные ограничения.
  • Модификатор size задает для всех ограничений значение 100dp.
  • Image соблюдает эти ограничения и сообщает о размере 100dp x 100dp.
  • Модификатор padding добавляет 10dp со всех сторон к размеру, сообщаемому Image, поэтому макет с отступом сообщает ширину и высоту 120dp.
  • Теперь, на этапе рисования, модификатор clip действует на холсте размером 120dp на 120dp. Будет создана круглая маска указанного размера.
  • Затем модификатор padding вставляет свое содержимое на 10dp со всех сторон, что уменьшает размер холста для Image до 100dp на 100dp.
  • Image рисуется на этом меньшем холсте. Изображение обрезается по исходному кругу 120dp, поэтому результат получается некруглым.

В следующих трех фрагментах кода элемент Box с фоновым цветом помещается в тот же контейнер размером 300dp x 200dp.

Box(
    modifier = Modifier
        .requiredWidth(400.dp)
        .height(100.dp)
        .background(Color(0xFF3DDC84))
)

Этот фрагмент кода дает следующий результат:

Широкий зеленый прямоугольник, расположенный по центру светло-синего контейнера и выходящий за его пределы по горизонтали.
Рисунок 17. При использовании requiredWidth(400.dp) Box выходит за пределы контейнера 300dp на 50dp с каждой стороны.
  • Модификатор requiredWidth заменяет входящие ограничения ширины точными границами 400dp. Оно сохраняет ограничения по высоте, 0 до 200dp.
  • Модификатор height задает высоту 100dp, которая соответствует ограничениям.
  • Box измеряет 400dp по 100dp. Эта ширина больше, чем 300dp, разрешенные контейнером, поэтому requiredWidth сообщает родительскому элементу ширину 300dp и центрирует свой контент в этом пространстве: Box выходит за пределы каждой стороны контейнера на 50dp.

Box(
    modifier = Modifier
        .widthIn(min = 100.dp, max = 400.dp)
        .heightIn(max = 100.dp)
        .fillMaxSize()
        .background(Color(0xFF3DDC84))
)

Этот фрагмент кода дает следующий результат:

Зеленый прямоугольник, расположенный по центру вертикально внутри светло-синего контейнера,
    соответствующий полной ширине контейнера, не выходя за его стороны.
Рисунок 18. widthIn, Box имеет размеры 300dp на 100dp и остается внутри контейнера.
  • Модификатор widthIn запрашивает ширину от 100dp до 400dp. Максимальная ширина входящего видеопотока составляет 300dp, поэтому ограничения по ширине становятся равны 100dp и 300dp.
  • Модификатор heightIn задает максимальную высоту 100dp, поэтому ограничения по высоте становятся от 0 до 100dp.
  • Модификатор fillMaxSize устанавливает минимальную ширину и высоту, равные этим максимальным значениям, поэтому Box имеет размер 300dp на 100dp и остается внутри контейнера.

Box(
    modifier = Modifier
        .requiredSizeIn(minWidth = 100.dp, maxWidth = 400.dp, maxHeight = 100.dp)
        .fillMaxSize()
        .background(Color(0xFF3DDC84))
)

Этот фрагмент кода дает следующий результат:

Широкий зеленый прямоугольник, расположенный по центру светло-синего контейнера и выходящий за его пределы по горизонтали.
Рисунок 19. При использовании requiredSizeIn Box имеет размеры 400dp на 100dp и выходит за пределы контейнера на 50dp с каждой стороны. Результат такой же, как на рисунке 17.
  • Модификатор requiredSizeIn заменяет входящие ограничения шириной от 100dp до 400dp и высотой от 0 до 100dp. Минимальная высота не задана, поэтому используется значение 0.
  • Модификатор fillMaxSize устанавливает минимальную ширину и высоту равными этим максимальным значениям, поэтому Box имеет размеры 400dp на 100dp.
  • Как и в примере с requiredWidth, ширина больше, чем позволяет контейнер, поэтому Box центрируется и выходит за пределы каждой стороны на 50dp.

При одинаковом диапазоне widthIn и heightIn сохраняют Box внутри контейнера, а requiredSizeIn – нет.