使用者可透過 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_WALLET
true
- 如果錢包顯示在螢幕鎖定畫面上,解鎖手機會導致系統重新查詢卡片,因此卡片內容可能會有所不同。
無障礙測試
- 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 付款方式。