أداة تعديل أسلوب الإدخال (IME) هي عنصر تحكّم للمستخدم يتيح للمستخدمين إدخال النص. يوفر Android إطار عمل أسلوب إدخال قابل للتوسع يتيح للتطبيقات توفير أساليب إدخال بديلة للمستخدمين، مثل لوحات المفاتيح على الشاشة أو إدخال الكلام. بعد تثبيت أدوات IME، يمكن للمستخدم اختيار أداة من إعدادات النظام واستخدامه في النظام بأكمله. لا يمكن تفعيل أكثر من أداة IME واحدة في كل مرة.
لإضافة أداة IME إلى نظام Android، يمكنك إنشاء تطبيق Android يحتوي على فئة تتضمن
InputMethodService
.
بالإضافة إلى ذلك، يمكنك عادةً إنشاء نشاط "الإعدادات" الذي يمرر الخيارات إلى خدمة IME. يمكنك أيضًا تحديد واجهة مستخدم الإعدادات التي يتم عرضها كجزء من إعدادات النظام.
تتناول هذه الصفحة المواضيع التالية:
- مراحل نشاط أداة IME
- توضيح مكوّنات أداة IME في بيان التطبيق
- واجهة برمجة التطبيقات IME
- تصميم واجهة مستخدم لأداة IME
- إرسال نص من أداة IME إلى تطبيق
- استخدام الأنواع الفرعية لأداة IME
- اعتبارات أخرى لأداة IME
إذا لم يسبق لك استخدام أدوات IME، يمكنك قراءة المقالة التمهيدية طرق الإدخال على الشاشة أولاً.
مراحل نشاط أداة IME
يوضِّح المخطّط التالي دورة حياة أداة IME:
![صورة تعرض دورة حياة أداة IME.](https://developer.android.com/static/resources/articles/images/inputmethod_lifecycle_image.png?authuser=5&hl=ar)
توضّح الأقسام التالية كيفية تنفيذ واجهة المستخدم والرمز المرتبط بأداة 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:
![صورة تعرض إدخالاً نصيًا في أداة تحرير أسلوب إدخال لاتينية](https://developer.android.com/static/images/ui/text_input.png?authuser=5&hl=ar)
وإليك الواجهة التي يوفرها محرِّر أسلوب الإدخال اللاتيني للإدخال الرقمي لنظام Android:
![صورة تعرض إدخالاً رقميًا في أداة تحرير أسلوب إدخال لاتينية](https://developer.android.com/static/images/ui/numeric_input.png?authuser=5&hl=ar)
عندما يتلقّى أحد حقول الإدخال التركيز وبدء أداة 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، كما هو موضح في الشكل التالي:
![صورة تعرض قائمة "اللغات وأنظمة الإدخال"](https://developer.android.com/static/images/ui/languages_and_input.png?authuser=5&hl=ar)
اختيار الأنواع الفرعية لأداة IME من إعدادات النظام
يمكن للمستخدم أيضًا التحكّم في كيفية استخدام الأنواع الفرعية في لوحة إعدادات اللغة والإدخال في إعدادات النظام:
![صورة تعرض قائمة اختيار "اللغات"](https://developer.android.com/static/images/ui/languages.png?authuser=5&hl=ar)
التبديل بين الأنواع الفرعية لأداة IME
يمكنك السماح للمستخدمين بالتبديل بسهولة بين الأنواع الفرعية لأداة IME من خلال توفير مفتاح تبديل، مثل رمز اللغة على شكل كرة أرضية على لوحة المفاتيح. فهذا يحسن سهولة استخدام لوحة المفاتيح ويكون ملائمًا للمستخدم. لتفعيل عملية التبديل هذه، عليك اتّباع الخطوات التالية:
- حدِّد
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">
- وعليك استدعاء الطريقة
shouldOfferSwitchingToNextInputMethod()
. - إذا أرجعت الطريقة true، اعرض مفتاح تبديل.
- عندما ينقر المستخدم على مفتاح التبديل، نفِّذ الإجراء على
switchToNextInputMethod()
، وسيتم ضبط القيمة على "خطأ". تطلب القيمة "false" من النظام أن يتعامل مع جميع الأنواع الفرعية بالتساوي، بغض النظر عن أداة IME التي تنتمي إليها. يتطلب تحديد "صحيح" أن يتنقل النظام بين الأنواع الفرعية في أداة IME الحالية.
اعتبارات أداة IME العامة
في ما يلي أمور أخرى يجب مراعاتها عند تنفيذ أداة IME:
- عليك توفير طريقة تمكّن المستخدمين من ضبط الخيارات مباشرةً من واجهة مستخدم أداة IME.
- عليك توفير طريقة تمكّن المستخدمين من التبديل إلى أداة IME مختلفة مباشرةً من واجهة مستخدم أسلوب الإدخال، بسبب احتمال تثبيت أدوات IME متعددة على الجهاز.
- اعرض واجهة مستخدم أداة IME بسرعة. يمكنك تحميل أي موارد كبيرة مسبقًا أو تحميلها عند الطلب حتى يظهر للمستخدمين أداة IME عند النقر على حقل نصي. ذاكرة التخزين المؤقت للموارد وطرق العرض للاستدعاءات اللاحقة لطريقة الإدخال.
- عليك إطلاق عمليات تخصيص كبيرة للذاكرة فور إخفاء نافذة أسلوب الإدخال، لكي تتوفّر لدى التطبيقات ذاكرة كافية لتشغيلها. استخدِم رسالة متأخرة لتحرير الموارد في حال إخفاء أداة IME لبضع ثوانٍ.
- تأكَّد من أنّه يمكن للمستخدمين إدخال أكبر عدد ممكن من الأحرف للّغة أو اللغة المرتبطة بأداة IME. قد يستخدم المستخدمون علامات الترقيم في كلمات المرور أو أسماء المستخدمين، لذلك يجب أن توفّر أداة IME عدة أحرف مختلفة للسماح للمستخدمين بإدخال كلمة المرور والوصول إلى الجهاز.