جعل تطبيقات التلفزيون قابلة للبحث

يستخدم Android TV واجهة البحث في Android لاسترداد بيانات المحتوى من التطبيقات المثبّتة وعرض نتائج البحث للمستخدم. ويمكن تضمين بيانات محتوى التطبيق مع هذه النتائج لمنح المستخدم إمكانية الوصول الفوري إلى المحتوى في تطبيقك.

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

قبل قراءة هذا الدليل، تأكّد من أنّك على دراية بالمفاهيم الموضّحة في دليل Search API. راجِع أيضًا المقالة إضافة وظيفة بحث.

يأتي الرمز النموذجي في هذا الدليل من نموذج تطبيق Leanback .

تحديد الأعمدة

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

تتضمّن الفئة SearchManager عدة أعمدة لـ Android TV. يتم وصف بعض الأعمدة الأكثر أهمية في الجدول التالي.

يتطلب إطار عمل البحث الأعمدة التالية:

• SUGGEST_COLUMN_TEXT_1
• SUGGEST_COLUMN_PRODUCTION_YEAR
• SUGGEST_COLUMN_DURATION

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

قد تحدد فئة قاعدة البيانات في تطبيقك الأعمدة على النحو التالي:

class VideoDatabase {
    companion object {
        // The columns we'll include in the video database table
        val KEY_NAME = SearchManager.SUGGEST_COLUMN_TEXT_1
        val KEY_DESCRIPTION = SearchManager.SUGGEST_COLUMN_TEXT_2
        val KEY_ICON = SearchManager.SUGGEST_COLUMN_RESULT_CARD_IMAGE
        val KEY_DATA_TYPE = SearchManager.SUGGEST_COLUMN_CONTENT_TYPE
        val KEY_IS_LIVE = SearchManager.SUGGEST_COLUMN_IS_LIVE
        val KEY_VIDEO_WIDTH = SearchManager.SUGGEST_COLUMN_VIDEO_WIDTH
        val KEY_VIDEO_HEIGHT = SearchManager.SUGGEST_COLUMN_VIDEO_HEIGHT
        val KEY_AUDIO_CHANNEL_CONFIG = SearchManager.SUGGEST_COLUMN_AUDIO_CHANNEL_CONFIG
        val KEY_PURCHASE_PRICE = SearchManager.SUGGEST_COLUMN_PURCHASE_PRICE
        val KEY_RENTAL_PRICE = SearchManager.SUGGEST_COLUMN_RENTAL_PRICE
        val KEY_RATING_STYLE = SearchManager.SUGGEST_COLUMN_RATING_STYLE
        val KEY_RATING_SCORE = SearchManager.SUGGEST_COLUMN_RATING_SCORE
        val KEY_PRODUCTION_YEAR = SearchManager.SUGGEST_COLUMN_PRODUCTION_YEAR
        val KEY_COLUMN_DURATION = SearchManager.SUGGEST_COLUMN_DURATION
        val KEY_ACTION = SearchManager.SUGGEST_COLUMN_INTENT_ACTION
        ...
    }
    ...
}

public class VideoDatabase {
    // The columns we'll include in the video database table
    public static final String KEY_NAME = SearchManager.SUGGEST_COLUMN_TEXT_1;
    public static final String KEY_DESCRIPTION = SearchManager.SUGGEST_COLUMN_TEXT_2;
    public static final String KEY_ICON = SearchManager.SUGGEST_COLUMN_RESULT_CARD_IMAGE;
    public static final String KEY_DATA_TYPE = SearchManager.SUGGEST_COLUMN_CONTENT_TYPE;
    public static final String KEY_IS_LIVE = SearchManager.SUGGEST_COLUMN_IS_LIVE;
    public static final String KEY_VIDEO_WIDTH = SearchManager.SUGGEST_COLUMN_VIDEO_WIDTH;
    public static final String KEY_VIDEO_HEIGHT = SearchManager.SUGGEST_COLUMN_VIDEO_HEIGHT;
    public static final String KEY_AUDIO_CHANNEL_CONFIG =
            SearchManager.SUGGEST_COLUMN_AUDIO_CHANNEL_CONFIG;
    public static final String KEY_PURCHASE_PRICE = SearchManager.SUGGEST_COLUMN_PURCHASE_PRICE;
    public static final String KEY_RENTAL_PRICE = SearchManager.SUGGEST_COLUMN_RENTAL_PRICE;
    public static final String KEY_RATING_STYLE = SearchManager.SUGGEST_COLUMN_RATING_STYLE;
    public static final String KEY_RATING_SCORE = SearchManager.SUGGEST_COLUMN_RATING_SCORE;
    public static final String KEY_PRODUCTION_YEAR = SearchManager.SUGGEST_COLUMN_PRODUCTION_YEAR;
    public static final String KEY_COLUMN_DURATION = SearchManager.SUGGEST_COLUMN_DURATION;
    public static final String KEY_ACTION = SearchManager.SUGGEST_COLUMN_INTENT_ACTION;
...

عند إنشاء خريطة من أعمدة "SearchManager" إلى حقول البيانات، عليك أيضًا تحديد _ID لمنح كل صف معرّفًا فريدًا.

companion object {
    ....
    private fun buildColumnMap(): Map<String, String> {
        return mapOf(
          KEY_NAME to KEY_NAME,
          KEY_DESCRIPTION to KEY_DESCRIPTION,
          KEY_ICON to KEY_ICON,
          KEY_DATA_TYPE to KEY_DATA_TYPE,
          KEY_IS_LIVE to KEY_IS_LIVE,
          KEY_VIDEO_WIDTH to KEY_VIDEO_WIDTH,
          KEY_VIDEO_HEIGHT to KEY_VIDEO_HEIGHT,
          KEY_AUDIO_CHANNEL_CONFIG to KEY_AUDIO_CHANNEL_CONFIG,
          KEY_PURCHASE_PRICE to KEY_PURCHASE_PRICE,
          KEY_RENTAL_PRICE to KEY_RENTAL_PRICE,
          KEY_RATING_STYLE to KEY_RATING_STYLE,
          KEY_RATING_SCORE to KEY_RATING_SCORE,
          KEY_PRODUCTION_YEAR to KEY_PRODUCTION_YEAR,
          KEY_COLUMN_DURATION to KEY_COLUMN_DURATION,
          KEY_ACTION to KEY_ACTION,
          BaseColumns._ID to ("rowid AS " + BaseColumns._ID),
          SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID to ("rowid AS " + SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID),
          SearchManager.SUGGEST_COLUMN_SHORTCUT_ID to ("rowid AS " + SearchManager.SUGGEST_COLUMN_SHORTCUT_ID)
        )
    }
}

...
  private static HashMap<String, String> buildColumnMap() {
    HashMap<String, String> map = new HashMap<String, String>();
    map.put(KEY_NAME, KEY_NAME);
    map.put(KEY_DESCRIPTION, KEY_DESCRIPTION);
    map.put(KEY_ICON, KEY_ICON);
    map.put(KEY_DATA_TYPE, KEY_DATA_TYPE);
    map.put(KEY_IS_LIVE, KEY_IS_LIVE);
    map.put(KEY_VIDEO_WIDTH, KEY_VIDEO_WIDTH);
    map.put(KEY_VIDEO_HEIGHT, KEY_VIDEO_HEIGHT);
    map.put(KEY_AUDIO_CHANNEL_CONFIG, KEY_AUDIO_CHANNEL_CONFIG);
    map.put(KEY_PURCHASE_PRICE, KEY_PURCHASE_PRICE);
    map.put(KEY_RENTAL_PRICE, KEY_RENTAL_PRICE);
    map.put(KEY_RATING_STYLE, KEY_RATING_STYLE);
    map.put(KEY_RATING_SCORE, KEY_RATING_SCORE);
    map.put(KEY_PRODUCTION_YEAR, KEY_PRODUCTION_YEAR);
    map.put(KEY_COLUMN_DURATION, KEY_COLUMN_DURATION);
    map.put(KEY_ACTION, KEY_ACTION);
    map.put(BaseColumns._ID, "rowid AS " +
            BaseColumns._ID);
    map.put(SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID, "rowid AS " +
            SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID);
    map.put(SearchManager.SUGGEST_COLUMN_SHORTCUT_ID, "rowid AS " +
            SearchManager.SUGGEST_COLUMN_SHORTCUT_ID);
    return map;
  }
...

في المثال السابق، لاحِظ عملية الربط بالحقل SUGGEST_COLUMN_INTENT_DATA_ID. هذا هو الجزء من معرف الموارد المنتظم (URI) الذي يشير إلى المحتوى الفريد للبيانات في هذا الصف - الجزء الأخير من معرف الموارد المنتظم (URI)، ويصف مكان تخزين المحتوى. يتم ضبط الجزء الأول من معرّف الموارد المنتظم (URI) عندما يكون مشتركًا بين جميع الصفوف في الجدول، وذلك في ملف searchable.xml باعتباره السمة android:searchSuggestIntentData، كما هو موضّح في القسم التعامل مع اقتراحات البحث.

إذا كان الجزء الأول من معرّف الموارد المنتظم (URI) مختلفًا لكل صف في الجدول، اربط هذه القيمة بالحقل SUGGEST_COLUMN_INTENT_DATA. عندما يختار المستخدم هذا المحتوى، يوفّر الغرض الذي يتم تنشيطه بيانات intent من مجموعة SUGGEST_COLUMN_INTENT_DATA_ID وإما السمة android:searchSuggestIntentData أو قيمة الحقل SUGGEST_COLUMN_INTENT_DATA.

تقديم بيانات اقتراحات البحث

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

fun query(uri: Uri, projection: Array<String>, selection: String, selectionArgs: Array<String>,
        sortOrder: String): Cursor {
    // Use the UriMatcher to see what kind of query we have and format the db query accordingly
    when (URI_MATCHER.match(uri)) {
        SEARCH_SUGGEST -> {
            Log.d(TAG, "search suggest: ${selectionArgs[0]} URI: $uri")
            if (selectionArgs == null) {
                throw IllegalArgumentException(
                        "selectionArgs must be provided for the Uri: $uri")
            }
            return getSuggestions(selectionArgs[0])
        }
        else -> throw IllegalArgumentException("Unknown Uri: $uri")
    }
}

private fun getSuggestions(query: String): Cursor {
    val columns = arrayOf<String>(
            BaseColumns._ID,
            VideoDatabase.KEY_NAME,
            VideoDatabase.KEY_DESCRIPTION,
            VideoDatabase.KEY_ICON,
            VideoDatabase.KEY_DATA_TYPE,
            VideoDatabase.KEY_IS_LIVE,
            VideoDatabase.KEY_VIDEO_WIDTH,
            VideoDatabase.KEY_VIDEO_HEIGHT,
            VideoDatabase.KEY_AUDIO_CHANNEL_CONFIG,
            VideoDatabase.KEY_PURCHASE_PRICE,
            VideoDatabase.KEY_RENTAL_PRICE,
            VideoDatabase.KEY_RATING_STYLE,
            VideoDatabase.KEY_RATING_SCORE,
            VideoDatabase.KEY_PRODUCTION_YEAR,
            VideoDatabase.KEY_COLUMN_DURATION,
            VideoDatabase.KEY_ACTION,
            SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID
    )
    return videoDatabase.getWordMatch(query.toLowerCase(), columns)
}

@Override
public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs,
        String sortOrder) {
    // Use the UriMatcher to see what kind of query we have and format the db query accordingly
    switch (URI_MATCHER.match(uri)) {
        case SEARCH_SUGGEST:
            Log.d(TAG, "search suggest: " + selectionArgs[0] + " URI: " + uri);
            if (selectionArgs == null) {
                throw new IllegalArgumentException(
                        "selectionArgs must be provided for the Uri: " + uri);
            }
            return getSuggestions(selectionArgs[0]);
        default:
            throw new IllegalArgumentException("Unknown Uri: " + uri);
    }
}

private Cursor getSuggestions(String query) {
    query = query.toLowerCase();
    String[] columns = new String[]{
        BaseColumns._ID,
        VideoDatabase.KEY_NAME,
        VideoDatabase.KEY_DESCRIPTION,
        VideoDatabase.KEY_ICON,
        VideoDatabase.KEY_DATA_TYPE,
        VideoDatabase.KEY_IS_LIVE,
        VideoDatabase.KEY_VIDEO_WIDTH,
        VideoDatabase.KEY_VIDEO_HEIGHT,
        VideoDatabase.KEY_AUDIO_CHANNEL_CONFIG,
        VideoDatabase.KEY_PURCHASE_PRICE,
        VideoDatabase.KEY_RENTAL_PRICE,
        VideoDatabase.KEY_RATING_STYLE,
        VideoDatabase.KEY_RATING_SCORE,
        VideoDatabase.KEY_PRODUCTION_YEAR,
        VideoDatabase.KEY_COLUMN_DURATION,
        VideoDatabase.KEY_ACTION,
        SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID
    };
    return videoDatabase.getWordMatch(query, columns);
}
...

في ملف البيان، يتلقّى موفّر المحتوى معاملة خاصة. وبدلاً من وضع علامة عليه كنشاط، يتم وصفه على أنّه <provider>. يتضمّن الموفِّر السمة android:authorities لإخبار النظام بمساحة الاسم لموفّر المحتوى. ويجب أيضًا ضبط سمة android:exported على "true" حتى يتمكّن محرّك بحث Android العام من استخدام النتائج المعروضة منها.

<provider android:name="com.example.android.tvleanback.VideoContentProvider"
    android:authorities="com.example.android.tvleanback"
    android:exported="true" />

التعامل مع اقتراحات البحث

يجب أن يتضمّن تطبيقك ملف res/xml/searchable.xml لضبط إعدادات اقتراحات البحث.

في ملف res/xml/searchable.xml، ضمِّن السمة android:searchSuggestAuthority لإعلام النظام بمساحة الاسم الخاصة بموفّر المحتوى. ويجب أن تتطابق مع قيمة السلسلة التي تحدّدها في السمة android:authorities للعنصر <provider> في ملف AndroidManifest.xml.

عليك أيضًا تضمين تصنيف، وهو اسم التطبيق. تستخدم إعدادات البحث في النظام هذا التصنيف عند تعداد التطبيقات القابلة للبحث.

يجب أن يتضمّن الملف searchable.xml أيضًا android:searchSuggestIntentAction مع القيمة "android.intent.action.VIEW" لتحديد إجراء intent لتقديم اقتراح مخصّص. ويختلف هذا عن الإجراء المقصود بتقديم عبارة بحث كما هو موضّح في القسم التالي. للتعرّف على الطرق الأخرى لتوضيح الإجراء المقصود بالاقتراحات، يمكنك الاطّلاع على الإعلان عن الإجراء المقصود.

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

تحدد السمة android:searchSuggestSelection=" ?" القيمة التي يتم تمريرها باعتبارها المعلمة selection للطريقة query(). يتم استبدال قيمة علامة الاستفهام (?) بنص طلب البحث.

أخيرًا، يجب أيضًا تضمين السمة android:includeInGlobalSearch مع القيمة "true". إليك مثال على ملف searchable.xml:

<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/search_label"
    android:hint="@string/search_hint"
    android:searchSettingsDescription="@string/settings_description"
    android:searchSuggestAuthority="com.example.android.tvleanback"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:searchSuggestIntentData="content://com.example.android.tvleanback/video_database_leanback"
    android:searchSuggestSelection=" ?"
    android:searchSuggestThreshold="1"
    android:includeInGlobalSearch="true">
</searchable>

التعامل مع عبارات البحث

عند توفّر كلمة في مربّع حوار البحث تتطابق مع القيمة الواردة في أحد أعمدة تطبيقك، كما هو موضّح في القسم تحديد الأعمدة، يعمل النظام على تنشيط ACTION_SEARCH intent. يشير النشاط الموجود في تطبيقك الذي يعالج قصدًا إلى البحث في المستودع عن أعمدة تحتوي على كلمة معينة في قيمها ويعرض قائمة بعناصر المحتوى التي تحتوي على تلك الأعمدة. في ملف AndroidManifest.xml، يمكنك تحديد النشاط الذي يعالج نية ACTION_SEARCH كما هو موضّح في المثال التالي:

...
  <activity
      android:name="com.example.android.tvleanback.DetailsActivity"
      android:exported="true">

      <!-- Receives the search request. -->
      <intent-filter>
          <action android:name="android.intent.action.SEARCH" />
          <!-- No category needed, because the Intent will specify this class component -->
      </intent-filter>

      <!-- Points to searchable meta data. -->
      <meta-data android:name="android.app.searchable"
          android:resource="@xml/searchable" />
  </activity>
...
  <!-- Provides search suggestions for keywords against video meta data. -->
  <provider android:name="com.example.android.tvleanback.VideoContentProvider"
      android:authorities="com.example.android.tvleanback"
      android:exported="true" />
...

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

رابط لموضع معيّن في تطبيقك في شاشة التفاصيل

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

عندما ينقر المستخدم على رابط تطبيقك، المحدد من خلال الزر **متاح في** في شاشة التفاصيل، يبدأ النظام النشاط الذي يعالج ACTION_VIEW المضبوط على android:searchSuggestIntentAction بالقيمة "android.intent.action.VIEW" في ملف searchable.xml.

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

سلوك البحث

يتوفّر البحث في Android TV من الشاشة الرئيسية ومن داخل تطبيقك. وتختلف نتائج البحث في هاتين الحالتين.

البحث من الشاشة الرئيسية

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

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

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

البحث من تطبيقك

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

مزيد من المعلومات

لمزيد من المعلومات حول البحث في تطبيق تلفزيون، يمكنك الاطّلاع على مقالة دمج ميزات البحث على Android في تطبيقك وإضافة وظيفة بحث.

لمزيد من المعلومات حول طريقة تخصيص تجربة البحث داخل التطبيق باستخدام SearchFragment، يمكنك الاطّلاع على البحث في تطبيقات التلفزيون.