الرسومات في Compose

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

رسم أساسي مع مفاتيح التعديل وDrawScope

إنّ الطريقة الأساسية لرسم عنصر مخصّص في Compose هي باستخدام مفاتيح التعديل، مثل Modifier.drawWithContent وModifier.drawBehind وModifier.drawWithCache.

على سبيل المثال، لرسم عنصر خلف العنصر القابل للإنشاء، يمكنك استخدام أداة التعديل drawBehind لبدء تنفيذ أوامر الرسم:

Spacer(
    modifier = Modifier
        .fillMaxSize()
        .drawBehind {
            // this = DrawScope
        }
)
CanvasSnippets.kt

إذا كان كل ما تحتاجه هو عنصر قابل للإنشاء وجذاب، يمكنك استخدام Canvas القابل للإنشاء. عنصر Canvas القابل للإنشاء هو برنامج ربط مريح حول Modifier.drawBehind. يمكنك وضع Canvas في التنسيق بالطريقة نفسها التي تضعها مع أي عنصر آخر في واجهة Compose. وضمن Canvas، يمكنك رسم عناصر مع إمكانية التحكّم الدقيق في نمطها وموقعها.

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

تعرض جميع معدِّلات الرسم DrawScope، وهي بيئة رسم مُفصَّل تحافظ على حالتها الخاصة. يتيح لك هذا تعيين المعاملات لمجموعة من العناصر الرسومية. توفّر DrawScope عدة حقول مفيدة، مثل size، وهي عنصر Size يحدّد الأبعاد الحالية للسمة DrawScope.

لرسم شيء، يمكنك استخدام إحدى دوال الرسم العديدة في DrawScope. على سبيل المثال، ترسم التعليمة البرمجية التالية مستطيلاً في الزاوية العلوية اليسرى من الشاشة:

Canvas(modifier = Modifier.fillMaxSize()) {
    val canvasQuadrantSize = size / 2F
    drawRect(
        color = Color.Magenta,
        size = canvasQuadrantSize
    )
}
CanvasSnippets.kt

الشكل 1. مستطيل مرسوم باستخدام "لوحة الرسم" في Compose

لمعرفة المزيد من المعلومات حول معدِّلات الرسم المختلفة، يمكنك الاطّلاع على مستندات معدِّلات الرسومات.

نظام الإحداثيات

لرسم عنصر على الشاشة، عليك معرفة الإزاحة (x وy) وحجم العنصر. في العديد من طرق الرسم على DrawScope، يتم توفير الموضع والحجم من خلال قيم المعلَمات التلقائية. تضع المعلمات التلقائية بشكل عام العنصر عند النقطة [0, 0] على لوحة الرسم وتوفر علامة size تلقائية تملأ مساحة الرسم بأكملها، كما في المثال أعلاه. يظهر المستطيل في أعلى يسار الصفحة. لضبط حجم العنصر وموضعه، تحتاج إلى فهم نظام الإحداثيات في Compose.

يقع أصل نظام الإحداثيات ([0,0]) في أعلى وحدات البكسل في أقصى اليسار في منطقة الرسم. تزيد قيمة x كلما تحركت إلى اليمين وتزداد قيمة y كلما تحركت لأسفل.

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

الشكل 2. نظام إحداثيات الرسم / شبكة الرسم

على سبيل المثال، إذا أردت رسم خط قُطري من أعلى يسار مساحة لوحة الرسم إلى أسفل يسار الشاشة، يمكنك استخدام الدالة DrawScope.drawLine() وتحديد إزاحة البداية والنهاية باستخدام موضعَي x وy المقابلتَين:

Canvas(modifier = Modifier.fillMaxSize()) {
    val canvasWidth = size.width
    val canvasHeight = size.height
    drawLine(
        start = Offset(x = canvasWidth, y = 0f),
        end = Offset(x = 0f, y = canvasHeight),
        color = Color.Blue
    )
}
CanvasSnippets.kt

التحويلات الأساسية

تقدّم DrawScope عمليات تحويل لتغيير مكان أو كيفية تنفيذ أوامر الرسم.

ملاحظة: لا تنطبق هذه عمليات التحويل إلا في مرحلة الرسم من دورة حياة الإعلانات القابلة للتعديل، ولن تؤدي أي تغييرات في الحجم أو الموضع إلى تغيير حجم التنسيق وموضعه. وقد تظهر العناصر فوق عناصر أخرى إذا تم نقلها من حجم وموضعها.

المقياس

استخدِم DrawScope.scale() لزيادة حجم عمليات الرسم بمقدار عامل. تنطبق عمليات مثل scale() على جميع عمليات الرسم داخل دالة lambda المقابلة. على سبيل المثال، يزيد الرمز التالي من scaleX 10 مرات وscaleY 15 مرة:

Canvas(modifier = Modifier.fillMaxSize()) {
    scale(scaleX = 10f, scaleY = 15f) {
        drawCircle(Color.Blue, radius = 20.dp.toPx())
    }
}
CanvasSnippets.kt

الشكل 3. تطبيق عملية مقياس على دائرة على لوحة الرسم.

ترجمة

استخدِم رمز DrawScope.translate() لتحريك عمليات الرسم للأعلى أو للأسفل أو لليسار أو لليمين. على سبيل المثال، ينقل الرمز التالي الرسم 100 بكسل إلى اليمين و300 بكسل لأعلى:

Canvas(modifier = Modifier.fillMaxSize()) {
    translate(left = 100f, top = -300f) {
        drawCircle(Color.Blue, radius = 200.dp.toPx())
    }
}
CanvasSnippets.kt

الشكل 4. تطبيق عملية ترجمة على دائرة في لوحة الرسم.

تدوير

استخدِم DrawScope.rotate() لتدوير عمليات الرسم حول نقطة محورية. على سبيل المثال، تقوم التعليمة البرمجية التالية بتدوير مستطيل 45 درجة:

Canvas(modifier = Modifier.fillMaxSize()) {
    rotate(degrees = 45F) {
        drawRect(
            color = Color.Gray,
            topLeft = Offset(x = size.width / 3F, y = size.height / 3F),
            size = size / 3F
        )
    }
}
CanvasSnippets.kt

الشكل 5. نستخدم rotate() لتطبيق التدوير على نطاق الرسم الحالي، الذي يعمل على تدوير المستطيل بمقدار 45 درجة.

مساحة داخلية

يمكنك استخدام DrawScope.inset() لضبط المعلَمات التلقائية للمعلَمات الحالية DrawScope وتغيير حدود الرسم وترجمة الرسومات وفقًا لذلك:

Canvas(modifier = Modifier.fillMaxSize()) {
    val canvasQuadrantSize = size / 2F
    inset(horizontal = 50f, vertical = 30f) {
        drawRect(color = Color.Green, size = canvasQuadrantSize)
    }
}
CanvasSnippets.kt

تضيف هذه التعليمة البرمجية مساحة متروكة بشكل فعّال لأوامر الرسم:

الشكل 6. تطبيق مساحة داخلية على أوامر الرسم

عمليات تحويل متعددة

لتطبيق عمليات تحويل متعددة على رسوماتك، استخدِم الدالة DrawScope.withTransform() التي تنشئ وتطبّق عملية تحويل واحدة تجمع كل التغييرات المطلوبة. يُعد استخدام withTransform() أكثر فعالية من إجراء استدعاءات متداخلة لتحويلات فردية، لأنه يتم تنفيذ جميع التحويلات معًا في عملية واحدة، بدلًا من أن تحتاج ميزة Compose إلى حساب وحفظ كل تحويل من التحويلات المتداخلة.

على سبيل المثال، تطبق التعليمة البرمجية التالية كلاً من الترجمة والتدوير على المستطيل:

Canvas(modifier = Modifier.fillMaxSize()) {
    withTransform({
        translate(left = size.width / 5F)
        rotate(degrees = 45F)
    }) {
        drawRect(
            color = Color.Gray,
            topLeft = Offset(x = size.width / 3F, y = size.height / 3F),
            size = size / 3F
        )
    }
}
CanvasSnippets.kt

الشكل 7. استخدِم withTransform لتطبيق كل من التدوير والترجمة، وتدوير المستطيل وتحويله إلى اليسار.

عمليات الرسم الشائعة

رسم نص

لرسم نص في Compose، يمكنك عادةً استخدام عنصر Text القابل للإنشاء. مع ذلك، إذا كنت في DrawScope أو تريد رسم النص يدويًا باستخدام التخصيص، يمكنك استخدام الطريقة DrawScope.drawText().

لرسم نص، أنشئ TextMeasurer باستخدام rememberTextMeasurer واطلب drawText باستخدام أداة القياس:

val textMeasurer = rememberTextMeasurer()

Canvas(modifier = Modifier.fillMaxSize()) {
    drawText(textMeasurer, "Hello")
}
CanvasSnippets.kt

الشكل 8. رسم نص على "لوحة الرسم"

قياس النص

يعمل نص الرسم بشكل مختلف قليلاً عن أوامر الرسم الأخرى. عادةً، تعطي أمر الرسم الحجم (العرض والارتفاع) لرسم الشكل/الصورة به. تتوفّر في النص بعض المعلَمات التي تتحكّم في حجم النص المعروض، مثل حجم الخط والخط والأحرف المتصلة والمسافات بين الأحرف.

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

val textMeasurer = rememberTextMeasurer()

Spacer(
    modifier = Modifier
        .drawWithCache {
            val measuredText =
                textMeasurer.measure(
                    AnnotatedString(longTextSample),
                    constraints = Constraints.fixedWidth((size.width * 2f / 3f).toInt()),
                    style = TextStyle(fontSize = 18.sp)
                )

            onDrawBehind {
                drawRect(pinkColor, size = measuredText.size.toSize())
                drawText(measuredText)
            }
        }
        .fillMaxSize()
)
CanvasSnippets.kt

ملاحظة: يستخدم المثال أعلاه العلامة Modifier.drawWithCache لأنّ رسم النص عملية مكلفة. يساعد استخدام drawWithCache في ذاكرة التخزين المؤقت للكائنات التي تم إنشاؤها إلى أن يتغيّر حجم منطقة الرسم. لمزيد من المعلومات، راجِع مستندات Modifier.drawWithCache.

ينتج مقتطف الرمز هذا خلفية وردية على النص:

الشكل 9. نص متعدد الأسطر يشغل حجم 2⁄3 من المساحة الكاملة، مع مستطيل للخلفية.

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

val textMeasurer = rememberTextMeasurer()

Spacer(
    modifier = Modifier
        .drawWithCache {
            val measuredText =
                textMeasurer.measure(
                    AnnotatedString(longTextSample),
                    constraints = Constraints.fixed(
                        width = (size.width / 3f).toInt(),
                        height = (size.height / 3f).toInt()
                    ),
                    overflow = TextOverflow.Ellipsis,
                    style = TextStyle(fontSize = 18.sp)
                )

            onDrawBehind {
                drawRect(pinkColor, size = measuredText.size.toSize())
                drawText(measuredText)
            }
        }
        .fillMaxSize()
)
CanvasSnippets.kt

يتم الآن رسم النص ضمن القيود مع علامة حذف في النهاية:

الشكل 10. TextOverflow.Ellipsis مع قيود ثابتة على قياس النص.

ملاحظة: لمزيد من المعلومات حول النص، يمكنك الاطّلاع على مستندات النص.

رسم صورة

لرسم ImageBitmap باستخدام DrawScope، يمكنك تحميل الصورة باستخدام ImageBitmap.imageResource() ثم الاتصال بـ drawImage:

val dogImage = ImageBitmap.imageResource(id = R.drawable.dog)

Canvas(modifier = Modifier.fillMaxSize(), onDraw = {
    drawImage(dogImage)
})
CanvasSnippets.kt

الشكل 11. رسم "ImageBitmap" على لوحة رسم

ملاحظة: يمكنك الاطّلاع على مستندات تخصيص الصور للحصول على مزيد من المعلومات عن طريقة تطبيق الفلاتر على صورك.

رسم أشكال أساسية

هناك العديد من دوال رسم الأشكال في DrawScope. لرسم شكل، استخدم إحدى دوال الرسم المحددة مسبقًا، مثل drawCircle:

val purpleColor = Color(0xFFBA68C8)
Canvas(
    modifier = Modifier
        .fillMaxSize()
        .padding(16.dp),
    onDraw = {
        drawCircle(purpleColor)
    }
)
CanvasSnippets.kt

واجهة برمجة التطبيقات	ناتج
drawCircle()
drawRect()
drawRoundedRect()
drawLine()
drawOval()
drawArc()
drawPoints()

رسم مسار

المسار هو سلسلة من التعليمات الرياضية التي تؤدي إلى رسم بمجرد تنفيذه. يمكن لـ DrawScope رسم مسار باستخدام الطريقة DrawScope.drawPath().

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

Spacer(
    modifier = Modifier
        .drawWithCache {
            val path = Path()
            path.moveTo(0f, 0f)
            path.lineTo(size.width / 2f, size.height / 2f)
            path.lineTo(size.width, 0f)
            path.close()
            onDrawBehind {
                drawPath(path, Color.Magenta, style = Stroke(width = 10f))
            }
        }
        .fillMaxSize()
)
CanvasSnippets.kt

الشكل 12. إنشاء Path ورسمه في Compose

جارٍ الوصول إلى عنصر واحد (Canvas)

من خلال DrawScope، ليس لديك إمكانية الوصول المباشر إلى عنصر Canvas. يمكنك استخدام DrawScope.drawIntoCanvas() للوصول إلى كائن Canvas نفسه الذي يمكنك استدعاء الدوال عليه.

على سبيل المثال، إذا كان لديك عنصر Drawable مخصّص تريد رسمه على اللوحة، يمكنك الوصول إلى اللوحة واستدعاء Drawable#draw()، مع تمرير الكائن Canvas:

val drawable = ShapeDrawable(OvalShape())
Spacer(
    modifier = Modifier
        .drawWithContent {
            drawIntoCanvas { canvas ->
                drawable.setBounds(0, 0, size.width.toInt(), size.height.toInt())
                drawable.draw(canvas.nativeCanvas)
            }
        }
        .fillMaxSize()
)
CanvasSnippets.kt

الشكل 13. جارٍ الوصول إلى لوحة الرسم لرسم Drawable.

مزيد من المعلومات

لمزيد من المعلومات حول "الرسم في Compose"، ألق نظرة على الموارد التالية:

• معدِّلات الرسومات - يمكنك التعرّف على الأنواع المختلفة لتعديلات الرسم.
• الفرشاة - تعرَّف على طريقة تخصيص رسمة المحتوى.
• التنسيقات والرسومات المخصَّصة في Compose - Android Dev Summit لعام 2022 - تعرَّف على كيفية إنشاء واجهة مستخدم مخصَّصة في Compose باستخدام التنسيقات والرسومات.
• نموذج JetLagged - إنشاء نموذج يوضح كيفية رسم رسم بياني مخصص.