القيود وترتيب مفاتيح التعديل

في Compose، يمكنك ربط معدِّلات متعدّدة معًا لتغيير شكل العنصر القابل للإنشاء ومظهره. يمكن أن تؤثر سلاسل المعدِّلات هذه في القيود التي يتم تمريرها إلى العناصر القابلة للإنشاء، والتي تحدّد حدود العرض والارتفاع.

توضّح هذه الصفحة كيف تؤثّر المعدِّلات المتسلسلة في القيود، وبالتالي في قياس العناصر القابلة للإنشاء وتحديد موضعها.

مفاتيح التعديل في شجرة واجهة المستخدم

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

في شجرة واجهة المستخدم، يمكنك تصوُّر المعدِّلات كعُقد تغليف لعُقد التصميم:

الشكل 1. المعدِّلات التي تغلف عقد التنسيق في شجرة واجهة المستخدم

تؤدي إضافة أكثر من معدِّل واحد إلى عنصر قابل للإنشاء إلى إنشاء سلسلة من المعدِّلات. عند ربط معدّلات متعددة، يغلّف كل عقدة معدّل بقية السلسلة وعقدة التنسيق في الداخل. على سبيل المثال، عند ربط معدِّل clip بمعدِّل size، يغلّف عقدة المعدِّل clip عقدة المعدِّل size، التي بدورها تغلف عقدة التنسيق Image.

في مرحلة التنسيق، تبقى الخوارزمية التي تتنقّل في الشجرة كما هي، ولكن يتم أيضًا الانتقال إلى كل عقدة معدِّل. بهذه الطريقة، يمكن للمعدِّل تغيير متطلبات الحجم وموضع المعدِّل أو عقدة التنسيق التي يغلّفها.

كما هو موضّح في "الشكل 2"، يتألف تنفيذ العنصرين القابلين للإنشاء Image وText من سلسلة من المعدِّلات التي تتضمّن عقدة تخطيط واحدة.

إنّ عمليات تنفيذ Row وColumn هي عقد تخطيط تصف كيفية ترتيب العناصر التابعة لها.

الشكل 2. بنية الشجرة نفسها كما في الشكل 1، ولكن مع عرض العناصر القابلة للإنشاء في شجرة واجهة المستخدم على شكل سلاسل من المعدِّلات.

باختصار:

• تتضمّن المعدِّلات معدِّلاً واحدًا أو عقدة تخطيط واحدة.
• يمكن لعُقد التنسيق ترتيب عُقد ثانوية متعددة.

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

القيود في مرحلة التخطيط

تتّبع مرحلة التنسيق خوارزمية من ثلاث خطوات للعثور على عرض وارتفاع وإحداثيات x وy لكل عقدة تنسيق:

1. قياس العناصر التابعة: تقيس العقدة العناصر التابعة لها، إن وُجدت.
2. تحديد الحجم: استنادًا إلى هذه القياسات، تحدّد العقدة حجمها.
3. وضع العناصر التابعة: يتم وضع كل عنصر تابع بالنسبة إلى موضع العنصر الرئيسي.

Constraints تساعد في العثور على الأحجام المناسبة للعُقد خلال الخطوتَين الأوليَين من الخوارزمية. تحدّد القيود الحدود الدنيا والقصوى لعرض وارتفاع عقدة. عندما تحدّد العقدة حجمها، يجب أن يندرج حجمها المقاس ضمن نطاق الحجم هذا.

أنواع القيود

يمكن أن يكون القيد أحد ما يلي:

• محدود: يحتوي العقدة على حدّ أقصى وأدنى للعرض والارتفاع.

الشكل 3. القيود المحدودة:

• غير محدود: لا يتقيّد العنصر بأي حجم. تم ضبط الحدّ الأقصى للعرض والارتفاع على قيمة لا نهائية.

الشكل 4. القيود غير المحدودة

• المطابقة التامة: يُطلب من العقدة اتّباع متطلبات الحجم المحدّد. يتم ضبط الحد الأدنى والأقصى على القيمة نفسها.

الشكل 5. القيود الدقيقة

• مُجمَّعة: تتبع العقدة مجموعة من أنواع القيود السابقة. على سبيل المثال، يمكن أن يحدّ قيد من العرض مع السماح بأقصى ارتفاع غير محدود، أو يمكن أن يضبط عرضًا دقيقًا مع توفير ارتفاع محدود.

الشكل 6. مجموعات من القيود المحدودة وغير المحدودة والعرض والارتفاع الدقيقَين

يوضّح القسم التالي كيفية نقل هذه القيود من عنصر رئيسي إلى عنصر فرعي.

كيفية نقل القيود من العنصر الرئيسي إلى العنصر الثانوي

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

عندما تقيس عقدة أصلية حجم العُقد التابعة لها، فإنّها توفّر هذه القيود لكل عقدة تابعة لإعلامها بالحجم المسموح لها به. بعد ذلك، عندما يقرّر حجمه، يلتزم أيضًا بالقيود التي تم تمريرها من خلال العناصر الرئيسية.

بشكل عام، تعمل الخوارزمية بالطريقة التالية:

1. لتحديد الحجم الذي تريد أن تشغله فعليًا، تقيس العقدة الجذرية في شجرة واجهة المستخدم العناصر التابعة لها وتُعيد توجيه القيود نفسها إلى العنصر التابع الأول.
2. إذا كان العنصر التابع معدِّلاً لا يؤثّر في القياس، يعيد توجيه القيود إلى المعدِّل التالي. يتم تمرير القيود إلى سلسلة المعدِّلات كما هي ما لم يتم الوصول إلى معدِّل يؤثر في القياس. بعد ذلك، يتم تغيير حجم القيود وفقًا لذلك.
3. عند الوصول إلى عقدة ليس لديها أي عقد فرعية (يُشار إليها باسم "عقدة ورقة")، يتم تحديد حجمها استنادًا إلى القيود التي تم تمريرها، ويتم إرجاع هذا الحجم الذي تم تحديده إلى العقدة الرئيسية.
4. يعدّل العنصر الأصلي قيوده استنادًا إلى قياسات هذا العنصر التابع، ويستدعي العنصر التابع التالي مع هذه القيود المعدَّلة.
5. بعد قياس حجم جميع العناصر الفرعية للعنصر الأصلي، يحدّد العنصر الأصلي حجمه ويُبلغ العنصر الأصلي الخاص به بهذا الحجم.
6. بهذه الطريقة، يتم اجتياز الشجرة بأكملها أولاً بأول. في النهاية، تحدّد جميع العُقد أحجامها، وتكتمل خطوة القياس.

للاطّلاع على مثال مفصّل، شاهِد الفيديو ترتيب القيود والمعدّلات.

المعدِّلات التي تؤثر في القيود

لقد تعرّفت في القسم السابق على أنّ بعض المعدِّلات يمكن أن تؤثر في حجم القيود. توضّح الأقسام التالية معدِّلات معيّنة تؤثّر في القيود.

المعدِّل size

يحدّد المعدِّل size الحجم المفضّل للمحتوى.

على سبيل المثال، يجب عرض شجرة واجهة المستخدم التالية في حاوية بحجم 300dp في 200dp. القيود محدودة، ما يسمح بعرض يتراوح بين 100dp و300dp، وارتفاع يتراوح بين 100dp و200dp:

الشكل 7. القيود المحدودة في شجرة واجهة المستخدم وتمثيلها في حاوية

يعدّل المعدِّل size القيود الواردة لتتطابق مع القيمة التي تم تمريرها إليه. في هذا المثال، تكون القيمة 150dp:

الشكل 8. المعدِّل size الذي يضبط القيود على 150dp

إذا كان العرض والارتفاع أصغر من الحد الأدنى لمدى القيود أو أكبر من الحد الأقصى لمدى القيود، يتطابق المعدِّل مع القيود التي تم تمريرها بأكبر قدر ممكن مع الالتزام بالقيود التي تم تمريرها في:

الشكل 9. معدِّل size الذي يلتزم بالقيود التي تم تمريرها بأكبر قدر ممكن من الدقة

يُرجى العِلم أنّ ربط معدِّلات size متعدّدة معًا لا يعمل. يضبط المعدِّل الأول size كلاً من الحد الأدنى والأقصى على قيمة ثابتة. حتى إذا طلبت أداة تعديل الحجم الثانية حجمًا أصغر أو أكبر، يجب أن تلتزم بالحدود الدقيقة التي تم تمريرها، وبالتالي لن تتجاوز هذه القيم:

الشكل 10. سلسلة من معدِّلَين size، حيث لا تلغي القيمة الثانية التي تم تمريرها في (50dp) القيمة الأولى (100dp).

المعدِّل requiredSize

استخدِم المعدِّل requiredSize بدلاً من size إذا كنت بحاجة إلى أن يتجاوز العنصر القيود الواردة. يحلّ المعدِّل requiredSize محل القيود الواردة ويُمرّر الحجم الذي تحدّده كحدود دقيقة.

عندما يتم تمرير الحجم مرة أخرى إلى أعلى العرض التدرّجي، سيتم توسيط العقدة الفرعية في المساحة المتاحة:

الشكل 11. المعدِّل requiredSize الذي يتجاوز القيود الواردة من المعدِّل size

المعدّلان width وheight

يعدّل المعدِّل size كلاً من عرض القيود وارتفاعها. باستخدام المعدِّل width، يمكنك ضبط عرض ثابت ولكن ترك الارتفاع بدون تحديد. وبالمثل، باستخدام المعدِّل height، يمكنك ضبط ارتفاع ثابت، ولكن ترك العرض بدون تحديد:

الشكل 12. المعدِّل width والمعدِّل height اللذان يحدّدان عرضًا وارتفاعًا ثابتَين على التوالي

المعدِّل sizeIn

تتيح لك أداة التعديل sizeIn ضبط قيود الحدّ الأدنى والأقصى الدقيقة للعرض والارتفاع. استخدِم المعدِّل sizeIn إذا كنت بحاجة إلى تحكّم دقيق في القيود.

الشكل 13. المعدِّل sizeIn مع القيم minWidth وmaxWidth وminHeight وmaxHeight.

أمثلة

يعرض هذا القسم ويشرح الناتج من عدة مقتطفات رمز تتضمّن معدّلات مرتبطة.

Image(
    painterResource(R.drawable.hero),
    contentDescription = null,
    Modifier
        .fillMaxSize()
        .size(50.dp)
)
ConstraintsModifiersSnippets.kt

ينتج عن مقتطف الرمز البرمجي التالي المخرجات التالية:

الشكل 14. يملأ Image الحد الأقصى للحجم نتيجةً لسلسلة المعدِّلات.

• تغيّر أداة التعديل fillMaxSize القيود لضبط الحد الأدنى لكل من العرض والارتفاع على القيمة القصوى، أي 300dp في العرض و200dp في الارتفاع.
• على الرغم من أنّ المعدِّل size يريد استخدام حجم 50dp، إلا أنّه لا يزال بحاجة إلى الالتزام بالحد الأدنى من القيود الواردة. وبالتالي، سيؤدي المعدِّل size أيضًا إلى عرض حدود القيود الدقيقة الخاصة بـ 300 حسب 200، ما يؤدي فعليًا إلى تجاهل القيمة المقدَّمة في المعدِّل size.
• تتّبع السمة Image هذه الحدود وتُبلغ عن حجم 300 في 200، ويتم تمرير هذا الحجم إلى أعلى الشجرة.

Image(
    painterResource(R.drawable.hero),
    contentDescription = null,
    Modifier
        .fillMaxSize()
        .wrapContentSize()
        .size(50.dp)
)
ConstraintsModifiersSnippets.kt

ينتج عن مقتطف الرمز البرمجي التالي المخرجات التالية:

الشكل 15. يتم توسيط Image وتحديد حجمه على النحو التالي: 50dp.

• تعدّل أداة التعديل fillMaxSize القيود لضبط الحد الأدنى لكل من العرض والارتفاع على القيمة القصوى، أي 300dp في العرض و200dp في الارتفاع.
• تعيد أداة التعديل wrapContentSize ضبط الحد الأدنى للقيود. وبالتالي، بينما أدّت fillMaxSize إلى قيود ثابتة، فإنّ wrapContentSize تعيد ضبطها إلى قيود محدودة. يمكن للعقدة التالية الآن أن تشغل المساحة بأكملها مجددًا، أو أن تكون أصغر من المساحة بأكملها.
• تضبط أداة التعديل size القيود على الحدّ الأدنى والأقصى للنطاق 50.
• يتم تحديد حجم Image على أنّه 50 × 50، ويتم توجيه ذلك من خلال المعدِّل size.
• يحتوي المعدِّل wrapContentSize على سمة خاصة. تأخذ هذه الطريقة العنصر الفرعي وتضعه في منتصف الحدود الدنيا المتاحة التي تم تمريرها إليها. وبالتالي، يكون الحجم الذي يتم إرساله إلى العناصر الرئيسية مساويًا للحدود الدنيا التي تم تمريرها إليه.

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

Image(
    painterResource(R.drawable.hero),
    contentDescription = null,
    Modifier
        .clip(CircleShape)
        .padding(10.dp)
        .size(100.dp)
)
ConstraintsModifiersSnippets.kt

ينتج عن مقتطف الرمز البرمجي التالي المخرجات التالية:

الشكل 16. شكل تم اقتصاصه بشكل غير صحيح بسبب ترتيب المعدِّل.

• لا يغيّر المعدِّل clip القيود.
• يؤدي المعدِّل padding إلى خفض الحدّ الأقصى للقيود.
• يضبط المعدِّل size جميع القيود على 100dp.
• تلتزم Image بهذه القيود وتُبلغ عن حجم 100dp × 100dp.
• تضيف أداة التعديل padding قيمة 10dp على جميع الجوانب إلى الحجم الذي تعرضه Image، لذا يعرض التصميم الذي يتضمّن مساحة متروكة عرضًا وارتفاعًا بقيمة 120dp.
• أما الآن، ففي مرحلة الرسم، يعمل مفتاح التعديل clip على لوحة رسم بحجم 120dp × 120dp. سيتم إنشاء قناع دائري بهذا الحجم.
• يُدرج المعدِّل padding المحتوى الخاص به بمقدار 10dp من جميع الجوانب، ما يؤدي إلى تقليل حجم لوحة العرض الخاصة بـ Image إلى 100dp بمقدار 100dp.
• يتم رسم Image في لوحة العرض الأصغر هذه. يتم قص الصورة استنادًا إلى الدائرة الأصلية الخاصة بـ 120dp، وبالتالي تكون النتيجة غير دائرية.