Python/python-pptx 사용자 가이드 - 12. Tables

https://python-pptx.readthedocs.io/en/latest/user/table.html

Working with tables

PowerPoint allows text and numbers to be presented in tabular form (aligned rows and columns) in a reasonably flexible way. A PowerPoint table is not nearly as functional as an Excel spreadsheet, and is definitely less powerful than a table in Microsoft Word, but it serves well for most presentation purposes.

PowerPoint에서는 텍스트와 숫자를 합리적으로 유연한 방식으로 표 형식(행과 열 정렬)으로 표시할 수 있다. PowerPoint 표는 Excel 스프레드시트만큼 기능적이지 않으며 Microsoft Word의 표보다 확실히 덜 강력하지만 대부분의 프레젠테이션 목적에 적합하다.

Concepts

There are a few terms worth reviewing as a basis for understanding PowerPoint tables:

table

A table is a matrix of cells arranged in aligned rows and columns. This orderly arrangement allows a reader to more easily make sense of relatively large number of individual items. It is commonly used for displaying numbers, but can also be used for blocks of text.

PowerPoint 표를 이해하기 위한 기초로 검토해 볼 만한 몇 가지 용어가 있다.

테이블

테이블은 정렬된 행과 열로 배열된 셀의 행렬이다. 이러한 질서정연한 배열을 통해 독자는 상대적으로 많은 수의 개별 항목을 더 쉽게 이해할 수 있다. 일반적으로 숫자를 표시하는 데 사용되지만 텍스트 블록에도 사용할 수 있다.

cell

An individual content “container” within a table. A cell has a text-frame in which it holds that content. A PowerPoint table cell can only contain text. I cannot hold images, other shapes, or other tables.

A cell has a background fill, borders, margins, and several other formatting settings that can be customized on a cell-by-cell basis.

row

A side-by-side sequence of cells running across the table, all sharing the same top and bottom boundary.

column

A vertical sequence of cells spanning the height of the table, all sharing the same left and right boundary.

table grid, also cell grid

The underlying cells in a PowerPoint table are strictly regular. In a three-by-three table there are nine grid cells, three in each row and three in each column. The presence of merged cells can obscure portions of the cell grid, but not change the number of cells in the grid. Access to a table cell in python-pptx is always via that cell’s coordinates in the cell grid, which may not conform to its visual location (or lack thereof) in the table.

merged cell

A cell can be “merged” with adjacent cells, horizontally, vertically, or both, causing the resulting cell to look and behave like a single cell that spans the area formerly occupied by those individual cells.

셀

테이블 내의 개별 콘텐츠 '컨테이너'이다. 셀에는 해당 내용을 담는 텍스트 프레임이 있다. PowerPoint 표 셀에는 텍스트만 포함될 수 있다. 이미지나 다른 도형, 다른 테이블을 담을 수 없다.

셀에는 셀별로 사용자 정의할 수 있는 배경 채우기, 테두리, 여백 및 기타 여러 서식 설정이 있다.

행

테이블을 가로질러 나란히 배열된 셀의 순서로, 모두 동일한 상단 및 하단 경계를 공유한다.

열

테이블 높이에 걸쳐 있는 셀의 수직 시퀀스로, 모두 동일한 왼쪽 및 오른쪽 경계를 공유한다.

테이블 그리드, 셀 그리드

PowerPoint 표의 기본 셀은 엄격하게 규칙적이다. 3x3 테이블에는 9개의 그리드 셀이 있으며, 각 행에 3개, 각 열에 3개가 있다. 병합된 셀이 있으면 셀 그리드의 일부가 가려질 수 있지만 그리드의 셀 수는 변경되지 않는다. python-pptx에서 테이블 셀에 대한 액세스는 항상 셀 그리드의 해당 셀 좌표를 통해 이루어지며, 이는 테이블의 시각적 위치(또는 일치하지 않음)와 일치하지 않을 수 있다.

병합된 셀

셀은 수평, 수직 또는 둘 다로 인접한 셀과 "병합"될 수 있으며, 이로 인해 결과 셀은 이전에 해당 개별 셀이 차지했던 영역에 걸쳐 있는 단일 셀처럼 보이고 동작하게 된다.

merge-origin cell

The top-left grid-cell in a merged cell has certain special behaviors. The content of that cell is what appears on the slide; content of any “spanned” cells is hidden. In python-pptx a merge-origin cell can be identified with the _Cell.is_merge_origin property. Such a cell can report the size of the merged cell with its span_height and span_width properties, and can be “unmerged” back to its underlying grid cells using its split() method.

spanned-cell

A grid-cell other than the merge-origin cell that is “occupied” by a merged cell is called a spanned cell. Intuitively, the merge-origin cell “spans” the other grid cells within its area. A spanned cell can be identified with its _Cell.is_spanned property. A merge-origin cell is not itself a spanned cell.

병합 원본 셀

병합된 셀의 왼쪽 상단 그리드 셀에는 특정한 특수 동작이 있다. 해당 셀의 내용이 슬라이드에 표시된다. "스패닝된" 셀의 내용은 숨겨진다. python-pptx에서 병합 원본 셀은 _Cell.is_merge_origin 속성으로 식별할 수 있다. 이러한 셀은span_height 및span_width 속성을 사용하여 병합된 셀의 크기를 보고할 수 있으며, 분할() 메서드를 사용하여 기본 그리드 셀로 다시 "병합 해제"될 수 있다.

스팬 셀

병합된 셀이 "점유"하는 병합 원본 셀 이외의 그리드 셀을 스팬 셀이라고 한다. 직관적으로 병합 원본 셀은 해당 영역 내의 다른 그리드 셀에 "포함"된다. 확장된 셀은 _Cell.is_spanned 속성으로 식별할 수 있다. 병합 원본 셀 자체는 확장된 셀이 아니다.

Adding a table

The following code adds a 3-by-3 table in a new presentation:

다음 코드는 새 프레젠테이션에 3x3 테이블을 추가한다.

>>> from pptx import Presentation
>>> from pptx.util import Inches

>>> # ---create presentation with 1 slide---
>>> prs = Presentation()
>>> slide = prs.slides.add_slide(prs.slide_layouts[5])

>>> # ---add table to slide---
>>> x, y, cx, cy = Inches(2), Inches(2), Inches(4), Inches(1.5)
>>> shape = slide.shapes.add_table(3, 3, x, y, cx, cy)

>>> shape

>>> shape.has_table
True
>>> table = shape.table
>>> table

A couple things to note:

• SlideShapes.add_table() returns a shape that contains the table, not the table itself. In PowerPoint, a table is contained in a graphic-frame shape, as is a chart or SmartArt. You can determine whether a shape contains a table using its has_table property and you access the table object using the shape’s table property.

참고할 몇 가지 사항:

• SlideShapes.add_table()은 테이블 자체가 아니라 테이블을 포함하는 도형을 반환한다. PowerPoint에서 표는 차트나 SmartArt와 마찬가지로 그래픽 프레임 도형에 포함되어 있다. has_table 속성을 사용하여 도형에 테이블이 포함되어 있는지 확인하고 도형의 table 속성을 사용하여 테이블 개체에 액세스할 수 있다.

Inserting a table into a table placeholder

A placeholder allows you to specify the position and size of a shape as part of the presentation “template”, and to place a shape of your choosing into that placeholder when authoring a presentation based on that template. This can lead to a better looking presentation, with objects appearing in a consistent location from slide-to-slide.

Placeholders come in different types, one of which is a table placeholder. A table placeholder behaves like other placeholders except it can only accept insertion of a table. Other placeholder types accept text bullets or charts.

There is a subtle distinction between a layout placeholder and a slide placeholder. A layout placeholder appears in a slide layout, and defines the position and size of the placeholder “cloned” from it onto each slide created with that layout. As long as you don’t adjust the position or size of the slide placeholder, it will inherit it’s position and size from the layout placeholder it derives from.

To insert a table into a table placeholder, you need a slide layout that includes a table placeholder, and you need to create a slide using that layout. These examples assume that the third slide layout in template.pptx includes a table placeholder:

자리 표시자를 사용하면 프레젠테이션 "템플릿"의 일부로 도형의 위치와 크기를 지정할 수 있고 해당 템플릿을 기반으로 프레젠테이션을 작성할 때 선택한 도형을 해당 자리 표시자에 배치할 수 있다. 이렇게 하면 슬라이드 간에 개체가 일관된 위치에 표시되므로 프레젠테이션이 더 좋아질 수 있다.

자리 표시자는 다양한 유형으로 제공되며 그 중 하나는 테이블 자리 표시자이다. 테이블 자리 표시자는 테이블 삽입만 허용한다는 점을 제외하면 다른 자리 표시자와 동일하게 작동한다. 다른 자리 표시자 유형은 텍스트 글머리 기호나 차트를 허용한다.

레이아웃 자리 표시자와 슬라이드 자리 표시자 사이에는 미묘한 차이가 있다. 레이아웃 자리 표시자는 슬라이드 레이아웃에 나타나며 해당 레이아웃으로 생성된 각 슬라이드에 "복제된" 자리 표시자의 위치와 크기를 정의한다. 슬라이드 자리 표시자의 위치나 크기를 조정하지 않는 한 슬라이드 자리 표시자는 파생된 레이아웃 자리 표시자의 위치와 크기를 상속받는다.

표 자리 표시자에 표를 삽입하려면 표 자리 표시자가 포함된 슬라이드 레이아웃이 필요하며 해당 레이아웃을 사용하여 슬라이드를 만들어야 한다. 다음 예에서는 template.pptx의 세 번째 슬라이드 레이아웃에 테이블 자리 표시자가 포함되어 있다고 가정한다.

>>> prs = Presentation('template.pptx')
>>> slide = prs.slides.add_slide(prs.slide_layouts[2])

Accessing the table placeholder. Generally, the easiest way to access a placeholder shape is to know its position in the slide.shapes collection. If you always use the same template, it will always show up in the same position:

테이블 자리표시자에 액세스 중이다. 일반적으로 자리 표시자 도형에 액세스하는 가장 쉬운 방법은 Slide.shapes 컬렉션에서 해당 위치를 아는 것이다. 항상 동일한 템플릿을 사용하는 경우 항상 동일한 위치에 표시된다.

>>> table_placeholder = slide.shapes[1]

Inserting a table. A table is inserted into the placeholder by calling its insert_table() method and providing the desired number of rows and columns:

테이블 삽입. insert_table() 메서드를 호출하고 원하는 수의 행과 열을 제공하여 테이블이 자리 표시자에 삽입된다.

>>> shape = table_placeholder.insert_table(rows=3, cols=4)

The return value is a GraphicFrame shape containing the new table, not the table object itself. Use the table property of that shape to access the table object:

반환 값은 테이블 개체 자체가 아니라 새 테이블을 포함하는 GraphicFrame 도형이다. 해당 도형의 table 속성을 사용하여 테이블 개체에 액세스한다.

>>> table = shape.table

The containing shape controls the position and size. Everything else, like accessing cells and their contents, is done from the table object.

포함하는 도형은 위치와 크기를 제어한다. 셀 및 해당 내용에 액세스하는 것과 같은 다른 모든 작업은 테이블 개체에서 수행된다.

Accessing a cell

All content in a table is in a cell, so getting a reference to one of those is a good place to start:

테이블의 모든 콘텐츠는 셀에 있으므로 그 중 하나에 대한 참조를 얻는 것이 좋은 시작점이다.

>>> cell = table.cell(0, 0)
>>> cell.text
''
>>> cell.text = 'Unladen Swallow'

The cell is specified by its row, column coordinates as zero-based offsets. The top-left cell is at row, column (0, 0).

Like an auto-shape, a cell has a text-frame and can contain arbitrary text divided into paragraphs and runs. Any desired character formatting can be applied individually to each run.

Often however, cell text is just a simple string. For these cases the read/write _Cell.text property can be the quickest way to set cell contents.

셀은 행, 열 좌표로 0부터 시작하는 오프셋으로 지정된다. 왼쪽 위 셀은 행, 열(0, 0)에 있다.

자동 도형과 마찬가지로 셀에는 텍스트 프레임이 있으며 단락과 실행으로 구분된 임의의 텍스트를 포함할 수 있다. 원하는 문자 형식을 각 실행마다 개별적으로 적용할 수 있다.

그러나 셀 텍스트는 단순한 문자열인 경우가 많다. 이러한 경우 읽기/쓰기 _Cell.text 속성은 셀 내용을 설정하는 가장 빠른 방법이 될 수 있다.

Merging cells

A merged cell is produced by specifying two diagonal cells. The merged cell will occupy all the grid cells in the rectangular region specified by that diagonal:

두 개의 대각선 셀을 지정하면 병합된 셀이 생성된다. 병합된 셀은 해당 대각선으로 지정된 직사각형 영역의 모든 그리드 셀을 차지한다.

>>> cell = table.cell(0, 0)
>>> other_cell = table.cell(1, 1)
>>> cell.is_merge_origin
False
>>> cell.merge(other_cell)
>>> cell.is_merge_origin
True
>>> cell.is_spanned
False
>>> other_cell.is_spanned
True
>>> table.cell(0, 1).is_spanned
True

A few things to observe:

• The merged cell appears as a single cell occupying the space formerly occupied by the other grid cells in the specified rectangular region.
• The formatting of the merged cell (background color, font etc.) is taken from the merge origin cell, the top-left cell of the table in this case.
• Content from the merged cells was migrated to the merge-origin cell. That content is no longer present in the spanned grid cells (although you can’t see those at the moment). The content of each cell appears as a separate paragraph in the merged cell; it isn’t concatenated into a single paragraph. Content is migrated in left-to-right, top-to-bottom order of the original cells.
• Calling other_cell.merge(cell) would have the exact same effect. The merge origin is always the top-left cell in the specified rectangular region. There are four distinct ways to specify a given rectangular region (two diagonals, each having two orderings).

관찰해야 할 몇 가지 사항:

• 병합된 셀은 지정된 직사각형 영역에서 이전에 다른 그리드 셀이 차지했던 공간을 차지하는 단일 셀로 나타난다.
• 병합된 셀의 서식(배경색, 글꼴 등)은 이 경우 테이블의 왼쪽 상단 셀인 병합 원본 셀에서 가져온다.
• 병합된 셀의 콘텐츠가 병합 원본 셀로 마이그레이션되었다. 해당 콘텐츠는 확장된 그리드 셀에 더 이상 존재하지 않는다(단, 지금은 볼 수 없음). 각 셀의 내용은 병합된 셀에서 별도의 단락으로 나타난다. 단일 단락으로 연결되지 않다. 콘텐츠는 원본 셀의 왼쪽에서 오른쪽, 위에서 아래 순서로 마이그레이션된다.
• other_cell.merge(cell)을 호출하면 똑같은 효과가 나타난다. 병합 원점은 항상 지정된 직사각형 영역의 왼쪽 위 셀이다. 주어진 직사각형 영역(두 개의 대각선, 각각 두 개의 순서를 가짐)을 지정하는 네 가지 방법이 있다.

Un-merging a cell

A merged cell can be restored to its underlying grid cells by calling the split() method on its merge-origin cell. Calling split() on a cell that is not a merge-origin raises ValueError:

병합 원본 셀에서 split() 메서드를 호출하여 병합된 셀을 기본 그리드 셀로 복원할 수 있다. 병합 원본이 아닌 셀에서 split()을 호출하면 ValueError가 발생한다.

>>> cell = table.cell(0, 0)
>>> cell.is_merge_origin
True
>>> cell.split()
>>> cell.is_merge_origin
False
>>> table.cell(0, 1).is_spanned
False

Note that the content migration performed as part of the .merge() operation was not reversed.

.merge() 작업의 일부로 수행된 콘텐츠 마이그레이션은 취소되지 않았다.

A few snippets that might be handy

Use Case: Interrogate table for merged cells:

사용 사례: 병합된 셀에 대한 질문 테이블:

def iter_merge_origins(table):
    """Generate each merge-origin cell in *table*.

    Cell objects are ordered by their position in the table,
    left-to-right, top-to-bottom.
    """
    return (cell for cell in table.iter_cells() if cell.is_merge_origin)

def merged_cell_report(cell):
    """Return str summarizing position and size of merged *cell*."""
    return (
        'merged cell at row %d, col %d, %d cells high and %d cells wide'
        % (cell.row_idx, cell.col_idx, cell.span_height, cell.span_width)
    )

# ---Print a summary line for each merged cell in *table*.---
for merge_origin_cell in iter_merge_origins(table):
    print(merged_cell_report(merge_origin_cell))

prints a report like:

다음과 같은 보고서를 인쇄한다.

merged cell at row 0, col 0, 2 cells high and 2 cells wide
merged cell at row 3, col 2, 1 cells high and 2 cells wide
merged cell at row 4, col 0, 2 cells high and 1 cells wide

Use Case: Access only cells that display text (are not spanned):

사용 사례: 텍스트를 표시하는 셀에만 액세스한다(범위가 확장되지 않음).

def iter_visible_cells(table):
    return (cell for cell in table.iter_cells() if not cell.is_spanned)

Use Case: Determine whether table contains merged cells:

사용 사례: 테이블에 병합된 셀이 포함되어 있는지 확인한다.

def has_merged_cells(table):
    for cell in table.iter_cells():
        if cell.is_merge_origin:
            return True
    return False

 

Python/python-pptx 사용자 가이드