تفکیک اصلاح‌کننده‌ها بر اساس فاز

Jetpack Compose اصلاح‌کننده‌ها را در فازهای مجزا اجرا می‌کند. جزئیات زیر نشان می‌دهد که اصلاح‌کننده‌های رایج به کدام فاز تعلق دارند و چه زمانی آرگومان‌ها یا لامبداهای آنها ارزیابی می‌شوند.

مرحله ۱: مرحله ترکیب

این اصلاح‌کننده‌ها آرگومان‌ها را به صورت همزمان درون بدنه @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)
  • اصلاح‌کننده‌های پویای قابل ترکیب :
    • Modifier.composed { ... } (در طول ترکیب، بدنه‌ی factory را اجرا می‌کند)

مرحله ۲: مرحله طرح‌بندی

مرحله طرح‌بندی به دو زیرمرحله مجزا با حوزه‌های ابطال جداگانه تقسیم می‌شود:

مرحله 2A: اندازه‌گیری

اندازه ( width ، height ) و محدودیت‌ها را تعیین می‌کند. حالت خوانده شده در اینجا باعث اندازه‌گیری مجدد و جایگزینی مجدد می‌شود:

  • Modifier.layout { measurable, constraints -> ... } : کدی که قبل از layout(w, h) در حین اندازه‌گیری اجرا می‌شود.

مرحله ۲ب: فراخوانی‌های جایگذاری و طرح‌بندی

موقعیت مختصات (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.onPlaced { layoutCoordinates -> ... } : پس از تعیین مختصات والد در حین جایگذاری، فراخوانی می‌شود.
  • Modifier.onSizeChanged { intSize -> ... } : در صورت تغییر اندازه، پس از تکمیل اندازه‌گیری طرح‌بندی فراخوانی می‌شود.
  • Modifier.onGloballyPositioned { layoutCoordinates -> ... } : پس از اتمام کل مرحله‌ی چیدمان پنجره، فراخوانی می‌شود.

مرحله ۳: مرحله طراحی

این اصلاح‌کننده‌ها در طول طراحی بوم اجرا می‌شوند. حالت خوانده شده در داخل این بلوک‌ها ، از هر دو بخش ترکیب‌بندی و طرح‌بندی صرف نظر می‌کند و فقط مرحله‌ی طراحی را اجرا می‌کند:

  • Modifier.graphicsLayer { ... } :
    • ویژگی‌های به‌روزرسانی‌شده در لامبدا: alpha ، translationX ، translationY ، scaleX ، scaleY ، rotationX ، rotationY ، rotationZ ، shadowElevation ، shape ، clip ، renderEffect ، transformOrigin .
  • Modifier.drawBehind { ... } :
    • دستورات بوم را پشت محتوای قابل ترکیب ترسیم می‌کند.
  • Modifier.drawWithContent { ... } :
    • ترتیب ترسیم را با drawContent() کنترل می‌کند.
  • Modifier.drawWithCache { ... } :
    • بلوک بیرونی (Outer block) با تغییر اندازه یا طرح‌بندی در حافظه پنهان (cache) اشیاء 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 پس از تأخیر پیکربندی شده، در یک کوروتین تغییر کند.

مرجع سریع: مقدار در مقابل فاز لامبدا

خواندن مقدار حالت در یک لامبدا، خواندن را به مرحله‌ی بعدی موکول می‌کند، که با تغییر آن حالت، مراحل قبلی را نادیده می‌گیرد :

اصلاح‌کننده / الگو ارزش مستقیم (ترکیب) نوع لامبدا (فاز معوق) وقتی ایالت تغییر می‌کند
افست 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

برای اصلاح‌کننده‌های سفارشی که از رابط برنامه‌نویسی کاربردی (API) با کارایی بالای Modifier.Node استفاده می‌کنند، فازها مستقیماً به رابط‌های قابلیت گره نگاشت می‌شوند:

فاز رابط گره Modifier.Node روش‌های اصلی
طرح‌بندی (اندازه‌گیری و مکان‌یابی) LayoutModifierNode measure(measurable, constraints)
طرح‌بندی (مختصات جهانی) GlobalPositionAwareModifierNode onGloballyPositioned(coordinates)
چیدمان (جایگذاری) LayoutAwareModifierNode onRemeasured(size) , onPlaced(coordinates)
طراحی DrawModifierNode draw(ContentDrawScope)
ورودی / اشاره‌گر PointerInputModifierNode onPointerEvent(...) ، onCancelPointerInput()
معناشناسی SemanticsModifierNode applySemantics(SemanticsPropertyReceiver)
تمرکز FocusEventModifierNode onFocusEvent(focusState)