ใช้งานตาราง

เอกสารนี้อธิบายวิธีทำงานกับตารางใน Google Docs API

Docs API ช่วยให้คุณแก้ไขเนื้อหาตารางได้ การดำเนินการที่คุณทำได้มีดังนี้

• แทรกและลบแถว คอลัมน์ หรือทั้งตาราง
• แทรกเนื้อหาลงในเซลล์ตาราง
• อ่านเนื้อหาจากเซลล์ตาราง
• แก้ไขพร็อพเพอร์ตี้ของคอลัมน์และรูปแบบของแถว

ตารางใน Google เอกสารจะแสดงเป็นประเภทของ StructuralElement ในเอกสาร แต่ละ Tableมีรายการ ออบเจ็กต์ TableRow ซึ่งแต่ละแถวมีรายการ ออบเจ็กต์ TableCell เช่นเดียวกับองค์ประกอบโครงสร้างทั้งหมด ตารางมีดัชนีเริ่มต้นและสิ้นสุด ซึ่งระบุตำแหน่งของตารางในเอกสาร คุณสมบัติของตารางประกอบด้วยองค์ประกอบรูปแบบต่างๆ เช่น ความกว้างของคอลัมน์และการเว้นวรรค

ตารางตัวอย่าง

ส่วน JSON ต่อไปนี้แสดงตาราง 2x2 ที่นำรายละเอียดส่วนใหญ่ออก

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

ตารางต่อไปนี้แสดงออฟเซ็ตดัชนีสำหรับองค์ประกอบโครงสร้างแต่ละรายการในตาราง 2x2 โดยสมมติว่าตารางเริ่มต้นที่ดัชนี S และเซลล์ทั้งหมดว่างเปล่า (แต่ละเซลล์ มีอักขระขึ้นบรรทัดใหม่ \n เพียงตัวเดียวที่มีความยาว = 1)

องค์ประกอบ	เส้นทาง	ดัชนีเริ่มต้น	ดัชนีสิ้นสุด
ตาราง	/	S	S + 12
TableRow 0	/rows[0]	S + 1	S + 6
TableCell (0,0)	/rows[0]/cells[0]	S + 2	S + 4
ย่อหน้า	/rows[0]/cells[0]/p[0]	S + 3	S + 4
TableCell (0,1)	/rows[0]/cells[1]	S + 4	S + 6
ย่อหน้า	/rows[0]/cells[1]/p[0]	S + 5	S + 6
TableRow 1	/rows[1]	S + 6	S + 11
TableCell (1,0)	/rows[1]/cells[0]	S + 7	S + 9
ย่อหน้า	/rows[1]/cells[0]/p[0]	S + 8	S + 9
TableCell (1,1)	/rows[1]/cells[1]	S + 9	S + 11
ย่อหน้า	/rows[1]/cells[1]/p[0]	S + 10	S + 11

แทรกและลบตาราง

หากต้องการเพิ่มตารางลงในเอกสาร ให้ใช้ InsertTableRequest คุณต้องระบุข้อมูลต่อไปนี้เมื่อแทรกตาราง

• มิติข้อมูลตารางในแถวและคอลัมน์
• ตำแหน่งที่จะแทรกตาราง: ตำแหน่งนี้อาจเป็นดัชนีภายในกลุ่ม (เช่น เนื้อหา ส่วนหัว หรือส่วนท้าย) หรืออาจเป็นจุดสิ้นสุดของกลุ่มก็ได้ โดยทั้ง 2 อย่างควรมีรหัสของแท็บที่ระบุ

หากต้องการแทรกตารางที่ส่วนท้ายของเนื้อหา ให้ระบุออบเจ็กต์ EndOfSegmentLocation และปล่อยให้ segmentId ว่างไว้

ไม่มีวิธีที่ชัดเจนในการลบตาราง หากต้องการลบตารางออกจากเอกสาร ให้ปฏิบัติต่อตารางเหมือนกับเนื้อหาอื่นๆ โดยใช้ DeleteContentRangeRequest ระบุ range ที่ครอบคลุมทั้งตาราง

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีแทรกตาราง 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(<var>TAB_ID</var>))
                .setRows(3)
                .setColumns(3)));

BatchUpdateDocumentRequest body =
    new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response =
    docsService.documents().batchUpdate(<var>DOCUMENT_ID</var>, 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': <var>TAB_ID</var>
        }
    },
}
]

result = service.documents().batchUpdate(documentId=<var>DOCUMENT_ID</var>, 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(<var>DOCUMENT_ID</var>).setIncludeTabsContent(true).execute();
String tabId = document.getTabs().get(0).getTabProperties().getTabId();
DocumentTab documentTab = document.getTabs().get(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(<var>DOCUMENT_ID</var>, 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=<var>DOCUMENT_ID</var>, body={'requests': requests}).execute()

หมายเหตุ: เนื่องจากตัวอย่างการแทรกจะแทรกตารางที่จุดเริ่มต้นของ ส่วนเนื้อหา ตัวอย่างการลบจึงคาดหวังให้ตารางเป็นองค์ประกอบที่ 3 (ดัชนีเป็น 0) องค์ประกอบ 2 รายการแรกคือตัวแบ่งส่วนแรกและย่อหน้า ซึ่งจะมีอยู่เสมอและนำออกไม่ได้

แทรกและลบแถว

หากเอกสารมีตารางอยู่แล้ว 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(<var>TAB_ID</var>))));
requests.add(new Request().setInsertTableRow(new InsertTableRowRequest()
        .setTableCellLocation(new TableCellLocation()
                .setTableStartLocation(new Location()
                        .setIndex(2).setTabId(<var>TAB_ID</var>))
                .setRowIndex(1)
                .setColumnIndex(1))
        .setInsertBelow(true)));

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

Python

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

result = service.documents().batchUpdate(documentId=<var>DOCUMENT_ID</var>, 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(<var>TAB_ID</var>))
                        .setRowIndex(0)
                        .setColumnIndex(0))
                .setInsertRight(true)));

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

Python

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

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

หากต้องการลบคอลัมน์ ให้ใช้ DeleteTableColumnRequest คุณต้องระบุตำแหน่งเซลล์ภายในคอลัมน์เป้าหมายตามที่แสดงก่อนหน้านี้ เพื่อแทรกคอลัมน์

อ่านเนื้อหาจากเซลล์ตาราง

เซลล์ตารางมีรายการออบเจ็กต์ StructuralElement องค์ประกอบโครงสร้างแต่ละรายการอาจเป็นย่อหน้าที่มีข้อความหรือ โครงสร้างประเภทอื่น หรือแม้แต่ตารางอื่น หากต้องการอ่านเนื้อหาของตาราง คุณ สามารถตรวจสอบแต่ละองค์ประกอบแบบเรียกซ้ำได้ตามที่แสดงในตัวอย่างโค้ดดึงข้อความจากเอกสารด้วย Docs API

แทรกเนื้อหาลงในเซลล์ตาราง

หากต้องการเขียนไปยังเซลล์ของตาราง ให้ใช้ InsertTextRequest ที่ตั้งค่าเป็น location ของเซลล์ที่ต้องการอัปเดต ดัชนีของตารางจะปรับ เพื่อให้สอดคล้องกับข้อความที่อัปเดต การลบข้อความในเซลล์ด้วย DeleteContentRangeRequest ก็เช่นกัน

หมายเหตุ: คุณไม่สามารถแทรกตารางและเขียนลงในเซลล์ภายในคำขอbatchUpdateเดียวได้ เนื่องจากการแปลดัชนีจะเลื่อนดัชนีการแทรกที่ตามมาโดยอัตโนมัติ ไปหลังตารางใหม่ คุณจึงต้องแทรกตารางก่อน จากนั้นเรียกข้อมูลstartIndex ของตาราง แล้วส่งคำขอ batchUpdate แยกต่างหากโดยใช้ ดัชนีพิกัดเซลล์ที่คำนวณถูกต้อง

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีเขียนไปยังตาราง

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Hello")
        .setLocation(new Location().setIndex(5).setTabId(<var>TAB_ID</var>))));

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

Python

requests = [{
    'insertText': {
      'location': {
        'index': 5,
        'tabId': <var>TAB_ID</var>
      },
      'text': 'Hello'
    }
}]

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

การแก้ไขพร็อพเพอร์ตี้ของคอลัมน์

UpdateTableColumnPropertiesRequest ช่วยให้คุณแก้ไขพร็อพเพอร์ตี้ของคอลัมน์อย่างน้อย 1 คอลัมน์ในตารางได้

คุณต้องระบุดัชนีเริ่มต้นของตารางพร้อมกับออบเจ็กต์ TableColumnProperties หากต้องการแก้ไขเฉพาะคอลัมน์ที่เลือก ให้ระบุรายการหมายเลขคอลัมน์ในคำขอ หากต้องการแก้ไขคอลัมน์ทั้งหมดในตาราง ให้ระบุรายการที่ว่างเปล่า

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีอัปเดตกว้างของคอลัมน์ในตาราง ตั้งค่าให้ทุกคอลัมน์มีความกว้าง 100 พอยต์ จากนั้นตั้งค่าให้คอลัมน์แรกมีความกว้าง 200 พอยต์

Java

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setUpdateTableColumnProperties(
            new UpdateTableColumnPropertiesRequest()
                .setTableStartLocation(
                    new Location()
                        .setIndex(2)
                        .setTabId(<var>TAB_ID</var>))
                .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(<var>TAB_ID</var>))
                .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(<var>DOCUMENT_ID</var>, body).execute();

Python

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

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

แก้ไขรูปแบบแถว

UpdateTableRowStyleRequest ช่วยให้คุณแก้ไขรูปแบบของแถวอย่างน้อย 1 แถวในตารางได้

คุณต้องระบุดัชนีเริ่มต้นของตารางพร้อมกับออบเจ็กต์ 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(<var>TAB_ID</var>))
                .setRowIndices(rowIndices)
                .setTableRowStyle(
                    new TableRowStyle()
                        .setMinRowHeight(
                            new Dimension().setMagnitude(18d).setUnit("PT")))
                .setFields("*")));

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

Python

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

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

หัวข้อที่เกี่ยวข้อง

• คำขอแบบกลุ่ม
• คำขอและการตอบกลับ