تفکیک توصیف‌گر براساس فاز

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

فاز ۱: فاز ترکیب‌بندی

این اصلاح‌کننده‌ها آرگومان‌ها را به‌طور هم‌زمان در @Composable body ارزیابی می‌کنند. هر وضعیتی که در اینجا خوانده می‌شود، وابستگی‌ای را با محدوده بازراه‌اندازی 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) (reads state during composition)
    • ‫Modifier.rotate(degrees) (reads state during composition)
    • ‫Modifier.scale(scaleX, scaleY) (reads state during composition)
    • 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) (direct value overload)
    • Modifier.absoluteOffset(x = dp, y = dp)
  • اصلاح‌کننده‌های ترکیب‌پذیر پویا:
    • ‫Modifier.composed { ... } (بدنه کارخانه را درطول ترکیب‌بندی اجرا می‌کند؛ برای عملکرد توصیه نمی‌شود—به‌جای آن از Modifier.Node برای اصلاح‌کننده‌های سفارشی استفاده کنید)

فاز ۲: فاز چیدمان

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

مرحله ۲الف: اندازه‌گیری

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

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

مرحله ۲ب: بازخوانی‌های جای آگهی و چیدمان

موقعیت مختصات (x, y) را تعیین می‌کند. خواندن وضعیت در بلوک‌های جای‌گذاری فقط جای‌گذاری مجدد را راه‌اندازی می‌کند (با رد شدن از اندازه‌گیری و ترکیب‌بندی):

  • Modifier.offset { IntOffset(x, y) } (lambda overload)
  • Modifier.absoluteOffset { IntOffset(x, y) } (lambda overload)
  • ‫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 را برای مرزهای محلی، یا requireLayoutCoordinates() را درصورت نیاز در Modifier.Node ترجیح دهید.

مرحله ۳: مرحله قرعه‌کشی

این اصلاح‌کننده‌ها درطول طراحی بوم اجرا می‌شوند. خواندن وضعیت در داخل این بلوک‌ها هم ترکیب‌بندی و هم چیدمان را رد می‌کند و فقط گذر ترسیم را اجرا می‌کند:

  • ‫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 پس‌از تأخیر پیکربندی‌شده تغییر می‌کند، فراخوانی برگشتی در یک coroutine فراخوانده می‌شود.

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

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

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

فاز میانای 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)