تسمح لك واجهة برمجة تطبيقات "مستندات Google" بتعديل محتوى الجدول. وتشمل العمليات التي يمكنك تنفيذها ما يلي:
- يمكنك إدراج الصفوف أو الأعمدة أو الجداول بالكامل وحذفها.
- إدراج المحتوى في خلايا الجدول.
- قراءة المحتوى من خلايا الجدول.
- عدِّل خصائص العمود ونمط الصفوف.
يتم تمثيل الجداول في "مستندات Google" كنوع من العناصر الهيكلية في المستند. يحتوي كل جدول على قائمة بصفوف الجدول حيث يحتوي كل صف على قائمة بخلايا الجدول. كما هو الحال مع جميع العناصر الهيكلية، يحتوي الجدول على فهارس البداية والنهاية، مما يشير إلى موضع الجدول في المستند. يمكنك الاطّلاع على البنية للحصول على مزيد من المعلومات حول الفهرسة. تتضمن خصائص الجدول العديد من عناصر النمط مثل عرض الأعمدة والمساحة المتروكة.
يعرض جزء JSON التالي جدولاً بسيطًا 2x2 تمت إزالة معظم تفاصيله:
"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())
.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': ''
}
},
}
]
result = service.documents().batchUpdate(documentId=DOCUMENT_ID, body={'requests': requests}).execute()
يوضح المثال المقابل هذا كيفية حذف الجدول الذي تم إدراجه مسبقًا:
لغة Java
// Delete a table that was inserted at the start of the body.
// (The table is the second element in the body:
// document.getBody().getContent().get(2).)
Document document = docsService.documents().get(DOCUMENT_ID).execute();
StructuralElement table = document.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()))));
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.
# (The table is the second element in the body: ['body']['content'][2].)
document = service.documents().get(documentId=DOCUMENT_ID).execute()
table = document['body']['content'][2]
requests = [{
'deleteContentRange': {
'range': {
'segmentId': '',
'startIndex': table['startIndex'],
'endIndex': table['endIndex']
}
},
}
]
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))));
requests.add(new Request().setInsertTableRow(new InsertTableRowRequest()
.setTableCellLocation(new TableCellLocation()
.setTableStartLocation(new Location()
.setIndex(2))
.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
},
'text': 'Hello'
}
},
{
'insertTableRow': {
'tableCellLocation': {
'tableStartLocation': {
'index': 2
},
'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))
.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
},
'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))
.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))
.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},
'columnIndices': [],
'tableColumnProperties': {
'widthType': 'FIXED_WIDTH',
'width': {
'magnitude': 100,
'unit': 'PT'
}
},
'fields': '*'
},
'updateTableColumnProperties': {
'tableStartLocation': {'index': 2},
'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))
.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},
'rowIndices': [3],
'tableRowStyle': {
'minRowHeight': {
'magnitude': 18,
'unit': 'PT'
}
},
'fields': '*'
},
}
]
result = service.documents().batchUpdate(documentId=DOCUMENT_ID, body={'requests': requests}).execute()