Startbildschirmdaten importieren und exportieren

Die Daten des Android-Startbildschirms werden von der LauncherProvider Klasse bereitgestellt, die ContentProvider erweitert und den Import und Export von Launcher Arbeitsplatzdaten mithilfe von XML ermöglicht.

Mit dem Content Provider interagieren

Verwenden Sie die Methode call, um mit der Klasse LaunchProvider zu interagieren, die ContentProvider erweitert:

class LauncherProvider : ContentProvider {
    public Bundle call(String method, String arg, Bundle extras);
}

Klasse „LaunchProvider“ aufrufen

Verwenden Sie Folgendes, um die Klasse LauncherProvider aus Ihrer App aufzurufen:

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()
    }
}

Parameter

Diese Konstanten werden in der Methode „call“ verwendet:

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";
}

Verwenden Sie die Konstanten LauncherProvider mit den folgenden Einschränkungen:

  • Verwenden Sie die Methode contentResolver.call mit EXPORT_LAYOUT_XML als Methodenparameter, um eine XML-Darstellung des Arbeitsplatzes des Launchers zu exportieren.
  • Während des Exports ist die XML-Darstellung im zurückgegebenen Bundle über den Schlüssel KEY_LAYOUT zugänglich.
  • Verwenden Sie die Methode contentResolver.call mit IMPORT_LAYOUT_XML als Methodenparameter, um eine XML-Darstellung des Arbeitsplatzes des Launchers zu importieren.
  • Während des Imports wird die XML-Darstellung als Parameter arg der Methode „call“ bereitgestellt.
  • Bei API-Aufrufen für den Export und Import gibt die erfolgreiche Ausführung des ausgewählten Vorgangs success zurück. Bei unterbrochenen oder fehlgeschlagenen Vorgängen wird failure zurückgegeben.
  • Der Wert success oder failure kann im zurückgegebenen Bundle über den Schlüssel KEY_RESULT abgerufen werden.

Ein Beispiel finden Sie unter Klasse „LaunchProvider“ aufrufen.

XML-Darstellung

Verwenden Sie die folgenden Anleitungen für die XML-Struktur während des Imports und Exports.

  • Workspace-App:

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

  • App-Leiste:

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

  • Widget:

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

  • Ordner:

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

  • Deep shortcut:

    <?xml version='1.0' encoding='UTF-8' standalone='yes' ?>
<workspace>
  <shortcut shortcutId="shortcut2" packageName="com.google.android.apps.nexuslauncher.tests" />
</workspace>

  • App-Paar:

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

Verhaltensannahmen

Im Folgenden finden Sie Verhaltensannahmen für die Klasse LaunchProvider.

  • Methoden sind atomar und blockierend.
  • Analoge Daten im Launcher werden während des Imports überschrieben, sodass nur die neu importierten Daten übrig bleiben.
  • Importierte Daten sind sofort verfügbar. Wenn Sie direkt nach dem Import exportieren, werden die neuen Daten zurückgegeben.