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/awaitPointerEventScopeModifier.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) |