تنفّذ Jetpack Compose المُعدِّلات على مراحل مختلفة. يوضّح التقسيم التالي المرحلة التي تنتمي إليها المُعدِّلات الشائعة ومتى يتم تقييم وسيطاتها أو دوال lambda.
المرحلة 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)(direct value overload)Modifier.absoluteOffset(x = dp, y = dp)
- معدِّلات الدوال المركّبة الديناميكية:
Modifier.composed { ... }(يتم تشغيل نص المصنع أثناء الإنشاء، ولا يُنصح باستخدامه لتحسين الأداء، بل يُنصح باستخدامModifier.Nodeلتعديل العناصر المخصّصة بدلاً من ذلك)
المرحلة 2: مرحلة التخطيط
تنقسم مرحلة "التنسيق" إلى خطوتَين فرعيتَين مختلفتَين مع نطاقات إبطال منفصلة:
الخطوة 2 (أ): القياس
يحدّد الحجم (width، height) والقيود. تؤدي قراءة الحالة هنا إلى تفعيل إعادة القياس وإعادة تحديد الموضع:
-
Modifier.layout { measurable, constraints -> ... }: يتم تنفيذ الرمز البرمجي قبلlayout(w, h)أثناء القياس.
الخطوة 2 (ب): عمليات الاستدعاء الخاصة بالموضع والتنسيق
تحدّد موضع الإحداثي (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.
المرحلة 3: مرحلة الرسم
يتم تنفيذ هذه المُعدِّلات أثناء الرسم على اللوحة. تتخطى قراءة الحالة داخل هذه الوحدات كل من "الإنشاء" و"التنسيق"، ويتم تشغيل مرحلة الرسم فقط:
Modifier.graphicsLayer { ... }:- تم تعديل السمات في lambda:
alphaوtranslationXوtranslationYوscaleXوscaleYوrotationXوrotationYوrotationZوshadowElevationوshapeوclipوrenderEffectوtransformOrigin.
- تم تعديل السمات في lambda:
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 -> ... }: يتم استدعاء دالة الاستدعاء عند تغيُّر مستوى ظهور دالة مركّبة بعد مهلة تم ضبطها، في كوروتين.
مرجع سريع: مرحلة القيمة مقابل مرحلة Lambda
تؤدي قراءة قيمة حالة في دالة lambda إلى تأجيل القراءة إلى مرحلة لاحقة، ما يؤدي إلى تخطّي المراحل السابقة عند تغيُّر تلك الحالة:
| المعدِّل / النمط | القيمة المباشرة (المحتوى) | متحوّر 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 } |
الرسم (يتخطّى "التكوين" و"التصميم") |
| المقياس | 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() |
| Semantics | SemanticsModifierNode |
applySemantics(SemanticsPropertyReceiver) |
| التركيز | FocusEventModifierNode |
onFocusEvent(focusState) |