کار با جداول

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

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

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

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

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

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

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

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

برای درج جدول در انتهای بدنه، شی endOfSegmentLocation را مشخص کرده و segmentId را خالی بگذارید.

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

مثال زیر یک جدول 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())
                .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': ''
          }
      },
  }
  ]

  result = service.documents().batchUpdate(documentId=DOCUMENT_ID, body={'requests': requests}).execute()

این مثال مربوطه نحوه حذف جدولی که قبلا درج شده را نشان می دهد:

جاوا

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

پایتون

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

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

جاوا

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

پایتون

  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 که قبلا نشان داده شده است وارد کنید:

جاوا

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

پایتون

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

خواندن مطالب از سلول های جدول

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

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

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

اصلاح خصوصیات ستون

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

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

مثال زیر عرض ستون های جدول را به روز می کند و همه ستون ها را روی 100pts و سپس عرض ستون اول را روی 200pt قرار می دهد:

جاوا

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

پایتون

  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 جدول را تعیین می کند:

جاوا

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

پایتون

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