使用者可透過 Android 11 以上版本提供的「快速存取電子錢包」功能,直接從電源鍵選單存取付款卡和相關票證。主要用途包括在 NFC 終端機進行交易前選取適當的付款方式,以及快速存取即將到來活動的航班和其他票證。
在 Android 12 以上版本中,如圖 1 和圖 2 所示,你可以從陰影區域使用「快速存取錢包」功能。
![]() |
![]() |
在 Android 11 中,這項功能會顯示在電源鍵選單中,如圖 3 所示。

需求條件
裝置必須支援 NFC,才能使用快速存取錢包功能。這項功能會繫結至預設 NFC 付款應用程式的 QuickAccessWalletService,因此裝置也必須支援 NFC 主機卡片模擬 (HCE)。
功能總覽
快速存取錢包分為兩部分:快速存取錢包使用者介面和快速存取錢包卡片供應商。
在 Android 12 以上版本中,錢包 UI 會在系統 UI 中執行,且位於 frameworks/base/packages/SystemUI/src/com/android/systemui/wallet。在 Android 11 中,位於 platform/packages/apps/QuickAccessWallet 的錢包 UI 必須安裝並列入許可清單。
快速存取錢包卡片供應商是預設的 NFC 付款應用程式。使用者可以同時安裝多個 NFC 付款應用程式,但只有預設 NFC 付款應用程式可以在電源鍵選單中顯示卡片。您可以指定一開始的預設 NFC 付款應用程式,但使用者可以在「設定」中選取其他應用程式。如果只安裝一個 NFC 付款應用程式,系統會自動將其設為預設應用程式 (請參閱 CardEmulationManager)。
實作
如要將卡片提供給快速存取錢包 UI,NFC 支付應用程式必須實作 QuickAccessWalletService。付款應用程式必須包含宣傳服務的資訊清單項目。
為確保只有系統 UI 可以繫結至 QuickAccessWalletService,NFC 付款應用程式必須要求 android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE 權限。要求這項權限可確保只有系統 UI 能繫結至 QuickAccessWalletService。
<service
android:name=".MyQuickAccessWalletService"
android:label="@string/my_default_tile_label"
android:icon="@drawable/my_default_icon_label"
android:logo="@drawable/my_wallet_logo"
android:permission="android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE">
<intent-filter>
<action android:name="android.service.quickaccesswallet.QuickAccessWalletService" />
<category android:name="android.intent.category.DEFAULT"/>
</intent-filter>
<meta-data android:name="android.quickaccesswallet"
android:resource="@xml/quickaccesswallet_configuration" />
<meta-data
android:name="android.quickaccesswallet.tile"
android:resource="@drawable/my_default_tile_icon"/>
</service>
連結的 XML 檔案包含錢包的其他資訊:
<quickaccesswallet-service
xmlns:android="http://schemas.android.com/apk/res/android"
android:settingsActivity="com.example.android.SettingsActivity"
android:shortcutLongLabel="@string/my_wallet_empty_state_text"
android:shortcutShortLabel="@string/my_wallet_button_text"
android:targetActivity="com.example.android.WalletActivity"/>
接著,付款應用程式必須實作 QuickAccessWalletService:
public class MyQuickAccessWalletService extends QuickAccessWalletService {
@Override
public void onWalletCardsRequested(
GetWalletCardsRequest request,
GetWalletCardsCallback callback) {
GetWalletCardsResponse response = // generate response
callback.onSuccess(response);
}
@Override
public void onWalletCardSelected(SelectWalletCardRequest request) {
// selecting a card should ensure that it is used when making an NFC payment
}
@Override
public void onWalletDismissed() {
// May un-select card if the wallet app has the concept of a 'default'
// payment method
}
}
如果 HostApduService 開始處理 NFC 交易,並因此啟動活動來顯示付款進度和結果,也應嘗試取得繫結 QuickAccessWalletService 的參照,並使用 TYPE_NFC_PAYMENT_STARTED 的事件類型呼叫 QuickAccessWalletService#sendEvent。這會導致快速存取錢包使用者介面遭到關閉,讓使用者能清楚查看付款活動。
如需導入 QuickAccessWalletService 的其他說明文件,請參閱
QuickAccessWalletService
和
TestQuickAccessWalletService
CTS 測試。
在 Android 11 中啟用「快速存取電子錢包」使用者介面
如要設定在 Android 11 的電源選單中顯示快速存取錢包,請在建構作業中加入 QuickAccessWallet 目標,並將下方程式碼範例中以粗體顯示的程式碼行新增至 overlay/frameworks/base/packages/SystemUI/res/values/config.xml 檔案,啟用 globalactions.wallet 外掛程式。
<resources> ... <!-- SystemUI Plugins that can be loaded on user builds. --> <string-array name="config_pluginWhitelist" translatable="false"> <item>com.android.systemui</item> <item>com.android.systemui.plugin.globalactions.wallet</item> </string-array> </resources>
在設定設定檔中使用 def_nfc_payment_component 指定預設的 NFC 付款應用程式。
預設 NFC 付款應用程式必須公開
QuickAccessWalletService
,才能將卡片提供給快速存取錢包。如果預設的 NFC 付款應用程式未匯出這項服務,錢包使用者介面就會隱藏。
QuickAccessWalletService 實作詳細資料
QuickAccessWalletService 包含三種必須實作的抽象方法:onWalletCardsRequested、onWalletCardSelected 和 onWalletDismissed。下方的序列圖說明在 NFC 付款前立即查看快速存取錢包時的呼叫序列。
並非每次查看快速存取錢包後都會進行 NFC 付款,但上方的圖 4 說明瞭 QuickAccessWalletService 的所有功能。在本範例中,快速存取錢包卡片供應商會實作以藍色標示的元素。假設付款卡儲存在裝置的資料庫中,並透過名為 PaymentCardManager 的介面存取。此外,我們也假設名為 PaymentActivity 的活動會顯示 NFC 付款結果。流程如下:
- 使用者執行手勢,開啟快速存取錢包。
快速存取錢包 UI (屬於系統 UI) 會檢查套件管理員,確認預設 NFC 付款應用程式是否匯出
QuickAccessWalletService。- 如果未匯出服務,系統就不會顯示快速存取錢包。
快速存取電子錢包 UI 會繫結至
QuickAccessWalletService,並呼叫onWalletCardsRequested。這個方法會接收要求物件,其中包含可提供的卡片數量和大小相關資料,以及回呼。回呼可從背景執行緒呼叫。QuickAccessWalletService會計算要顯示的資訊卡,然後在提供的回呼中呼叫onSuccess方法。建議服務在背景執行緒執行這些動作。卡片一顯示,系統 UI 就會呼叫
QuickAccessWalletService,通知onWalletCardSelected已選取第一張卡片。- 每當使用者選取新卡片,就會呼叫
onWalletCardSelected。 - 即使目前選取的卡片未變更,系統也可能會呼叫
onWalletCardSelected。
- 每當使用者選取新卡片,就會呼叫
使用者關閉快速存取 Google 錢包時,系統 UI 會呼叫
onWalletDismissed,通知QuickAccessWalletService。
在上述範例中,使用者在顯示錢包時,將手機帶到 NFC 支付終端機的感應範圍內。處理 NFC 付款的重要元件是 HostApduService,必須實作這個元件,才能處理 NFC 讀取器提供的 APDU (詳情請參閱「以主機為基礎的卡片模擬」)。假設付款應用程式會啟動活動,顯示與 NFC 終端機互動的進度和結果。不過,快速存取錢包使用者介面會顯示在應用程式視窗上方,因此付款活動會遭到遮蔽。如要修正這個問題,應用程式必須通知系統 UI 應關閉快速存取錢包 UI。方法是取得繫結 QuickAccessWalletService 的參照,然後呼叫 sendWalletServiceEvent 並傳入事件類型 TYPE_NFC_PAYMENT_STARTED。
QuickAccessWalletService 範例實作
/** Sample implementation of {@link QuickAccessWalletService} */
@RequiresApi(VERSION_CODES.R)
public class MyQuickAccessWalletService extends QuickAccessWalletService {
private static final String TAG = "QAWalletSvc";
private ExecutorService executor;
private PaymentCardManager paymentCardManager;
@Override
public void onCreate() {
super.onCreate();
if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
Log.w(TAG, "Should not run on pre-R devices");
stopSelf();
return;
}
executor = Executors.newSingleThreadExecutor();
paymentCardManager = new PaymentCardManager();
}
@Override
public void onDestroy() {
if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
return;
}
executor.shutdownNow();
}
@Override
public void onWalletCardsRequested(
@NonNull GetWalletCardsRequest request, @NonNull GetWalletCardsCallback callback) {
if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
return;
}
executor.submit(
() -> {
List<PaymentCard> paymentCards = paymentCardManager.getCards();
int maxCards = Math.min(paymentCards.size(), request.getMaxCards());
List<WalletCard> walletCards = new ArrayList<>(maxCards);
int selectedIndex = 0;
int cardWidthPx = request.getCardWidthPx();
int cardHeightPx = request.getCardHeightPx();
for (int index = 0; index < maxCards; index++) {
PaymentCard paymentCard = paymentCards.get(index);
WalletCard walletCard =
new WalletCard.Builder(
paymentCard.getCardId(),
paymentCard.getCardImage(cardWidthPx, cardHeightPx),
paymentCard.getContentDescription(),
paymentCard.getPendingIntent())
.build();
walletCards.add(walletCard);
if (paymentCard.isSelected()) {
selectedIndex = index;
}
}
GetWalletCardsResponse response =
new GetWalletCardsResponse(walletCards, selectedIndex);
callback.onSuccess(response);
});
}
@Override
public void onWalletCardSelected(@NonNull SelectWalletCardRequest request) {
if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
return;
}
executor.submit(
() -> paymentCardManager.selectCardById(request.getCardId()));
}
@Override
public void onWalletDismissed() {
if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
return;
}
executor.submit(() -> {
paymentCardManager.removeCardOverrides();
});
}
}
如要進一步瞭解 QuickAccessWalletService,請參閱 QuickAccessWalletService API 參考資料。
權限
QuickAccessWalletService 的資訊清單項目必須要求 Android 11 中導入的 android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE 權限。這是 System UI 持有的簽章層級權限,也就是說,只有 System UI 程序可以繫結至 QuickAccessWalletService 的實作項目。請注意,側載應用程式可以聲明這項權限,並完整存取搭載 Android 10 以下版本裝置上的 QuickAccessWalletService 資料。為避免發生這種情況,建議服務在 onCreate 中檢查建構版本,並僅在搭載 Android 11 以上版本的裝置上啟用服務。除了提供主機卡模擬付款服務所需的權限外,您不需要其他應用程式權限。
如果預設 NFC 付款應用程式未實作或匯出 QuickAccessWalletService,系統就不會顯示快速存取錢包使用者介面。
Android 12 設定
如要啟用或停用從螢幕鎖定畫面快速存取電子錢包的功能,使用者可以前往「設定」 >「螢幕」 >「螢幕鎖定」,然後使用「顯示電子錢包」切換按鈕。如要停用錢包,使用者必須在快速設定選單中手動編輯。
圖 5. 在「設定」的「螢幕鎖定」頁面中顯示「錢包」切換鈕。
Android 11 中的設定
使用者可以在「設定」應用程式中關閉「快速存取錢包」功能。如要前往設定頁面,請依序輕觸「設定」>「系統」>「手勢」>「卡片和票證」。

自訂
在系統 UI 的其他位置新增「快速存取錢包」檢視畫面
快速存取電子錢包使用者介面是系統外掛程式。雖然 AOSP 實作會使用 GlobalActionsDialog (長按電源鍵時顯示),但只要維持外掛程式介面指定的合約,您就可以將這項功能移至其他手勢。
public interface GlobalActionsPanelPlugin extends Plugin {
/** Invoked when the view is shown */
PanelViewController onPanelShown(Callbacks callbacks, boolean deviceLocked);
/** Callbacks for interacting with the view container */
interface Callbacks {
/** Dismisses the view */
void dismissGlobalActionsMenu();
/** Starts a PendingIntent, dismissing the keyguard if necessary. */
void startPendingIntentDismissingKeyguard(PendingIntent pendingIntent);
}
/** Provides the Quick Access Wallet view */
interface PanelViewController {
/** Returns the QuickAccessWallet view, which may take any size */
View getPanelContent();
/** Invoked when the view is dismissed */
void onDismissed();
/** Invoked when the device is either locked or unlocked. */
void onDeviceLockStateChanged(boolean locked);
}
}
「快速存取電子錢包」使用者介面會實作 GlobalActionsPanelPlugin 和 PanelViewController。GlobalActionsDialog 使用 com.android.systemui.Dependency 取得錢包外掛程式的例項:
GlobalActionsPanelPlugin mPanelPlugin =
Dependency.get(ExtensionController.class)
.newExtension(GlobalActionsPanelPlugin.class)
.withPlugin(GlobalActionsPanelPlugin.class)
.build()
.get();
確認外掛程式為非空值,且 onPanelShown 傳回的 PanelViewController 為非空值後,對話方塊會將 getPanelContent 提供的 View 附加至自己的 View,並為系統事件提供適當的回呼。
// Construct a Wallet PanelViewController.
// `this` implements GlobalActionsPanelPlugin.Callbacks
GlobalActionsPanelPlugin.PanelViewController mPanelController =
mPanelPlugin.onPanelShown(this, !mKeyguardStateController.isUnlocked());
// Attach the view
FrameLayout panelContainer = findViewById(R.id.my_panel_container);
FrameLayout.LayoutParams panelParams =
new FrameLayout.LayoutParams(
FrameLayout.LayoutParams.MATCH_PARENT,
FrameLayout.LayoutParams.MATCH_PARENT);
panelContainer.addView(mPanelController.getPanelContent(), panelParams);
// Respond to unlock events (if the view can be accessed while the phone is locked)
keyguardStateController.addCallback(new KeyguardStateController.Callback() {
@Override
public void onUnlockedChanged() {
boolean unlocked = keyguardStateController.isUnlocked()
|| keyguardStateController.canDismissLockScreen();
mPanelController.onDeviceLockStateChanged(unlocked);
}
});
// Implement GlobalActionsPanelPlugin.Callbacks
@Override
public void dismissGlobalActionsMenu() {
dismissDialog();
}
@Override
public void startPendingIntentDismissingKeyguard(PendingIntent pendingIntent) {
mActivityStarter.startPendingIntentDismissingKeyguard(pendingIntent);
}
// Notify the wallet when the container view is dismissed
mPanelController.onDismissed();
如要從電源鍵選單中移除「快速存取錢包」,請從系統建構中省略 QuickAccessWallet 目標。如要從電源鍵選單中移除「快速存取錢包」,但將其新增至其他系統 UI 提供的檢視畫面,請加入建構目標,並移除對 GlobalActionsPanelPlugin 的參照 (來自 GlobalActionsImpl)。
設定預設設定
Android 12
在 Android 12 以上版本中,快速存取錢包一律會顯示在快速設定選單中。如要在螢幕鎖定畫面中顯示「快速存取錢包」,必須先啟用下列安全設定:
LOCKSCREEN_SHOW_WALLET。這項設定可控制鎖定畫面右下角是否顯示「快速存取錢包」圖示。這項設定預設為開啟 true,但使用者可以依序前往「設定」>「螢幕」>「螢幕鎖定」>「顯示 Google 錢包」 關閉這項設定。
Android 11
在 Android 11 中,快速存取錢包的顯示設定受兩項安全設定控管:GLOBAL_ACTIONS_PANEL_ENABLED 和 GLOBAL_ACTIONS_PANEL_AVAILABLE。AVAILABLE設定可控管是否能在「設定」中開啟及關閉這項功能。這項設定是由「true」WalletPluginService設為「true」。如果建構版本未包含 QuickAccessWallet,設定會維持 false。ENABLED 設定預設為 true,但使用者可以在「設定」中關閉。如要變更預設行為,請修改 WalletPluginService#enableFeatureInSettings。
驗證
如要驗證快速存取電子錢包的實作情形,請執行 CTS 和手動測試。外掛程式的變更也應執行隨附的 robolectric 測試。
CTS 測試
執行位於 cts/tests/quickaccesswallet 的 CTS 測試。
Android 12 手動測試
測試快速存取錢包的核心功能時,需要 NFC 支付終端機 (實體或虛擬) 和實作 QuickAccessWalletService (錢包應用程式) 的 NFC 支付應用程式。必須測試的核心功能包括:可用性、零狀態、卡片選取和螢幕鎖定行為。
適用地區
- 如果預設的 NFC 付款應用程式不支援這項功能,您就無法透過快速設定或螢幕鎖定存取快速存取錢包。
- 如果預設的 NFC 付款應用程式支援這項功能,即可在快速設定選單中存取「快速存取錢包」。
- 如果預設的 NFC 付款應用程式支援這項功能,且
LOCKSCREEN_SHOW_WALLET設定為true,即可在螢幕鎖定畫面上存取快速存取錢包。 - 如果預設的 NFC 付款應用程式支援這項功能,且
LOCKSCREEN_SHOW_WALLET設定為false,就無法在螢幕鎖定時使用快速存取錢包功能。
零狀態
如果啟用
QuickAccessWalletService並匯出,但未提供任何資訊卡,快速設定面板中的動態磚就會如圖 7 所示。點選動態磚會開啟預設的 NFC 付款應用程式。
圖 7. 陰影中的範例動態磚,顯示預設的 NFC 付款應用程式。
如圖 8 所示,點選空白狀態檢視畫面會開啟預設的 NFC 付款應用程式。只有在使用者錢包中只剩一張卡片,並從卡片詳細資料頁面移除卡片,然後返回錢包檢視畫面時,才會顯示這個空白狀態檢視畫面。
鎖定畫面上會顯示錢包圖示。
圖 8. 快速存取 Google 錢包使用者介面的空白狀態檢視畫面。
非零狀態
如果錢包應用程式提供一或多張卡片,陰影中的圖塊會如圖 9 所示。
圖 9.錢包應用程式有一或多張卡片時,通知陰影中的範例動態磚。
按一下動態磚會顯示資訊卡輪轉介面。
鎖定畫面上會顯示開啟「快速存取錢包」的按鈕。
圖 10. 快速存取錢包使用者介面,顯示一張卡片。
如果顯示的卡片代表 NFC 付款方式,將手機靠近 NFC 感應式刷卡機就會使用該付款方式,並關閉錢包檢視畫面。
按一下顯示的資訊卡,即可開啟該資訊卡的詳細活動記錄。
如果
QuickAccessWalletService提供多張卡片,使用者可以滑動切換卡片。溢位選單包含一個項目:開啟螢幕鎖定設定,讓使用者可以變更「顯示錢包」選項。
鎖定狀態測試
- 如果手機已上鎖,錢包會顯示在快速設定的陰影中。如果預設付款應用程式中沒有任何卡片,系統會顯示「新增卡片」說明;如果預設付款應用程式中有卡片,系統則會顯示「解鎖以使用」說明。
- 如果手機已鎖定,錢包在鎖定螢幕上的顯示狀態取決於
Secure.LOCKSCREEN_SHOW_WALLET設定,這項設定可在「設定」中控管。 - 如果手機已鎖定、
LOCKSCREEN_SHOW_WALLET為false,且預設 NFC 付款應用程式中沒有任何卡片,錢包就不會顯示在鎖定畫面上。 - 如果手機已鎖定、
LOCKSCREEN_SHOW_WALLET為true,且預設 NFC 付款應用程式中沒有任何卡片,錢包就不會顯示在鎖定畫面上。 - 如果手機已鎖定,且預設的 NFC 付款應用程式中有卡片,鎖定畫面上就會顯示錢包。
LOCKSCREEN_SHOW_WALLETtrue - 如果錢包顯示在螢幕鎖定畫面上,解鎖手機會導致系統重新查詢卡片,因此卡片內容可能會有所不同。
無障礙測試
- Talkback 使用者可以左右滑動,並聆聽卡片的內容說明,藉此瀏覽錢包檢視畫面。
- 啟用 TalkBack 後,向左和向右滑動即可依序選取每張資訊卡。 Talkback 使用者可以在 NFC 付款終端機選取並使用 NFC 付款方式。
Android 11 手動測試
測試快速存取錢包的核心功能時,需要 NFC 支付終端機 (實體或虛擬) 和實作 QuickAccessWalletService (錢包應用程式) 的 NFC 支付應用程式。必須測試的核心功能包括可用性、零狀態、卡片選取和螢幕鎖定行為。
適用地區
- 如果
GLOBAL_ACTIONS_PANEL_ENABLED設定為true,且預設 NFC 支付應用程式支援這項功能,即可存取快速存取 Google 錢包。 - 如果
GLOBAL_ACTIONS_PANEL_ENABLED設定為false,且預設 NFC 付款應用程式支援這項功能,則無法存取快速存取錢包。 - 如果
GLOBAL_ACTIONS_PANEL_ENABLED設定為true,且預設 NFC 付款應用程式不支援這項功能,就無法使用快速存取錢包。 - 如果
GLOBAL_ACTIONS_PANEL_ENABLED設定為false,且預設 NFC 付款應用程式不支援這項功能,就無法使用快速存取錢包。
零狀態
- 如果啟用
QuickAccessWalletService並匯出,但未提供任何卡片,快速存取錢包 UI 會顯示空白狀態檢視畫面。 按一下空白狀態檢視畫面,即可開啟錢包應用程式。
圖 11. 快速存取電子錢包 UI 中的空白狀態檢視畫面。
非零狀態
如果錢包應用程式提供一或多張卡片,這些卡片會顯示在快速存取錢包 UI 中。
圖 12. 顯示卡片的快速存取錢包使用者介面。 如果顯示的卡片代表 NFC 付款方式,將手機靠近 NFC 感應式刷卡機就會使用該付款方式,並關閉錢包檢視畫面。
點選顯示的卡片會關閉錢包檢視畫面,並開啟該卡片的詳細活動記錄。
如果
QuickAccessWalletService提供多張卡片,使用者可以滑動切換卡片。溢位選單包含兩個項目:一個會開啟錢包應用程式,另一個則會開啟「設定」中的「顯示卡片和票證」畫面。
鎖定狀態測試
- 如果手機已鎖定,錢包的顯示狀態取決於
Settings.Secure.POWER_MENU_LOCK_SHOW_CONTENT設定,您可以在「設定」中控管這項設定。 - 如果手機已鎖定且
POWER_MENU_LOCK_SHOW_CONTENT設為false,系統就不會顯示錢包。 - 如果手機已鎖定且
POWER_MENU_LOCK_SHOW_CONTENT處於true狀態,系統會顯示錢包。 - 在錢包顯示於螢幕鎖定畫面的情況下解鎖手機,系統會重新查詢卡片,因此卡片內容可能會有所不同。
無障礙測試
- TalkBack 使用者可以左右滑動,並聆聽資訊卡的內容說明,藉此瀏覽錢包檢視畫面。
- 啟用 TalkBack 後,向左和向右滑動即可依序選取每張卡片。 TalkBack 使用者可以在 NFC 支付終端機選取並使用 NFC 付款方式。
