记事是 Android 的一项核心功能,可提高大屏设备的用户效率。记事应用可让用户在浮动窗口或全屏模式下书写和绘画、捕获和注释屏幕内容,以及保存笔记以供日后查看和修改。
用户可以从锁屏界面或在运行其他应用时访问记事应用。
记事功能支持手写笔,提供卓越的用户体验。
笔记角色
角色用于标识记事应用,并授予它们 RoleManager.ROLE_NOTES
权限。LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE
如需为您的应用获取笔记角色,请执行以下操作
- 调用
以检查角色的状态。isRoleAvailable()
- 如果笔记角色可用,请调用
以获取笔记专用 Intent。createRequestRoleIntent()
- 使用笔记 Intent 调用
,以提示用户向您的应用授予笔记角色。startActivityForResult()
只有一个应用可以拥有笔记角色。
应用会响应隐式
Intent 操作而打开。如果从设备锁屏界面调用,应用会全屏打开;如果屏幕解锁时调用,则会在浮动窗口中打开。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>
该声明让用户可以将笔记角色分配给您的应用,使其成为默认的记事应用
设置了您的应用会响应的 Intent 操作ACTION_CREATE_NOTE
使您的应用可从设备锁屏界面访问showWhenLocked
可让您的应用在运行时打开设备屏幕turnScreenOn
应用功能
一款差异化的大屏记事应用提供了全套的记事功能。
手写笔支持
当通过将
Intent extra 设为 EXTRA_USE_STYLUS_MODE
true
来调用您的应用时,应用应打开接受手写笔(或手指触摸)输入的笔记。
如果 Intent extra 设为 false
,您的应用应打开接受键盘输入的笔记。
锁屏访问
您的应用必须提供一个全屏 Activity,以便在应用从设备锁屏界面打开时运行。
如果用户已同意(在设备解锁状态下)显示过去的笔记,则您的应用应仅显示历史笔记。否则,当从锁屏界面打开时,您的应用应始终创建新笔记。
您可以使用
检查您的应用是否从锁屏界面启动。如需请求用户进行身份验证并解锁设备,请调用 KeyguardManager#isKeyguardLocked()
KeyguardManager#requestDismissKeyguard()
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. }
} )
浮动窗口
对于上下文记事,您的应用必须提供一个 Activity,以便在另一个应用运行时在浮动窗口中打开。
您的应用应支持
模式,以便用户即使在记事应用全屏或分屏模式下启动时,也可以在多个浮动窗口中创建多个笔记。multi-instance
内容捕获
内容捕获是记事应用的一项关键功能。通过内容捕获,用户可以截取记事应用浮动窗口后方显示屏的屏幕截图。用户可以捕获显示屏的全部或部分内容,将内容粘贴到笔记中,并对捕获的内容进行注释或突出显示。
您的记事应用应提供一个 UI 触发元素,用于启动由
创建的 registerForActivityResult()
。ActivityResultLauncher
Intent 操作将直接或通过 ACTION_LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE
提供给启动器。ActivityResultContract
系统 Activity 会捕获内容并将其保存到设备上,然后通过 registerForActivityResult()
的回调参数将内容 URI 返回给您的应用。
以下示例使用通用
contractStartActivityForResult
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")} }
您的应用应处理所有结果代码
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
内容捕获成功后,将捕获的图片粘贴到笔记中,例如
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. } }
内容捕获功能应仅在您的记事应用在浮动窗口中运行时通过 UI 触发元素公开,而不是在全屏运行或从设备锁屏界面启动时。 (用户可以使用设备截图功能截取记事应用本身的屏幕截图。)
要确定您的应用是否在浮动窗口(或气泡)中,请调用以下方法
用于检查您的记事应用是否未从设备锁屏界面全屏启动isLaunchedFromBubble()
用于验证您的应用是否是默认记事应用(如果您的应用不拥有笔记角色,它可以在对话或其他类型的气泡中运行)isRoleHeld(RoleManager.ROLE_NOTES)