筆記是 Android 的核心功能,可提高使用者在大螢幕裝置上的工作效率。筆記應用程式可讓使用者在浮動視窗或全螢幕畫面中撰寫和草圖、擷取螢幕畫面內容並加上註解,以及儲存附註以供日後查看和修訂。
使用者可以透過螢幕鎖定畫面或執行其他應用程式時存取筆記應用程式。
支援使用觸控筆做記事,帶來卓越的使用者體驗。
「記事」角色
RoleManager.ROLE_NOTES
角色可識別筆記應用程式,並授予 LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE
權限。
如要取得應用程式的記事角色,請按照下列步驟操作:
- 呼叫
isRoleAvailable()
查看角色狀態。 - 如果有可用的筆記角色,請呼叫
createRequestRoleIntent()
來取得附註專屬意圖。 - 使用附註意圖呼叫
startActivityForResult()
,提示使用者將附註角色授予應用程式。
只有一個應用程式可擁有記事角色。
系統會開啟應用程式,以回應隱含的 ACTION_CREATE_NOTE
意圖動作。如果你是從裝置螢幕鎖定畫面叫用,應用程式會開啟全螢幕;如果在螢幕解鎖後叫用,會在浮動視窗中使用。
應用程式資訊清單
如要取得附註角色的資格,應用程式必須在應用程式資訊清單中加入下列宣告:
<activity
android:name="YourActivityName"
android:exported="true"
android:showWhenLocked="true"
android:turnScreenOn="true">
<intent-filter>
<action android:name="android.intent.action.CREATE_NOTE" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>
該宣告可讓使用者將記事角色指派給應用程式,將其設為預設的筆記應用程式:
ACTION_CREATE_NOTE
可設定應用程式回應的意圖動作showWhenLocked
可讓您從裝置螢幕鎖定畫面存取應用程式turnScreenOn
可讓應用程式在應用程式執行時開啟裝置螢幕
應用程式功能
大螢幕差異化的筆記應用程式已全面補充筆記功能。
觸控筆支援
透過設為 true
的 EXTRA_USE_STYLUS_MODE
意圖額外項目叫用應用程式時,應用程式應開啟可接受觸控筆 (或手指觸控) 輸入內容的附註。
如果意圖額外項目設為 false
,應用程式應開啟一則接受鍵盤輸入內容的附註。
螢幕鎖定畫面存取權
應用程式必須提供全螢幕活動,讓應用程式在裝置螢幕鎖定畫面上開啟時執行。
只有在使用者同意 (在解鎖裝置狀態處於解鎖狀態) 顯示過去的附註時,應用程式才應該顯示歷史附註。否則,從螢幕鎖定畫面開啟應用程式時,應用程式應一律建立新記事。
您可以使用 KeyguardManager#isKeyguardLocked()
,檢查應用程式是否已從螢幕鎖定畫面啟動。如要要求使用者驗證及解鎖裝置,請呼叫 KeyguardManager#requestDismissKeyguard()
:
Kotlin
val keyguardManager = getSystemService(KEYGUARD_SERVICE) as KeyguardManager keyguardManager.requestDismissKeyguard( this, object : KeyguardDismissCallback() { override fun onDismissError() { // Unlock failed. Dismissing keyguard is not feasible. } override fun onDismissSucceeded() { // Unlock succeeded. Device is now unlocked. } override fun onDismissCancelled() { // Unlock failed. User cancelled operation or request otherwise cancelled. } })
Java
KeyguardManager keyguardManager = (KeyguardManager) getSystemService(KEYGUARD_SERVICE); boolean isLocked = keyguardManager.isKeyguardLocked(); keyguardManager.requestDismissKeyguard( this, new KeyguardManager.KeyguardDismissCallback() { @Override public void onDismissError() { // Unlock failed. Dismissing keyguard is not feasible. } @Override public void onDismissSucceeded() { // Unlock succeeded. Device is now unlocked. } @Override public void onDismissCancelled() { // Unlock failed. User cancelled operation or request otherwise cancelled. } });
浮動視窗
針對情境式筆記,應用程式必須提供一項活動,當另一個應用程式執行時,會在浮動視窗中開啟。
您的應用程式應支援 multi-instance
模式,如此一來,即使筆記應用程式啟動為全螢幕模式或處於分割畫面模式,使用者還是可以在多個浮動視窗中建立多個記事。
內容擷取
內容擷取是記事應用程式的重要功能,透過內容擷取,使用者可以在筆記應用程式的浮動視窗後方擷取螢幕螢幕截圖。使用者可以擷取螢幕畫面的全部或部分畫面,將內容貼入筆記,也可以為擷取的內容加上註解或醒目顯示。
筆記應用程式應提供 UI 功能提示,用於啟動 registerForActivityResult()
建立的 ActivityResultLauncher
。ACTION_LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE
意圖動作會直接提供給啟動器,或透過 ActivityResultContract
提供。
系統活動會擷取內容並將內容儲存在裝置上,然後在 registerForActivityResult()
的回呼引數中將內容 URI 傳回應用程式。
以下範例使用一般的 StartActivityForResult
合約:
Kotlin
private val startForResult = registerForActivityResult( ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> if (result.resultCode == Intent.CAPTURE_CONTENT_FOR_NOTE_SUCCESS) { val uri = result.data?.data // Use the URI to paste the captured content into the note. } } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContent { NotesTheme { Surface(color = MaterialTheme.colorScheme.background) { CaptureButton( onClick = { Log.i("ContentCapture", "Launching intent...") startForResult.launch(Intent(ACTION_LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE)) }) } } } } @Composable fun CaptureButton(onClick: () -> Unit) { Button(onClick = onClick) {Text("Capture Content")} }
Java
private final ActivityResultLauncher<Intent> startForResult = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), result -> { if (result.getResultCode() == Intent.CAPTURE_CONTENT_FOR_NOTE_SUCCESS) { Uri uri = result.getData() != null ? result.getData().getData() : null; // Use the URI to paste the captured content into the note. } }); @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); Button captureButton = findViewById(R.id.capture_button); captureButton.setOnClickListener( view -> { Log.i("ContentCapture", "Launching intent..."); startForResult.launch(new Intent(ACTION_LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE)); }); }
應用程式應處理所有結果代碼:
CAPTURE_CONTENT_FOR_NOTE_SUCCESS
CAPTURE_CONTENT_FOR_NOTE_FAILED
CAPTURE_CONTENT_FOR_NOTE_USER_CANCELED
CAPTURE_CONTENT_FOR_NOTE_WINDOW_MODE_UNSUPPORTED
CAPTURE_CONTENT_FOR_NOTE_BLOCKED_BY_ADMIN
內容擷取成功後,請將擷取的圖片貼到筆記中,例如:
Kotlin
registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> if (result.resultCode == Intent.CAPTURE_CONTENT_FOR_NOTE_SUCCESS) { val uri = result.data?data // Use the URI to paste the captured content into the note. } }
Java
registerForActivityResult(new ActivityResultContracts.StartActivityForResult(), result -> { if (result.getResultCode() == Intent.CAPTURE_CONTENT_FOR_NOTE_SUCCESS) { Uri uri = result.getData() != null ? result.getData().getData() : null; // Use the URI to paste the captured content into the note. } });
只有在筆記應用程式於浮動視窗中執行 (而非從裝置螢幕鎖定畫面啟動) 執行時,內容擷取功能才應透過 UI 功能提示提供。(使用者可以使用裝置螢幕截圖功能,擷取筆記應用程式本身的螢幕截圖)。
如要判斷應用程式是否位於浮動視窗 (或對話框) 中,請呼叫下列方法:
isLaunchedFromBubble()
可檢查筆記應用程式並未從裝置螢幕鎖定畫面啟動全螢幕isRoleHeld(RoleManager.ROLE_NOTES)
可驗證應用程式是否為預設的筆記應用程式 (如果應用程式沒有附註角色,應用程式則可在對話或其他類型的泡泡中執行)