עבודה עם טבלאות

אפשר לערוך את תוכן הטבלה ב-Google Docs API. הפעולות שאפשר כוללות את:

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

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

בקטע ה-JSON הבא מוצגת טבלה פשוטה בגודל 2x2 עם רוב הפרטים הוסר:

"table": {
    "columns": 2,
    "rows": 2,
    "tableRows": [
        { "tableCells": [
                {
                    "content": [ { "paragraph": { ...  }, } ],
                },
                {
                    "content": [ { "paragraph": { ... }, } ],
                }
            ],
        },
        {
            "tableCells": [
                {
                    "content": [ { "paragraph": { ... }, } ],
                },
                {
                    "content": [ { "paragraph": { ... }, } ],
                }
            ],
        }
    ]
}

הוספה ומחיקה של טבלאות

כדי להוסיף טבלה חדשה למסמך, משתמשים InsertTableRequest. כשמוסיפים טבלה, צריך לציין את הפרטים הבאים:

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

כדי להוסיף טבלה בסוף הגוף, צריך לציין את endOfSegmentLocation אובייקט, ומשאירים את השדה segmentId ריק.

אין שיטה מפורשת למחיקת טבלאות. כדי למחוק טבלה מתוך מתייחס אליו כמו לכל תוכן אחר: השתמשו DeleteContentRangeRequest, לציון טווח שמכסה את כל הטבלה.

בדוגמה הבאה מכניסים טבלה בגודל 3x3 בסוף של מסמך ריק:

Java

// Insert a table at the end of the body.
// (An empty or unspecified segmentId field indicates the document's body.)

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setInsertTable(
            new InsertTableRequest()
                .setEndOfSegmentLocation(
                    new EndOfSegmentLocation().setTabId(TAB_ID))
                .setRows(3)
                .setColumns(3)));

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

Python

# Insert a table at the end of the body.
# (An empty or unspecified segmentId field indicates the document's body.)

requests = [{
    'insertTable': {
        'rows': 3,
        'columns': 3,
        'endOfSegmentLocation': {
          'segmentId': '',
          'tabId': TAB_ID
        }
    },
}
]

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

הדוגמה המתאימה מראה איך למחוק את הטבלה שהוספתם בעבר:

Java

// Delete a table that was inserted at the start of the body of the first tab.
// (The table is the second element in the body:
//  documentTab.getBody().getContent().get(2).)

Document document = docsService.documents().get(DOCUMENT_ID).setIncludeTabsContent(true).execute();
String tabId = document.getTabs()[0].getTabProperties().getTabId();
DocumentTab documentTab = document.getTabs()[0].getDocumentTab();
StructuralElement table = documentTab.getBody().getContent().get(2);

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setDeleteContentRange(
            new DeleteContentRangeRequest()
                .setRange(
                    new Range()
                        .setStartIndex(table.getStartIndex())
                        .setEndIndex(table.getEndIndex())
                        .setTabId(tabId))));

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

Python

# Delete a table that was inserted at the start of the body of the first tab.
# (The table is the second element in the body: ['body']['content'][2].)

document = service.documents().get(documentId=DOCUMENT_ID, includeTabsContent=True).execute()
tab_id = document['tabs'][0]['tabProperties']['tabId']
document_tab = document['tabs'][0]['documentTab']
table = document_tab['body']['content'][2]

requests = [{
    'deleteContentRange': {
      'range': {
        'segmentId': '',
        'startIndex': table['startIndex'],
        'endIndex':   table['endIndex'],
        'tabId': tab_id
      }
    },
}
]

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

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

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

הוספה ומחיקה של שורות

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

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

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Hello")
        .setLocation(new Location().setIndex(5).setTabId(TAB_ID))));
requests.add(new Request().setInsertTableRow(new InsertTableRowRequest()
        .setTableCellLocation(new TableCellLocation()
                .setTableStartLocation(new Location()
                        .setIndex(2).setTabId(TAB_ID))
                .setRowIndex(1)
                .setColumnIndex(1))
        .setInsertBelow(true)));

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

Python

requests = [{
      'insertText': {
        'location': {
          'index': 5,
          'tabId': TAB_ID
        },
        'text': 'Hello'
    }
  },
  {
    'insertTableRow': {
        'tableCellLocation': {
            'tableStartLocation': {
                'index': 2,
                'tabId': TAB_ID
            },
            'rowIndex': 1,
            'columnIndex': 1
        },
        'insertBelow': 'true'
    }
  }
]

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

הוספה ומחיקה של עמודות

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

• תא שאליו רוצים להוסיף עמודה חדשה.
• איזה צד (שמאל או ימין) צריך להוסיף את העמודה החדשה.

הדוגמה הבאה מראה איך מוסיפים עמודה לפורמט 2x2 טבלה שהוצגה קודם לכן:

Java

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setInsertTableColumn(
            new InsertTableColumnRequest()
                .setTableCellLocation(
                    new TableCellLocation()
                        .setTableStartLocation(
                            new Location().setIndex(2).setTabId(TAB_ID))
                        .setRowIndex(0)
                        .setColumnIndex(0))
                .setInsertRight(true)));

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

Python

requests = [{
    'insertTableColumn': {
      'tableCellLocation': {
        'tableStartLocation': {
          'segmentId': '',
          'index': 2,
          'tabId': TAB_ID
        },
        'rowIndex': 0,
        'columnIndex': 0
      },
      'insertRight': True
    },
}
]

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

כדי למחוק עמודה, משתמשים DeleteTableColumnRequest. צריך לציין את מיקום התא בעמודת יעד, כפי שמוצג קודם לכן להוספת עמודה.

קריאת תוכן מתאים בטבלה

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

הוספת תוכן לתאים בטבלה

כדי לכתוב בתא בטבלה צריך להשתמש ב-InsertTextRequest לאינדקס בתוך התא שרוצים לעדכן. האינדקסים של הטבלה מותאמים ל: לחשבון של הטקסט המעודכן. אותה זכות חלה על מחיקת טקסט תא עם DeleteContentRangeRequest.

שינוי המאפיינים של עמודות

UpdateTableColumnPropertiesRequest מאפשר לשנות את המאפיינים של עמודה אחת או יותר בטבלה.

עליכם לספק את האינדקס ההתחלתי של הטבלה, יחד עם TableColumnProperties לאובייקט. כדי לשנות רק את העמודות שנבחרו, צריך לכלול רשימה של מספרי העמודות בעמודה בקשה; כדי לשנות את כל העמודות בטבלה, צריך לספק רשימה ריקה.

הדוגמה הבאה מעדכנת את מידות הרוחב של העמודות בטבלה ומגדירה את כל העמודות עד 100 נקודות, ואז רוחב העמודה הראשונה עד 200 נק':

Java

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setUpdateTableColumnProperties(
            new UpdateTableColumnPropertiesRequest()
                .setTableStartLocation(
                    new Location()
                        .setIndex(2)
                        .setTabId(TAB_ID))
                .setColumnIndices(null)
                .setTableColumnProperties(
                    new TableColumnProperties()
                        .setWidthType("FIXED_WIDTH")
                        .setWidth(
                            new Dimension().setMagnitude(100d).setUnit("PT")))
                .setFields("*")));

List<Integer> columnIndices = new ArrayList<>();
columnIndices.add(0);
requests.add(
    new Request()
        .setUpdateTableColumnProperties(
            new UpdateTableColumnPropertiesRequest()
                .setTableStartLocation(
                    new Location()
                        .setIndex(2)
                        .setTabId(TAB_ID))
                .setColumnIndices(columnIndices)
                .setTableColumnProperties(
                    new TableColumnProperties()
                        .setWidthType("FIXED_WIDTH")
                        .setWidth(
                            new Dimension().setMagnitude(200d).setUnit("PT")))
                .setFields("*")));

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

Python

requests = [{
  'updateTableColumnProperties': {
    'tableStartLocation': {'index': 2, 'tabId': TAB_ID},
    'columnIndices': [],
    'tableColumnProperties': {
      'widthType': 'FIXED_WIDTH',
      'width': {
        'magnitude': 100,
        'unit': 'PT'
      }
    },
    'fields': '*'
  },
  'updateTableColumnProperties': {
    'tableStartLocation': {'index': 2, 'tabId': TAB_ID},
    'columnIndices': [0],
    'tableColumnProperties': {
      'widthType': 'FIXED_WIDTH',
      'width': {
        'magnitude': 200,
        'unit': 'PT'
      }
    },
    'fields': '*'
  },
}
]

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

שינוי סגנונות של שורות

השדה UpdateTableRowsStyleRequest מאפשר לשנות את הסגנון של אחת או יותר מהשורות בטבלה.

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

בדוגמה הבאה נקבע את הגובה המינימלי של שורה 3 בטבלה:

Java

List<Integer> rowIndices = new ArrayList<>();
rowIndices.add(3);

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setUpdateTableRowStyle(
            new UpdateTableRowStyleRequest()
                .setTableStartLocation(
                    new Location()
                        .setIndex(2)
                        .setTabId(TAB_ID))
                .setRowIndices(rowIndices)
                .setTableRowStyle(
                    new TableRowStyle()
                        .setMinRowHeight(
                            new Dimension().setMagnitude(18d).setUnit("PT")))
                .setFields("*")));

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

Python

requests = [{
    'updateTableRowStyle': {
        'tableStartLocation': {'index': 2, 'tabId': TAB_ID},
        'rowIndices': [3],
        'tableRowStyle': {
            'minRowHeight': {
              'magnitude': 18,
              'unit': 'PT'
            }
        },
        'fields': '*'
    },
}
]

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