استيراد بيانات الشاشة الرئيسية وتصديرها

يتم توفير بيانات الشاشة الرئيسية على Android من خلال الفئة LauncherProvider التي توسّع ContentProvider، ما يسمح باستيراد بيانات مساحة عمل مشغّل التطبيقات وتصديرها باستخدام 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()
    }
}

المعلَمات

تُستخدَم هذه الثوابت في الطريقة call:

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 للطريقة call.
  • بالنسبة إلى طلبات واجهة برمجة التطبيقات للاستيراد والتصدير، يعرض إكمال العملية المختارة بنجاح القيمة success، بينما تعرض العمليات التي تمّت مقاطعتها أو التي تعذّر إكمالها القيمة failure.
  • يمكن استرداد القيمة success أو failure في الحزمة التي يتم عرضها باستخدام المفتاح KEY_RESULT.

للاطّلاع على مثال، يُرجى مراجعة استدعاء الفئة LaunchProvider.

تمثيل XML

استخدِم الأدلة التالية لهيكل XML أثناء الاستيراد والتصدير.

  • تطبيق مساحة العمل:

    <?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>
    
  • تطبيق منطقة الإرساء القابلة للتخصيص:

    <?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.

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