עבודה עם רשימות

‫Google Docs API תומך ביצירת רשימות במסמכים חדשים, בהמרת פסקאות קיימות ללא עיצוב לרשימות עם תבליטים ובהסרת תבליטים מפסקאות.

יצירת רשימה ממוספרת במסמך חדש

‫Docs API תומך ביצירת רשימה ממוספרת במסמך חדש על ידי הוספת טקסט ואז החלת סגנון רשימה על הטקסט בבקשה מקובצת אחת.

כדי ליצור רשימה ממוספרת במסמך חדש:

1. משתמשים ב-method‏ documents.create כדי ליצור מסמך.

2. משתמשים בשיטה documents.batchUpdate ומספקים InsertTextRequest כדי להוסיף תוכן למסמך. כדי להפריד בין הפריטים ברשימה, משתמשים בתווי שורה חדשה (\n).

3. באותו עדכון של קבוצת פריטים, כוללים את המאפיין CreateParagraphBulletsRequest, את המאפיין Range כדי לציין את טווח הטקסט ואת המאפיין BulletGlyphPreset כדי להגדיר את דפוס המספור.

בדוגמת הקוד הבאה אפשר לראות איך יוצרים מסמך ואז מוסיפים שלוש פריטים כרשימה ממוספרת. התג BulletGlyphPreset משתמש בתג NUMBERED_DECIMAL_ALPHA_ROMAN כדי לעצב את הרשימה. המשמעות היא ששלושת רמות הקינון הראשונות של הרשימה הממוספרת מיוצגות על ידי מספר עשרוני, אות קטנה וספרה רומית קטנה.

Java

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 method ומספקים CreateParagraphBulletsRequest. מוסיפים Range כדי לציין את הטקסט המושפע וBulletGlyphPreset כדי להגדיר את התבנית של התבליט.

כל הפסקאות שחופפות לטווח הנתון מסומנות בתבליטים. אם הטווח שצוין חופף לטבלה, התבליטים מוחלים בתוך התאים של הטבלה. רמת הקינון של כל פסקה נקבעת לפי מספר התווים של Tab שמופיעים בתחילת כל פסקה.

אי אפשר לשנות את רמת הקינון של תבליט קיים. במקום זאת, צריך למחוק את התבליט, להגדיר את טאבים המובילים לפני הפסקה ואז ליצור מחדש את התבליט. מידע נוסף מופיע במאמר הסרת תבליטים מרשימה.

אפשר גם להשתמש ב-CreateParagraphBulletsRequest כדי לשנות את סגנון התבליטים ברשימה קיימת.

בדוגמת הקוד הבאה מוצגת בקשה להוספת כמה פעולות בבת אחת. הפעולה הראשונה היא הוספת טקסט בתחילת המסמך, והפעולה השנייה היא יצירת רשימה מהפסקאות שמתפרסות על פני 50 התווים הראשונים. התבנית BulletGlyphPreset משתמשת ב-BULLET_ARROW_DIAMOND_DISC, כלומר שלוש רמות הקינון הראשונות של הרשימה עם התבליטים מיוצגות על ידי חץ, מעוין ועיגול.

Java

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.

השיטה מוחקת את כל התבליטים שחופפים לטווח הנתון, בלי קשר לרמת הקינון. כדי לשמור על רמת הקינון באופן חזותי, מוסיפים הזחה בתחילת כל פסקה תואמת.

בדוגמת הקוד הבאה מוצגת בקשה למחיקת תבליטים מרשימת פסקאות.

Java

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 במזהה של הכרטיסייה שמכילה את תוכן הרשימה, או משמיטים אותו כדי להשתמש בכרטיסייה הראשונה במסמך כברירת מחדל.