共用方式為

FrameProperties Class

  • 發行項

Defines the FrameProperties Class.When the object is serialized out as xml, its qualified name is w:framePr.

Inheritance Hierarchy

System.Object
  DocumentFormat.OpenXml.OpenXmlElement
    DocumentFormat.OpenXml.OpenXmlLeafElement
      DocumentFormat.OpenXml.Wordprocessing.FrameProperties

Namespace:  DocumentFormat.OpenXml.Wordprocessing
Assembly:  DocumentFormat.OpenXml (in DocumentFormat.OpenXml.dll)

Syntax

'Declaration
Public Class FrameProperties _
    Inherits OpenXmlLeafElement
'Usage
Dim instance As FrameProperties

public class FrameProperties : OpenXmlLeafElement

Remarks

[ISO/IEC 29500-1 1st Edition]

17.3.1.11 framePr (Text Frame Properties)

This element specifies information about the current paragraph with regard to text frames. Text frames are paragraphs of text in a document which are positioned in a separate region or frame in the document, and can be positioned with a specific size and position relative to non-frame paragraphs in the current document.

The first piece of information specified by the framePr element is that the current paragraph is actually part of a text frame in the document. This information is specified simply by the presence of the framePr element in paragraph's properties. If the framePr element is omitted, the paragraph shall not be part of any text frame in the document.

The second piece of information concerns the set of paragraphs which are part of the current text frame in the document. This is determined based on the attributes on the framePr element. If the set of attribute values specified on two adjacent paragraphs is identical, then those two paragraphs shall be considered to be part of the same text frame and rendered within the same frame in the document.

[Example: Consider a document in which the following two paragraphs are located adjacent to one another:

<w:p>
  <w:pPr>
    <w:framePr w:w="2191" w:h="811" w:hRule="exact" w:hSpace="180" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1921"/>
  </w:pPr>
  <w:r>
    <w:t>Paragraph One</w:t>
  </w:r>
</w:p>
<w:p>
  <w:pPr>
    <w:framePr w:w="2191" w:h="810" w:hRule="exact" w:hSpace="180" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1921"/>
  </w:pPr>
  <w:r>
    <w:t>Paragraph Two.</w:t>
  </w:r>
</w:p>

These two paragraphs, although each is a part of a text frame due to the presence of the framePr element, are different text frames because of the differing h value - 810 vs. 811. end example]

The positioning of the frame relative to the properties stored on its attribute values shall be calculated relative to the next paragraphs in the document which is itself not part of a text frame.

[Example: Consider a document in which the following three paragraphs are located adjacent to one another:

<w:p>
  <w:pPr>
    <w:framePr w:w="2191" w:h="811" w:hRule="exact" w:hSpace="180" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1921"/>
  </w:pPr>
  <w:r>
    <w:t>Paragraph One</w:t>
  </w:r>
</w:p>
<w:p>
  <w:pPr>
    <w:framePr w:w="2191" w:h="811" w:hRule="exact" w:hSpace="180" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1921"/>
  </w:pPr>
  <w:r>
    <w:t>Paragraph Two.</w:t>
  </w:r>
</w:p>
<w:p/>

The first two paragraphs form a single text frame, which is anchored using its attribute values relative to the first non-frame paragraph following it (the third paragraph in the example). end example]

Parent Elements

pPr (§17.3.1.26); pPr (§17.3.1.25); pPr (§17.7.5.2); pPr (§17.7.6.1); pPr (§17.9.23); pPr (§17.7.8.2)

Attributes

Description

anchorLock (Lock Frame Anchor to Paragraph)

Specifies that the frame shall always remain in the same logical position relative to the non-frame paragraphs which precede and follow it in this document.

This means that consumers which modify this document shall ensure that this text frame remains directly above the non-frame paragraph which it is currently above, by adjusting the frame's positioning properties as needed as the paragraph is moved throughout the document rather than moving the frame's logical location within the paragraphs in the document, if that would be more appropriate.

If this attribute is omitted, then this frame shall not have a locked anchor position.

[Example: Consider the following WordprocessingML paragraph contained in a text frame:

<w:p>
  <w:pPr>
    <w:framePr w:w="2419" w:h="2189" w:hRule="exact" w:hSpace="187" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1643" w:y="73" w:anchorLock="1"/>
  </w:pPr>
  <w:r>
    <w:t>Text Frame Content.</w:t>
  </w:r>
</w:p>

This text frame has a locked anchor using the anchorLock attribute. If the text frame is moved down in the document, the text frame properties must be adjusted to be relative to the parent paragraph's same logical position - the paragraph cannot be relocated in the document, which results in changes to the frame's properties as follows:

<w:p>
  <w:pPr>
    <w:framePr w:w="2419" w:h="2189" w:hRule="exact" w:hSpace="187" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1643" w:y="-5247" w:anchorLock="1"/>
  </w:pPr>
  <w:r>
    <w:t>Text Frame Content.</w:t>
  </w:r>
</w:p>

The non-frame paragraph was relocated 5320 twentieths of a point below its original location in the document, and the frame's vertical positioning properties were adjusted to ensure its logical location within the paragraph ordering was constant while its visual location was changed. end example]

The possible values for this attribute are defined by the ST_OnOff simple type (§22.9.2.7).

dropCap (Drop Cap Frame)

Specifies that the current frame contains a drop cap to be located at the beginning of the next non-frame paragraph in the document. Its contents shall be used to specify how that drop cap should be positioned relative to that paragraph.

If this attribute is omitted, then this frame shall not be considered a drop cap frame.

[Note: Although a drop cap is simply a text frame, this element is used to determine how the cap should be positioned relative to the following non-frame paragraph in relative terms (see possible values), rather than relying on absolute sizing. end note]

[Example: Consider the following paragraph containing a text frame which should be positioned as a drop cap:

<w:p> 
  <w:pPr>
    <w:framePr w:dropCap="margin" w:lines="3" w:hSpace="432" w:wrap="around" w:vAnchor="text" w:hAnchor="page" /> 
  </w:pPr>
  <w:r> 
    <w:t>A</w:t> 
  </w:r>
</w:p>

The dropCap attribute specifies a value of margin, so this drop cap is placed outside of the text margin before the start of the current text. end example]

The possible values for this attribute are defined by the ST_DropCap simple type (§17.18.20).

h (Frame Height)

Specifies the frame's height.

This height is expressed in twentieths of a point.

If this attribute is omitted, then its value shall be assumed to be 0.

The meaning of the value of the h attribute is defined based on the value of the hRule attribute for this text frame as follows:

  • If the value of hRule is auto, then the frame's height should be automatically determined based on the height of its contents. This value is ignored.

  • If the value of hRule is atLeast, then the frame's height should be at least the value of this attribute.

  • If the value of hRule is exact, then the frame's height should be exactly the value of this attribute.

[Example: Consider the following paragraph containing a text frame:

<w:p>
  <w:pPr>
    <w:framePr w:w="2419" w:h="2189" w:hRule="atLeast" w:hSpace="187" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1643" w:y="73" />
  </w:pPr>
  <w:r>
    <w:t>Text Frame Content.</w:t>
  </w:r>
</w:p>

The h attribute specifies a value of 2189 twentieths of a point, so this text frame is a minimum of 2189 twentieths of a point high regardless of its contents, since its hRule value is set to atLeast. end example]

The possible values for this attribute are defined by the ST_TwipsMeasure simple type (§22.9.2.14).

hAnchor (Frame Horizontal Positioning Base)

Specifies the base object from which the horizontal positioning in the x attribute should be calculated.

A text frame can be horizontally positioned relative to:

  • The vertical edge of the page before any runs of text (the left edge for left-to-right paragraphs, the right edge for right-to-left paragraphs)

  • The vertical edge of the text margin before any runs of text (the left edge for left-to-right paragraphs, the right edge for right-to-left paragraphs)

  • The vertical edge of the text margin for the column in which the anchor paragraph is located

If this attribute is omitted, then its value shall be assumed to be page.

[Example: Consider a text frame which should be positioned one inch to the right of its column in a left-to-right document. This text frame would be specified using the following WordprocessingML:

<w:pPr>
  <w:framePr … w:x="1440" w:hAnchor="column" />
</w:pPr>

These frame properties specify that they are relative to the anchor paragraph's column, and that relative to that column, the frame should be 1440 twentieths of a point in the direction of the flow of text (right, in this case). end example]

The possible values for this attribute are defined by the ST_HAnchor simple type (§17.18.35).

hRule (Frame Height Type)

Specifies the meaning of the height specified for this frame.

The meaning of the value of the h attribute is defined based on the value of the hRule attribute for this text frame as follows:

  • If the value of hRule is auto, then the frame's height should be automatically determined based on the height of its contents. The h value is ignored.

  • If the value of hRule is atLeast, then the frame's height should be at least the value the h attribute.

  • If the value of hRule is exact, then the frame's height should be exactly the value of the h attribute.

If this attribute is omitted, then its value shall be assumed to be auto.

[Example: Consider the following paragraph containing a text frame:

<w:p>
  <w:pPr>
    <w:framePr w:w="2419" w:h="2189" w:hRule="atLeast" w:hSpace="187" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1643" w:y="73" />
  </w:pPr>
  <w:r>
    <w:t>Text Frame Content.</w:t>
  </w:r>
</w:p>

The h attribute specifies a value of 2189 twentieths of a point, so this text frame is a minimum of 2189 twentieths of a point high regardless of its contents, since its hRule value is set to atLeast. end example]

The possible values for this attribute are defined by the ST_HeightRule simple type (§17.18.37).

hSpace (Horizontal Frame Padding)

Specifies the minimum distance which shall be maintained between the current text frame and any non-frame text which has been allowed to flow around this object when the wrap attribute on this text frame is set to around.

This distance is expressed in twentieths of a point.

If the wrap value is not set to around, this value shall be ignored. If this attribute is omitted, its value shall be assumed to be 0.

[Example: Consider a text frame which should have a minimum of a one-half inch spacing from any non-frame text on its left and right sides. This constraint would be specified using the following WordprocessingML:

<w:pPr>
  <w:framePr … w:hSpace="720" w:wrap="around" />
</w:pPr>

The wrap value of around allows text to wrap around this text frame, and the hSpace attribute specifies that the spacing between text and this frame must be a minimum of 720 twentieths of a point. end example]

The possible values for this attribute are defined by the ST_TwipsMeasure simple type (§22.9.2.14).

lines (Drop Cap Vertical Height in Lines)

Specifies the number of lines in the non-frame paragraph to which this text frame is anchored which should be used to calculate the drop cap's height.

If the current frame is not a drop cap (the parent framePr element does not have the dropCap attribute), this value is ignored. If the current text frame is a dropped cap and this attribute is present, then any other vertical positioning information shall be ignored.

If this attribute is omitted, then its value shall be considered to be 1.

[Example: Consider the following paragraph containing a text frame which should be positioned as a drop cap:

<w:p> 
  <w:pPr>
    <w:framePr w:dropCap="margin" w:lines="3" w:hSpace="432" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:y="400" w:yAlign="text" /> 
  </w:pPr>
  <w:r> 
    <w:t>O</w:t> 
  </w:r>
</w:p>

Since this frame is being used as a dropped cap, the y and yAlign attributes are ignored and the height of the drop cap is the first three lines of the anchor paragraph. end example]

The possible values for this attribute are defined by the ST_DecimalNumber simple type (§17.18.10).

vAnchor (Frame Vertical Positioning Base)

Specifies the base object from which the horizontal positioning in the y attribute should be calculated.

A text frame can be horizontally positioned relative to:

  • The horizontal edge of the page before any runs of text (the top edge for top-to-bottom sections, the bottom for bottom-to-top sections)

  • The horizontal edge of the text margin before any runs of text (the top edge for top-to-bottom sections, the bottom for bottom-to-top sections)

  • The horizontal edge of the page before any runs of text (the top edge for top-to-bottom sections, the bottom for bottom-to-top sections)

If this attribute is omitted, then its value shall be assumed to be page.

[Example: Consider a text frame which should be positioned two inches below the page top in a top-to-bottom document. This text frame would be specified using the following WordprocessingML:

<w:pPr>
  <w:framePr … w:y="2880" w:vAnchor="page" />
</w:pPr>

These frame properties specify that they are relative to the anchor page, and that relative to that column, the frame should be 2880 twentieths of a point in the direction of the flow of text (down, in this case). end example]

The possible values for this attribute are defined by the ST_VAnchor simple type (§17.18.100).

vSpace (Vertical Frame Padding)

Specifies the minimum distance which shall be maintained between the current text frame and any non-frame text which is above or below this text frame.

This distance is expressed in twentieths of a point.

If this attribute is omitted, its value shall be assumed to be 0.

[Example: Consider a text frame which should have a minimum of a one-half inch spacing from any non-frame text on its top and bottom sides. This constraint would be specified using the following WordprocessingML:

<w:pPr>
  <w:framePr … w:vSpace="720" />
</w:pPr>

The vspace attribute specifies that the spacing between text and this frame must be a minimum of 720 twentieths of a point. end example]

The possible values for this attribute are defined by the ST_TwipsMeasure simple type (§22.9.2.14).

w (Frame Width)

Specifies the exact value for this text frame's width.

This value is specified in twentieths of a point.

When this attribute is present, the text frame shall be rendered to the exact width specified. If this attribute is omitted, the text frame width shall be automatically determined by the maximum line width of the content within the text frame.

[Example: Consider the following WordprocessingML fragment specifying a text frame:

<w:p>
  <w:pPr>
    <w:framePr w:w="2419" w:h="2189" w:hRule="atLeast" w:hSpace="187" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1643" w:y="73" />
  </w:pPr>
  <w:r>
    <w:t>Text Frame Content.</w:t>
  </w:r>
</w:p>

This text frame specifies that its width must be exactly 2419 twips. If this attribute was removed, the text frame would be rendered at the width of the content Text Frame Content. end example]

The possible values for this attribute are defined by the ST_TwipsMeasure simple type (§22.9.2.14).

wrap (Text Wrapping Around Frame)

Specifies the style of text wrapping which should be allowed around the contents of this text frame. This attribute determines if non-frame text shall be allowed to flow around the contents of this frame.

If this attribute is omitted, its value shall be assumed to be around.

[Example: Consider the following WordprocessingML fragment specifying a text frame:

<w:p>
  <w:pPr>
    <w:framePr w:w="2419" w:h="2189" w:hRule="atLeast" w:hSpace="187" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1643" w:y="73" />
  </w:pPr>
  <w:r>
    <w:t>Text Frame Content.</w:t>
  </w:r>
</w:p>

This text frame specifies that when the frame is rendered on the page, any non-text frame paragraphs which would normally flow onto the same lines must be allowed to do so. end example]

The possible values for this attribute are defined by the ST_Wrap simple type (§17.18.104).

x (Absolute Horizontal Position)

Specifies an absolute horizontal position for the text frame. This absolute position is specified relative to the horizontal anchor specified by the hAnchor attribute for this text frame.

This value is expressed in twentieths of a point. If it is positive, then the text frame is positioned after the anchor object in the direction of horizontal text flow in this document. If it is negative, then the text frame is positioned before the anchor object in the direction of horizontal text flow in this document.

If the xAlign attribute is also specified, then this value is ignored. If this attribute is omitted, then its value shall be assumed to be 0.

[Example: Consider the following WordprocessingML fragment specifying a text frame:

<w:p>
  <w:pPr>
    <w:framePr w:w="2419" w:h="2189" w:hRule="atLeast" w:hSpace="187" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1643" w:y="73" />
  </w:pPr>
  <w:r>
    <w:t>Text Frame Content.</w:t>
  </w:r>
</w:p>

This text frame specifies that it should be located exactly 1643 twentieths of a point after the vertical edge of the page (from the hAnchor attribute). end example]

The possible values for this attribute are defined by the ST_SignedTwipsMeasure simple type (§17.18.81).

xAlign (Relative Horizontal Position)

Specifies a relative horizontal position for the text frame. This relative position is specified relative to the horizontal anchor specified by the hAnchor attribute for this text frame.

If omitted, this attribute is not specified and the value of the x attribute determines the absolute horizontal position of the text frame. If specified, the position for this attribute supersede any value which is specified in the x attribute, and that value is ignored.

[Example: Consider the following WordprocessingML fragment specifying a text frame:

<w:p>
  <w:pPr>
    <w:framePr w:w="2419" w:h="2189" w:hRule="atLeast" w:hSpace="187" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1643" w:xAlign="left" w:y="73" />
  </w:pPr>
  <w:r>
    <w:t>Text Frame Content.</w:t>
  </w:r>
</w:p>

This text frame specifies that it has a horizontal placement of exactly 1643 twentieths of a point relative to the page, but that exact placement is overridden by the presence of the xAlign attribute to place the frame on the left side of the page. end example]

The possible values for this attribute are defined by the ST_XAlign simple type (§22.9.2.18).

y (Absolute Vertical Position)

Specifies an absolute vertical position for the text frame. This absolute position is specified relative to the vertical anchor specified by the vAnchor attribute for this text frame.

This value is expressed in twentieths of a point. If it is positive, then the text frame is positioned after the anchor object in the direction of vertical text flow in this document. If it is negative, then the text frame is positioned before the anchor object in the direction of vertical text flow in this document.

If the yAlign attribute is also specified, then this value is ignored. If this attribute is omitted, then its value shall be assumed to be 0.

[Example: Consider the following WordprocessingML fragment specifying a text frame:

<w:p>
  <w:pPr>
    <w:framePr w:w="2419" w:h="2189" w:hRule="atLeast" w:hSpace="187" w:wrap="around" w:vAnchor="text" w:hAnchor="page" w:x="1643" w:y="73" />
  </w:pPr>
  <w:r>
    <w:t>Text Frame Content.</w:t>
  </w:r>
</w:p>

This text frame specifies that it should be located exactly 79 twentieths of a point below the top vertical edge of the anchor's paragraph's text (from the vAnchor attribute), assuming that the vertical text direction is top to bottom. end example]

The possible values for this attribute are defined by the ST_SignedTwipsMeasure simple type (§17.18.81).

yAlign (Relative Vertical Position)

Specifies a relative vertical position for the text frame. This relative position is specified relative to the vertical anchor specified by the vAnchor attribute for this text frame.

If omitted, this attribute is not specified and the value of the y attribute determines the absolute horizontal position of the text frame. If specified, the position for this attribute supersedes any value which is specified in the y attribute, and that value is ignored, unless the vAnchor is set to text, in which case any relative positioning is not allowed, and is itself ignored.

[Example: Consider the following WordprocessingML fragment specifying a text frame:

<w:p>
  <w:pPr>
    <w:framePr w:w="2419" w:h="2189" w:hRule="atLeast" w:hSpace="187" w:wrap="around" w:vAnchor="margin" w:hAnchor="page" w:x="1643" w:y="73" w:yAlign="center" />
  </w:pPr>
  <w:r>
    <w:t>Text Frame Content.</w:t>
  </w:r>
</w:p>

This text frame specifies that it has a vertical placement of exactly 73 twentieths of a point relative to the top margin, but that exact placement is overridden by the presence of the yAlign attribute to place the frame in the center of the margin. end example]

The possible values for this attribute are defined by the ST_YAlign simple type (§22.9.2.20).

[Note: The W3C XML Schema definition of this element’s content model (CT_FramePr) is located in §A.1. end note]

© ISO/IEC29500: 2008.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

FrameProperties Members

DocumentFormat.OpenXml.Wordprocessing Namespace