Importer et exporter les données de l'écran d'accueil

Les données de l'écran d'accueil Android sont fournies par la classe LauncherProvider, qui étend ContentProvider, ce qui permet d'importer et d'exporter les données de l'espace de travail du lanceur d'applications à l'aide d'XML.

Interagir avec le fournisseur de contenu

Pour interagir avec la classe LaunchProvider, qui étend ContentProvider, utilisez la méthode call :

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

Appeler la classe LaunchProvider

Pour appeler la classe LauncherProvider depuis votre application, utilisez le code suivant :

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

Paramètres

Ces constantes sont utilisées dans la méthode d'appel :

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

Utilisez les constantes LauncherProvider avec les contraintes suivantes :

• Utilisez la méthode contentResolver.call avec EXPORT_LAYOUT_XML comme paramètre de méthode pour exporter une représentation XML de l'espace de travail du lanceur d'applications.
• Lors de l'exportation, la représentation XML est accessible dans le bundle renvoyé à l'aide de la clé KEY_LAYOUT.
• Utilisez la méthode contentResolver.call avec IMPORT_LAYOUT_XML comme paramètre de méthode pour importer une représentation XML de l'espace de travail du lanceur.
• Lors de l'importation, la représentation XML est fournie en tant que paramètre arg de la méthode d'appel.
• Pour les appels d'API d'exportation et d'importation, l'opération choisie renvoie success si elle se termine correctement, et failure si elle est interrompue ou échoue.
• La valeur success ou failure peut être récupérée dans le bundle renvoyé à l'aide de la clé KEY_RESULT.

Pour obtenir un exemple, consultez Appeler la classe LaunchProvider.

Représentation XML

Consultez les guides suivants pour connaître la structure XML lors de l'importation et de l'exportation.

• Application 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>
  

• Application 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>
  

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

• Dossier :

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

• Raccourci profond :

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

• Paire d'applications :

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

Hypothèses comportementales

Voici les hypothèses de comportement pour la classe LaunchProvider.

• Les méthodes sont atomiques et bloquantes.
• Les données analogues du lanceur sont écrasées lors de l'importation, ce qui ne laisse que les données nouvellement importées.
• Les données importées sont immédiatement accessibles. Si vous les exportez juste après l'importation, les nouvelles données sont renvoyées.