节对象

Section objects

中文

提供对诸如边距和页面方向等部分属性的访问。

英文

Provides access to section properties such as margins and page orientation.

|Sections|对象

Sections objects

class docx.section.Sections(document_elm: CT_Document, document_part: DocumentPart)

Sequence of Section objects corresponding to the sections in the document.

Supports len(), iteration, and indexed access.

|Section|对象

Section objects

class docx.section.Section(sectPr: CT_SectPr, document_part: DocumentPart)

Document section, providing access to section and page setup settings.

Also provides access to headers and footers.

property bottom_margin: Length | None

Read/write. Bottom margin for pages in this section, in EMU.

None when no bottom margin has been specified. Assigning None removes any bottom-margin setting.

property different_first_page_header_footer: bool

True if this section displays a distinct first-page header and footer.

Read/write. The definition of the first-page header and footer are accessed using first_page_header and first_page_footer respectively.

property even_page_footer: _Footer

_Footer object defining footer content for even pages.

The content of this footer definition is ignored unless the document setting odd_and_even_pages_header_footer is set True.

property even_page_header: _Header

_Header object defining header content for even pages.

The content of this header definition is ignored unless the document setting odd_and_even_pages_header_footer is set True.

property first_page_footer: _Footer

_Footer object defining footer content for the first page of this section.

The content of this footer definition is ignored unless the property different_first_page_header_footer is set True.

property first_page_header: _Header

_Header object defining header content for the first page of this section.

The content of this header definition is ignored unless the property different_first_page_header_footer is set True.

footer

_Footer object representing default page footer for this section.

The default footer is used for odd-numbered pages when separate odd/even footers are enabled. It is used for both odd and even-numbered pages otherwise.

property footer_distance: Length | None

Distance from bottom edge of page to bottom edge of the footer.

Read/write. None if no setting is present in the XML.

property gutter: Length | None

Length object representing page gutter size in English Metric Units.

Read/write. The page gutter is extra spacing added to the inner margin to ensure even margins after page binding. Generally only used in book-bound documents with double-sided and facing pages.

This setting applies to all pages in this section.

header

_Header object representing default page header for this section.

The default header is used for odd-numbered pages when separate odd/even headers are enabled. It is used for both odd and even-numbered pages otherwise.

property header_distance: Length | None

Distance from top edge of page to top edge of header.

Read/write. None if no setting is present in the XML. Assigning None causes default value to be used.

iter_inner_content() → Iterator[Paragraph | Table]

Generate each Paragraph or Table object in this section.

Items appear in document order.

property left_margin: Length | None

Length object representing the left margin for all pages in this section in English Metric Units.

property orientation: WD_ORIENTATION

WD_ORIENTATION member specifying page orientation for this section.

One of WD_ORIENT.PORTRAIT or WD_ORIENT.LANDSCAPE.

property page_height: Length | None

Total page height used for this section.

This value is inclusive of all edge spacing values such as margins.

Page orientation is taken into account, so for example, its expected value would be Inches(8.5) for letter-sized paper when orientation is landscape.

property page_width: Length | None

Total page width used for this section.

This value is like "paper size" and includes all edge spacing values such as margins.

Page orientation is taken into account, so for example, its expected value would be Inches(11) for letter-sized paper when orientation is landscape.

property right_margin: Length | None

Length object representing the right margin for all pages in this section in English Metric Units.

property start_type: WD_SECTION_START

Type of page-break (if any) inserted at the start of this section.

For exmple, WD_SECTION_START.ODD_PAGE if the section should begin on the next odd page, possibly inserting two page-breaks instead of one.

property top_margin: Length | None

Length object representing the top margin for all pages in this section in English Metric Units.

_Header 和 _Footer 对象

_Header and _Footer objects

class docx.section._Header

Page header, used for all three types (default, even-page, and first-page).

Note that, like a document or table cell, a header must contain a minimum of one paragraph and a new or otherwise "empty" header contains a single empty paragraph. This first paragraph can be accessed as header.paragraphs[0] for purposes of adding content to it. Using add_paragraph() by itself to add content will leave an empty paragraph above the newly added one.

add_paragraph(text: str = '', style: str | ParagraphStyle | None = None) → Paragraph

Return paragraph newly added to the end of the content in this container.

The paragraph has text in a single run if present, and is given paragraph style style.

If style is None, no paragraph style is applied, which has the same effect as applying the 'Normal' style.

add_table(rows: int, cols: int, width: Length) → Table

Return table of width having rows rows and cols columns.

The table is appended appended at the end of the content in this container.

width is evenly distributed between the table columns.

property is_linked_to_previous: bool

True if this header/footer uses the definition from the prior section.

False if this header/footer has an explicit definition.

Assigning True to this property removes the header/footer definition for this section, causing it to "inherit" the corresponding definition of the prior section. Assigning False causes a new, empty definition to be added for this section, but only if no definition is already present.

iter_inner_content() → Iterator[Paragraph | Table]

Generate each Paragraph or Table in this container in document order.

property paragraphs

A list containing the paragraphs in this container, in document order.

Read-only.

property tables

A list containing the tables in this container, in document order.

Read-only.

class docx.section._Footer

Page footer, used for all three types (default, even-page, and first-page).

Note that, like a document or table cell, a footer must contain a minimum of one paragraph and a new or otherwise "empty" footer contains a single empty paragraph. This first paragraph can be accessed as footer.paragraphs[0] for purposes of adding content to it. Using add_paragraph() by itself to add content will leave an empty paragraph above the newly added one.

add_paragraph(text: str = '', style: str | ParagraphStyle | None = None) → Paragraph

Return paragraph newly added to the end of the content in this container.

The paragraph has text in a single run if present, and is given paragraph style style.

If style is None, no paragraph style is applied, which has the same effect as applying the 'Normal' style.

add_table(rows: int, cols: int, width: Length) → Table

Return table of width having rows rows and cols columns.

The table is appended appended at the end of the content in this container.

width is evenly distributed between the table columns.

property is_linked_to_previous: bool

True if this header/footer uses the definition from the prior section.

False if this header/footer has an explicit definition.

Assigning True to this property removes the header/footer definition for this section, causing it to "inherit" the corresponding definition of the prior section. Assigning False causes a new, empty definition to be added for this section, but only if no definition is already present.

iter_inner_content() → Iterator[Paragraph | Table]

Generate each Paragraph or Table in this container in document order.

property paragraphs

A list containing the paragraphs in this container, in document order.

Read-only.

property tables

A list containing the tables in this container, in document order.

Read-only.