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

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

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

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

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

אם המסמך כבר מכיל טבלה, אפשר להשתמש ב-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()