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

تتيح مكتبة Jetpack androidx.compose.material3 للمستخدمين الكتابة في أي مكوّن TextField في أي تطبيق باستخدام قلم إلكتروني.

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

لتفعيل إدخال البيانات باستخدام القلم الرقمي تلقائيًا، أضِف عنصر المكتبة التابع إلى ملف build.gradle في تطبيقك:

Kotlin

dependencies {
    implementation("androidx.compose.foundation:foundation:LATEST_COMPOSE_VERSION")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "LATEST_EXTENSION_VERSION"
    }

    kotlinOptions {
        jvmTarget = "LATEST_JVM_VERSION"
    }
}

Groovy

dependencies {
    implementation 'androidx.compose.foundation:foundation:LATEST_COMPOSE_VERSION'
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = 'LATEST_EXTENSION_VERSION'
    }

    kotlinOptions {
        jvmTarget = 'LATEST_JVM_VERSION'
    }
}

TextField

تكون الكتابة بخط اليد باستخدام قلم الشاشة مفعّلة تلقائيًا لجميع مكونات TextField على الإصدار 14 من نظام التشغيل Android والإصدارات الأحدث، وكذلك على حزمة androidx.compose.foundation:foundation:1.7.0. يبدأ وضع الكتابة اليدوية عند رصد حدث حركة قلم داخل حدود الكتابة اليدوية للمكوّن.TextField

تتضمّن حدود الكتابة اليدوية مساحة متروكة عمودية تبلغ 40 وحدة بكسل مستقلة عن الكثافة ومساحة متروكة أفقية تبلغ 10 وحدات بكسل مستقلة عن الكثافة حول حقل الإدخال.

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

لا تتوفّر الكتابة بخط اليد باستخدام قلم الشاشة في حقول TextField عند طلب محرر طريقة الإدخال باستخدام KeyboardType.Password.

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

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

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

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

استخدِم واجهات برمجة التطبيقات الخاصة بتفويض الكتابة اليدوية لتوفير إمكانية إدخال الكتابة اليدوية باستخدام قلم في حقول الإدخال الخاصة بالعناصر النائبة (راجِع handwritingDetector و handwritingHandler). يتم ضبط عنصر واجهة المستخدم الخاص بالعنصر النائب لتفويض الكتابة اليدوية إلى حقل إدخال وظيفي. للاطّلاع على مثال للتنفيذ، يُرجى الرجوع إلى HandwritingDetectorSample.kt.

يبدأ وضع الكتابة بخط اليد باستخدام قلم الشاشة عندما يكتسب حقل الإدخال الوظيفي التركيز وينشئ InputConnection.

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

الاختبار

تتوفّر ميزة الكتابة اليدوية باستخدام القلم على أجهزة 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 التجريبي لاختبار الميزة إذا كنت تستخدم جهازًا لا يتوافق مع القلم.

مراجع إضافية

السابق
نظرة عامة
التالي
الميزات المتقدّمة لقلم الشاشة