العمل باستخدام الجداول

يوضّح هذا المستند كيفية التعامل مع الجداول في 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. يجب تحديد ما يلي عند إدراج جدول:

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

لإدراج جدول في نهاية النص الأساسي، حدِّد العنصر EndOfSegmentLocation، واترك segmentId فارغًا.

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

توضح عينة التعليمات البرمجية التالية كيفية إدراج جدول 3x3 في نهاية مستند فارغ:

جافا

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

توضح عينة التعليمات البرمجية التالية كيفية حذف جدول من خلال تحديد فهرسَي البدء والنهاية. يوضّح هذا النموذج كيفية استرداد هذه الفهارس من محتوى المستند.

جافا

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

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

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

إذا كان المستند يتضمّن جدولاً، تتيح لك واجهة برمجة التطبيقات Docs API إدراج صفوف الجدول وحذفها. استخدِم InsertTableRowRequest لإدراج صفوف قبل خلية جدول محدّدة أو بعدها، واستخدِم DeleteTableRowRequest لإزالة صف يمتد على موقع الخلية المحدّد.

يوضّح نموذج الرمز التالي كيفية إدراج نص في الخلية الأولى من جدول حالي وإضافة صف جدول:

جافا

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 المثال الموضّح سابقًا:

جافا

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 منفصل باستخدام فهارس إحداثيات الخلايا المحسوبة الصحيحة.

يوضّح نموذج الرمز التالي كيفية الكتابة في خلية جدول:

جافا

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 تعديل خصائص عمود واحد أو أكثر في جدول.

يجب تقديم فهرس بدء الجدول، بالإضافة إلى كائن TableColumnProperties. لتعديل الأعمدة المحدّدة فقط، أدرِج قائمة بأرقام الأعمدة في الطلب. لتعديل جميع الأعمدة في الجدول، قدِّم قائمة فارغة.

توضح عينة التعليمات البرمجية التالية كيفية تعديل عرض أعمدة جدول، من خلال ضبط عرض جميع الأعمدة على 100 نقطة، ثم ضبط عرض العمود الأول على 200 نقطة:

جافا

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 تعديل نمط صف واحد أو أكثر في جدول.

يجب تقديم فهرس بدء الجدول، بالإضافة إلى كائن TableRowStyle. لتعديل الصفوف المحدّدة فقط، أدرِج قائمة بأرقام الصفوف في الطلب. لتعديل جميع الصفوف في الجدول، قدِّم قائمة فارغة.

يوضّح نموذج الرمز التالي كيفية ضبط الحد الأدنى لارتفاع الصف الثالث في جدول:

جافا

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

مواضيع ذات صلة

• الطلبات المجمّعة
• الطلبات والردود