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

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

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

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

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

EditText

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

تتضمّن حدود الكتابة اليدوية مساحة متروكة عمودية تبلغ 40 وحدة بكسل مستقلة عن الكثافة ومساحة متروكة أفقية تبلغ 10 وحدات بكسل مستقلة عن الكثافة حول طريقة العرض. عدِّل حدود الكتابة بخط اليد باستخدام 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);
}

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

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

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

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

يتم ربط طرق عرض البحث الوظيفية وعناصر نائب النص بالسمة 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 التجريبي لاختبار الميزة إذا كنت تستخدم جهازًا لا يتوافق مع القلم.

مراجع إضافية