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

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

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

يتم تمثيل الجداول في "مستندات Google" كنوع من StructuralElement في المستند. يحتوي كل جدول على قائمة بـ صفوف الجدول حيث يحتوي كل صف على قائمة بخلوص جدول. كما هو الحال مع جميع العناصر الهيكلية، يحتوي الجدول على فهرسَي البدء والنهاية، ما يشير إلى موضع الجدول في المستند. يمكنك الاطّلاع على البنية للحصول على مزيد من المعلومات عن ميزة الفهرسة. تتضمّن سمات الجدول العديد من عناصر التصميم، مثل عرض الأعمدة والشدَّة.

يعرض المقتطف التالي من ملف JSON جدولاً بسيطًا بحجم 2×2 مع إزالة معظم التفاصيل:

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

إدراج الجداول وحذفها

لإضافة جدول جديد إلى مستند، استخدِم InsertTableRequest. يجب تحديد ما يلي عند إدراج جدول:

  • سمات الجدول في الصفوف والأعمدة
  • مكان إدراج الجدول الجديد: يمكن أن يكون فهرسًا ضمن قسم، أو يمكن أن يكون نهاية قسم. يجب أن يتضمّن أيّ منهما معرّف علامة التبويب المحدّدة.

لا تتوفّر طريقة صريحة لحذف الجداول. لحذف جدول من مستند، عليك التعامل معه كما تتعامل مع أي محتوى آخر: استخدِم DeleteContentRangeRequest، مع تحديد نطاق يغطي الجدول بأكمله.

يُدرج المثال التالي جدولاً مقاس 3×3 في نهاية مستند فارغ:

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. يجب تحديد ما يلي:

  • خلية تريد إدراج عمود جديد بجانبها
  • الجانب الذي سيتم إدراج العمود الجديد فيه (اليسار أو اليمين)

يوضّح المثال التالي كيفية إدراج عمود في جدول 2×2 الذي سبق أن عرضناه:

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