کار با جداول

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

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

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

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

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

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

برای اضافه کردن یک جدول جدید به یک سند، از InsertTableRequest استفاده کنید. هنگام درج جدول باید موارد زیر را مشخص کنید:

  • ابعاد جدول در سطرها و ستون‌ها.
  • محل درج جدول جدید: این می‌تواند یک اندیس در یک بخش یا انتهای یک بخش باشد. در هر صورت، باید شناسه‌ی تب مشخص شده را وارد کنید.

هیچ روش صریحی برای حذف جداول وجود ندارد. برای حذف یک جدول از یک سند، با آن مانند هر محتوای دیگری رفتار کنید: از DeleteContentRangeRequest استفاده کنید و محدوده‌ای را مشخص کنید که کل جدول را پوشش می‌دهد.

مثال زیر یک جدول ۳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(TAB_ID))
                .setRows(3)
                .setColumns(3)));

BatchUpdateDocumentRequest body =
    new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response =
    docsService.documents().batchUpdate(DOCUMENT_ID, 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': TAB_ID
        }
    },
}
]

result = service.documents().batchUpdate(documentId=DOCUMENT_ID, 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(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();

پایتون

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

از آنجا که شما یک جدول را به عنوان محتوای معمولی حذف می‌کنید - با مشخص کردن اندیس‌های شروع و پایان - باید این اندیس‌ها را از جایی دریافت کنید. این مثال یک روش برای استخراج این اندیس‌ها از محتوای سند را نشان می‌دهد.

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

اگر سند شما از قبل حاوی جدول است، API گوگل داکز به شما امکان می‌دهد ردیف‌های جدول را درج و حذف کنید. از InsertTableRowRequest برای درج ردیف‌های بالا یا پایین یک سلول جدول مشخص شده و از DeleteTableRowRequest برای حذف ردیفی که در محل سلول مشخص شده قرار دارد، استفاده کنید.

مثال زیر متنی را در اولین سلول جدول وارد می‌کند و یک ردیف جدول اضافه می‌کند.

جاوا

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

پایتون

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 استفاده کنید. باید موارد زیر را مشخص کنید:

  • سلولی که می‌خواهید ستون جدیدی در کنار آن درج شود.
  • ستون جدید در کدام سمت (چپ یا راست) درج شود.

مثال زیر نشان می‌دهد که چگونه می‌توانید یک ستون را در جدول ۲x۲ که قبلاً نشان داده شده است، وارد کنید:

جاوا

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

پایتون

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

خواندن محتوا از سلول‌های جدول

یک سلول جدول شامل فهرستی از عناصر ساختاری است؛ هر یک از این عناصر ساختاری می‌تواند یک پاراگراف با متن یا نوع دیگری از ساختار - حتی یک جدول دیگر - باشد. برای خواندن محتوای جدول، می‌توانید به صورت بازگشتی هر عنصر را بررسی کنید، همانطور که در Extract Text نشان داده شده است.

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

برای نوشتن در یک سلول جدول، از یک InsertTextRequest برای اندیس درون سلولی که می‌خواهید به‌روزرسانی کنید استفاده کنید. اندیس‌های جدول برای در نظر گرفتن متن به‌روزرسانی‌شده تنظیم می‌شوند. همین امر برای حذف متن سلول با DeleteContentRangeRequest نیز صدق می‌کند.

تغییر ویژگی‌های ستون

تابع UpdateTableColumnPropertiesRequest به شما امکان می‌دهد ویژگی‌های یک یا چند ستون در یک جدول را تغییر دهید.

شما باید اندیس شروع جدول را به همراه یک شیء TableColumnProperties ارائه دهید. برای تغییر فقط ستون‌های انتخاب شده، لیستی از شماره ستون‌ها را در درخواست قرار دهید؛ برای تغییر همه ستون‌های جدول، یک لیست خالی ارائه دهید.

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

جاوا

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

پایتون

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

مثال زیر حداقل ارتفاع ردیف ۳ یک جدول را تعیین می‌کند:

جاوا

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

پایتون

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