إنشاء تطبيق لتدوين الملاحظات

يُعد تدوين الملاحظات من الميزات الأساسية في Android التي تعزز إنتاجية المستخدمين على الأجهزة ذات الشاشات الكبيرة. تمكن تطبيقات تدوين الملاحظات المستخدمين من الكتابة والرسم في نافذة عائمة أو على الشاشة الكاملة والتقاط محتوى الشاشة وإضافة تعليقات توضيحية إليه وحفظ الملاحظات لمراجعتها ومراجعتها لاحقًا.

يمكن للمستخدمين الوصول إلى تطبيقات تدوين الملاحظات من شاشة القفل أو أثناء تشغيل تطبيقات أخرى.

تتيح ميزة تدوين الملاحظات باستخدام قلم الشاشة تجربة استثنائية للمستخدمين.

دور الملاحظات

يحدد الدور RoleManager.ROLE_NOTES تطبيقات تدوين الملاحظات ويمنحها الإذن LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE.

للحصول على دور الملاحظات في تطبيقك، عليك اتّباع الخطوات التالية:

1. يمكنك طلب isRoleAvailable() للتحقّق من حالة الدور.
2. إذا كان دور الملاحظات متاحًا، يمكنك استدعاء createRequestRoleIntent() للحصول على هدف خاص بالملاحظات.
3. يمكنك استدعاء startActivityForResult() مع تضمين الملاحظات بهدف مطالبة المستخدم بمنح دور الملاحظات إلى تطبيقك.

يمكن لتطبيق واحد فقط امتلاك دور الملاحظات.

يتم فتح التطبيق استجابةً لإجراء ACTION_CREATE_NOTE ضمني. إذا تم استدعاؤه من شاشة قفل الجهاز، يفتح التطبيق في وضع ملء الشاشة، وإذا تم استدعاؤه أثناء فتح قفل الشاشة، في نافذة عائمة.

ملاحظة: في إعدادات النظام، يمكن للمستخدمين إيقاف الحصول على تطبيق تلقائي لتدوين الملاحظات، وفي هذه الحالة لن يستجيب أي تطبيق لإجراء 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 لتطبيقك تشغيل شاشة الجهاز عند تشغيل التطبيق

ميزات التطبيق

يوفِّر تطبيق تدوين الملاحظات المتمايز ذي الشاشة الكبيرة مجموعة كاملة من إمكانات تدوين الملاحظات.

التوافق مع قلم الشاشة

عند استدعاء تطبيقك مع ضبط الرغبة الإضافية EXTRA_USE_STYLUS_MODE على true، من المفترض أن يفتح التطبيق ملاحظة تقبل إدخال قلم الشاشة (أو اللمس بالأصابع).

إذا تم ضبط intent الإضافية على false، من المفترض أن يفتح تطبيقك ملاحظة تقبل إدخال لوحة المفاتيح.

الوصول إلى شاشة القفل

يجب أن يوفّر تطبيقك نشاطًا بملء الشاشة يتم تشغيله عند فتح التطبيق من شاشة قفل الجهاز.

يجب أن يعرض تطبيقك الملاحظات السابقة فقط إذا وافق المستخدم على عرض الملاحظات السابقة (في حالة فتح قفل الجهاز). بخلاف ذلك، يجب أن ينشئ تطبيقك دائمًا ملاحظة جديدة عند فتحه من شاشة القفل.

يمكنك التحقّق مما إذا تم تشغيل تطبيقك من شاشة القفل باستخدام 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.
        }
    }
)

تحذير: عند تشغيل التطبيق من شاشة قفل الجهاز، يجب أن يضمن تطبيقك خصوصية المستخدم.

نوافذ عائمة

لتدوين الملاحظات حسب السياق، يجب أن يوفّر تطبيقك نشاطًا يفتح في نافذة عائمة عند تشغيل تطبيق آخر.

يجب أن يتيح تطبيقك استخدام وضع multi-instance لكي يتمكّن المستخدمون من إنشاء ملاحظات متعددة في نوافذ عائمة متعددة حتى عند تشغيل تطبيق تدوين الملاحظات في وضع ملء الشاشة أو في وضع تقسيم الشاشة.

تسجيل المحتوى

تسجيل المحتوى هو ميزة رئيسية لتطبيقات تدوين الملاحظات. باستخدام ميزة التقاط المحتوى، يمكن للمستخدمين التقاط لقطات شاشة للشاشة خلف النافذة العائمة لتطبيق تدوين الملاحظات. يمكن للمستخدمين التقاط الشاشة بالكامل أو جزء منها، ولصق المحتوى في ملاحظتهم، وإضافة تعليقات توضيحية على المحتوى الذي تم التقاطه أو تمييزه.

يجب أن يوفّر تطبيق تدوين الملاحظات عنصر واجهة مستخدم يؤدي إلى تشغيل ActivityResultLauncher تم إنشاؤه من قِبل registerForActivityResult(). يتم توفير إجراء نية ACTION_LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE لمشغّل التطبيقات إما مباشرةً أو من خلال ActivityResultContract.

يلتقط نشاط النظام المحتوى ويحفظه على الجهاز ويعرض معرّف الموارد المنتظم (URI) للمحتوى إلى تطبيقك في وسيطة معاودة الاتصال للسمة registerForActivityResult().

يستخدم المثال التالي عقد StartActivityForResult عام:

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.
        }
}

يجب إظهار ميزة التقاط المحتوى من خلال واجهة المستخدم فقط عندما يكون تطبيق تدوين الملاحظات قيد التشغيل في نافذة عائمة، وليس عند تشغيل وضع ملء الشاشة الذي يتم تشغيله من شاشة قفل الجهاز. (يمكن للمستخدمين أخذ لقطات شاشة لتطبيق تدوين الملاحظات نفسه مع إمكانات لقطات الشاشة على الجهاز).

لتحديد ما إذا كان تطبيقك في نافذة عائمة (أو فقاعة)، يمكنك استدعاء الطرق التالية:

• isLaunchedFromBubble() للتأكد من أنه لم يتم تشغيل تطبيق تدوين الملاحظات في وضع ملء الشاشة من شاشة قفل الجهاز
• isRoleHeld(RoleManager.ROLE_NOTES) للتأكّد من أنّ تطبيقك هو تطبيق تدوين الملاحظات التلقائي (يمكن أن يعمل تطبيقك في محادثة أو في أي نوع آخر من فقاعات المحادثات إذا لم يكن للتطبيق دور تدوين الملاحظات)

ملاحظة: يجب أن يتحقق تطبيقك مما إذا كانت السياسات الإدارية للأجهزة تسمح بالتقاط المحتوى. استدعِ getScreenCaptureDisabled() مع استخدام null كوسيطة.

مصادر إضافية

• الحصول على نتيجة من نشاط