Ana ekran verilerini içe ve dışa aktarma

Android ana ekran verileri, ContentProvider'ı genişleten LauncherProvider sınıfı tarafından sağlanır. Bu sınıf, XML kullanarak Launcher çalışma alanı verilerinin içe ve dışa aktarılmasına olanak tanır.

İçerik sağlayıcıyla etkileşim kurma

ContentProvider sınıfını genişleten LaunchProvider sınıfıyla etkileşim kurmak için call yöntemini kullanın:

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

LaunchProvider sınıfını çağırma

Uygulamanızdan LauncherProvider sınıfını çağırmak için aşağıdakileri kullanın:

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

Parametreler

Bu sabitler, arama yönteminde kullanılır:

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 sabitlerini aşağıdaki kısıtlamalarla kullanın:

• Başlatıcının çalışma alanının XML gösterimini dışa aktarmak için yöntem parametresi olarak EXPORT_LAYOUT_XML ile contentResolver.call yöntemini kullanın.
• Dışa aktarma sırasında, döndürülen paketteki XML gösterimine KEY_LAYOUT anahtarı kullanılarak erişilebilir.
• Başlatıcı çalışma alanının XML gösterimini içe aktarmak için yöntem parametresi olarak IMPORT_LAYOUT_XML ile contentResolver.call yöntemini kullanın.
• İçe aktarma sırasında XML gösterimi, çağrı yönteminin arg parametresi olarak sağlanır.
• Hem dışa aktarma hem de içe aktarma API çağrılarında, seçilen işlemin başarıyla tamamlanması success, kesintiye uğrayan veya başarısız olan işlemler ise failure döndürür.
• success veya failure değeri, KEY_RESULT anahtarı kullanılarak döndürülen pakette alınabilir.

Örnek için LaunchProvider sınıfını çağırma bölümüne bakın.

XML gösterimi

İçe ve dışa aktarma sırasında XML yapısı için aşağıdaki kılavuzları kullanın.

• Workspace uygulaması:

  <?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 uygulaması:

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

• Klasör:

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

• Derin kısayol:

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

• Uygulama çifti:

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

Davranışsal varsayımlar

LaunchProvider sınıfıyla ilgili davranışsal varsayımlar aşağıda verilmiştir.

• Yöntemler atomik ve engelleyici olmalıdır.
• Başlatıcıdaki benzer verilerin üzerine içe aktarma sırasında yazılır ve yalnızca yeni içe aktarılan veriler kalır.
• İçe aktarılan verilere hemen erişilebilir. İçe aktarma işleminden hemen sonra dışa aktarma işlemi yapıldığında yeni veriler döndürülür.