يتم توفير بيانات شاشة Android الرئيسية من خلال الفئة LauncherProvider التي توسّع ContentProvider، ما يتيح استيراد بيانات مساحة عمل Launcher وتصديرها باستخدام XML.
التفاعل مع مقدّم المحتوى
للتفاعل مع الفئة LaunchProvider التي توسّع ContentProvider،
استخدِم الطريقة call:
class LauncherProvider : ContentProvider {
    public Bundle call(String method, String arg, Bundle extras);
}
استدعاء فئة LaunchProvider
لاستدعاء فئة LauncherProvider من تطبيقك، استخدِم ما يلي:
class YourClass {
    /**
     * This method imports Launcher workspace data as a XML string. Calling this method clears the old
     * data model within Launcher and replaces it with the imported data. It should be noted
     * that it doesn't need to clear all the Launcher's data, just what is similar to what is being imported.
     */
    fun importLauncherData(xmlRepresentation: String, ctx: Context): Boolean {
        val uri = try {
            getLauncherProviderUri(ctx)
        } catch (e: IllegalStateException) {
            Log.e(TAG, "Failed to get launcher provider URI", e)
            return false
        }
        val bundle = ctx.contentResolver.call(
            uri,
            LauncherProviderConstants.METHOD_IMPORT_LAYOUT_XML,
            xmlRepresentation,
            null,
        )
        return LauncherProviderConstants.SUCCESS
            .equals(bundle.getBoolean(LauncherProviderConstants.KEY_RESULT))
    }
    /**
     * Use this function to retrieve an XML string representation of the Launcher's Workspace.
     * This method doesn't return what the user sees on their home screen,
     * but rather what is in their data model at the moment it's called.
     */
    fun exportLauncherData(xmlRepresentation: String, ctx: Context): String {
        val uri = try {
            getLauncherProviderUri(ctx)
        } catch (e: IllegalStateException) {
            Log.e(TAG, "Failed to get launcher provider URI", e)
            return ""
        }
        val bundle = ctx.contentResolver.call(
            uri,
            LauncherProviderConstants.METHOD_EXPORT_LAYOUT_XML,
            null,
            null,
        )
        if (LauncherProviderConstants.FAILURE
            .equals(bundle.getBoolean(LauncherProviderConstants.KEY_RESULT))) {
            Log.e(TAG, "failed to export launcher data; review previous logs for the cause.")
        }
        return bundle.getString(LauncherProviderConstants.KEY_LAYOUT, "")
    }
    /**
     * Returns a Uri for interacting with Launcher's ContentProvider.
     *
     * Not all Launchers implement this api. This method throws an IllegalStateException
     * if the Launcher doesn't support it.
     */
    private fun getLauncherProviderUri(ctx: Context): Uri {
        val homeIntent = Intent(Intent.ACTION_MAIN).addCategory(Intent.CATEGORY_HOME)
        val launcherPackage: String =
            ctx.packageManager
                .resolveActivity(homeIntent, PackageManager.MATCH_DEFAULT_ONLY)
                ?.activityInfo
                ?.packageName ?: throw IllegalStateException("No launcher package found")
        val authority = "${launcherPackage}.settings"
        ctx.packageManager.resolveContentProvider(authority, 0)
            ?: throw IllegalStateException(
                "Launcher package '$launcherPackage' does not support LauncherProvider",
            )
        return "content://$authority".toUri()
    }
}
المعلمات
يتم استخدام هذه الثوابت في طريقة الاتصال:
object LauncherProviderConstants {
    // Valid arg parameters for export and import operations
    private static final String METHOD_EXPORT_LAYOUT_XML = "EXPORT_LAYOUT_XML";
    private static final String METHOD_IMPORT_LAYOUT_XML = "IMPORT_LAYOUT_XML";
    // Bundle key and value set for determining if operation completed successfully or not
    private static final String KEY_RESULT = "KEY_RESULT";
    private static final String SUCCESS = "success";
    private static final String FAILURE = "failure";
    // Bundle key used to store exported XML-string representation of Launcher's workspace layout
    // and item metadata
    private static final String KEY_LAYOUT = "KEY_LAYOUT";
}
استخدِم الثوابت LauncherProvider مع القيود التالية:
- استخدِم طريقة contentResolver.callمعEXPORT_LAYOUT_XMLكمعلَمة للطريقة لتصدير تمثيل XML لمساحة عمل مشغّل التطبيقات.
- أثناء التصدير، يمكن الوصول إلى تمثيل XML في الحزمة التي تم إرجاعها باستخدام المفتاح KEY_LAYOUT.
- استخدِم طريقة contentResolver.callمعIMPORT_LAYOUT_XMLكمعلَمة للطريقة لاستيراد تمثيل XML لمساحة عمل مشغّل التطبيقات.
- أثناء الاستيراد، يتم توفير تمثيل XML كمعلَمة argلطريقة الاستدعاء.
- بالنسبة إلى طلبات البيانات من واجهة برمجة التطبيقات الخاصة بالتصدير والاستيراد، يؤدي إكمال العملية المحدّدة بنجاح إلى عرض success، بينما يؤدي تعذّر إكمال العمليات أو إيقافها إلى عرضfailure.
- يمكن استرداد القيمة successأوfailureفي الحزمة التي تم إرجاعها باستخدام المفتاحKEY_RESULT.
للاطّلاع على مثال، راجِع استدعاء فئة LaunchProvider.
تمثيل XML
استخدِم الأدلة التالية لبنية XML أثناء الاستيراد والتصدير.
- تطبيق Workspace: - <?xml version='1.0' encoding='UTF-8' standalone='yes' ?> <workspace rows="4" columns="5"> <autoinstall container="desktop" x="1" y="1" screen="0" className="com.android.launcher3.tests.Activity2" packageName="com.google.android.apps.nexuslauncher" /> </workspace>
- تطبيق Hotseat: - <?xml version='1.0' encoding='UTF-8' standalone='yes' ?> <workspace> <autoinstall container="hotseat" rank="0" className="com.android.launcher3.tests.Activity2" packageName="com.google.android.apps.nexuslauncher" /> </workspace>
- التطبيق المصغَّر: - <?xml version='1.0' encoding='UTF-8' standalone='yes' ?> <workspace> <appwidget container="desktop" spanX="2" spanY="2" x="0" y="1" screen="0" className="PlaceholderWidget" packageName="com.test.pending" /> </workspace>
- المجلد: - <?xml version='1.0' encoding='UTF-8' standalone='yes' ?> <workspace> <folder container="desktop" x="1" y="1" screen="1" titleText="CustomFolder"> <autoinstall className="com.android.launcher3.tests.Activity1" packageName="com.google.android.apps.nexuslauncher" /> <autoinstall className="com.android.launcher3.tests.Activity2" packageName="com.google.android.apps.nexuslauncher" /> <autoinstall className="com.android.launcher3.tests.Activity3" packageName="com.google.android.apps.nexuslauncher" /> </folder> </workspace>
- الاختصار العميق: - <?xml version='1.0' encoding='UTF-8' standalone='yes' ?> <workspace> <shortcut shortcutId="shortcut2" packageName="com.google.android.apps.nexuslauncher.tests" /> </workspace>
- استخدام تطبيقين في الوقت نفسه: - <?xml version='1.0' encoding='UTF-8' standalone='yes' ?> <workspace> <apppair container="desktop" x="1" y="1" screen="1" titleText="CustomFolder"> <autoinstall className="com.android.launcher3.tests.Activity1" packageName="com.google.android.apps.nexuslauncher" /> <autoinstall className="com.android.launcher3.tests.Activity2" packageName="com.google.android.apps.nexuslauncher" /> </apppair> </workspace>
الافتراضات السلوكية
في ما يلي افتراضات سلوكية للفئة LaunchProvider.
- الطُرق ذرية وحظر.
- يتم استبدال البيانات المشابهة في مشغّل التطبيقات أثناء الاستيراد، ولا تبقى سوى البيانات المستورَدة حديثًا.
- يمكن الوصول إلى البيانات المستورَدة على الفور، كما أنّ تصدير البيانات بعد استيرادها مباشرةً يعرض البيانات الجديدة.
