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

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

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

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

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

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

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

1. يمكنك الاتصال بالرقم isRoleAvailable() للتحقّق من حالة الدور.
2. في حال توفّر دور الملاحظات، يمكنك استدعاء الرمز createRequestRoleIntent() للحصول على غرض خاص بالملاحظات.
3. عليك استدعاء 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 لتطبيقك تشغيل شاشة الجهاز عند تشغيله

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

يوفر تطبيق تدوين الملاحظات المميز على الشاشة الكبيرة ميزات كاملة في تدوين الملاحظات.

إمكانية استخدام قلم الشاشة

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

إذا تم ضبط الغرض الإضافي على 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.
    }
})

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

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

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

يجب أن يوفر تطبيق تدوين الملاحظات واجهة مستخدم تشغِّل 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")}
}

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

عندما يتم التقاط المحتوى بنجاح، الصق الصورة التي تم التقاطها في الملاحظة، على سبيل المثال:

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

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) للتأكّد من أنّ تطبيقك هو التطبيق التلقائي لتدوين الملاحظات (يمكن تشغيل تطبيقك في محادثة أو أي نوع آخر من فقاعات المحادثات إذا لم يكن التطبيق يشغل دور الملاحظات)

مصادر إضافية

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