Excel.RangeFormat class

Объект формата, в который включены шрифт, заливка, границы, выравнивание и другие свойства диапазона.

Свойства

autoIndent	Указывает, автоматически ли увеличивается отступ текста, если для выравнивания текста задано равное распределение.
borders	Коллекция объектов границ, которые применяются ко всему диапазону.
columnWidth	Определяет ширину всех столбцов в диапазоне. Если ширина столбцов неоднородна, `null` будет возвращен результат.
context	Контекст запроса, связанный с объектом. Это соединяет процесс надстройки с процессом основного приложения Office.
fill	Возвращает объект заливки, определенный для всего диапазона.
font	Возвращает объект шрифта, определенный для всего диапазона.
horizontalAlignment	Представляет выравнивание по горизонтали для указанного объекта. См. `Excel.HorizontalAlignment` дополнительные сведения.
indentLevel	Целое число от 0 до 250, указывающее уровень отступа.
protection	Возвращает объект защиты формата для диапазона.
readingOrder	Направление чтения для диапазона.
rowHeight	Высота всех строк в диапазоне. Если высота строки неодинакова, `null` будет возвращен результат.
shrinkToFit	Указывает, сжимается ли текст автоматически в соответствии с доступной шириной столбца.
textOrientation	Ориентация текста всех ячеек в диапазоне. Ориентация текста должна быть целым числом от -90 до 90 или 180 для вертикально ориентированного текста. Если ориентация в пределах диапазона неоднородна, будет `null` возвращен указатель.
useStandardHeight	Определяет, равна ли высота `Range` строки объекта стандартной высоте листа. Возвращает значение `true` , если высота строки объекта `Range` равна стандартной высоте листа. Возвращает значение `null` , если диапазон содержит несколько строк и они не имеют одинаковой высоты. В противном случае возвращает обратное значение `false` . Примечание. Это свойство должно быть задано только в `true`значение . При этом `false` ничего не происходит.
useStandardWidth	Указывает, равна ли ширина `Range` столбца стандартной ширине листа ширине столбца. Возвращает значение `true` , если ширина `Range` столбца объекта равна стандартной ширине листа. Возвращает `null` , если диапазон содержит несколько столбцов и они разных высот. В противном случае возвращает обратное значение `false` . Примечание. Это свойство должно быть задано только в `true`значение . При этом `false` ничего не происходит.
verticalAlignment	Представляет выравнивание по вертикали для указанного объекта. См. `Excel.VerticalAlignment` дополнительные сведения.
wrapText	Указывает, переносит ли Excel текст в объект. Значение `null` указывает, что для всего диапазона не используется единый параметр обтекания

Методы

adjustIndent(amount)	Настройка отступа форматирования диапазонов. Значение отступа находится в диапазоне от 0 до 250 и измеряется в символах.
autofitColumns()	Изменяет ширину столбцов текущего диапазона на оптимальную с учетом текущих данных в столбцах.
autofitRows()	Изменяет высоту строк текущего диапазона на оптимальную с учетом текущих данных в столбцах.
load(options)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNames)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNamesAndPaths)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
set(properties, options)	Задает несколько свойств объекта одновременно. Вы можете передать либо простой объект с соответствующими свойствами, либо другой объект API того же типа.
set(properties)	Одновременно задает несколько свойств объекта на основе существующего загруженного объекта.
toJSON()	Переопределяет метод JavaScript `toJSON()` , чтобы обеспечить более полезные выходные данные при передаче объекта API в `JSON.stringify()`. (`JSON.stringify`, в свою очередь, вызывает `toJSON` метод переданного ему объекта.) В то время как исходный `Excel.RangeFormat` объект является объектом API, `toJSON` метод возвращает простой объект JavaScript (типизированный как `Excel.Interfaces.RangeFormatData`), который содержит неглубокие копии любых загруженных дочерних свойств исходного объекта.

autoIndent

Указывает, автоматически ли увеличивается отступ текста, если для выравнивания текста задано равное распределение.

autoIndent: boolean;

Значение свойства

boolean

borders

Коллекция объектов границ, которые применяются ко всему диапазону.

readonly borders: Excel.RangeBorderCollection;

Значение свойства

Excel.RangeBorderCollection

columnWidth

Определяет ширину всех столбцов в диапазоне. Если ширина столбцов неоднородна, null будет возвращен результат.

columnWidth: number;

Значение свойства

number

context

Контекст запроса, связанный с объектом. Это соединяет процесс надстройки с процессом основного приложения Office.

context: RequestContext;

Значение свойства

Excel.RequestContext

fill

Возвращает объект заливки, определенный для всего диапазона.

readonly fill: Excel.RangeFill;

Значение свойства

Excel.RangeFill

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/formatting.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");

    const range = sheet.getRange("B2:E2");
    range.format.fill.color = "#4472C4";;
    range.format.font.color = "white";

    await context.sync();
});

font

Возвращает объект шрифта, определенный для всего диапазона.

readonly font: Excel.RangeFont;

Значение свойства

Excel.RangeFont

horizontalAlignment

Представляет выравнивание по горизонтали для указанного объекта. См. Excel.HorizontalAlignment дополнительные сведения.

horizontalAlignment: Excel.HorizontalAlignment | "General" | "Left" | "Center" | "Right" | "Fill" | "Justify" | "CenterAcrossSelection" | "Distributed";

Значение свойства

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-pivotlayout.yaml

await Excel.run(async (context) => {
  // Set a default value for an empty cell in the PivotTable. This doesn't include cells left blank by the layout.
  const pivotTable = context.workbook.pivotTables.getItem("Farm Sales");
  const pivotLayout = pivotTable.layout;

  pivotLayout.emptyCellText = "--";

  // Set the text alignment to match the rest of the PivotTable.
  pivotLayout.getDataBodyRange().format.horizontalAlignment = Excel.HorizontalAlignment.right;
  await context.sync();
});

indentLevel

Целое число от 0 до 250, указывающее уровень отступа.

indentLevel: number;

Значение свойства

number

protection

Возвращает объект защиты формата для диапазона.

readonly protection: Excel.FormatProtection;

Значение свойства

Excel.FormatProtection

readingOrder

Направление чтения для диапазона.

readingOrder: Excel.ReadingOrder | "Context" | "LeftToRight" | "RightToLeft";

Значение свойства

Excel.ReadingOrder | "Context" | "LeftToRight" | "RightToLeft"

rowHeight

Высота всех строк в диапазоне. Если высота строки неодинакова, null будет возвращен результат.

rowHeight: number;

Значение свойства

number

shrinkToFit

Указывает, сжимается ли текст автоматически в соответствии с доступной шириной столбца.

shrinkToFit: boolean;

Значение свойства

boolean

textOrientation

Ориентация текста всех ячеек в диапазоне. Ориентация текста должна быть целым числом от -90 до 90 или 180 для вертикально ориентированного текста. Если ориентация в пределах диапазона неоднородна, будет null возвращен указатель.

textOrientation: number;

Значение свойства

number

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-text-orientation.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B2:E2");

    // Set textOrientation to either an integer between -90 and 90
    // or to 180 for vertically-oriented text.
    range.format.textOrientation = 90;

    await context.sync();
});

useStandardHeight

Определяет, равна ли высота Range строки объекта стандартной высоте листа. Возвращает значение true , если высота строки объекта Range равна стандартной высоте листа. Возвращает значение null , если диапазон содержит несколько строк и они не имеют одинаковой высоты. В противном случае возвращает обратное значение false . Примечание. Это свойство должно быть задано только в trueзначение . При этом false ничего не происходит.

useStandardHeight: boolean;

Значение свойства

boolean

useStandardWidth

Указывает, равна ли ширина Range столбца стандартной ширине листа ширине столбца. Возвращает значение true , если ширина Range столбца объекта равна стандартной ширине листа. Возвращает null , если диапазон содержит несколько столбцов и они разных высот. В противном случае возвращает обратное значение false . Примечание. Это свойство должно быть задано только в trueзначение . При этом false ничего не происходит.

useStandardWidth: boolean;

Значение свойства

boolean

verticalAlignment

Представляет выравнивание по вертикали для указанного объекта. См. Excel.VerticalAlignment дополнительные сведения.

verticalAlignment: Excel.VerticalAlignment | "Top" | "Center" | "Bottom" | "Justify" | "Distributed";

Значение свойства

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/style.yaml

await Excel.run(async (context) => {
    let worksheet = context.workbook.worksheets.getItem("Sample");
    let range = worksheet.getRange("A1:E1");
    // Apply new style.
    range.style = ("Diagonal Orientation Style");
    range.format.verticalAlignment = "Justify";

    await context.sync();
});

wrapText

Указывает, переносит ли Excel текст в объект. Значение null указывает, что для всего диапазона не используется единый параметр обтекания

wrapText: boolean;

Значение свойства

boolean

adjustIndent(amount)

Настройка отступа форматирования диапазонов. Значение отступа находится в диапазоне от 0 до 250 и измеряется в символах.

adjustIndent(amount: number): void;

Параметры

amount: number

Число знаковых интервалов, на которые изменяется текущий отступ. Это значение должно находиться в диапазоне от -250 до 250. Примечание. Если сумма поднимет уровень отступа выше 250, уровень отступа останется на уровне 250. Аналогично, если сумма снижает уровень отступа ниже 0, уровень отступа остается равным 0.

Возвращаемое значение

void

autofitColumns()

Изменяет ширину столбцов текущего диапазона на оптимальную с учетом текущих данных в столбцах.

autofitColumns(): void;

Возвращаемое значение

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-table-changed.yaml

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");
    let range = sheet.getRange("B7");
    range.values = [[900]];
    range.format.autofitColumns();

    await context.sync();
    console.log("B7 value has been changed.");
});

autofitRows()

Изменяет высоту строк текущего диапазона на оптимальную с учетом текущих данных в столбцах.

autofitRows(): void;

Возвращаемое значение

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/14-conditional-formatting/conditional-formatting-advanced.yaml

function queueCommandsToCreateTemperatureTable(sheet: Excel.Worksheet) {
    let temperatureTable = sheet.tables.add('A1:M1', true);
    temperatureTable.name = "TemperatureTable";
    temperatureTable.getHeaderRowRange().values = [["Category", "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]];
    temperatureTable.rows.add(null, [
        ["Avg High", 40, 38, 44, 45, 51, 56, 67, 72, 79, 59, 45, 41],
        ["Avg Low", 34, 33, 38, 41, 45, 48, 51, 55, 54, 45, 41, 38],
        ["Record High", 61, 69, 79, 83, 95, 97, 100, 101, 94, 87, 72, 66],
        ["Record Low", -1, 2, 9, 24, 28, 32, 36, 39, 35, 21, 12, 4]
    ]);
    temperatureTable.getRange().format.autofitColumns();
    temperatureTable.getRange().format.autofitRows();
}

load(options)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

load(options?: Excel.Interfaces.RangeFormatLoadOptions): Excel.RangeFormat;

Параметры

options: Excel.Interfaces.RangeFormatLoadOptions

Предоставляет параметры для загружаемых свойств объекта.

Возвращаемое значение

Excel.RangeFormat

load(propertyNames)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

load(propertyNames?: string | string[]): Excel.RangeFormat;

Параметры

propertyNames: string | string[]

Строка с разделителями-запятыми или массив строк, которые определяют свойства для загрузки.

Возвращаемое значение

Excel.RangeFormat

Примеры

// Select all of the range's format properties.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "F:G";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    range.load(["format/*", "format/fill", "format/borders", "format/font"]);
    await context.sync();
    
    console.log(range.format.wrapText);
    console.log(range.format.fill.color);
    console.log(range.format.font.name);
});

load(propertyNamesAndPaths)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.RangeFormat;

Параметры

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

propertyNamesAndPaths.select — это строка с разделителями-запятыми, указывающая загружаемые свойства, и строка propertyNamesAndPaths.expand через запятую, указывающая свойства навигации для загрузки.

Возвращаемое значение

Excel.RangeFormat

set(properties, options)

Задает несколько свойств объекта одновременно. Вы можете передать либо простой объект с соответствующими свойствами, либо другой объект API того же типа.

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

Параметры

properties: Excel.Interfaces.RangeFormatUpdateData

Объект JavaScript со свойствами, структурированными изоморфно свойствам объекта, для которого вызывается метод.

options: OfficeExtension.UpdateOptions

Предоставляет возможность подавления ошибок, если объект properties пытается задать какие-либо свойства только для чтения.

Возвращаемое значение

void

set(properties)

Одновременно задает несколько свойств объекта на основе существующего загруженного объекта.

set(properties: Excel.RangeFormat): void;

Параметры

properties: Excel.RangeFormat

Возвращаемое значение

void

toJSON()

Переопределяет метод JavaScript toJSON() , чтобы обеспечить более полезные выходные данные при передаче объекта API в JSON.stringify(). (JSON.stringify, в свою очередь, вызывает toJSON метод переданного ему объекта.) В то время как исходный Excel.RangeFormat объект является объектом API, toJSON метод возвращает простой объект JavaScript (типизированный как Excel.Interfaces.RangeFormatData), который содержит неглубокие копии любых загруженных дочерних свойств исходного объекта.

toJSON(): Excel.Interfaces.RangeFormatData;

Возвращаемое значение

Excel.Interfaces.RangeFormatData

Комментарии

Используется

Свойства

Методы

Сведения о свойстве

autoIndent

Значение свойства

Комментарии

borders

Значение свойства

Комментарии

columnWidth

Значение свойства

Комментарии

context

Значение свойства

fill

Значение свойства

Комментарии

Примеры

font

Значение свойства

Комментарии

horizontalAlignment

Значение свойства

Комментарии

Примеры

indentLevel

Значение свойства

Комментарии

protection

Значение свойства

Комментарии

readingOrder

Значение свойства

Комментарии

rowHeight

Значение свойства

Комментарии

shrinkToFit

Значение свойства

Комментарии

textOrientation

Значение свойства

Комментарии

Примеры

useStandardHeight

Значение свойства

Комментарии

useStandardWidth

Значение свойства

Комментарии

verticalAlignment

Значение свойства

Комментарии

Примеры

wrapText

Значение свойства

Комментарии

Сведения о методе

adjustIndent(amount)

Параметры

Возвращаемое значение

Комментарии

autofitColumns()

Возвращаемое значение

Комментарии

Примеры

autofitRows()

Возвращаемое значение

Комментарии

Примеры

load(options)

Параметры

Возвращаемое значение

load(propertyNames)

Параметры

Возвращаемое значение

Примеры