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

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

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

الجداول في "مستندات Google" يتم تمثيلها كنوع من 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()

لأنك تحذف جدول كمحتوى عادي، عن طريق تحديد البداية والنهاية الفهارس الخاصة، فأنت بحاجة إلى الحصول على هذه الفهارس من مكان ما. يوضح المثال بطريقة واحدة لاستخراج هذه الفهارس من محتوى المستند.

أدرج المثال السابق الجدول في البداية من الجسم، أي في هذا المثال أن يكون العنصر الثالث (بدون فهرسة). أول عنصرين هما فاصل القسم الأول paragraph; تكون هذه المجموعات متاحة دائمًا ولا يمكن إزالتها.

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

إذا كان المستند يحتوي على جدول من قبل، تتيح لك واجهة برمجة تطبيقات "مستندات Google" إدراج وحذف صفوف الجدول. استخدام 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 . لتعديل أعمدة محددة فقط، قم بتضمين قائمة بأرقام الأعمدة في request; لتعديل جميع الأعمدة في الجدول، يجب تقديم قائمة فارغة.

في المثال التالي، يتم تعديل عرض الأعمدة في الجدول، مع ضبط جميع الأعمدة. إلى 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 . لتعديل الصفوف المحددة فقط، قم بتضمين قائمة بأرقام الصفوف في request; لتعديل جميع الصفوف في الجدول، يجب تقديم قائمة فارغة.

يحدد المثال التالي الحد الأدنى لارتفاع الصف 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()