کار با جداول، کار با جداول

این سند نحوه کار با جداول در API گوگل داکس را توضیح می‌دهد.

API اسناد به شما امکان ویرایش محتوای جدول را می‌دهد. عملیاتی که می‌توانید انجام دهید شامل موارد زیر است:

• درج و حذف سطرها، ستون‌ها یا کل جداول.
• درج محتوا در سلول‌های جدول
• خواندن محتوا از سلول‌های جدول.
• ویژگی‌های ستون‌ها و سبک ردیف‌ها را تغییر دهید.

جداول در Google Docs به عنوان نوعی StructuralElement در سند نمایش داده می‌شوند. هر Table شامل فهرستی از اشیاء TableRow است که در آن هر سطر شامل فهرستی از اشیاء TableCell است. مانند تمام عناصر ساختاری، جدول دارای اندیس‌های شروع و پایان است که موقعیت جدول را در یک سند نشان می‌دهد. ویژگی‌های جدول شامل بسیاری از عناصر سبک مانند عرض ستون‌ها و padding است.

جدول نمونه

قطعه JSON زیر یک جدول ۲x۲ را نشان می‌دهد که بیشتر جزئیات آن حذف شده است:

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

جدول زیر، جابجایی‌های اندیس را برای هر عنصر ساختاری در یک جدول ۲x۲ نشان می‌دهد، با فرض اینکه جدول از اندیس S شروع می‌شود و همه سلول‌ها خالی هستند (هر کدام فقط شامل یک کاراکتر خط جدید \n با طول = ۱ هستند):

عنصر	مسیر	شروع فهرست	فهرست پایان
میز	/	S	S + 12
ردیف جدول 0	/rows[0]	S + 1	S + 6
سلول جدول (0،0)	/rows[0]/cells[0]	S + 2	S + 4
پاراگراف	/rows[0]/cells[0]/p[0]	S + 3	S + 4
سلول جدول (0،1)	/rows[0]/cells[1]	S + 4	S + 6
پاراگراف	/rows[0]/cells[1]/p[0]	S + 5	S + 6
ردیف جدول ۱	/rows[1]	S + 6	S + 11
سلول جدولی (1،0)	/rows[1]/cells[0]	S + 7	S + 9
پاراگراف	/rows[1]/cells[0]/p[0]	S + 8	S + 9
سلول جدولی (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 مشخص کنید که کل جدول را پوشش می‌دهد.

نمونه کد زیر نحوه درج یک جدول ۳x۳ در انتهای یک سند خالی را نشان می‌دهد:

جاوا

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

پایتون

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

پایتون

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

نکته: از آنجایی که مثال درج، جدول را در ابتدای بخش بدنه درج می‌کند، مثال حذف انتظار دارد که جدول عنصر سوم (با اندیس صفر) باشد. دو عنصر اول، اولین بخش و پاراگراف هستند که همیشه وجود دارند و قابل حذف نیستند.

درج و حذف ردیف‌ها

اگر سند شما از قبل حاوی جدول است، 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();

پایتون

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

پایتون

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 است. هر یک از این عناصر ساختاری می‌تواند یک پاراگراف با متن یا نوع دیگری از ساختار - حتی یک جدول دیگر - باشد. برای خواندن محتوای جدول، می‌توانید به صورت بازگشتی هر عنصر را بررسی کنید، همانطور که در نمونه کد API استخراج متن از یک سند با Docs نشان داده شده است.

درج محتوا در سلول‌های جدول

برای نوشتن در یک سلول جدول، از یک 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();

پایتون

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 ارائه دهید. برای تغییر فقط ستون‌های انتخاب شده، لیستی از شماره ستون‌ها را در درخواست قرار دهید. برای تغییر همه ستون‌های جدول، یک لیست خالی ارائه دهید.

نمونه کد زیر نحوه به‌روزرسانی عرض ستون‌های یک جدول را نشان می‌دهد، به این صورت که عرض همه ستون‌ها را روی ۱۰۰ پوینت و عرض ستون اول را روی ۲۰۰ پوینت تنظیم می‌کند:

جاوا

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

پایتون

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

پایتون

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

مباحث مرتبط

• درخواست‌های دسته‌ای
• درخواست‌ها و پاسخ‌ها