Word. Paragraph class

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/paragraph-properties.yaml

await Word.run(async (context) => {
  // Center last paragraph alignment.
  context.document.body.paragraphs.getLast().alignment = "Centered";

  await context.sync();
});

contentControls

获取段落中内容控件对象的集合。

readonly contentControls: Word.ContentControlCollection;

属性值

Word.ContentControlCollection

注解

context

与对象关联的请求上下文。这会将加载项的进程连接到 Office 主机应用程序的进程。

context: RequestContext;

属性值

Word.RequestContext

endnotes

获取段落中的尾注集合。

readonly endnotes: Word.NoteItemCollection;

属性值

Word.NoteItemCollection

注解

[ API 集：WordApi 1.5 ]

fields

获取段落中字段的集合。

readonly fields: Word.FieldCollection;

属性值

Word.FieldCollection

注解

firstLineIndent

指定第一行或悬挂缩进的值（以磅为单位）。用正数设置首行缩进的尺寸，用负数设置悬挂缩进的尺寸。

firstLineIndent: number;

属性值

number

注解

font

获取段落的文本格式。使用此对象获取和设置字体名称、大小、颜色和其他属性。

readonly font: Word.Font;

属性值

Word.Font

注解

footnotes

获取段落中的脚注集合。

readonly footnotes: Word.NoteItemCollection;

属性值

Word.NoteItemCollection

注解

[ API 集：WordApi 1.5 ]

inlinePictures

获取段落中的 InlinePicture 对象的集合。集合不包括浮动图像。

readonly inlinePictures: Word.InlinePictureCollection;

属性值

Word.InlinePictureCollection

注解

isLastParagraph

指明 paragraph 是其父正文内的最后一个段落。

readonly isLastParagraph: boolean;

属性值

boolean

注解

isListItem

检查 paragraph 是否为 listItem。

readonly isListItem: boolean;

属性值

boolean

注解

leftIndent

指定段落的左缩进值（以磅为单位）。

leftIndent: number;

属性值

number

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/paragraph-properties.yaml

await Word.run(async (context) => {
  // Indent the first paragraph.
  context.document.body.paragraphs.getFirst().leftIndent = 75; //units = points

  return context.sync();
});

lineSpacing

指定指定段落的行距（以磅为单位）。在 Word UI 中，该值应除以 12。

lineSpacing: number;

属性值

number

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/paragraph-properties.yaml

await Word.run(async (context) => {
  // Adjust line spacing.
  context.document.body.paragraphs.getFirst().lineSpacing = 20;

  await context.sync();
});

lineUnitAfter

指定段落后网格线中的间距量。

lineUnitAfter: number;

属性值

number

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/paragraph-properties.yaml

await Word.run(async (context) => {
  // Set the space (in line units) after the first paragraph.
  context.document.body.paragraphs.getFirst().lineUnitAfter = 1;

  await context.sync();
});

lineUnitBefore

指定段落前的网格线间距量。

lineUnitBefore: number;

属性值

number

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/paragraph-properties.yaml

await Word.run(async (context) => {
  // Set the space (in line units) before the first paragraph.
  context.document.body.paragraphs.getFirst().lineUnitBefore = 1;

  await context.sync();
});

list

获取 paragraph 所属的 List。 ItemNotFound如果段落不在列表中，则引发错误。

readonly list: Word.List;

属性值

Word.List

注解

listItem

获取 paragraph 的 ListItem。如果段落不是列表的一 ItemNotFound 部分，则引发错误。

readonly listItem: Word.ListItem;

属性值

Word.ListItem

注解

listItemOrNullObject

获取 paragraph 的 ListItem。如果段落不是列表的一部分，则此方法将返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

readonly listItemOrNullObject: Word.ListItem;

属性值

Word.ListItem

注解

listOrNullObject

获取 paragraph 所属的 List。如果段落不在列表中，则此方法将返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

readonly listOrNullObject: Word.List;

属性值

Word.List

注解

outlineLevel

指定段落的大纲级别。

outlineLevel: number;

属性值

number

注解

parentBody

获取 paragraph 的父正文。

readonly parentBody: Word.Body;

属性值

Word.Body

注解

parentContentControl

获取包含段落的内容控件。 ItemNotFound如果没有父内容控件，则引发错误。

readonly parentContentControl: Word.ContentControl;

属性值

Word.ContentControl

注解

parentContentControlOrNullObject

获取包含段落的内容控件。如果没有父内容控件，则此方法将返回其属性设置为 true的对象isNullObject。有关详细信息，请参阅 *OrNullObject 方法和属性。

readonly parentContentControlOrNullObject: Word.ContentControl;

属性值

Word.ContentControl

注解

parentTable

获取包含 paragraph 的 table。 ItemNotFound如果未包含在表中，则引发错误。

readonly parentTable: Word.Table;

属性值

Word.Table

注解

parentTableCell

获取包含 paragraph 的 tableCell。 ItemNotFound如果表单元格中未包含错误，则引发错误。

readonly parentTableCell: Word.TableCell;

属性值

Word.TableCell

注解

parentTableCellOrNullObject

获取包含 paragraph 的 tableCell。如果它未包含在表单元格中，则此方法将返回其 isNullObject 属性设置为 true的对象。有关详细信息，请参阅 *OrNullObject 方法和属性。

readonly parentTableCellOrNullObject: Word.TableCell;

属性值

Word.TableCell

注解

parentTableOrNullObject

获取包含 paragraph 的 table。如果它未包含在表中，则此方法将返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

readonly parentTableOrNullObject: Word.Table;

属性值

Word.Table

注解

rightIndent

指定段落的右缩进值（以磅为单位）。

rightIndent: number;

属性值

number

注解

spaceAfter

指定段落后的间距（以磅为单位）。

spaceAfter: number;

属性值

number

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/paragraph-properties.yaml

await Word.run(async (context) => {
  // Set the space (in points) after the first paragraph.
  context.document.body.paragraphs.getFirst().spaceAfter = 20;

  await context.sync();
});

spaceBefore

指定段落前的间距（以磅为单位）。

spaceBefore: number;

属性值

number

注解

style

指定段落的样式名称。请对自定义样式和本地化样式名称使用此属性。若要使用可以在区域设置之间移植的嵌入样式，请参阅“styleBuiltIn”属性。

style: string;

属性值

string

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-styles.yaml

// Applies the specified style to a paragraph.
await Word.run(async (context) => {
  const styleName = $("#style-name-to-use").val() as string;
  if (styleName == "") {
    console.warn("Enter a style name to apply.");
    return;
  }

  const style = context.document.getStyles().getByNameOrNullObject(styleName);
  style.load();
  await context.sync();

  if (style.isNullObject) {
    console.warn(`There's no existing style with the name '${styleName}'.`);
  } else if (style.type != Word.StyleType.paragraph) {
    console.log(`The '${styleName}' style isn't a paragraph style.`);
  } else {
    const body = context.document.body;
    body.clear();
    body.insertParagraph(
      "Video provides a powerful way to help you prove your point. When you click Online Video, you can paste in the embed code for the video you want to add. You can also type a keyword to search online for the video that best fits your document.",
      "Start"
    );
    const paragraph = body.paragraphs.getFirst();
    paragraph.style = style.nameLocal;
    console.log(`'${styleName}' style applied to first paragraph.`);
  }
});

styleBuiltIn

指定段落的内置样式名称。请对可以在区域设置之间移植的嵌入样式使用此属性。若要使用自定义样式或本地化样式名称，请参阅“style”属性。

styleBuiltIn: Word.BuiltInStyleName | "Other" | "Normal" | "Heading1" | "Heading2" | "Heading3" | "Heading4" | "Heading5" | "Heading6" | "Heading7" | "Heading8" | "Heading9" | "Toc1" | "Toc2" | "Toc3" | "Toc4" | "Toc5" | "Toc6" | "Toc7" | "Toc8" | "Toc9" | "FootnoteText" | "Header" | "Footer" | "Caption" | "FootnoteReference" | "EndnoteReference" | "EndnoteText" | "Title" | "Subtitle" | "Hyperlink" | "Strong" | "Emphasis" | "NoSpacing" | "ListParagraph" | "Quote" | "IntenseQuote" | "SubtleEmphasis" | "IntenseEmphasis" | "SubtleReference" | "IntenseReference" | "BookTitle" | "Bibliography" | "TocHeading" | "TableGrid" | "PlainTable1" | "PlainTable2" | "PlainTable3" | "PlainTable4" | "PlainTable5" | "TableGridLight" | "GridTable1Light" | "GridTable1Light_Accent1" | "GridTable1Light_Accent2" | "GridTable1Light_Accent3" | "GridTable1Light_Accent4" | "GridTable1Light_Accent5" | "GridTable1Light_Accent6" | "GridTable2" | "GridTable2_Accent1" | "GridTable2_Accent2" | "GridTable2_Accent3" | "GridTable2_Accent4" | "GridTable2_Accent5" | "GridTable2_Accent6" | "GridTable3" | "GridTable3_Accent1" | "GridTable3_Accent2" | "GridTable3_Accent3" | "GridTable3_Accent4" | "GridTable3_Accent5" | "GridTable3_Accent6" | "GridTable4" | "GridTable4_Accent1" | "GridTable4_Accent2" | "GridTable4_Accent3" | "GridTable4_Accent4" | "GridTable4_Accent5" | "GridTable4_Accent6" | "GridTable5Dark" | "GridTable5Dark_Accent1" | "GridTable5Dark_Accent2" | "GridTable5Dark_Accent3" | "GridTable5Dark_Accent4" | "GridTable5Dark_Accent5" | "GridTable5Dark_Accent6" | "GridTable6Colorful" | "GridTable6Colorful_Accent1" | "GridTable6Colorful_Accent2" | "GridTable6Colorful_Accent3" | "GridTable6Colorful_Accent4" | "GridTable6Colorful_Accent5" | "GridTable6Colorful_Accent6" | "GridTable7Colorful" | "GridTable7Colorful_Accent1" | "GridTable7Colorful_Accent2" | "GridTable7Colorful_Accent3" | "GridTable7Colorful_Accent4" | "GridTable7Colorful_Accent5" | "GridTable7Colorful_Accent6" | "ListTable1Light" | "ListTable1Light_Accent1" | "ListTable1Light_Accent2" | "ListTable1Light_Accent3" | "ListTable1Light_Accent4" | "ListTable1Light_Accent5" | "ListTable1Light_Accent6" | "ListTable2" | "ListTable2_Accent1" | "ListTable2_Accent2" | "ListTable2_Accent3" | "ListTable2_Accent4" | "ListTable2_Accent5" | "ListTable2_Accent6" | "ListTable3" | "ListTable3_Accent1" | "ListTable3_Accent2" | "ListTable3_Accent3" | "ListTable3_Accent4" | "ListTable3_Accent5" | "ListTable3_Accent6" | "ListTable4" | "ListTable4_Accent1" | "ListTable4_Accent2" | "ListTable4_Accent3" | "ListTable4_Accent4" | "ListTable4_Accent5" | "ListTable4_Accent6" | "ListTable5Dark" | "ListTable5Dark_Accent1" | "ListTable5Dark_Accent2" | "ListTable5Dark_Accent3" | "ListTable5Dark_Accent4" | "ListTable5Dark_Accent5" | "ListTable5Dark_Accent6" | "ListTable6Colorful" | "ListTable6Colorful_Accent1" | "ListTable6Colorful_Accent2" | "ListTable6Colorful_Accent3" | "ListTable6Colorful_Accent4" | "ListTable6Colorful_Accent5" | "ListTable6Colorful_Accent6" | "ListTable7Colorful" | "ListTable7Colorful_Accent1" | "ListTable7Colorful_Accent2" | "ListTable7Colorful_Accent3" | "ListTable7Colorful_Accent4" | "ListTable7Colorful_Accent5" | "ListTable7Colorful_Accent6";

属性值

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/90-scenarios/doc-assembly.yaml

await Word.run(async (context) => {
    const paragraph = context.document.body.insertParagraph("Timeline", "End");
    paragraph.styleBuiltIn = "Heading2";
    const paragraph2 = context.document.body.insertParagraph("The Services shall commence on July 31, 2015, and shall continue through July 29, 2015.", "End");
    paragraph2.styleBuiltIn = "Normal";
    const paragraph3 = context.document.body.insertParagraph("Project Costs by Phase", "End");
    paragraph3.styleBuiltIn = "Heading2";
    // Note a content control with the title of "ProjectCosts" is added. Content will be replaced later.
    const paragraph4 = context.document.body.insertParagraph("<Add Project Costs Here>", "End");
    paragraph4.styleBuiltIn = "Normal";
    paragraph4.font.highlightColor = "#FFFF00";
    const contentControl = paragraph4.insertContentControl();
    contentControl.title = "ProjectCosts";
    const paragraph5 = context.document.body.insertParagraph("Project Team", "End");
    paragraph5.styleBuiltIn = "Heading2";
    paragraph5.font.highlightColor = "#FFFFFF";
    const paragraph6 = context.document.body.insertParagraph("Terms of Work", "End");
    paragraph6.styleBuiltIn = "Heading1";
    const paragraph7 = context.document.body.insertParagraph("Contractor shall provide the Services and Deliverable(s) as follows:", "End");
    paragraph7.styleBuiltIn = "Normal";
    const paragraph8 = context.document.body.insertParagraph("Out-of-Pocket Expenses / Invoice Procedures", "End");
    paragraph8.styleBuiltIn = "Heading2";
    const paragraph9 = context.document.body.insertParagraph("Client will be invoiced monthly for the consulting services and T&L expenses. Standard Contractor invoicing is assumed to be acceptable. Invoices are due upon receipt. client will be invoiced all costs associated with out-of-pocket expenses (including, without limitation, costs and expenses associated with meals, lodging, local transportation and any other applicable business expenses) listed on the invoice as a separate line item. Reimbursement for out-of-pocket expenses in connection with performance of this SOW, when authorized and up to the limits set forth in this SOW, shall be in accordance with Client's then-current published policies governing travel and associated business expenses, which information shall be provided by the Client Project Manager.", "End");
    paragraph9.styleBuiltIn = "Normal";
    // Insert a page break at the end of the document.
    context.document.body.insertBreak("Page", "End");

    await context.sync();
});

tableNestingLevel

获取 paragraph 的表级别。如果段落不在表中，则返回 0。

readonly tableNestingLevel: number;

属性值

number

注解

text

获取段落的文本。

readonly text: string;

属性值

string

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/get-paragraph-on-insertion-point.yaml

await Word.run(async (context) => {
  // The collection of paragraphs of the current selection returns the full paragraphs contained in it.
  const paragraph = context.document.getSelection().paragraphs.getFirst();
  paragraph.load("text");

  await context.sync();
  console.log(paragraph.text);
});

uniqueLocalId

获取表示当前会话中的段落标识符的字符串。 ID 采用标准 8-4-4-4-12 GUID 格式，没有大括号，并且因会话和共同创作者而异。

readonly uniqueLocalId: string;

属性值

string

注解

[ API 集：WordApi 1.6 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-annotations.yaml

// Registers event handlers.
await Word.run(async (context) => {
  eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
  eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

  eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
  eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
  eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
  eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);

  await context.sync();

  console.log("Event handlers registered.");
});

...

async function paragraphChanged(args: Word.ParagraphChangedEventArgs) {
  await Word.run(async (context) => {
    const results = [];
    for (let id of args.uniqueLocalIds) {
      let para = context.document.getParagraphByUniqueLocalId(id);
      para.load("uniqueLocalId");

      results.push({ para: para, text: para.getText() });
    }

    await context.sync();

    for (let result of results) {
      console.log(`${args.type}: ${result.para.uniqueLocalId} - ${result.text.value}`);
    }
  });
}

方法详细信息

attachToList(listId, level)

将 paragraph 加入指定级别的现有 list。如果 paragraph 无法加入 list 或已是 listItem，则无法执行此方法。

attachToList(listId: number, level: number): Word.List;

参数

listId: number

必需。现有列表的 ID。

level: number

必需。列表中的级别。

Word.List

注解

clear()

清除 paragraph 对象的内容。用户可以对已清除的内容执行撤消操作。

clear(): void;

void

注解

示例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a proxy object for the paragraphs collection.
    const paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for all of the paragraphs.
    paragraphs.load('style');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();

    // Queue a command to clear the contents of the first paragraph.
    paragraphs.items[0].clear();

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('Cleared the contents of the first paragraph.');
});

delete()

从文档中删除段落及其内容。

delete(): void;

void

注解

示例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a proxy object for the paragraphs collection.
    const paragraphs = context.document.body.paragraphs;

    // Queue a command to load the text property for all of the paragraphs.
    paragraphs.load('text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();

    // Queue a command to delete the first paragraph.
    paragraphs.items[0].delete();

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('Deleted the first paragraph.');
});

detachFromList()

如果此段落是列表项目的话，从列表中移出此段落。

detachFromList(): void;

void

注解

getAnnotations()

获取在此 Paragraph 对象上设置的注释。

getAnnotations(): Word.AnnotationCollection;

Word.AnnotationCollection

注解

[ API 集：WordApi 1.7 ]

getComments()

获取与段落关联的注释。

getComments(): Word.CommentCollection;

Word.CommentCollection

注解

getContentControls(options)

获取段落中当前支持的内容控件。

getContentControls(options?: Word.ContentControlOptions): Word.ContentControlCollection;

参数

options: Word.ContentControlOptions

可选。用于定义返回哪些内容控件的选项。

Word.ContentControlCollection

注解

[ API 集：WordApi 1.5 ]

重要说明：如果在 options 参数中提供了特定类型，则仅返回受支持类型的内容控件。请注意，在使用泛型Word的方法时将引发异常。与特定类型无关的 ContentControl。随着时间的推移，可能会支持其他类型的内容控件。因此，外接程序应请求并处理特定类型的内容控件。

getHtml()

获取段落对象的 HTML 表示形式。在网页或 HTML 查看器中呈现时，格式将与文档的格式相匹配，但不完全匹配。此方法不会为不同平台上的相同文档返回完全相同的 HTML， (Windows、Mac、web 上的Word等 ) 。如果需要精确保真度或跨平台的一致性，请使用 Paragraph.getOoxml() 返回的 XML 并将其转换为 HTML。

getHtml(): OfficeExtension.ClientResult<string>;

注解

示例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a proxy object for the paragraphs collection.
    const paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for all of the paragraphs.
    paragraphs.load('style');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();

    // Queue a set of commands to get the HTML of the first paragraph.
    const html = paragraphs.items[0].getHtml();

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('Paragraph HTML: ' + html.value);
});

getNext()

获取下一个段落。如果段落是最后一个 ItemNotFound 段落，则引发错误。

getNext(): Word.Paragraph;

Word.Paragraph

注解

getNextOrNullObject()

获取下一个段落。如果段落是最后一个段落，则此方法将返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

getNextOrNullObject(): Word.Paragraph;

Word.Paragraph

注解

getOoxml()

获取 paragraph 对象的 Office Open XML (OOXML) 表示形式。

getOoxml(): OfficeExtension.ClientResult<string>;

注解

示例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a proxy object for the paragraphs collection.
    const paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for the top 2 paragraphs.
    paragraphs.load({select: 'style', top: 2} );

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();

    // Queue a set of commands to get the OOXML of the first paragraph.
    const ooxml = paragraphs.items[0].getOoxml();

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('Paragraph OOXML: ' + ooxml.value);
});

getPrevious()

获取上一个段落。如果段落是第一个 ItemNotFound 段落，则引发错误。

getPrevious(): Word.Paragraph;

Word.Paragraph

注解

getPreviousOrNullObject()

获取上一个段落。如果段落是第一个段落，则此方法将返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

getPreviousOrNullObject(): Word.Paragraph;

Word.Paragraph

注解

示例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a proxy object for the paragraphs collection.
    const paragraphs = context.document.body.paragraphs;

    // Queue a command to load the text property for all of the paragraphs.
    paragraphs.load('text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();

    // Queue commands to create a proxy object for the next-to-last paragraph.
    const indexOfLastParagraph = paragraphs.items.length - 1;
    const precedingParagraph = paragraphs.items[indexOfLastParagraph].getPreviousOrNullObject();

    // Queue a command to load the text of the preceding paragraph.
    precedingParagraph.load('text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    if (precedingParagraph.isNullObject) {
        console.log('There are no paragraphs before the current one.');
    } else {
        console.log('The preceding paragraph is: ' + precedingParagraph.text);
    }
});

getRange(rangeLocation)

获取整个段落或段落的起点/终点，作为一个范围。

getRange(rangeLocation?: Word.RangeLocation.whole | Word.RangeLocation.start | Word.RangeLocation.end | Word.RangeLocation.after | Word.RangeLocation.content | "Whole" | "Start" | "End" | "After" | "Content"): Word.Range;

参数

rangeLocation: whole | start | end | after | content | "Whole" | "Start" | "End" | "After" | "Content"

可选。范围位置必须为“Whole”、“Start”、“End”、“After”或“Content”。

Word.Range

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/get-paragraph-on-insertion-point.yaml

await Word.run(async (context) => {
  // Get the complete sentence (as range) associated with the insertion point.
  const sentences = context.document
    .getSelection()
    .getTextRanges(["."] /* Using the "." as delimiter */, false /*means without trimming spaces*/);
  sentences.load("$none");
  await context.sync();

  // Expand the range to the end of the paragraph to get all the complete sentences.
  const sentencesToTheEndOfParagraph = sentences.items[0]
    .getRange()
    .expandTo(
      context.document
        .getSelection()
        .paragraphs.getFirst()
        .getRange(Word.RangeLocation.end)
    )
    .getTextRanges(["."], false /* Don't trim spaces*/);
  sentencesToTheEndOfParagraph.load("text");
  await context.sync();

  for (let i = 0; i < sentencesToTheEndOfParagraph.items.length; i++) {
    console.log(sentencesToTheEndOfParagraph.items[i].text);
  }
});

getReviewedText(changeTrackingVersion)

根据 ChangeTrackingVersion 选择获取审阅的文本。

getReviewedText(changeTrackingVersion?: Word.ChangeTrackingVersion): OfficeExtension.ClientResult<string>;

参数

changeTrackingVersion: Word.ChangeTrackingVersion

可选。该值必须为“Original”或“Current”。默认值为“Current”。

注解

getReviewedText(changeTrackingVersionString)

根据 ChangeTrackingVersion 选择获取审阅的文本。

getReviewedText(changeTrackingVersionString?: "Original" | "Current"): OfficeExtension.ClientResult<string>;

参数

changeTrackingVersionString: "Original" | "Current"

可选。该值必须为“Original”或“Current”。默认值为“Current”。

注解

getText(options)

返回段落的文本。这不包括公式、图形 (例如图像、视频、绘图) ，以及标记各种内容 (的特殊字符，例如内容控件、字段、注释、脚注、尾注) 。默认情况下，将排除隐藏的文本和标记为已删除的文本。

getText(options?: Word.GetTextOptions | {
            IncludeHiddenText?: boolean;
            IncludeTextMarkedAsDeleted?: boolean;
        }): OfficeExtension.ClientResult<string>;

参数

options: Word.GetTextOptions | { IncludeHiddenText?: boolean; IncludeTextMarkedAsDeleted?: boolean; }

可选。用于定义最终结果是否应包括隐藏文本和标记为已删除的文本的选项。

注解

[ API 集：WordApi 1.7 ]

getTextRanges(endingMarks, trimSpacing)

使用标点符号和/或其他结束标记获取段落中的文本范围。

getTextRanges(endingMarks: string[], trimSpacing?: boolean): Word.RangeCollection;

参数

endingMarks: string[]

必需。标点符号和/或其他结束标记作为字符串数组。

trimSpacing: boolean

可选。指示是否剪裁 (空格、制表符、分栏符和段落结束标记) 范围集合中返回的范围的开头和末尾的间距字符。默认值为 false，指示范围集合中包含范围开头和末尾的间距字符。

Word.RangeCollection

注解

getTrackedChanges()

获取段落中 TrackedChange 对象的集合。

getTrackedChanges(): Word.TrackedChangeCollection;

Word.TrackedChangeCollection

注解

[ API 集：WordApi 1.6 ]

insertAnnotations(annotations)

在此 Paragraph 对象上插入批注。

insertAnnotations(annotations: Word.AnnotationSet): OfficeExtension.ClientResult<string[]>;

参数

annotations: Word.AnnotationSet

要设置的批注。

OfficeExtension.ClientResult<string[]>

插入的批注标识符的数组。

注解

[ API 集：WordApi 1.7 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-annotations.yaml

// Adds annotations to the selected paragraph.
await Word.run(async (context) => {
  const paragraph = context.document.getSelection().paragraphs.getFirst();
  const critique1 = {
    colorScheme: Word.CritiqueColorScheme.red,
    start: 1,
    length: 3
  };
  const critique2 = {
    colorScheme: Word.CritiqueColorScheme.green,
    start: 6,
    length: 1
  };
  const critique3 = {
    colorScheme: Word.CritiqueColorScheme.blue,
    start: 10,
    length: 3
  };
  const critique4 = {
    colorScheme: Word.CritiqueColorScheme.lavender,
    start: 14,
    length: 3
  };
  const critique5 = {
    colorScheme: Word.CritiqueColorScheme.berry,
    start: 18,
    length: 10
  };
  const annotationSet: Word.AnnotationSet = {
    critiques: [critique1, critique2, critique3, critique4, critique5]
  };

  const annotationIds = paragraph.insertAnnotations(annotationSet);

  await context.sync();

  console.log("Annotations inserted:", annotationIds.value);
});

insertBreak(breakType, insertLocation)

在主文档的指定位置插入分隔符。

insertBreak(breakType: Word.BreakType | "Page" | "Next" | "SectionNext" | "SectionContinuous" | "SectionEven" | "SectionOdd" | "Line", insertLocation: Word.InsertLocation.before | Word.InsertLocation.after | "Before" | "After"): void;

参数

breakType: Word.BreakType | "Page" | "Next" | "SectionNext" | "SectionContinuous" | "SectionEven" | "SectionOdd" | "Line"

必填。要添加到文档的分隔符类型。

insertLocation: before | after | "Before" | "After"

必填。该值必须为“Before”或“After”。

void

注解

示例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a proxy object for the paragraphs collection.
    const paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for the top 2 paragraphs.
    // We never perform an empty load. We always must request a property.
    paragraphs.load({select: 'style', top: 2} );

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();

    // Queue a command to get the first paragraph.
    const paragraph = paragraphs.items[0];

    // Queue a command to insert a page break after the first paragraph.
    paragraph.insertBreak(Word.BreakType.page, Word.InsertLocation.after);

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('Inserted a page break after the paragraph.');
});

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/insert-line-and-page-breaks.yaml

Word.run(async (context) => {
  context.document.body.paragraphs.getFirst().insertBreak(Word.BreakType.line, "After");

  await context.sync();
  console.log("success");
});

insertContentControl(contentControlType)

使用内容控件包装 Paragraph 对象。

insertContentControl(contentControlType?: Word.ContentControlType.richText | Word.ContentControlType.plainText | Word.ContentControlType.checkBox | "RichText" | "PlainText" | "CheckBox"): Word.ContentControl;

参数

contentControlType: richText | plainText | checkBox | "RichText" | "PlainText" | "CheckBox"

可选。要插入的内容控件类型。必须为“RichText”、“PlainText”或“CheckBox”。默认值为“RichText”。

Word.ContentControl

注解

注意：参数 contentControlType 是在 WordApi 1.5 中引入的。 PlainText 支持已在 WordApi 1.5 中添加。 CheckBox 支持已在 WordApi 1.7 中添加。

示例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a proxy object for the paragraphs collection.
    const paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for the top 2 paragraphs.
    // We never perform an empty load. We always must request a property.
    paragraphs.load({select: 'style', top: 2} );

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();

    // Queue a command to get the first paragraph.
    const paragraph = paragraphs.items[0];

    // Queue a command to wrap the first paragraph in a rich text content control.
    paragraph.insertContentControl();

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('Wrapped the first paragraph in a content control.');
});

insertFileFromBase64(base64File, insertLocation)

将文档插入到指定位置的段落中。

insertFileFromBase64(base64File: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;

参数

base64File: string

必需。 .docx 文件的 Base64 编码内容。

insertLocation: replace | start | end | "Replace" | "Start" | "End"

必填。该值必须为“Replace”、“Start”或“End”。

Word.Range

注解

注意：如果要插入的文档在窗体字段中) 可能包含 ActiveX 控件 (，则不支持插入。请考虑将此类窗体字段替换为适合你的方案的内容控件或其他选项。

insertHtml(html, insertLocation)

将 HTML 插入到段落中的指定位置。

insertHtml(html: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;

参数

html: string

必填。要插入到段落中的 HTML。

insertLocation: replace | start | end | "Replace" | "Start" | "End"

必填。该值必须为“Replace”、“Start”或“End”。

Word.Range

注解

示例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a proxy object for the paragraphs collection.
    const paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for the top 2 paragraphs.
    // We never perform an empty load. We always must request a property.
    paragraphs.load({select: 'style', top: 2} );

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();

    // Queue a command to get the first paragraph.
    const paragraph = paragraphs.items[0];

    // Queue a command to insert HTML content at the end of the first paragraph.
    paragraph.insertHtml('<strong>Inserted HTML.</strong>', Word.InsertLocation.end);

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('Inserted HTML content at the end of the first paragraph.');
});

insertInlinePictureFromBase64(base64EncodedImage, insertLocation)

将图片插入到段落中的指定位置。

insertInlinePictureFromBase64(base64EncodedImage: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.InlinePicture;

参数

base64EncodedImage: string

必需。要插入的 Base64 编码图像。

insertLocation: replace | start | end | "Replace" | "Start" | "End"

必需。该值必须为“Replace”、“Start”或“End”。

Word.InlinePicture

注解

示例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a proxy object for the paragraphs collection.
    const paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for all of the paragraphs.
    paragraphs.load('style');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();

    // Queue a command to get the first paragraph.
    const paragraph = paragraphs.items[0];

    const b64encodedImg = "iVBORw0KGgoAAAANSUhEUgAAAB4AAAANCAIAAAAxEEnAAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACFSURBVDhPtY1BEoQwDMP6/0+XgIMTBAeYoTqso9Rkx1zG+tNj1H94jgGzeNSjteO5vtQQuG2seO0av8LzGbe3anzRoJ4ybm/VeKEerAEbAUpW4aWQCmrGFWykRzGBCnYy2ha3oAIq2MloW9yCCqhgJ6NtcQsqoIKdjLbFLaiACnYyf2fODbrjZcXfr2F4AAAAAElFTkSuQmCC";

    // Queue a command to insert a base64 encoded image at the beginning of the first paragraph.
    paragraph.insertInlinePictureFromBase64(b64encodedImg, Word.InsertLocation.start);

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('Added an image to the first paragraph.');
});

insertOoxml(ooxml, insertLocation)

将 OOXML 插入到指定位置的段落中。

insertOoxml(ooxml: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;

参数

ooxml: string

必需。要插入到段落中的 OOXML。

insertLocation: replace | start | end | "Replace" | "Start" | "End"

必需。该值必须为“Replace”、“Start”或“End”。

Word.Range

注解

insertParagraph(paragraphText, insertLocation)

在指定位置插入段落。

insertParagraph(paragraphText: string, insertLocation: Word.InsertLocation.before | Word.InsertLocation.after | "Before" | "After"): Word.Paragraph;

参数

paragraphText: string

必需。要插入的段落文本。

insertLocation: before | after | "Before" | "After"

必需。该值必须为“Before”或“After”。

Word.Paragraph

注解

insertTable(rowCount, columnCount, insertLocation, values)

插入包含指定行数和列数的 table。

insertTable(rowCount: number, columnCount: number, insertLocation: Word.InsertLocation.before | Word.InsertLocation.after | "Before" | "After", values?: string[][]): Word.Table;

参数

rowCount: number

必需。表格的行数。

columnCount: number

必需。表格的列数。

insertLocation: before | after | "Before" | "After"

必需。该值必须为“Before”或“After”。

values: string[][]

可选的二维数组。如果指定数组中的对应字符串，则填充单元格。

Word.Table

注解

insertText(text, insertLocation)

将文本插入到段落中的指定位置。

insertText(text: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;

参数

text: string

必填。要插入的文本。

insertLocation: replace | start | end | "Replace" | "Start" | "End"

必填。该值必须为“Replace”、“Start”或“End”。

Word.Range

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/insert-in-different-locations.yaml

await Word.run(async (context) => {
  // Replace the last paragraph.
  const range = context.document.body.paragraphs.getLast().insertText("Just replaced the last paragraph!", "Replace");
  range.font.highlightColor = "black";
  range.font.color = "white";

  await context.sync();
});

load(options)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

load(options?: Word.Interfaces.ParagraphLoadOptions): Word.Paragraph;

参数

options: Word.Interfaces.ParagraphLoadOptions

提供要加载对象的属性的选项。

Word.Paragraph

load(propertyNames)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

load(propertyNames?: string | string[]): Word.Paragraph;

参数

propertyNames: string | string[]

逗号分隔的字符串或指定要加载的属性的字符串数组。

Word.Paragraph

load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Word.Paragraph;

参数

propertyNamesAndPaths: { select?: string; expand?: string; }

propertyNamesAndPaths.select 是一个逗号分隔的字符串，指定要加载的属性，是 propertyNamesAndPaths.expand 一个逗号分隔的字符串，指定要加载的导航属性。

Word.Paragraph

search(searchText, searchOptions)

对段落对象的作用域使用指定的 SearchOptions 执行搜索。搜索结果是 range 对象的集合。

search(searchText: string, searchOptions?: Word.SearchOptions | {
            ignorePunct?: boolean;
            ignoreSpace?: boolean;
            matchCase?: boolean;
            matchPrefix?: boolean;
            matchSuffix?: boolean;
            matchWholeWord?: boolean;
            matchWildcards?: boolean;
        }): Word.RangeCollection;

参数

searchText: string

必填。搜索文本。

searchOptions: Word.SearchOptions | { ignorePunct?: boolean; ignoreSpace?: boolean; matchCase?: boolean; matchPrefix?: boolean; matchSuffix?: boolean; matchWholeWord?: boolean; matchWildcards?: boolean; }

可选。用于搜索的选项。

Word.RangeCollection

注解

select(selectionMode)

选择并在 Word UI 中导航到段落。

select(selectionMode?: Word.SelectionMode): void;

参数

selectionMode: Word.SelectionMode

可选。选择模式必须为“Select”、“Start”或“End”。 “Select”为默认值。

void

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/35-ranges/scroll-to-range.yaml

await Word.run(async (context) => {
  // If select is called with no parameters, it selects the object.
  context.document.body.paragraphs.getLast().select();

  await context.sync();
});

...

await Word.run(async (context) => {
  // Select can be at the start or end of a range; this by definition moves the insertion point without selecting the range.
  context.document.body.paragraphs.getLast().select(Word.SelectionMode.end);

  await context.sync();
});

select(selectionModeString)

选择并在 Word UI 中导航到段落。

select(selectionModeString?: "Select" | "Start" | "End"): void;

参数

selectionModeString: "Select" | "Start" | "End"

可选。选择模式必须为“Select”、“Start”或“End”。 “Select”为默认值。

void

注解

set(properties, options)

同时设置对象的多个属性。可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。

set(properties: Interfaces.ParagraphUpdateData, options?: OfficeExtension.UpdateOptions): void;

参数

properties: Word.Interfaces.ParagraphUpdateData

一个 JavaScript 对象，其属性按同构方式构造为调用方法的对象的属性。

options: OfficeExtension.UpdateOptions

提供一个选项，用于在 properties 对象尝试设置任何只读属性时禁止显示错误。

void

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/90-scenarios/multiple-property-set.yaml

await Word.run(async (context) => {
  const paragraph = context.document.body.paragraphs.getFirst();
  paragraph.set({
    leftIndent: 30,
    font: {
      bold: true,
      color: "red"
    }
  });

  await context.sync();
});

...

await Word.run(async (context) => {
  const firstParagraph = context.document.body.paragraphs.getFirst();
  const secondParagraph = firstParagraph.getNext();
  firstParagraph.load("text, font/color, font/bold, leftIndent");

  await context.sync();

  secondParagraph.set(firstParagraph);

  await context.sync();
});

set(properties)

基于现有的已加载对象，同时对对象设置多个属性。

set(properties: Word.Paragraph): void;

参数

properties: Word.Paragraph

void

split(delimiters, trimDelimiters, trimSpacing)

使用分隔符将段落拆分为多个子范围。

split(delimiters: string[], trimDelimiters?: boolean, trimSpacing?: boolean): Word.RangeCollection;

参数

delimiters: string[]

必填。分隔符作为字符串数组。

trimDelimiters: boolean

可选。指示是否从范围集合中的区域剪裁分隔符。默认值为 false，指示分隔符包含在范围集合中返回的区域中。

trimSpacing: boolean

Word.RangeCollection

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/35-ranges/split-words-of-first-paragraph.yaml

await Word.run(async (context) => {
  const paragraph = context.document.body.paragraphs.getFirst();
  const words = paragraph.split([" "], true /* trimDelimiters*/, true /* trimSpaces */);
  words.load("text");

  await context.sync();

  for (let i = 0; i < words.items.length; i++) {
    if (i >= 1) {
      words.items[i - 1].font.highlightColor = "#FFFFFF";
    }
    words.items[i].font.highlightColor = "#FFFF00";

    await context.sync();
    await pause(200);
  }
});

startNewList()

生成包含此 paragraph 的新 list。如果此 paragraph 已是 listItem，则无法执行此方法。

startNewList(): Word.List;

Word.List

注解

OfficeExtension.EventHandlers<Word.CommentEventArgs>

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/20-lists/insert-list.yaml

// This example starts a new list with the second paragraph.
await Word.run(async (context) => {
  const paragraphs = context.document.body.paragraphs;
  paragraphs.load("$none");

  await context.sync();

  // Start new list using the second paragraph.
  const list = paragraphs.items[1].startNewList();
  list.load("$none");

  await context.sync();

  // To add new items to the list, use Start or End on the insertLocation parameter.
  list.insertParagraph("New list item at the start of the list", "Start");
  const paragraph = list.insertParagraph("New list item at the end of the list (set to list level 5)", "End");

  // Set up list level for the list item.
  paragraph.listItem.level = 4;

  // To add paragraphs outside the list, use Before or After.
  list.insertParagraph("New paragraph goes after (not part of the list)", "After");

  await context.sync();
});

toJSON()

重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (，反过来又调用toJSON传递给它的对象的方法。) 而原始Word。Paragraph 对象是一个 API 对象，toJSON该方法返回一个纯 JavaScript 对象， (类型为 Word.Interfaces.ParagraphData) ，其中包含原始对象中加载的任何子属性的浅表副本。

toJSON(): Word.Interfaces.ParagraphData;

Word.Interfaces.ParagraphData

track()

根据文档中的相应更改来跟踪对象，以便进行自动调整。此调用是 context.trackedObjects.add (thisObject) 的简写。如果跨 .sync 调用和“.run”批处理的顺序执行外部使用此对象，并在设置属性或调用对象方法时收到“InvalidObjectPath”错误，则需要在首次创建对象时将该对象添加到跟踪的对象集合。如果此对象是集合的一部分，则还应跟踪父集合。

track(): Word.Paragraph;

Word.Paragraph

untrack()

释放与此对象关联的内存（如果先前已跟踪过）。此调用是 context.trackedObjects.remove (thisObject) 的简写。拥有许多跟踪对象会降低主机应用程序的速度，因此请在使用完毕后释放所添加的任何对象。在内存发布生效之前，需要调用 context.sync() 。

untrack(): Word.Paragraph;

Word.Paragraph

事件详细信息

onCommentAdded

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。请勿在生产环境中使用此 API。

在添加新注释时发生。

readonly onCommentAdded: OfficeExtension.EventHandlers<Word.CommentEventArgs>;

事件类型

注解

OfficeExtension.EventHandlers<Word.CommentEventArgs>

onCommentChanged

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。请勿在生产环境中使用此 API。

更改批注或其回复时发生。

readonly onCommentChanged: OfficeExtension.EventHandlers<Word.CommentEventArgs>;

事件类型

注解

OfficeExtension.EventHandlers<Word.CommentEventArgs>

onCommentDeleted

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。请勿在生产环境中使用此 API。

删除批注时发生。

readonly onCommentDeleted: OfficeExtension.EventHandlers<Word.CommentEventArgs>;

事件类型

注解

OfficeExtension.EventHandlers<Word.CommentEventArgs>

onCommentDeselected

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。请勿在生产环境中使用此 API。

在取消选择批注时发生。

readonly onCommentDeselected: OfficeExtension.EventHandlers<Word.CommentEventArgs>;

事件类型

注解

OfficeExtension.EventHandlers<Word.CommentEventArgs>

onCommentSelected

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。请勿在生产环境中使用此 API。

在选择批注时发生。

readonly onCommentSelected: OfficeExtension.EventHandlers<Word.CommentEventArgs>;

事件类型

注解