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

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

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

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

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

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

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

ويوضّح المخطّط التالي دورة حياة أداة 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():

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.

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

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

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

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

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

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

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

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

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

ها هي الواجهة التي يوفرها Latin IME للإدخال الرقمي لنظام Android:

عندما يتلقّى أحد حقول الإدخال التركيز ويبدأ محرر أسلوب الإدخال (IME)، يستدعي النظام 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 لإدخال كلمات المرور. يعرض أسلوب الإدخال رموز dingbat بدلاً من النص الفعلي.

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!":

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 عرض العديد من أوضاع الإدخال واللغات التي يدعمها محرر أسلوب الإدخال (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، كما هو موضح في الشكل التالي:

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

اعتبارات عامة في أداة IME

وفي ما يلي أمور أخرى يجب مراعاتها عند تنفيذ محرر أسلوب الإدخال (IME):

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