记事是 Android 的一项核心功能,可提高用户在大屏设备上的工作效率。借助笔记应用,用户可以在浮动窗口或全屏窗口中撰写和素描,截取屏幕内容并为其添加注释,以及保存笔记以供日后查看和修订。
用户可以在锁定屏幕上或在运行其他应用时访问记事应用。
触控笔支持记事,可提供卓越的用户体验。
“记事”角色
RoleManager.ROLE_NOTES
角色可识别记事应用,并向其授予 LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE
权限。
如需为您的应用获取备注角色,请执行以下操作:
- 调用
isRoleAvailable()
以检查角色的状态。 - 如果“记事”角色可用,请调用
createRequestRoleIntent()
以获取记事专用 intent。 - 使用备注 intent 调用
startActivityForResult()
,以提示用户向您的应用授予备注角色。
只能有一个应用具有备注角色。
应用为响应隐式 ACTION_CREATE_NOTE
intent 操作而打开。从设备锁定屏幕调用时,应用会全屏打开;如果在屏幕处于解锁状态时调用,则会在浮动窗口中打开。
应用清单
为了满足“记事”角色的申请条件,您的应用必须在应用清单中添加以下声明:
<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
设置应用响应的 intent 操作showWhenLocked
:使您的应用可从设备锁定屏幕访问turnScreenOn
可让应用在运行时开启设备屏幕
应用功能
一款与众不同的大屏记事应用,提供全面的记事功能。
触控笔支持
通过将 EXTRA_USE_STYLUS_MODE
intent extra 设置为 true
来调用您的应用时,应用应打开一条接受触控笔(或手指触摸)输入的记事。
如果 intent extra 设置为 false
,您的应用应打开一条接受键盘输入的记事。
锁屏访问
您的应用必须提供在从设备锁定屏幕打开应用时运行的全屏 activity。
如果用户同意(在设备处于解锁状态时)显示过去的记事,您的应用应仅显示历史记事。否则,当从锁定屏幕打开时,您的应用应始终创建新记事。
您可以使用 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. } });
悬浮窗口
对于上下文记事,您的应用必须提供一个在其他应用运行时在浮动窗口中打开的 activity。
您的应用应支持 multi-instance
模式,这样,即使记事应用在全屏模式或分屏模式下启动,用户仍可在多个浮动窗口中创建多个记事。
内容捕获
内容捕获是记事应用的一项关键功能。借助内容捕获功能,用户可以截取记事应用的浮动窗口背后显示内容的屏幕截图。用户可以截取整个或部分显示画面,将内容粘贴到记事中,并对截取的内容添加注释或突出显示。
记事应用应提供一种界面功能,用于启动由 registerForActivityResult()
创建的 ActivityResultLauncher
。ACTION_LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE
intent 操作可直接或通过 ActivityResultContract
提供给启动器。
系统 activity 捕获内容,将其保存在设备上,并在 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. } });
仅当您的记事应用在浮动窗口中运行时(而不是当全屏运行(从设备锁定屏幕启动)时,才应通过界面功能提供内容捕获功能。(用户可以使用设备屏幕截图功能截取记事应用本身的屏幕截图)。
如需确定应用是否在浮动窗口(或气泡)中,请调用以下方法:
isLaunchedFromBubble()
,用于检查您的记事应用是否未在设备锁定屏幕上全屏启动isRoleHeld(RoleManager.ROLE_NOTES)
,用于验证您的应用是否为默认的记事应用(如果应用不具有记事角色,则可以在对话或其他类型的气泡中运行)