廣播總覽

Android 應用程式會傳送及接收來自 Android 系統和其他 Android 應用程式的廣播訊息,類似於發布/訂閱設計模式。系統和應用程式通常會在特定事件發生時傳送廣播。舉例來說,Android 系統會在發生各種系統事件時傳送廣播,例如系統啟動或裝置充電。應用程式也會傳送自訂廣播訊息,例如通知其他應用程式可能感興趣的事件 (例如下載新資料)。

應用程式可以註冊接收特定廣播訊息。廣播訊息傳送後,系統會自動將訊息轉送至已訂閱接收該特定類型廣播訊息的應用程式。

一般來說,廣播訊息可用於跨應用程式和一般使用者流程以外的訊息系統。不過,請務必小心,不要濫用回應廣播和在背景執行工作的機會,以免導致系統效能降低。

關於系統廣播訊息

系統會在發生各種系統事件時自動傳送廣播,例如系統切換飛航模式時。所有訂閱型應用程式都會收到這些廣播。

Intent 物件會包裝廣播訊息。action 字串會識別發生的事件,例如 android.intent.action.AIRPLANE_MODE。意圖也可能包含額外欄位中附加的其他資訊。舉例來說,飛航模式意圖包含布林值額外項目,指出飛航模式是否開啟。

如要進一步瞭解如何讀取意圖,以及從意圖取得動作字串,請參閱「意圖和意圖篩選器」。

系統廣播訊息動作

如需系統廣播動作的完整清單,請參閱 Android SDK 中的 BROADCAST_ACTIONS.TXT 檔案。每個廣播動作都有相關聯的常數欄位。舉例來說,常數 ACTION_AIRPLANE_MODE_CHANGED 的值為 android.intent.action.AIRPLANE_MODE。每個廣播動作的說明文件都可在其相關聯的常數欄位中找到。

系統廣播訊息異動

隨著 Android 平台不斷演進,系統廣播訊息的行為也會定期變更。請留意下列異動,確保支援所有 Android 版本。

Android 16

在 Android 16 中,使用 android:priority 屬性或 IntentFilter.setPriority() 跨不同程序廣播時,無法保證傳送順序。廣播優先順序只會在同一個應用程式程序中生效,不會跨所有程序。

此外,廣播優先順序會自動限制在 (SYSTEM_LOW_PRIORITY + 1, SYSTEM_HIGH_PRIORITY - 1) 範圍內。只有系統元件可以將 SYSTEM_LOW_PRIORITY、SYSTEM_HIGH_PRIORITY 設為廣播優先順序。

Android 14

當應用程式處於快取狀態時,系統會最佳化廣播訊息傳送,以維護系統健康。舉例來說,當應用程式處於快取狀態時,系統會延遲傳送較不重要的系統廣播訊息,例如 ACTION_SCREEN_ON。應用程式從快取狀態進入有效程序生命週期後,系統會傳送所有延遲的廣播訊息。

在資訊清單中宣告的重要廣播訊息,會暫時將應用程式從快取狀態中移除,以便傳送。

Android 9

自 Android 9 (API 級別 28) 起,NETWORK_STATE_CHANGED_ACTION 廣播不會收到使用者位置或個人識別資料的相關資訊。

如果應用程式安裝在搭載 Android 9.0 (API 級別 28) 以上版本的裝置上,系統不會在 Wi-Fi 廣播中加入 SSID、BSSID、連線資訊或掃描結果。如要取得這項資訊,請改為呼叫 getConnectionInfo()。

Android 8.0

自 Android 8.0 (API 級別 26) 起,系統會對資訊清單宣告的接收器施加額外限制。

如果應用程式指定 Android 8.0 以上版本,您就無法使用資訊清單,為大多數隱式廣播 (並非專門指定應用程式的廣播) 宣告接收器。使用者正在使用應用程式時,您仍可使用內容註冊接收器。

Android 7.0

Android 7.0 (API 級別 24) 以上版本不會傳送下列系統廣播訊息:

此外,指定 Android 7.0 以上版本的應用程式必須使用 registerReceiver(BroadcastReceiver, IntentFilter) 註冊 CONNECTIVITY_ACTION 廣播。在資訊清單中宣告接收器不會有任何作用。

接收廣播

應用程式可以透過兩種方式接收廣播:透過內容註冊接收器和資訊清單宣告接收器。

註冊使用情境的接收器

只要註冊情境有效,註冊情境的接收器就會收到廣播。這通常介於 registerReceiver 和 unregisterReceiver 的呼叫之間。當系統刪除對應的情境時,註冊情境也會失效。舉例來說,如果您在 Activity 情境中註冊,只要活動保持啟用狀態,您就會收到廣播。如果使用應用程式情境註冊,只要應用程式執行,就會收到廣播。

如要向內容註冊接收器,請按照下列步驟操作:

  1. 在應用程式的模組層級建構檔案中,加入 1.9.0 以上版本的 AndroidX Core 程式庫:

    Groovy

    dependencies {
        def core_version = "1.19.1"
    
        // Java language implementation
        implementation "androidx.core:core:$core_version"
        // Kotlin
        implementation "androidx.core:core-ktx:$core_version"
    
        // To use RoleManagerCompat
        implementation "androidx.core:core-role:1.1.0"
    
        // To use the Animator APIs
        implementation "androidx.core:core-animation:1.0.0"
        // To test the Animator APIs
        androidTestImplementation "androidx.core:core-animation-testing:1.0.0"
    
        // Optional - To enable APIs that query the performance characteristics of GMS devices.
        implementation "androidx.core:core-performance:1.0.0"
    
        // Optional - to use ShortcutManagerCompat to donate shortcuts to be used by Google
        implementation "androidx.core:core-google-shortcuts:1.1.0"
    
        // Optional - to support backwards compatibility of RemoteViews
        implementation "androidx.core:core-remoteviews:1.1.0"
    
        // Optional - APIs for SplashScreen, including compatibility helpers on devices prior Android 12
        implementation "androidx.core:core-splashscreen:1.2.0"
    }

    Kotlin

    dependencies {
        val core_version = "1.19.1"
    
        // Java language implementation
        implementation("androidx.core:core:$core_version")
        // Kotlin
        implementation("androidx.core:core-ktx:$core_version")
    
        // To use RoleManagerCompat
        implementation("androidx.core:core-role:1.1.0")
    
        // To use the Animator APIs
        implementation("androidx.core:core-animation:1.0.0")
        // To test the Animator APIs
        androidTestImplementation("androidx.core:core-animation-testing:1.0.0")
    
        // Optional - To enable APIs that query the performance characteristics of GMS devices.
        implementation("androidx.core:core-performance:1.0.0")
    
        // Optional - to use ShortcutManagerCompat to donate shortcuts to be used by Google
        implementation("androidx.core:core-google-shortcuts:1.1.0")
    
        // Optional - to support backwards compatibility of RemoteViews
        implementation("androidx.core:core-remoteviews:1.1.0")
    
        // Optional - APIs for SplashScreen, including compatibility helpers on devices prior Android 12
        implementation("androidx.core:core-splashscreen:1.2.0")
    }
  2. 建立 BroadcastReceiver 的執行個體:

    Kotlin

    val myBroadcastReceiver = MyBroadcastReceiver()
    

    Java

    MyBroadcastReceiver myBroadcastReceiver = new MyBroadcastReceiver();
    
  3. 建立 IntentFilter 的執行個體:

    Kotlin

    val filter = IntentFilter("com.example.snippets.ACTION_UPDATE_DATA")
    

    Java

    IntentFilter filter = new IntentFilter("com.example.snippets.ACTION_UPDATE_DATA");
    
  4. 選擇是否要匯出廣播接收器,並向裝置上的其他應用程式顯示。如果這個接收器正在監聽系統或其他應用程式 (甚至是您擁有的其他應用程式) 傳送的廣播,請使用 RECEIVER_EXPORTED 旗標。如果這個接收器只監聽應用程式傳送的廣播,請使用 RECEIVER_NOT_EXPORTED 旗標。

    Kotlin

    val listenToBroadcastsFromOtherApps = false
    val receiverFlags = if (listenToBroadcastsFromOtherApps) {
        ContextCompat.RECEIVER_EXPORTED
    } else {
        ContextCompat.RECEIVER_NOT_EXPORTED
    }
    

    Java

    boolean listenToBroadcastsFromOtherApps = false;
    int receiverFlags = listenToBroadcastsFromOtherApps
            ? ContextCompat.RECEIVER_EXPORTED
            : ContextCompat.RECEIVER_NOT_EXPORTED;
    
  5. 呼叫 registerReceiver() 註冊接收器:

    Kotlin

    ContextCompat.registerReceiver(context, myBroadcastReceiver, filter, receiverFlags)
    

    Java

    ContextCompat.registerReceiver(context, myBroadcastReceiver, filter, receiverFlags);
    
  6. 如要停止接收廣播,請呼叫 unregisterReceiver(android.content.BroadcastReceiver)。當您不再需要接收器或結構定義不再有效時,請務必取消註冊接收器。

取消註冊廣播接收器

廣播接收器註冊後,會保留註冊時使用的 Context 參照。如果接收器的註冊範圍超出 Context 生命週期範圍,可能會導致洩漏。舉例來說,如果您在 Activity 範圍註冊接收器,但在系統刪除 Activity 時忘記取消註冊,就可能發生這種情況。因此,請務必取消註冊廣播接收器。

Kotlin

class MyActivity : ComponentActivity() {
    private val myBroadcastReceiver = MyBroadcastReceiver()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...
        ContextCompat.registerReceiver(this, myBroadcastReceiver, filter, receiverFlags)
        setContent { MyApp() }
    }

    override fun onDestroy() {
        super.onDestroy()
        // When you forget to unregister your receiver here, you're causing a leak!
        this.unregisterReceiver(myBroadcastReceiver)
    }
}

Java

class MyActivity extends ComponentActivity {
    MyBroadcastReceiver myBroadcastReceiver;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // ...
        ContextCompat.registerReceiver(this, myBroadcastReceiver, filter, receiverFlags);
        // Set content
    }
}

在最小範圍內註冊接收器

只有在您確實對結果感興趣時,才應註冊廣播接收器。選擇最小的接收器範圍:

  • LifecycleResumeEffect 或活動 onResume/onPause 生命週期方法:廣播接收器只會在應用程式處於恢復狀態時接收更新。
  • LifecycleStartEffect 或活動 onStart/onStop 生命週期方法:廣播接收器只會在應用程式處於恢復狀態時接收更新。
  • DisposableEffect:只有在可組合函式位於組合樹狀結構中時,廣播接收器才會接收更新。這個範圍不會附加至活動生命週期範圍。建議您在應用程式內容中註冊接收器。這是因為可組合項理論上可能超出活動生命週期範圍,並洩漏活動。
  • Activity onCreate/onDestroy:Activity 處於建立狀態時,廣播接收器會收到更新。請務必在 onDestroy() 取消註冊,而非 onSaveInstanceState(Bundle),因為系統可能不會呼叫後者。
  • 自訂範圍:舉例來說,您可以在 ViewModel 範圍內註冊接收器,這樣接收器就不會在活動重建時消失。請務必使用應用程式內容註冊接收器,因為接收器的生命週期可能超過活動生命週期範圍,並導致活動外洩。

建立有狀態和無狀態可組合函式

Compose 包含有狀態和無狀態可組合項。在可組合函式中註冊或取消註冊廣播接收器,會使其成為有狀態。可組合函式並非確定性函式,在傳遞相同參數時,不會算繪相同內容。內部狀態可能會根據對已註冊廣播接收器的呼叫而變更。

在 Compose 中,我們建議的最佳做法是將可組合項分為有狀態和無狀態版本。因此,建議您將廣播接收器的建立作業從可組合項中提升,使其不具狀態:

@Composable
fun MyStatefulScreen() {
    val myBroadcastReceiver = remember { MyBroadcastReceiver() }
    val context = LocalContext.current
    LifecycleStartEffect(true) {
        // ...
        ContextCompat.registerReceiver(context, myBroadcastReceiver, filter, flags)
        onStopOrDispose { context.unregisterReceiver(myBroadcastReceiver) }
    }
    MyStatelessScreen()
}

@Composable
fun MyStatelessScreen() {
    // Implement your screen
}

資訊清單宣告的接收器

如果您在資訊清單中宣告廣播接收器,系統會在傳送廣播時啟動應用程式。如果應用程式尚未執行,系統會啟動應用程式。

如要在資訊清單中宣告廣播接收器,請按照下列步驟操作:

  1. 在應用程式資訊清單中指定 <receiver> 元素。

    <!-- If this receiver listens for broadcasts sent from the system or from
         other apps, even other apps that you own, set android:exported to "true". -->
    <receiver android:name=".MyBroadcastReceiver" android:exported="false">
        <intent-filter>
            <action android:name="com.example.snippets.ACTION_UPDATE_DATA" />
        </intent-filter>
    </receiver>
    

    意圖篩選器會指定接收器訂閱的廣播動作。

  2. 子類別 BroadcastReceiver 並實作 onReceive(Context, Intent)。以下範例中的廣播接收器會記錄並顯示廣播內容:

    Kotlin

    class MyBroadcastReceiver : BroadcastReceiver() {
    
        @Inject
        lateinit var dataRepository: DataRepository
    
        override fun onReceive(context: Context, intent: Intent) {
            if (intent.action == "com.example.snippets.ACTION_UPDATE_DATA") {
                val data = intent.getStringExtra("com.example.snippets.DATA") ?: "No data"
                // Do something with the data, for example send it to a data repository:
                dataRepository.updateData(data)
            }
        }
    }
    

    Java

    public static class MyBroadcastReceiver extends BroadcastReceiver {
    
        @Inject
        DataRepository dataRepository;
    
        @Override
        public void onReceive(Context context, Intent intent) {
            if (Objects.equals(intent.getAction(), "com.example.snippets.ACTION_UPDATE_DATA")) {
                String data = intent.getStringExtra("com.example.snippets.DATA");
                // Do something with the data, for example send it to a data repository:
                if (data != null) { dataRepository.updateData(data); }
            }
        }
    }
    

系統套件管理員會在安裝應用程式時註冊接收器。接收器會成為應用程式的獨立進入點,也就是說,如果應用程式未執行,系統可以啟動應用程式並傳送廣播。

系統會建立新的 BroadcastReceiver 元件物件,處理收到的每個廣播。這個物件僅在呼叫 onReceive(Context, Intent) 期間有效。當程式碼從這個方法傳回時,系統會將元件視為不再有效。

對程序狀態的影響

BroadcastReceiver 是否運作會影響其包含的程序,進而改變系統終止的可能性。前景程序會執行接收器的 onReceive() 方法。除非記憶體壓力極大,否則系統會執行該程序。

系統會在 onReceive()後停用BroadcastReceiver。接收器主機程序的重要性取決於其應用程式元件。如果該程序只託管資訊清單宣告的接收器,系統可能會在 onReceive() 後終止該程序,釋出資源給其他更重要的程序。如果使用者從未或最近未與應用程式互動,通常會發生這種情況。

因此,廣播接收器不應啟動長時間執行的背景執行緒。系統可在 onReceive() 之後隨時停止程序,以回收記憶體,並終止建立的執行緒。如要讓程序保持運作,請使用 JobScheduler 從接收器排定 JobService,讓系統知道程序仍在運作。詳情請參閱「背景工作總覽」。

傳送廣播

Android 提供兩種讓應用程式傳送廣播的方式:

  • sendOrderedBroadcast(Intent, String) 方法會一次將廣播訊息傳送給一個接收器。由於每個接收器會按順序執行,因此可將結果傳播至下一個接收器。此外,也可以完全取消廣播,使其不會傳送至其他接收器。您可以控制接收器在同一個應用程式程序中的執行順序。如要這麼做,請使用相符意圖篩選器的 android:priority 屬性。優先順序相同的接收器會以任意順序執行。
  • sendBroadcast(Intent) 方法會以未定義的順序,將廣播傳送給所有接收器。這稱為一般廣播。這種方式效率較高,但接收器無法讀取其他接收器的結果、傳播從廣播接收的資料,或取消廣播。

下列程式碼片段示範如何建立 Intent 並呼叫 sendBroadcast(Intent) 來傳送廣播。

Kotlin

val intent = Intent("com.example.snippets.ACTION_UPDATE_DATA").apply {
    putExtra("com.example.snippets.DATA", newData)
    setPackage("com.example.snippets")
}
context.sendBroadcast(intent)

Java

Intent intent = new Intent("com.example.snippets.ACTION_UPDATE_DATA");
intent.putExtra("com.example.snippets.DATA", newData);
intent.setPackage("com.example.snippets");
context.sendBroadcast(intent);

廣播訊息會包裝在 Intent 物件中。意圖的 action 字串必須提供應用程式的 Java 套件名稱語法,並能明確識別廣播事件。您可以使用 putExtra(String, Bundle) 將其他資訊附加至意圖。您也可以在意圖上呼叫 setPackage(String),將廣播限制在同一機構中的一組應用程式。

使用權限限制廣播

您可以透過權限,限制只有具備特定權限的應用程式才能接收廣播。您可以對廣播的傳送者或接收者強制執行限制。

傳送廣播訊息時須具備權限

呼叫 sendBroadcast(Intent, String) 或 sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle) 時,您可以指定權限參數。只有在資訊清單中使用 <uses-permission> 標記要求該權限的接收器,才能接收廣播。如果權限屬於危險權限,您必須先授予權限,接收器才能接收廣播。舉例來說,下列程式碼會傳送具有權限的廣播:

Kotlin

context.sendBroadcast(intent, android.Manifest.permission.ACCESS_COARSE_LOCATION)

Java

context.sendBroadcast(intent, android.Manifest.permission.ACCESS_COARSE_LOCATION);

如要接收廣播,接收端應用程式必須要求權限,如下所示:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

您可以指定現有的系統權限 (例如 BLUETOOTH_CONNECT),也可以使用 <permission> 元素定義自訂權限。如要瞭解一般權限和安全性,請參閱「系統權限」。

接收具有權限的廣播

如果您在註冊廣播接收器時指定權限參數 (使用 registerReceiver(BroadcastReceiver, IntentFilter, String, Handler) 或資訊清單中的 <receiver> 標記),則只有在資訊清單中使用 <uses-permission> 標記要求權限的廣播器,才能將意圖傳送至接收器。如果權限屬於危險權限,則播送者也必須獲得權限。

舉例來說,假設接收應用程式具有資訊清單宣告的接收器,如下所示:

<!-- If this receiver listens for broadcasts sent from the system or from
     other apps, even other apps that you own, set android:exported to "true". -->
<receiver
    android:name=".MyBroadcastReceiverWithPermission"
    android:permission="android.permission.ACCESS_COARSE_LOCATION"
    android:exported="true">
    <intent-filter>
        <action android:name="com.example.snippets.ACTION_UPDATE_DATA" />
    </intent-filter>
</receiver>

或者,接收應用程式具有內容註冊接收器,如下所示:

Kotlin

ContextCompat.registerReceiver(
    context, myBroadcastReceiver, filter,
    android.Manifest.permission.ACCESS_COARSE_LOCATION,
    null, // scheduler that defines thread, null means run on main thread
    receiverFlags
)

Java

ContextCompat.registerReceiver(
        context, myBroadcastReceiver, filter,
        android.Manifest.permission.ACCESS_COARSE_LOCATION,
        null, // scheduler that defines thread, null means run on main thread
        receiverFlags
);

接著,為了能將廣播傳送至這些接收器,傳送應用程式必須要求權限,如下所示:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

避免在同一程序中廣播

廣播是一種處理序間通訊 (IPC) 機制,用於在不同應用程式之間,或系統與應用程式之間傳送訊息。傳送「自我廣播」(即「所有」接收器都在傳送廣播的同一個程序中執行的廣播) 的效率非常低,會產生不必要的系統負擔,因此強烈不建議使用。

應用程式向自身傳送廣播的兩種常見情況包括:

  • 在同一程序中的元件之間通訊:例如在活動、片段、服務或背景執行緒之間傳遞事件或資料。請改用標準程序內通訊機制,例如觀察者模式或回應式串流:

    • Kotlin 資料流 (SharedFlow 和 StateFlow):Kotlin 的現代化慣用解決方案,用於在應用程式的協同程式和元件中,發出及觀察事件串流或狀態更新。
    • 共用 ViewModel:在同一活動中,促進不同 UI 元件 (例如片段或可組合項) 之間的資料和事件共用。
    • 回呼和事件監聽器:標準介面回呼或函式參照,直接在元件之間傳遞,或向中央存放區或控制器註冊。
  • 處理系統事件、工作或鬧鐘:例如接收排定的工作、鬧鐘或系統回呼,然後傳送廣播來觸發實際工作。請直接在該工作 (例如 JobService 或 WorkManager worker)、鬧鐘處理常式或系統回呼元件中完成工作,或直接委派給應用程式的商業邏輯類別,而不是傳送廣播。

在搭載 Android 17 QPR2 以上版本的裝置上,系統會將自我廣播傳回傳送程序,並在主執行緒上傳送至自己的接收器,更有效率地傳送自我廣播。傳送自我廣播不會提高程序的重要性,也不會防止快取程序凍結,因此請勿依賴自我廣播來維持應用程式運作,或在背景執行工作。請改為按照「背景工作總覽」中的說明,選擇適合您工作的 API。即使經過這項最佳化,自我廣播的效率仍低於程序內通訊機制,因此請改用這些替代方案。

如要進一步瞭解如何設計應用程式元件之間的通訊,請參閱「應用程式架構指南」。

安全性考量

以下是傳送及接收廣播時,需要考量的安全性事項:

  • 如果許多應用程式在資訊清單中註冊接收相同的廣播,可能會導致系統啟動大量應用程式,對裝置效能和使用者體驗造成重大影響。為避免這種情況,建議您使用內容註冊,而非資訊清單宣告。有時,Android 系統本身會強制使用在內容中註冊的接收器。舉例來說,CONNECTIVITY_ACTION 廣播只會傳送至內容註冊的接收器。

  • 請勿使用隱含意圖廣播機密資訊。任何應用程式只要註冊接收廣播,就能讀取資訊。你可以透過下列三種方式,控管哪些人可以接收你的廣播:

    • 您可以在傳送廣播時指定權限。
    • 在 Android 4.0 (API 級別 14) 以上版本中,您可以在傳送廣播時,使用 setPackage(String) 指定套件。系統會將廣播限制在與套件相符的應用程式組合。
  • 註冊接收器後,任何應用程式都能將可能有害的廣播訊息傳送至應用程式的接收器。您可以透過下列幾種方式,限制應用程式接收的廣播:

    • 您可以在註冊廣播接收器時指定權限。
    • 如果是資訊清單宣告的接收器,您可以在資訊清單中將 android:exported 屬性設為「false」。接收器不會接收來自應用程式外部來源的廣播。
  • 廣播動作的命名空間是全域性質。請確認動作名稱和其他字串是以您擁有的命名空間編寫。否則可能會不小心與其他應用程式發生衝突。

  • 由於接收器的 onReceive(Context, Intent) 方法會在主執行緒上執行,因此應快速執行並傳回。如需執行長時間執行的工作,請務必小心產生執行緒或啟動背景服務,因為系統可能會在 onReceive() 傳回後終止整個程序。詳情請參閱「對程序狀態的影響」。如要執行長時間執行的工作,建議您:

    • 在接收器的 onReceive() 方法中呼叫 goAsync(),並將 BroadcastReceiver.PendingResult 傳遞至背景執行緒。這樣一來,從 onReceive() 返回後,廣播就會保持啟用狀態。不過,即使採用這種方法,系統仍會要求您在極短時間內 (10 秒內) 完成廣播。但可讓您將工作移至其他執行緒,避免主執行緒發生故障。
    • 使用 JobScheduler 安排工作。詳情請參閱「智慧型工作排程」。
  • 請勿從廣播接收器啟動活動,因為使用者體驗會不協調,尤其是在有多個接收器的情況下。建議改為顯示通知。