フェーズ別の修飾子の内訳

Jetpack Compose は、複数のフェーズで修飾子を実行します。次の内訳は、一般的な修飾子がどのフェーズに属しているか、また、その引数またはラムダがいつ評価されるかを示しています。

フェーズ 1: コンポジション フェーズ

これらの修飾子は、@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)
  • 動的コンポーザブル修飾子:
    • Modifier.composed { ... } (コンポジション中にファクトリ本体を実行します。パフォーマンスの観点から推奨されません。代わりにカスタム修飾子に Modifier.Node を使用してください)

フェーズ 2: レイアウト フェーズ

レイアウト フェーズは、無効化のスコープが異なる 2 つのサブステップに分かれています。

ステップ 2A: 測定

サイズ(width、height)と制約を決定します。ここで状態を読み取ると、再測定と再配置がトリガーされます。

  • Modifier.layout { measurable, constraints -> ... }: layout(w, h) の前のコードは、測定中に実行されます。

ステップ 2B: プレースメントとレイアウトのコールバック

(x, y) 座標位置を決定します。配置ブロック内で状態を読み取ると、再配置のみがトリガーされます(測定とコンポジションはスキップされます)。

  • Modifier.offset { IntOffset(x, y) }(ラムダ オーバーロード)
  • Modifier.absoluteOffset { IntOffset(x, y) }(ラムダ オーバーロード)
  • Modifier.layout { ... layout(w, h) { placeable.place(x, y) } }: layout(w, h) { ... } ブロック内のコード。

レイアウト監視コールバックは、レイアウトパス中またはレイアウトパス後に実行されます(これらのコールバック内で Composition で読み取られる状態に書き込むと、後方書き込みが発生するため、避けてください)。

  • Modifier.onSizeChanged { intSize -> ... }: ノードのサイズが変更された場合に、レイアウト測定の完了後に呼び出されます。
  • Modifier.onPlaced { layoutCoordinates -> ... } と Modifier.onLayoutRectChanged { ... }: 配置後に呼び出され、グローバル ウィンドウ レイアウト パスにサブスクライブせずにローカル座標または境界を報告します。
  • Modifier.onGloballyPositioned { layoutCoordinates -> ... }: ノードが移動するたびに、ウィンドウ レイアウト パス全体が完了した後に呼び出されます。可能な限り onGloballyPositioned を避け、ビューポート トラッキングには Modifier.onVisibilityChanged、ローカル境界には Modifier.onPlaced または Modifier.onLayoutRectChanged、Modifier.Node 内のオンデマンドには requireLayoutCoordinates() を使用します。

フェーズ 3: 抽選フェーズ

これらの修飾子は、キャンバスの描画中に実行されます。これらのブロック内で読み取られた状態は、Composition とレイアウトの両方をスキップし、描画パスのみを実行します。

  • 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 は、各フレームの描画時に実行されます。

再コンポーズ ループの外 - 監視修飾子

一部の修飾子は、3 つのフレーム フェーズの外で動作し、ユーザー補助、ユーザー入力、ライフサイクルの監視を処理します。

セマンティクスとユーザー補助

ユーザー補助サービス(TalkBack)とテストのセマンティクス プロパティを処理します。

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

入力、ジェスチャー、イベント

3 フェーズのフレーム レンダリング パイプラインの外部で動作し、OS のモーション イベントとユーザー インタラクションを受け取ります。

  • 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 -> ... }: コルーチンで、設定された遅延後にコンポーザブルの公開設定が変更されると、コールバックが呼び出されます。

クイック リファレンス: 値とラムダフェーズ

ラムダで状態値を読み取ると、読み取りが後のフェーズに延期され、その状態が変化したときに前のフェーズがスキップされます。

修飾子 / パターン 直接値(構成) ラムダ バリアント(遅延フェーズ) 状態が変化したとき
オフセット Modifier.offset(x, y) Modifier.offset { IntOffset(x, y) } レイアウト(プレースメント)(コンポジションをスキップ)
アルファ / 不透明度 Modifier.alpha(alpha) Modifier.graphicsLayer { this.alpha = alpha } 描画(コンポジションとレイアウトをスキップ)
回転 Modifier.rotate(degrees) Modifier.graphicsLayer { rotationZ = degrees } 描画(コンポジションとレイアウトをスキップ)
スケーリング 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 インターフェースのマッピング

高パフォーマンスの Modifier.Node API を使用するカスタム修飾子の場合、フェーズはノード機能インターフェースに直接マッピングされます。

フェーズ 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)