استخدام القوائم

تتيح Google Docs API إنشاء قوائم في مستندات جديدة، وتحويل الفقرات العادية الحالية إلى قوائم نقطية، وإزالة النقاط من الفقرات.

إنشاء قائمة مرقّمة في مستند جديد

تتيح واجهة برمجة التطبيقات Docs API إنشاء قائمة مرقّمة في مستند جديد من خلال إدراج نص ثم تطبيق نمط قائمة على النص في طلب مجمّع واحد.

لإنشاء قائمة مرقّمة في مستند جديد:

1. استخدِم الطريقة documents.create لإنشاء مستند.

2. استخدِم طريقة documents.batchUpdate وقدِّم InsertTextRequest لإضافة محتوى إلى المستند. استخدِم أحرف السطر الجديد (\n) للفصل بين عناصر القائمة.

3. في عملية التعديل المجمّع نفسها، أدرِج CreateParagraphBulletsRequest وRange لتحديد نطاق النص، وBulletGlyphPreset لضبط نمط الترقيم.

تعرض عيّنة الرمز البرمجي التالية كيفية إنشاء مستند ثم إدراج ثلاثة عناصر فيه كقائمة مرقّمة. يستخدم BulletGlyphPreset NUMBERED_DECIMAL_ALPHA_ROMAN لتنسيق القائمة. وهذا يعني أنّ مستويات التداخل الثلاثة الأولى في القائمة المرقمة يتم تمثيلها برقم عشري وحرف صغير ورقم روماني صغير.

جافا

Document doc = new Document().setTitle("New List Document");
doc = docsService.documents().create(doc).execute();
String documentId = doc.getDocumentId();

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Item 1\nItem 2\nItem 3\n")
        .setLocation(new Location().setIndex(1).setTabId(TAB_ID))));

requests.add(new Request().setCreateParagraphBullets(
        new CreateParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(22)
                        .setTabId(TAB_ID))
                .setBulletPreset("NUMBERED_DECIMAL_ALPHA_ROMAN")));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
docsService.documents().batchUpdate(documentId, body).execute();

System.out.println("Created document with ID: " + documentId);

Python

title = 'New List Document'
body = {'title': title}
doc = service.documents().create(body=body).execute()
document_id = doc.get('documentId')

requests = [
    {
        'insertText': {
            'location': {
                'index': 1,
                'tabId': TAB_ID
            },
            'text': 'Item 1\nItem 2\nItem 3\n'
        }
    },
    {
        'createParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex': 22,
                'tabId': TAB_ID
            },
            'bulletPreset': 'NUMBERED_DECIMAL_ALPHA_ROMAN'
        }
    }
]

result = service.documents().batchUpdate(
    documentId=document_id, body={'requests': requests}).execute()

print(f"Created document with ID: {document_id}")

استبدِل TAB_ID بمعرّف علامة التبويب التي تحتوي على محتوى القائمة.

تحويل فقرة إلى قائمة

من العمليات الشائعة لتنسيق الفقرات تحويل الفقرات الحالية إلى قائمة نقطية.

لإنشاء قائمة، استخدِم الطريقة documents.batchUpdate وقدِّم CreateParagraphBulletsRequest. أدرِج Range لتحديد النص المتأثر وBulletGlyphPreset لضبط نمط النقطة.

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

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

يمكنك أيضًا استخدام CreateParagraphBulletsRequest لتغيير نمط التعداد النقطي لقائمة حالية.

يعرض نموذج الرمز البرمجي التالي طلبًا مجمّعًا يدرج النص أولاً في بداية المستند، ثم ينشئ قائمة من الفقرات التي تمتد على أول 50 حرفًا. يستخدم BulletGlyphPreset BULLET_ARROW_DIAMOND_DISC، ما يعني أنّ مستويات التداخل الثلاثة الأولى من القائمة النقطية ممثّلة بسهم وماسة وقرص.

جافا

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Item One\n")
        .setLocation(new Location().setIndex(1).setTabId(TAB_ID))));

requests.add(new Request().setCreateParagraphBullets(
        new CreateParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(50)
                        .setTabId(TAB_ID))
                .setBulletPreset("BULLET_ARROW_DIAMOND_DISC")));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
        .batchUpdate(DOCUMENT_ID, body).execute();

Python

requests = [
        {
        'insertText': {
            'location': {
                'index': 1,
                'tabId': TAB_ID
            },
            'text': 'Item One\n',
        }}, {
        'createParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex':  50,
                'tabId': TAB_ID
            },
            'bulletPreset': 'BULLET_ARROW_DIAMOND_DISC',
        }
    }
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID, body={'requests': requests}).execute()

استبدِل TAB_ID بمعرّف علامة التبويب التي تتضمّن محتوى القائمة، أو احذفه لاستخدام علامة التبويب الأولى في المستند تلقائيًا.

الشكل 1. تحويل فقرة إلى قائمة

إزالة الرموز النقطية من قائمة

لإزالة نقاط تعداد من قائمة فقرات، استخدِم طريقة documents.batchUpdate وقدِّم DeleteParagraphBulletsRequest. أدرِج Range لتحديد النص المتأثر.

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

يعرض نموذج الرمز البرمجي التالي طلبًا مجمّعًا يحذف نقاطًا من قائمة فقرات.

جافا

List<Request> requests = new ArrayList<>();
requests.add(new Request().setDeleteParagraphBullets(
        new DeleteParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(50)
                        .setTabId(TAB_ID))));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
        .batchUpdate(DOCUMENT_ID, body).execute();

Python

requests = [
        {
        'deleteParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex':  50,
                'tabId': TAB_ID
            },
        }
    }
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID, body={'requests': requests}).execute()

استبدِل TAB_ID بمعرّف علامة التبويب التي تتضمّن محتوى القائمة، أو احذفه لاستخدام علامة التبويب الأولى في المستند تلقائيًا.