Разбивка модификаторов по этапам

Jetpack Compose выполняет модификаторы на разных этапах. В таблице ниже показано, к какому этапу относятся распространенные модификаторы и когда оцениваются их аргументы или лямбда-выражения.

Этап 1. Создание

Эти модификаторы оценивают аргументы синхронно внутри тела @Composable. Любое состояние, считанное здесь, регистрирует зависимость с областью перезапуска Composable и запускает полную рекомпозицию при изменении.

  • Статические модификаторы размеров:
    • Modifier.size(dp), Modifier.width(dp), Modifier.height(dp)
    • Modifier.fillMaxSize(), Modifier.fillMaxWidth(), Modifier.fillMaxHeight()
    • Modifier.wrapContentSize(), Modifier.wrapContentWidth(), Modifier.wrapContentHeight()
    • Modifier.requiredSize(), Modifier.defaultMinSize()
    • Modifier.aspectRatio(ratio)
    • Modifier.weight(weight) (в RowScope или ColumnScope)
    • Modifier.width(IntrinsicSize.Min / Max)
    • Modifier.height(IntrinsicSize.Min / Max)
  • Статические интервалы и вставки:
    • Modifier.padding(all = dp), Modifier.padding(start, top, end, bottom)
    • Modifier.windowInsetsPadding(insets), Modifier.statusBarsPadding()
  • Визуальные модификаторы прямого значения:
    • Modifier.alpha(float) (считывает состояние во время компоновки)
    • Modifier.rotate(degrees) (считывает состояние во время создания)
    • Modifier.scale(scaleX, scaleY) (считывает состояние во время компоновки)
    • Modifier.background(color = Color, shape = Shape)
    • Modifier.border(width, color, shape)
    • Modifier.shadow(elevation, shape)
    • Modifier.clip(shape)
    • Modifier.blur(radius)
  • Модификаторы статической позиции:
    • Modifier.offset(x = dp, y = dp) (прямая перегрузка значения)
    • Modifier.absoluteOffset(x = dp, y = dp)
  • Динамические модификаторы Composable
    • Modifier.composed { ... } (выполняет тело фабрики во время композиции; не рекомендуется для повышения производительности – вместо этого используйте Modifier.Node для пользовательских модификаторов)

Этап 2. Макет

Фаза макета разделена на два отдельных подэтапа с отдельными областями недействительности:

Шаг 2А. Отслеживание

Определяет размер (width, height) и ограничения. Считывание состояния здесь запускает повторное измерение и размещение.

  • Modifier.layout { measurable, constraints -> ... } – код, который выполняется до layout(w, h) во время измерения.

Шаг 2Б. Обратные вызовы для размещения и макета

Определяет координату (x, y). Считывание состояния внутри блоков размещения запускает только повторное размещение (пропуская измерение и композицию):

  • Modifier.offset { IntOffset(x, y) } (перегрузка лямбда-функции)
  • Modifier.absoluteOffset { IntOffset(x, y) } (перегрузка лямбда-функции)
  • Modifier.layout { ... layout(w, h) { placeable.place(x, y) } } – код внутри блока layout(w, h) { ... }.

Обратные вызовы наблюдения за макетом также выполняются во время или после прохода макета (избегайте записи в состояние, которое считывается в композиции внутри этих обратных вызовов, так как это приводит к обратной записи):

  • Modifier.onSizeChanged { intSize -> ... } – вызывается после завершения измерения макета, если размеры узла изменились.
  • Modifier.onPlaced { layoutCoordinates -> ... } и Modifier.onLayoutRectChanged { ... } вызываются после размещения, чтобы сообщить локальные координаты или границы без подписки на глобальные проходы макета окна.
  • Modifier.onGloballyPositioned { layoutCoordinates -> ... } – вызывается после завершения всего прохода макета окна при перемещении любого узла. По возможности избегайте использования onGloballyPositioned. Для отслеживания области просмотра лучше использовать Modifier.onVisibilityChanged, для локальных границ – Modifier.onPlaced или Modifier.onLayoutRectChanged, а для запросов внутри Modifier.Node – requireLayoutCoordinates().

Этап 3. Рисование

Эти модификаторы выполняются во время рисования холста. Состояние, считываемое внутри этих блоков, пропускает как композицию, так и макет, выполняя только проход рисования:

  • Modifier.graphicsLayer { ... }:
    • Свойства, обновленные в лямбда-функции: alpha, translationX, translationY, scaleX, scaleY, rotationX, rotationY, rotationZ, shadowElevation, shape, clip, renderEffect, transformOrigin.
  • Modifier.drawBehind { ... }:
    • Рисует команды холста за составным контентом.
  • Modifier.drawWithContent { ... }:
    • Управляет порядком отрисовки с помощью drawContent().
  • Modifier.drawWithCache { ... }:
    • Внешний блок выполняется при изменении размера или макета для кеширования объектов Path, Paint или Brush; onDrawBehind или onDrawWithContent выполняется при отрисовке каждого кадра.

Вне цикла рекомпозиции – модификаторы наблюдения

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

Семантика и специальные возможности

Обрабатывает семантические свойства для сервисов специальных возможностей (TalkBack) и тестирования:

  • Modifier.semantics { ... }
  • Modifier.clearAndSetSemantics { ... }

Ввод, жесты и события

Работает вне трехэтапного конвейера рендеринга кадров, получая события движения ОС и взаимодействия с пользователем:

  • Modifier.pointerInput(key) { detectTapGestures { ... } } / detectDragGestures / awaitPointerEventScope
  • Modifier.clickable(enabled, onClickLabel) { ... }
  • Modifier.combinedClickable { ... }
  • Modifier.toggleable { ... }
  • Modifier.selectable { ... }
  • Modifier.draggable(...) / Modifier.scrollable(...) / Modifier.draggable2D(...)
  • Modifier.onFocusChanged { focusState -> ... }
  • Modifier.onKeyEvent { keyEvent -> ... }
  • Modifier.onVisibilityChanged { isVisible -> ... } – обратный вызов, который активируется, когда видимость composable-функции меняется после заданной задержки в сопрограмме.

Краткий справочник: Фаза значения и фаза лямбда

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

Модификатор / шаблон Прямое значение (состав) Вариант Lambda (отложенный этап) При изменении состояния
Offset Modifier.offset(x, y) Modifier.offset { IntOffset(x, y) } Макет (размещение) (пропускает компоновку)
Альфа-канал / прозрачность Modifier.alpha(alpha) Modifier.graphicsLayer { this.alpha = alpha } Рисование (пропускает композицию и макет)
Ротация Modifier.rotate(degrees) Modifier.graphicsLayer { rotationZ = degrees } Рисование (пропускает композицию и макет)
Scale Modifier.scale(scale) Modifier.graphicsLayer { scaleX = s; scaleY = s } Рисование (пропускает композицию и макет)
Перевод Modifier.padding(...) Modifier.graphicsLayer { translationX = ... } Рисование (пропускает композицию и макет)
Цвет фона Modifier.background(color) Modifier.drawBehind { drawRect(color) } Рисование (пропускает композицию и макет)
Прокрутка / параллакс Modifier.offset(scroll.dp) Modifier.offset { IntOffset(0, scroll) } Макет (размещение) (пропускает компоновку)

Сопоставление интерфейса Modifier.Node

Для пользовательских модификаторов, использующих высокопроизводительный API Modifier.Node, фазы сопоставляются непосредственно с интерфейсами возможностей узлов:

Этап Интерфейс Modifier.Node Основные методы
Макет (измерение и размещение) LayoutModifierNode measure(measurable, constraints)
Макет (глобальные координаты) GlobalPositionAwareModifierNode (предпочтительно requireLayoutCoordinates() по запросу) onGloballyPositioned(coordinates)
Макет (место размещения) LayoutAwareModifierNode onRemeasured(size), onPlaced(coordinates)
Рисунок DrawModifierNode draw(ContentDrawScope)
Ввод и указатель PointerInputModifierNode onPointerEvent(...), onCancelPointerInput()
Семантика SemanticsModifierNode applySemantics(SemanticsPropertyReceiver)
Фокус FocusEventModifierNode onFocusEvent(focusState)