العمل على الجداول

تتيح لك Google Docs API تعديل محتوى الجداول. تشمل العمليات التي يمكنك تنفيذها ما يلي:

  • إدراج الصفوف أو الأعمدة أو الجداول بأكملها وحذفها
  • إدراج محتوى في خلايا الجدول
  • قراءة المحتوى من خلايا الجدول
  • تعديل خصائص الأعمدة ونمط الصفوف

يتم تمثيل الجداول في "مستندات Google" كنوع من 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. لتعديل الأعمدة المحدّدة فقط، أدرِج قائمة بأرقام الأعمدة في الطلب، ولتعديل جميع الأعمدة في الجدول، قدِّم قائمة فارغة.

يعدّل المثال التالي عرض الأعمدة في جدول، ويضبط عرض جميع الأعمدة على 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()