匯入及匯出主畫面資料

Android 主畫面資料由 LauncherProvider 類別提供，這個類別會擴充 ContentProvider，可讓您使用 XML 匯入及匯出啟動器工作區資料。

與內容供應商互動

如要與擴充 ContentProvider 的 LaunchProvider 類別互動，請使用 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 做為方法參數，匯出啟動器的 Workspace XML 表示法。
• 匯出期間，您可以使用 KEY_LAYOUT 鍵，在傳回的套件中存取 XML 表示法。
• 使用 contentResolver.call 方法，並將 IMPORT_LAYOUT_XML 做為方法參數，匯入啟動器的 XML 工作區表示法。
• 匯入期間，XML 表示法會以呼叫方法的 arg 參數形式提供。
• 無論是匯出或匯入 API 呼叫，如果所選作業順利完成，系統都會傳回 success；如果作業中斷或失敗，則會傳回 failure。
• 您可以使用 KEY_RESULT 鍵，在傳回的套裝組合中擷取 success 或 failure 值。

如需範例，請參閱「叫用 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 類別的行為假設。

• 方法是不可分割且會封鎖。
• 匯入時，啟動器中的類似資料會遭到覆寫，只留下新匯入的資料。
• 匯入的資料會立即開放存取；匯入後立即匯出，系統會傳回新資料。