تفاصيل مفتاح التعديل حسب المرحلة

تنفِّذ 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) (تجاوز القيمة المباشرة)
  • Modifier.absoluteOffset(x = dp, y = dp)
• المعدّلات الديناميكية القابلة للإنشاء:
  • Modifier.composed { ... } (يتم تنفيذ نص الدالة البرمجية أثناء الإنشاء)

المرحلة 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.onPlaced { layoutCoordinates -> ... }: يتم استدعاؤه بعد تحديد إحداثيات العنصر الرئيسي أثناء عملية تحديد الموضع.
• ‫Modifier.onSizeChanged { intSize -> ... }: يتم استدعاء هذه الطريقة بعد اكتمال قياس التنسيق في حال تغيّر الحجم.
• Modifier.onGloballyPositioned { layoutCoordinates -> ... }: يتم استدعاء هذه الطريقة بعد انتهاء عملية تحديد تخطيط النافذة بالكامل.

المرحلة 3: مرحلة الرسم

يتم تنفيذ هذه المعدّلات أثناء الرسم على لوحة العرض. يؤدي قراءة الحالة داخل هذه الرموز البرمجية إلى تخطّي كل من الإنشاء والتصميم، وتنفيذ عملية الرسم فقط:

• Modifier.graphicsLayer { ... }:
  • السمات التي تم تعديلها في دالة lambda: 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 -> ... }: يتم استدعاء دالة معاودة الاتصال عندما يتغير نطاق ظهور العلامة التجارية لعنصر دالة مركّبة بعد التأخير الذي تم ضبطه، وذلك في كوروتين.

---

مرجع سريع: مرحلة القيمة مقابل مرحلة Lambda

تؤدي قراءة قيمة حالة في دالة 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	onGloballyPositioned(coordinates)
التصميم (موضع الإعلان)	LayoutAwareModifierNode	onRemeasured(size)، onPlaced(coordinates)
الرسم	DrawModifierNode	draw(ContentDrawScope)
الإدخال / المؤشر	PointerInputModifierNode	onPointerEvent(...)، onCancelPointerInput()
معاني	SemanticsModifierNode	applySemantics(SemanticsPropertyReceiver)
التركيز	FocusEventModifierNode	onFocusEvent(focusState)