Word.List class

  • 参考
包:
word

包含Word的集合。Paragraph 对象。

Extends
OfficeExtension.ClientObject

注解

[ 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 = 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();
});

属性

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, alignmentString)

设置列表中指定级别的项目符号、编号或图片的对齐方式。
setLevelBullet(level, listBullet, charCode, fontName)

设置 list 中指定级别的项目符号格式。 如果项目符号为“Custom”，则需要使用字符代码。
setLevelBullet(level, listBulletString, charCode, fontName)

设置 list 中指定级别的项目符号格式。 如果项目符号为“Custom”，则需要使用字符代码。
setLevelIndents(level, textIndent, bulletNumberPictureIndent)

设置列表中指定级别的两种缩进方式。
setLevelNumbering(level, listNumbering, formatString)

设置列表中指定级别的编号格式。
setLevelNumbering(level, listNumberingString, 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;

属性值

Word.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 = 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 = 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[];

属性值

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 = 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 = 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;

属性值

Word.ParagraphCollection

注解

[ API 集：WordApi 1.3 ]

方法详细信息

getLevelFont(level)

注意

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

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

getLevelFont(level: number): Word.Font;

参数

level

number

必需。 列表中的级别。

返回

Word.Font

注解

[ API 集：WordApi BETA (仅预览版) ]

getLevelParagraphs(level)

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

getLevelParagraphs(level: number): Word.ParagraphCollection;

参数

level

number

必需。 列表中的级别。

返回

Word.ParagraphCollection

注解

[ API 集：WordApi 1.3 ]

getLevelPicture(level)

注意

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

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

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

参数

level

number

必需。 列表中的级别。

返回

OfficeExtension.ClientResult<string>

注解

[ API 集：WordApi BETA (仅预览版) ]

getLevelString(level)

获取指定级别的项目符号、编号或图片作为字符串。

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

参数

level

number

必需。 列表中的级别。

返回

OfficeExtension.ClientResult<string>

注解

[ 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”。

返回

Word.Paragraph

注解

[ 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 = 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();
});

load(options)

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

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

参数

options
Word.Interfaces.ListLoadOptions

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

返回

Word.List

load(propertyNames)

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

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

参数

propertyNames

string | string[]

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

返回

Word.List

load(propertyNamesAndPaths)

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

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

参数

propertyNamesAndPaths

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

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

返回

Word.List

resetLevelFont(level, resetFontName)

注意

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

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

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

参数

level

number

必需。 列表中的级别。

resetFontName

boolean

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

返回

void

注解

[ API 集：WordApi BETA (仅预览版) ]

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, alignmentString)

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

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

参数

level

number

必填。 列表中的级别。

alignmentString

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

必填。 必须为“Left”、“Centered”或“Right”的级别对齐方式。

返回

void

注解

[ API 集：WordApi 1.3 ]

setLevelBullet(level, listBullet, charCode, fontName)

设置 list 中指定级别的项目符号格式。 如果项目符号为“Custom”，则需要使用字符代码。

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

参数

level

number

必需。 列表中的级别。

listBullet
Word.ListBullet

必填。 项目符号。

charCode

number

可选。 项目符号字符的代码值。 仅当项目符号为“自定义”时才使用。

fontName

string

可选。 项目符号的字体名称。 仅当项目符号为“自定义”时才使用。

返回

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

  await context.sync();

  // Use the first paragraph to start a new list.
  const 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 = 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, listBulletString, charCode, fontName)

设置 list 中指定级别的项目符号格式。 如果项目符号为“Custom”，则需要使用字符代码。

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

参数

level

number

必需。 列表中的级别。

listBulletString

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

必填。 项目符号。

charCode

number

可选。 项目符号字符的代码值。 仅当项目符号为“自定义”时才使用。

fontName

string

可选。 项目符号的字体名称。 仅当项目符号为“自定义”时才使用。

返回

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

  await context.sync();

  // Use the first paragraph to start a new list.
  const 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 = 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, listNumberingString, formatString)

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

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

参数

level

number

必填。 列表中的级别。

listNumberingString

"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)

注意

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

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

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

参数

level

number

必填。 列表中的级别。

base64EncodedImage

string

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

返回

void

注解

[ API 集：WordApi BETA (仅预览版) ]

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;

返回

Word.Interfaces.ListData

track()

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

track(): Word.List;

返回

Word.List

untrack()

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

untrack(): Word.List;

返回

Word.List