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

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

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

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

• دورة حياة IME
• تعريف مكوّنات محرّك طرق الإدخال في بيان التطبيق
• واجهة برمجة التطبيقات IME
• تصميم واجهة مستخدم لبرنامج IME
• إرسال نص من محرر أسلوب إدخال إلى تطبيق
• العمل باستخدام الأنواع الفرعية من IME
• اعتبارات أخرى بشأن محرّرات أساليب الإدخال

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

مراحل نشاط محرر طريقة الإدخال

يوضّح الرسم البياني التالي دورة حياة طريقة الإدخال:

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

تعريف مكوّنات محرر طريقة الإدخال في ملف البيان

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

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

<!-- 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 يشير إلى أنّ هذا النشاط هو نقطة الدخول الرئيسية لتطبيق طريقة الإدخال:

<!-- 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 في حزمتَي android.inputmethodservice و android.view.inputmethod. فئة KeyEvent مهمة للتعامل مع أحرف لوحة المفاتيح.

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

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

BaseInputConnection

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

KeyboardView

هي امتداد View يعرض لوحة مفاتيح ويستجيب لأحداث إدخال المستخدم. يتم تحديد تخطيط لوحة المفاتيح من خلال مثيل من Keyboard، ويمكنك تحديد هذا المثيل في ملف XML.

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

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

طريقة عرض الإدخال

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

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

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

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

    return inputView;
}

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

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

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

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

يوضّح هذا القسم بعض الاعتبارات المتعلّقة بتصميم واجهة المستخدم الخاصة بمحرّرات طرق الإدخال.

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

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

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

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

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

في ما يلي الواجهة التي توفّرها "محرّك إدخال اللغة اللاتينية" لمنصة Android لإدخال الأرقام:

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

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

inputType and InputType.TYPE_MASK_CLASS

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.

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

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

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

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

getTextBeforeCursor()

تعرض هذه السمة CharSequence التي تحتوي على عدد الأحرف المطلوبة قبل موضع المؤشر الحالي.

getTextAfterCursor()

تعرض هذه السمة CharSequence تحتوي على عدد الأحرف المطلوبة بعد موضع المؤشر الحالي.

deleteSurroundingText()

يحذف هذا الإجراء عدد الأحرف المحدّد قبل موضع المؤشر الحالي وبعده.

commitText()

تُضيف CharSequence إلى حقل النص وتضبط موضعًا جديدًا للمؤشر.

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

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

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

إتاحة كتابة النص قبل إرساله

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

يوضّح المقتطف التالي كيفية عرض مستوى التقدّم في حقل نصي:

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

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

اعتراض أحداث مفاتيح الأجهزة

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

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

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

إنشاء نوع فرعي من طريقة الإدخال

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

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

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

تُستخدَم معلومات النوع الفرعي لمربّع حوار مبدّل محرر أسلوب الإدخال (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 الخاص بمحرّر طريقة الإدخال. يتم تعريف مورد السلسلة label_subtype_generic، الذي يستخدمه تعريف واجهة المستخدم لطريقة الإدخال لضبط تصنيف النوع الفرعي، على النحو التالي:

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

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

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

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

اختيار أنواع محرّرات طرق الإدخال من "إعدادات النظام"

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

التبديل بين الأنواع الفرعية لطريقة الإدخال (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. إذا عرضت الطريقة القيمة "صحيح"، اعرض مفتاح تبديل.
4. عندما ينقر المستخدم على مفتاح التبديل، يتم استدعاء الدالة switchToNextInputMethod()، مع تمرير القيمة false. تشير القيمة false إلى أنّ النظام سيتعامل مع جميع الأنواع الفرعية بشكل متساوٍ، بغض النظر عن IME الذي تنتمي إليه. يؤدي تحديد القيمة "صحيح" إلى إلزام النظام بالتنقل بين الأنواع الفرعية في محرر أسلوب الإدخال الحالي.

اعتبارات عامة بشأن أداة IME

في ما يلي بعض الأمور الأخرى التي يجب مراعاتها أثناء تنفيذ طريقة الإدخال:

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