إدخال قلم الشاشة في الحقول النصية

تجربة طريقة Compose
‫Jetpack Compose هي مجموعة أدوات واجهة المستخدم المقترَحة لنظام Android. تعرَّف على كيفية استخدام قلم الشاشة في Compose.
إدخال قلم الشاشة في حقول النص ←

يتيح الإصدار Android 14 (مستوى واجهة برمجة التطبيقات 34) والإصدارات الأحدث للمستخدمين الكتابة في أي حقل لإدخال النص في أي تطبيق باستخدام قلم شاشة. تتيح حقول إدخال النص في Android، بما في ذلك EditText مكوّنات و WebView عناصر نصية، إدخال قلم الشاشة تلقائيًا.

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

الشكل 1 إدخال مكتوب بخط اليد باستخدام قلم شاشة

EditText

تكون الكتابة اليدوية باستخدام قلم الشاشة مفعّلة لجميع حقول EditText تلقائيًا على الإصدار Android 14 والإصدارات الأحدث. يبدأ وضع الكتابة اليدوية لحقل EditText عند رصد حدث حركة قلم شاشة ضمن حدود الكتابة اليدوية للعرض.

تتضمّن حدود الكتابة اليدوية 40 وحدة dp من المساحة المتروكة العمودية و10 وحدات dp من المساحة المتروكة الأفقية حول العرض. يمكنك تعديل حدود الكتابة اليدوية باستخدام setHandwritingBoundsOffsets(). يمكنك إيقاف الكتابة اليدوية باستخدام setAutoHandwritingEnabled(false).

حقل إدخال مع مستطيل محيط يشير إلى حدود رصد أحداث حركة القلم
الشكل 2 حدود الكتابة اليدوية لحقول EditText

تفويض الإدخال

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

الشكل 3 تفويض الإدخال من عنصر في واجهة المستخدم ثابت إلى حقل إدخال النص

تفويض إدخال قلم الشاشة

استخدِم واجهات برمجة التطبيقات لتفويض الكتابة اليدوية من أجل إتاحة إدخال الكتابة اليدوية باستخدام قلم الشاشة لحقول الإدخال النائبة (راجِع setHandwritingDelegatorCallback() و setIsHandwritingDelegate()). تم ضبط عنصر واجهة المستخدم النائب لتفويض الكتابة اليدوية إلى حقل إدخال وظيفي، على سبيل المثال:

Kotlin

if (Build.VERSION.SDK_INT >= 34) {
    placeholderInputField.setHandwritingDelegatorCallback {
        showAndFocusDelegateInputField()
    }
    delegateInputField.setIsHandwritingDelegate(true)
}

Java

if (Build.VERSION.SDK_INT >= 34) {
    placeholderInputField.setHandwritingDelegatorCallback(this::showAndFocusInputFieldDelegate);
    delegateInputField.setIsHandwritingDelegate(true);
}

تؤدي حركة قلم الشاشة فوق عرض حقل إدخال النص النائب إلى استدعاء معاودة الاتصال. تؤدي معاودة الاتصال إلى الانتقال إلى واجهة المستخدم لعرض حقل الإدخال الوظيفي والتركيز عليه. عادةً ما يكون تنفيذ معاودة الاتصال هو نفسه تنفيذ متتبِّع النقرات على العنصر النائب. عندما ينشئ حقل الإدخال الوظيفي creates an InputConnection, يبدأ وضع الكتابة اليدوية باستخدام قلم الشاشة.

الشكل 4 تفويض إدخال قلم الشاشة من عنصر في واجهة المستخدم ثابت إلى حقل الإدخال النصي

التصميم المتعدد الأبعاد

توفر SearchBar و SearchView لتسهيل تنفيذ نمط واجهة المستخدم النائبة.com.google.android.material.search

يتم ربط طرق عرض البحث النائبة والوظيفية باستخدام setUpWithSearchBar().

يتم ضبط تفويض الكتابة اليدوية في مكتبة Material بدون الحاجة إلى إجراء أي تطوير إضافي في تطبيقك.

التداخل مع أسطح الرسم

إذا كان تطبيقك يحتوي على سطح رسم مع حقل نص يراكب السطح، قد تحتاج إلى إيقاف الكتابة اليدوية باستخدام قلم الشاشة للسماح للمستخدم بالرسم. راجِع setAutoHandwritingEnabled().

الاختبار

تتوفّر الكتابة اليدوية باستخدام قلم الشاشة على أجهزة Android 14 والإصدارات الأحدث التي تحتوي على جهاز إدخال متوافق لقلم الشاشة ومحرّر طريقة إدخال (IME) يتيح استخدام واجهات برمجة التطبيقات للكتابة اليدوية باستخدام قلم الشاشة في Android 14.

إذا لم يكن لديك جهاز إدخال لقلم الشاشة، يمكنك محاكاة إدخال قلم الشاشة على أي جهاز لديه إذن الوصول إلى الجذر (بما في ذلك المحاكيات) باستخدام أوامر Android Debug Bridge (adb) التالية:


// Android 14
adb shell setprop persist.debug.input.simulate_stylus_with_touch true && adb shell stop && adb shell start

// Android 15 and higher
// Property takes effect after screen reconfiguration such as orientation change.
adb shell setprop debug.input.simulate_stylus_with_touch true

استخدِم الإصدار التجريبي من لوحة مفاتيح Gboard للاختبار إذا كنت تستخدم جهازًا لا يتيح استخدام قلم الشاشة.

مراجع إضافية