Word.List class

包含 Word 集合。段落对象。

扩展

注解

API 集:WordApi 1.3

使用方

示例

// 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: Word.ParagraphCollection = context.document.body.paragraphs;
  paragraphs.load("$none");

  await context.sync();

  // Start new list using the second paragraph.
  const list: Word.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: Word.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.
  const listItem: Word.ListItem = paragraph.listItem;
  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();
});

属性

context

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

id

获取列表的 ID。

levelExistences

检查 list 中是否包含所有 9 个级别。 true 指示该级别存在,这意味着该级别至少有一个列表项。

levelTypes

获取 list 中的所有 9 个级别类型。 每种类型可以是 bullet、 number或 picture。

paragraphs

获取 list 中的段落。

方法

getLevelFont(level)

获取列表中指定级别的项目符号、编号或图片的字体。

getLevelParagraphs(level)

获取列表中指定级别的段落。

getLevelPicture(level)

获取列表中指定级别的图片的 Base64 编码字符串表示形式。

getLevelString(level)

以字符串形式获取指定级别的项目符号、编号或图片。

insertParagraph(paragraphText, insertLocation)

在指定位置插入段落。

load(options)

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

load(propertyNames)

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

load(propertyNamesAndPaths)

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

resetLevelFont(level, resetFontName)

在列表中的指定级别重置项目符号、编号或图片的字体。

setLevelAlignment(level, alignment)

在列表中设置项目符号、编号或图片在指定级别的对齐方式。

setLevelAlignment(level, alignment)

在列表中设置项目符号、编号或图片在指定级别的对齐方式。

setLevelBullet(level, listBullet, charCode, fontName)

设置 list 中指定级别的项目符号格式。 如果项目符号为 custom, charCode 则为必需项。

setLevelBullet(level, listBullet, charCode, fontName)

设置 list 中指定级别的项目符号格式。 如果项目符号为 custom, charCode 则为必需项。

setLevelIndents(level, textIndent, bulletNumberPictureIndent)

设置列表中指定级别的两种缩进方式。

setLevelNumbering(level, listNumbering, formatString)

设置列表中指定级别的编号格式。

setLevelNumbering(level, listNumbering, formatString)

设置列表中指定级别的编号格式。

setLevelPicture(level, base64EncodedImage)

在列表中设置指定级别的图片。

setLevelStartingNumber(level, startingNumber)

设置 list 中指定级别的起始编号。 默认值为 1。

toJSON()

覆盖 JavaScript toJSON() 方法,以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 (JSON.stringify反过来调用 toJSON 传递给它的对象的方法。) 虽然原始 Word.List 对象是 API 对象, toJSON 但该方法返回一个纯 JavaScript 对象, (类型化为 Word.Interfaces.ListData) ,其中包含从原始对象加载的任何子属性的浅层副本。

track()

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

untrack()

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

属性详细信息

context

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

context: RequestContext;

属性值

id

获取列表的 ID。

readonly id: number;

属性值

number

注解

API 集:WordApi 1.3

levelExistences

检查 list 中是否包含所有 9 个级别。 true 指示该级别存在,这意味着该级别至少有一个列表项。

readonly levelExistences: boolean[];

属性值

boolean[]

注解

API 集:WordApi 1.3

示例

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

// Gets information about the first list in the document.
await Word.run(async (context) => {
  const lists: Word.ListCollection = context.document.body.lists;
  lists.load("items");

  await context.sync();

  if (lists.items.length === 0) {
    console.warn("There are no lists in this document.");
    return;
  }
  
  // Get the first list.
  const list: Word.List = lists.getFirst();
  list.load("levelTypes,levelExistences");

  await context.sync();

  const levelTypes  = list.levelTypes;
  console.log("Level types of the first list:");
  for (let i = 0; i < levelTypes.length; i++) {
    console.log(`- Level ${i + 1} (index ${i}): ${levelTypes[i]}`);
  }

  const levelExistences = list.levelExistences;
  console.log("Level existences of the first list:");
  for (let i = 0; i < levelExistences.length; i++) {
    console.log(`- Level ${i + 1} (index ${i}): ${levelExistences[i]}`);
  }
});

levelTypes

获取 list 中的所有 9 个级别类型。 每种类型可以是 bullet、 number或 picture。

readonly levelTypes: Word.ListLevelType[];

属性值

注解

API 集:WordApi 1.3

示例

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

// Gets information about the first list in the document.
await Word.run(async (context) => {
  const lists: Word.ListCollection = context.document.body.lists;
  lists.load("items");

  await context.sync();

  if (lists.items.length === 0) {
    console.warn("There are no lists in this document.");
    return;
  }
  
  // Get the first list.
  const list: Word.List = lists.getFirst();
  list.load("levelTypes,levelExistences");

  await context.sync();

  const levelTypes  = list.levelTypes;
  console.log("Level types of the first list:");
  for (let i = 0; i < levelTypes.length; i++) {
    console.log(`- Level ${i + 1} (index ${i}): ${levelTypes[i]}`);
  }

  const levelExistences = list.levelExistences;
  console.log("Level existences of the first list:");
  for (let i = 0; i < levelExistences.length; i++) {
    console.log(`- Level ${i + 1} (index ${i}): ${levelExistences[i]}`);
  }
});

paragraphs

获取 list 中的段落。

readonly paragraphs: Word.ParagraphCollection;

属性值

注解

API 集:WordApi 1.3

方法详细信息

getLevelFont(level)

获取列表中指定级别的项目符号、编号或图片的字体。

getLevelFont(level: number): Word.Font;

参数

level

number

列表中的级别。

返回

注解

API 集:WordApiDesktop 1.1

getLevelParagraphs(level)

获取列表中指定级别的段落。

getLevelParagraphs(level: number): Word.ParagraphCollection;

参数

level

number

列表中的级别。

返回

注解

API 集:WordApi 1.3

getLevelPicture(level)

获取列表中指定级别的图片的 Base64 编码字符串表示形式。

getLevelPicture(level: number): OfficeExtension.ClientResult<string>;

参数

level

number

列表中的级别。

返回

注解

API 集:WordApiDesktop 1.1

getLevelString(level)

以字符串形式获取指定级别的项目符号、编号或图片。

getLevelString(level: number): OfficeExtension.ClientResult<string>;

参数

level

number

列表中的级别。

返回

注解

API 集:WordApi 1.3

insertParagraph(paragraphText, insertLocation)

在指定位置插入段落。

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

参数

paragraphText

string

要插入的段落文本。

insertLocation

start | end | before | after | "Start" | "End" | "Before" | "After"

值必须为 start、end、、before或 。after

返回

注解

API 集:WordApi 1.3

示例

// 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: Word.ParagraphCollection = context.document.body.paragraphs;
  paragraphs.load("$none");

  await context.sync();

  // Start new list using the second paragraph.
  const list: Word.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: Word.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.
  const listItem: Word.ListItem = paragraph.listItem;
  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();
});

load(options)

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

load(options?: Word.Interfaces.ListLoadOptions): Word.List;

参数

options
Word.Interfaces.ListLoadOptions

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

返回

load(propertyNames)

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

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

参数

propertyNames

string | string[]

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

返回

load(propertyNamesAndPaths)

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

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

参数

propertyNamesAndPaths

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

propertyNamesAndPaths.select 是指定要加载的属性的逗号分隔字符串,以及 propertyNamesAndPaths.expand 指定要加载的导航属性的逗号分隔字符串。

返回

resetLevelFont(level, resetFontName)

在列表中的指定级别重置项目符号、编号或图片的字体。

resetLevelFont(level: number, resetFontName?: boolean): void;

参数

level

number

列表中的级别。

resetFontName

boolean

可选。 指示是否重置字体名称。 默认值为 false 指示字体名称保持不变。

返回

void

注解

API 集:WordApiDesktop 1.1

setLevelAlignment(level, alignment)

在列表中设置项目符号、编号或图片在指定级别的对齐方式。

setLevelAlignment(level: number, alignment: Word.Alignment): void;

参数

level

number

列表中的级别。

alignment
Word.Alignment

必须为 left、 、 centered或 right级别对齐方式。

返回

void

注解

API 集:WordApi 1.3

setLevelAlignment(level, alignment)

在列表中设置项目符号、编号或图片在指定级别的对齐方式。

setLevelAlignment(level: number, alignment: "Mixed" | "Unknown" | "Left" | "Centered" | "Right" | "Justified"): void;

参数

level

number

列表中的级别。

alignment

"Mixed" | "Unknown" | "Left" | "Centered" | "Right" | "Justified"

必须为 left、 、 centered或 right级别对齐方式。

返回

void

注解

API 集:WordApi 1.3

setLevelBullet(level, listBullet, charCode, fontName)

设置 list 中指定级别的项目符号格式。 如果项目符号为 custom, charCode 则为必需项。

setLevelBullet(level: number, listBullet: Word.ListBullet, charCode?: number, fontName?: string): void;

参数

level

number

列表中的级别。

listBullet
Word.ListBullet

子弹。

charCode

number

可选。 项目符号字符的代码值。 仅当项目符号为 custom时使用。

fontName

string

可选。 项目符号的字体名称。 仅当项目符号为 custom时使用。

返回

void

注解

API 集:WordApi 1.3

示例

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

// Inserts a list starting with the first paragraph then set numbering and bullet types of the list items.
await Word.run(async (context) => {
  const paragraphs: Word.ParagraphCollection = context.document.body.paragraphs;
  paragraphs.load("$none");

  await context.sync();

  // Use the first paragraph to start a new list.
  const list: Word.List = paragraphs.items[0].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: Word.Paragraph = list.insertParagraph("New list item at the end of the list (set to list level 5)", "End");

  // Set numbering for list level 1.
  list.setLevelNumbering(0, Word.ListNumbering.arabic);

  // Set bullet type for list level 5.
  list.setLevelBullet(4, Word.ListBullet.arrow);

  // Set list level for the last item in this list.
  paragraph.listItem.level = 4;

  list.load("levelTypes");

  await context.sync();
});

setLevelBullet(level, listBullet, charCode, fontName)

设置 list 中指定级别的项目符号格式。 如果项目符号为 custom, charCode 则为必需项。

setLevelBullet(level: number, listBullet: "Custom" | "Solid" | "Hollow" | "Square" | "Diamonds" | "Arrow" | "Checkmark", charCode?: number, fontName?: string): void;

参数

level

number

列表中的级别。

listBullet

"Custom" | "Solid" | "Hollow" | "Square" | "Diamonds" | "Arrow" | "Checkmark"

子弹。

charCode

number

可选。 项目符号字符的代码值。 仅当项目符号为 custom时使用。

fontName

string

可选。 项目符号的字体名称。 仅当项目符号为 custom时使用。

返回

void

注解

API 集:WordApi 1.3

setLevelIndents(level, textIndent, bulletNumberPictureIndent)

设置列表中指定级别的两种缩进方式。

setLevelIndents(level: number, textIndent: number, bulletNumberPictureIndent: number): void;

参数

level

number

列表中的级别。

textIndent

number

文本缩进(以磅为单位)。 它与段落左缩进相同。

bulletNumberPictureIndent

number

项目符号、数字或图片的相对缩进量(以磅为单位)。 它与段落首行缩进相同。

返回

void

注解

API 集:WordApi 1.3

setLevelNumbering(level, listNumbering, formatString)

设置列表中指定级别的编号格式。

setLevelNumbering(level: number, listNumbering: Word.ListNumbering, formatString?: Array<string | number>): void;

参数

level

number

列表中的级别。

listNumbering
Word.ListNumbering

序号格式。

formatString

Array<string | number>

可选。 定义为字符串或整数数组的编号字符串格式。 每个整数都是高于或等于此级别的数字类型的级别。 例如,[“ (”, level - 1, “.”, level, “) ”] 数组可以定义“ (2.c) ”的格式,其中 2 是父级的项目编号,c 是此级别的项目编号。

返回

void

注解

API 集:WordApi 1.3

示例

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

// Inserts a list starting with the first paragraph then set numbering and bullet types of the list items.
await Word.run(async (context) => {
  const paragraphs: Word.ParagraphCollection = context.document.body.paragraphs;
  paragraphs.load("$none");

  await context.sync();

  // Use the first paragraph to start a new list.
  const list: Word.List = paragraphs.items[0].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: Word.Paragraph = list.insertParagraph("New list item at the end of the list (set to list level 5)", "End");

  // Set numbering for list level 1.
  list.setLevelNumbering(0, Word.ListNumbering.arabic);

  // Set bullet type for list level 5.
  list.setLevelBullet(4, Word.ListBullet.arrow);

  // Set list level for the last item in this list.
  paragraph.listItem.level = 4;

  list.load("levelTypes");

  await context.sync();
});

setLevelNumbering(level, listNumbering, formatString)

设置列表中指定级别的编号格式。

setLevelNumbering(level: number, listNumbering: "None" | "Arabic" | "UpperRoman" | "LowerRoman" | "UpperLetter" | "LowerLetter", formatString?: Array<string | number>): void;

参数

level

number

列表中的级别。

listNumbering

"None" | "Arabic" | "UpperRoman" | "LowerRoman" | "UpperLetter" | "LowerLetter"

序号格式。

formatString

Array<string | number>

可选。 定义为字符串或整数数组的编号字符串格式。 每个整数都是高于或等于此级别的数字类型的级别。 例如,[“ (”, level - 1, “.”, level, “) ”] 数组可以定义“ (2.c) ”的格式,其中 2 是父级的项目编号,c 是此级别的项目编号。

返回

void

注解

API 集:WordApi 1.3

setLevelPicture(level, base64EncodedImage)

在列表中设置指定级别的图片。

setLevelPicture(level: number, base64EncodedImage?: string): void;

参数

level

number

列表中的级别。

base64EncodedImage

string

可选。 要设置的 Base64 编码图像。 如果未给定,则设置默认图片。

返回

void

注解

API 集:WordApiDesktop 1.1

setLevelStartingNumber(level, startingNumber)

设置 list 中指定级别的起始编号。 默认值为 1。

setLevelStartingNumber(level: number, startingNumber: number): void;

参数

level

number

列表中的级别。

startingNumber

number

要开始的数字。

返回

void

注解

API 集:WordApi 1.3

toJSON()

覆盖 JavaScript toJSON() 方法,以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 (JSON.stringify反过来调用 toJSON 传递给它的对象的方法。) 虽然原始 Word.List 对象是 API 对象, toJSON 但该方法返回一个纯 JavaScript 对象, (类型化为 Word.Interfaces.ListData) ,其中包含从原始对象加载的任何子属性的浅层副本。

toJSON(): Word.Interfaces.ListData;

返回

track()

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

track(): Word.List;

返回

untrack()

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

untrack(): Word.List;

返回