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

באמצעות 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. כשאתם מוסיפים טבלה, עליכם לציין את הפרטים הבאים:

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

אין שיטה מפורשת למחיקה של טבלאות. כדי למחוק טבלה ממסמך, צריך להתייחס אליה כמו לכל תוכן אחר: משתמשים ב-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()

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

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

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

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

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()