إنشاء أسلوب إدخال

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

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

تتناول هذه الصفحة المواضيع التالية:

إذا لم يسبق لك استخدام أدوات IME، يمكنك قراءة المقالة التمهيدية طرق الإدخال على الشاشة أولاً.

مراحل نشاط أداة IME

يوضِّح المخطّط التالي دورة حياة أداة IME:

صورة تعرض دورة حياة أداة IME.
الشكل 1. دورة حياة أداة IME.

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

تعريف مكونات أداة IME في البيان

في نظام Android، أداة IME هي تطبيق Android يحتوي على خدمة IME خاصة. ويجب أن يذكر ملف البيان للتطبيق عن الخدمة وأن يطلب الأذونات اللازمة وأن يوفر فلترًا للنية ويطابق الإجراء action.view.InputMethod وأن يقدِّم بيانات وصفية تحدِّد خصائص أداة IME. بالإضافة إلى ذلك، لتوفير واجهة إعدادات تتيح للمستخدم تعديل سلوك أداة IME، يمكنك تحديد نشاط "الإعدادات" الذي يمكن تشغيله من إعدادات النظام.

يذكر المقتطف التالي عن خدمة IME. تطلب الخدمة الإذن BIND_INPUT_METHOD للسماح للخدمة بربط أداة IME بالنظام، وإعداد فلتر أهداف يتطابق مع الإجراء android.view.InputMethod، وتحديد البيانات الوصفية لأداة IME:

<!-- Declares the input method service. -->
<service android:name="FastInputIME"
    android:label="@string/fast_input_label"
    android:permission="android.permission.BIND_INPUT_METHOD">
    <intent-filter>
        <action android:name="android.view.InputMethod" />
    </intent-filter>
    <meta-data android:name="android.view.im"
               android:resource="@xml/method" />
</service>

يوضح المقتطف التالي نشاط الإعدادات لأداة IME. ويحتوي على فلتر أهداف لـ ACTION_MAIN يشير إلى أن هذا النشاط هو نقطة الدخول الرئيسية لتطبيق IME:

<!-- Optional: an activity for controlling the IME settings. -->
<activity android:name="FastInputIMESettings"
    android:label="@string/fast_input_settings">
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
    </intent-filter>
</activity>

يمكنك أيضًا توفير الدخول إلى إعدادات أداة IME مباشرةً من واجهة المستخدم الخاصة بها.

واجهة برمجة التطبيقات أسلوب الإدخال

يمكن العثور على الفئات الخاصة بأدوات IME في حزمتَي android.inputmethodservice وandroid.view.inputmethod. تُعدّ الفئة KeyEvent مهمة للتعامل مع أحرف لوحة المفاتيح.

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

الفئات التالية مهمة أيضًا:

BaseInputConnection
تحدِّد هذه السياسة قناة التواصل من InputMethod إلى التطبيق الذي يتلقّى البيانات التي أدخلها. ويمكنك استخدامه لقراءة نص حول المؤشر، وربط النص في مربّع النص، وإرسال الأحداث الرئيسية الأولية إلى التطبيق. يجب أن توسّع التطبيقات هذه الفئة بدلاً من تنفيذ الواجهة الأساسية InputConnection.
KeyboardView
إضافة من View تعرض لوحة مفاتيح وتستجيب لأحداث إدخالات المستخدم. يتم تحديد تنسيق لوحة المفاتيح من خلال مثيل Keyboard، ويمكنك تحديده في ملف XML.

تصميم واجهة مستخدم أسلوب الإدخال

يتوفّر عنصران مرئيان رئيسيان في أداة IME: عرض الإدخال وعرض المرشحين. ما عليك سوى تنفيذ العناصر ذات الصلة بطريقة الإدخال التي تصممها.

عرض الإدخال

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

Kotlin

override fun onCreateInputView(): View {
    return layoutInflater.inflate(R.layout.input, null).apply {
        if (this is MyKeyboardView) {
            setOnKeyboardActionListener(this@MyInputMethod)
            keyboard = latinKeyboard
        }
    }
}

Java

@Override
public View onCreateInputView() {
    MyKeyboardView inputView =
        (MyKeyboardView) getLayoutInflater().inflate(R.layout.input, null);

    inputView.setOnKeyboardActionListener(this);
    inputView.setKeyboard(latinKeyboard);

    return inputView;
}

في هذا المثال، تمثّل السمة MyKeyboardView تنفيذًا مخصّصًا للسمة KeyboardView يعرض السمة Keyboard.

طريقة عرض المرشحين

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

اعتبارات تصميم واجهة المستخدم

يصف هذا القسم بعض اعتبارات تصميم واجهة المستخدم في أدوات IME.

التعامل مع أحجام الشاشات المتعددة

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

التعامل مع أنواع الإدخال المختلفة

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

على سبيل المثال، إليك الواجهة التي يوفرها محرر أسلوب الإدخال اللاتيني لإدخال نص نظام Android:

صورة تعرض إدخالاً نصيًا في أداة تحرير أسلوب إدخال لاتينية
الشكل 2. إدخال نص IME اللاتيني.

وإليك الواجهة التي يوفرها محرِّر أسلوب الإدخال اللاتيني للإدخال الرقمي لنظام Android:

صورة تعرض إدخالاً رقميًا في أداة تحرير أسلوب إدخال لاتينية
الشكل 3. الإدخال الرقمي لأداة IME اللاتينية

عندما يتلقّى أحد حقول الإدخال التركيز وبدء أداة IME، يستدعي النظام onStartInputView()، ويمرر كائن EditorInfo يحتوي على تفاصيل حول نوع الإدخال والسمات الأخرى لحقل النص. في هذا الكائن، يحتوي الحقل inputType على نوع إدخال الحقل النصي.

الحقل inputType هو int يحتوي على أنماط بت لمختلف إعدادات نوع الإدخال. لاختبار نوع إدخال حقل النص، يمكنك إضافة علامة TYPE_MASK_CLASS الثابتة إليه، على النحو التالي:

Kotlin

inputType and InputType.TYPE_MASK_CLASS

Java

inputType & InputType.TYPE_MASK_CLASS

يمكن أن يكون لنمط بت نوع الإدخال قيمة من عدة قيم، منها:

TYPE_CLASS_NUMBER
حقل نصي لإدخال الأرقام كما هو موضّح في الشكل 3، تعرض أداة IME اللاتينية لوحة أرقام للحقول من هذا النوع.
TYPE_CLASS_DATETIME
حقل نصي لإدخال التاريخ والوقت
TYPE_CLASS_PHONE
حقل نصي لإدخال أرقام الهواتف
TYPE_CLASS_TEXT
حقل نصي لإدخال أي أحرف متوافقة

يتم توضيح هذه الثوابت بمزيد من التفصيل في المستندات المرجعية للسمة InputType.

يمكن أن يحتوي الحقل inputType على وحدات بت أخرى تشير إلى صيغة مختلفة لنوع الحقل النصي، مثل:

TYPE_TEXT_VARIATION_PASSWORD
نسخة أخرى من TYPE_CLASS_TEXT لإدخال كلمات المرور ويعرض أسلوب الإدخال رموز اللغات بدلاً من النص الفعلي.
TYPE_TEXT_VARIATION_URI
صيغة من TYPE_CLASS_TEXT لإدخال عناوين URL على الويب ومعرّفات الموارد المنتظمة (URI) الأخرى
TYPE_TEXT_FLAG_AUTO_COMPLETE
صيغة من TYPE_CLASS_TEXT لإدخال نص يُكمله التطبيق تلقائيًا من قاموس أو بحث أو أي أداة أخرى

يُرجى وضع القناع على inputType مع القيمة الثابتة المناسبة عند اختبار هذه الخيارات. إنّ الثوابت الخاصة بالقناعات مُدرَجة في المستندات المرجعية لـ InputType.

إرسال رسالة نصية إلى التطبيق

بينما يُدخل المستخدم نصًا باستخدام أداة IME، يمكنك إرسال نص إلى التطبيق من خلال إرسال أحداث رئيسية فردية أو عن طريق تعديل النص حول المؤشر في حقل نص التطبيق. في كلتا الحالتين، استخدِم مثيل InputConnection لعرض النص. للحصول على هذا المثيل، يمكنك استدعاء InputMethodService.getCurrentInputConnection().

تعديل النص حول المؤشر

عند تعديل النص الحالي، إليك بعض الطرق المفيدة في BaseInputConnection:

getTextBeforeCursor()
لعرض CharSequence يحتوي على عدد الأحرف المطلوبة قبل موضع المؤشر الحالي.
getTextAfterCursor()
لعرض CharSequence يحتوي على عدد الأحرف المطلوبة بعد موضع المؤشر الحالي.
deleteSurroundingText()
لحذف العدد المحدّد من الأحرف قبل موضع المؤشر الحالي ومتابعته.
commitText()
لتنفيذ CharSequence في حقل النص وضبط موضع مؤشر جديد.

على سبيل المثال، يوضّح المقتطف التالي كيفية استبدال الأحرف الأربعة على يسار المؤشر بالنص "Hello!":

Kotlin

currentInputConnection.also { ic: InputConnection ->
    ic.deleteSurroundingText(4, 0)
    ic.commitText("Hello", 1)
    ic.commitText("!", 1)
}

Java

InputConnection ic = getCurrentInputConnection();
ic.deleteSurroundingText(4, 0);
ic.commitText("Hello", 1);
ic.commitText("!", 1);

دعم إنشاء النص قبل التنفيذ

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

يوضح المقتطف التالي كيفية إظهار التقدم في حقل نصي:

Kotlin

currentInputConnection.also { ic: InputConnection ->
    ic.setComposingText("Composi", 1)
    ic.setComposingText("Composin", 1)
    ic.commitText("Composing ", 1)
}

Java

InputConnection ic = getCurrentInputConnection();
ic.setComposingText("Composi", 1);
ic.setComposingText("Composin", 1);
ic.commitText("Composing ", 1);

اعتراض الأحداث الرئيسية للأجهزة

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

لاعتراض مفاتيح الأجهزة، عليك إلغاء onKeyDown() وonKeyUp().

يمكنك استدعاء طريقة super() للمفاتيح التي لا تريد التعامل معها بنفسك.

إنشاء نوع فرعي لأداة IME

تسمح الأنواع الفرعية لأداة IME بكشف أوضاع إدخال ولغات متعددة تتيحها أداة IME. يمكن أن يمثل النوع الفرعي ما يلي:

  • اللغة، مثل en_US أو fr_FR
  • وضع إدخال، مثل الصوت أو لوحة المفاتيح أو الكتابة بخط اليد
  • أنماط إدخال أو نماذج أو خصائص أخرى خاصة بأداة IME، مثل تنسيقات لوحة المفاتيح المكونة من 10 مفاتيح أو QWERTY

وقد يكون الوضع عبارة عن أي نص، مثل "لوحة المفاتيح" أو "صوت". يمكن أن يعرض النوع الفرعي أيضًا مجموعة من هذه الأشياء.

تُستخدم معلومات النوع الفرعي في مربع حوار أداة تبديل أداة IME المتاح من شريط الإشعارات ولإعدادات أداة IME. وتتيح المعلومات لإطار العمل إمكانية إظهار نوع فرعي معيّن من أداة IME مباشرةً. عند إنشاء أداة IME، استخدم تسهيل النوع الفرعي، لأنها تساعد المستخدم على التعرف على لغات وأوضاع IME المختلفة والتبديل بينها.

عرِّف الأنواع الفرعية في أحد ملفات XML الخاصة بأسلوب الإدخال باستخدام العنصر <subtype>. يحدّد مقتطف الرمز التالي أداة IME لنوعين فرعيين: نوع فرعي للوحة المفاتيح للّغة الإنجليزية الأمريكية ونوع فرعي آخر للوحة المفاتيح للغة الفرنسية في فرنسا:

<input-method xmlns:android="http://schemas.android.com/apk/res/android"
        android:settingsActivity="com.example.softkeyboard.Settings"
        android:icon="@drawable/ime_icon">
    <subtype android:name="@string/display_name_english_keyboard_ime"
            android:icon="@drawable/subtype_icon_english_keyboard_ime"
            android:languageTag="en-US"
            android:imeSubtypeMode="keyboard"
            android:imeSubtypeExtraValue="somePrivateOption=true" />
    <subtype android:name="@string/display_name_french_keyboard_ime"
            android:icon="@drawable/subtype_icon_french_keyboard_ime"
            android:languageTag="fr-FR"
            android:imeSubtypeMode="keyboard"
            android:imeSubtypeExtraValue="someVariable=30,someInternalOption=false" />
    <subtype android:name="@string/display_name_german_keyboard_ime" ... />
</input-method>

للتأكد من تسمية الأنواع الفرعية الخاصة بك بشكل صحيح في واجهة المستخدم، استخدم `%s` للحصول على تصنيف فرعي هو نفس تصنيف لغة النوع الفرعي. ويمكنك توضيح ذلك في مقتطفَي الرمز التاليَين. يعرض المقتطف الأول جزءًا من ملف XML لطريقة الإدخال:

<subtype
    android:label="@string/label_subtype_generic"
    android:imeSubtypeLocale="en_US"
    android:icon="@drawable/icon_en_us"
    android:imeSubtypeMode="keyboard" />

المقتطف التالي هو جزء من ملف strings.xml لأداة IME. إنّ مصدر السلسلة label_subtype_generic المُستخدَم من خلال تعريف واجهة المستخدم لأسلوب الإدخال لضبط تصنيف النوع الفرعي هو ما يلي:

<string name="label_subtype_generic">%s</string>

يؤدي هذا الإعداد إلى تطابق الاسم المعروض للنوع الفرعي مع إعداد اللغة. على سبيل المثال، في أي لغة إنجليزية، يكون الاسم المعروض هو "الإنجليزية (الولايات المتحدة)".

اختيار الأنواع الفرعية لأداة IME من شريط الإشعارات

يدير نظام Android جميع الأنواع الفرعية التي ترصدها جميع أدوات IME. يتم التعامل مع أنواع IME الفرعية كأوضاع من IME التي تنتمي إليها. ويمكن للمستخدم الانتقال من شريط الإشعارات أو تطبيق "الإعدادات" إلى قائمة من الأنواع الفرعية المتاحة لأداة IME، كما هو موضح في الشكل التالي:

صورة تعرض قائمة &quot;اللغات وأنظمة الإدخال&quot;
الشكل 4. قائمة النظام اللغات والإدخال

اختيار الأنواع الفرعية لأداة IME من إعدادات النظام

يمكن للمستخدم أيضًا التحكّم في كيفية استخدام الأنواع الفرعية في لوحة إعدادات اللغة والإدخال في إعدادات النظام:

صورة تعرض قائمة اختيار &quot;اللغات&quot;
الشكل 5. قائمة النظام اللغات

التبديل بين الأنواع الفرعية لأداة IME

يمكنك السماح للمستخدمين بالتبديل بسهولة بين الأنواع الفرعية لأداة IME من خلال توفير مفتاح تبديل، مثل رمز اللغة على شكل كرة أرضية على لوحة المفاتيح. فهذا يحسن سهولة استخدام لوحة المفاتيح ويكون ملائمًا للمستخدم. لتفعيل عملية التبديل هذه، عليك اتّباع الخطوات التالية:

  1. حدِّد supportsSwitchingToNextInputMethod = "true" في ملفات موارد XML الخاصة بأسلوب الإدخال. يجب أن يبدو البيان مشابهًا لمقتطف الرمز التالي:
    <input-method xmlns:android="http://schemas.android.com/apk/res/android"
            android:settingsActivity="com.example.softkeyboard.Settings"
            android:icon="@drawable/ime_icon"
            android:supportsSwitchingToNextInputMethod="true">
    
  2. وعليك استدعاء الطريقة shouldOfferSwitchingToNextInputMethod().
  3. إذا أرجعت الطريقة true، اعرض مفتاح تبديل.
  4. عندما ينقر المستخدم على مفتاح التبديل، نفِّذ الإجراء على switchToNextInputMethod()، وسيتم ضبط القيمة على "خطأ". تطلب القيمة "false" من النظام أن يتعامل مع جميع الأنواع الفرعية بالتساوي، بغض النظر عن أداة IME التي تنتمي إليها. يتطلب تحديد "صحيح" أن يتنقل النظام بين الأنواع الفرعية في أداة IME الحالية.

اعتبارات أداة IME العامة

في ما يلي أمور أخرى يجب مراعاتها عند تنفيذ أداة IME:

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