Excel.NamedItem class
Представляет определенное имя для диапазона ячеек или значения. Имена могут быть примитивными именованными объектами (как показано в приведенном ниже типе), объектом-диапазоном или ссылкой на диапазон. Этот объект может использоваться для получения объекта диапазона, связанного с именами.
- Extends
Комментарии
Используется
Примеры
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/34-named-item/create-and-remove-named-item.yaml
await Excel.run(async (context) => {
// Log all the named items in the active worksheet.
const namedItems = context.workbook.worksheets.getActiveWorksheet().names.load();
await context.sync();
console.log("This worksheet contains " + namedItems.items.length + " named items.");
for (let i = 0; i < namedItems.items.length; i++) {
const namedItem : Excel.NamedItem = namedItems.items[i];
console.log(JSON.stringify(namedItem)) + "\n";
}
await context.sync();
});
Свойства
| array |
Возвращает объект, содержащий значения и типы именованного элемента. |
| comment | Указывает комментарий, связанный с этим именем. |
| context | Контекст запроса, связанный с объектом. Это соединяет процесс надстройки с процессом основного приложения Office. |
| formula | Формула именованного элемента. Формулы всегда начинаются со знака равенства ("="). |
| name | Имя объекта. |
| scope | Указывает, ограничено ли имя книгой или определенным листом. Возможные значения: Лист, Книга. |
| type | Тип значения, возвращаемого формулой имени. См. |
| value | Представляет значение, вычисленное по формуле имени. Для именованного диапазона он вернет адрес диапазона. Этот API возвращает #VALUE! в пользовательском интерфейсе Excel, если он ссылается на пользовательскую функцию. |
| value |
JSON-представление значений в этом именованном элементе. В отличие от , |
| value |
JSON-представление значений в этом именованном элементе. В отличие от , |
| visible | Указывает, видим ли объект. |
| worksheet | Возвращает лист, к которому относится именованный элемент. Возникает ошибка, если область элемента ограничена книгой. |
| worksheet |
Возвращает лист, областью которого ограничен именованный элемент. Если вместо этого элемент ограничен книгой, этот метод возвращает объект со |
Методы
| delete() | Удаляет заданное имя. |
| get |
Возвращает объект диапазона, связанный с именем. Выдает ошибку, если именованный элемент не является диапазоном. |
| get |
Возвращает объект Range, сопоставленный с именем. Если тип именованного элемента не является диапазоном, этот метод возвращает объект со свойством |
| load(options) | Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод |
| load(property |
Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод |
| load(property |
Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод |
| set(properties, options) | Задает несколько свойств объекта одновременно. Вы можете передать либо простой объект с соответствующими свойствами, либо другой объект API того же типа. |
| set(properties) | Одновременно задает несколько свойств объекта на основе существующего загруженного объекта. |
| toJSON() | Переопределяет метод JavaScript |
Сведения о свойстве
arrayValues
Возвращает объект, содержащий значения и типы именованного элемента.
readonly arrayValues: Excel.NamedItemArrayValues;Значение свойства
Комментарии
comment
Указывает комментарий, связанный с этим именем.
comment: string;Значение свойства
string
Комментарии
context
Контекст запроса, связанный с объектом. Это соединяет процесс надстройки с процессом основного приложения Office.
context: RequestContext;Значение свойства
formula
Формула именованного элемента. Формулы всегда начинаются со знака равенства ("=").
formula: any;Значение свойства
any
Комментарии
Примеры
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/34-named-item/update-named-item.yaml
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem("Sample");
// Get the named item
const myNamedItem = sheet.names.getItemOrNullObject("MyRange");
myNamedItem.load("name, formula");
await context.sync();
if (myNamedItem.isNullObject) {
console.log(`There is no named item. Create it with "Add named item for a range" first.`);
} else {
// Update named item to point to the second range
myNamedItem.formula = "=Sample!$B$10:$D$14";
sheet.getRange("B10:D14").select();
await context.sync();
console.log(`Just updated the named item "${myNamedItem.name}" -- it's now located here: ${myNamedItem.formula}`);
}
});
name
scope
Указывает, ограничено ли имя книгой или определенным листом. Возможные значения: Лист, Книга.
readonly scope: Excel.NamedItemScope | "Worksheet" | "Workbook";Значение свойства
Excel.NamedItemScope | "Worksheet" | "Workbook"
Комментарии
type
Тип значения, возвращаемого формулой имени. См. Excel.NamedItemType дополнительные сведения.
readonly type: Excel.NamedItemType | "String" | "Integer" | "Double" | "Boolean" | "Range" | "Error" | "Array";Значение свойства
Excel.NamedItemType | "String" | "Integer" | "Double" | "Boolean" | "Range" | "Error" | "Array"
Комментарии
Набор API: ExcelApi 1.1 for String,Integer,Double,Boolean,Range,Error; 1.7 для массива
value
Представляет значение, вычисленное по формуле имени. Для именованного диапазона он вернет адрес диапазона. Этот API возвращает #VALUE! в пользовательском интерфейсе Excel, если он ссылается на пользовательскую функцию.
readonly value: any;Значение свойства
any
Комментарии
valueAsJson
JSON-представление значений в этом именованном элементе. В отличие от , NamedItem.valueNamedItem.valueAsJson поддерживает все типы данных, которые могут быть в ячейке. Примеры включают форматированные числовые значения и веб-изображения в дополнение к стандартным булевым, числовым и строковым значениям. Данные, возвращаемые этим API, всегда соответствуют языковому стандарту en-US. Чтобы получить данные в языковом стандарте отображения, заданном пользователем, используйте NamedItem.valueAsJsonLocal.
readonly valueAsJson: CellValue | string;Значение свойства
Excel.CellValue | string
Комментарии
valueAsJsonLocal
JSON-представление значений в этом именованном элементе. В отличие от , NamedItem.valueNamedItem.valueAsJsonLocal поддерживает все типы данных, которые могут быть в ячейке. Примеры включают форматированные числовые значения и веб-изображения в дополнение к стандартным булевым, числовым и строковым значениям. Данные, возвращаемые этим API, всегда соответствуют языковому стандарту отображения, выбранному пользователем. Для получения данных, не зависящих от языкового стандарта, используйте NamedItem.valueAsJson.
readonly valueAsJsonLocal: CellValue | string;Значение свойства
Excel.CellValue | string
Комментарии
visible
Указывает, видим ли объект.
visible: boolean;Значение свойства
boolean
Комментарии
worksheet
Возвращает лист, к которому относится именованный элемент. Возникает ошибка, если область элемента ограничена книгой.
readonly worksheet: Excel.Worksheet;Значение свойства
Комментарии
worksheetOrNullObject
Возвращает лист, областью которого ограничен именованный элемент. Если вместо этого элемент ограничен книгой, этот метод возвращает объект со isNullObject свойством true. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
readonly worksheetOrNullObject: Excel.Worksheet;Значение свойства
Комментарии
Сведения о методе
delete()
Удаляет заданное имя.
delete(): void;Возвращаемое значение
void
Комментарии
Примеры
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/34-named-item/create-and-remove-named-item.yaml
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem("Sample");
const totalName = sheet.names.getItemOrNullObject("TotalAmount");
totalName.load();
await context.sync();
if (totalName.value) {
totalName.delete();
// Replace the named item (TotalAmount) with the actual formula for TotalAmount to avoid displaying #NAME in the cell.
sheet.getRange("D11").values = [["=SUM(ExpensesTable[AMOUNT])"]];
} else {
console.log("No named item created for the formula.");
}
await context.sync();
});
getRange()
Возвращает объект диапазона, связанный с именем. Выдает ошибку, если именованный элемент не является диапазоном.
getRange(): Excel.Range;Возвращаемое значение
Комментарии
Примеры
// Returns the Range object that is associated with the name.
// Returns `null` if the name is not of type Range.
// Note: This API currently supports only the Workbook scoped items.
await Excel.run(async (context) => {
const names = context.workbook.names;
const range = names.getItem('MyRange').getRange();
range.load('address');
await context.sync();
console.log(range.address);
});
getRangeOrNullObject()
Возвращает объект Range, сопоставленный с именем. Если тип именованного элемента не является диапазоном, этот метод возвращает объект со свойством isNullObject , установленным в trueзначение . Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
getRangeOrNullObject(): Excel.Range;Возвращаемое значение
Комментарии
load(options)
Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().
load(options?: Excel.Interfaces.NamedItemLoadOptions): Excel.NamedItem;Параметры
Предоставляет параметры для загружаемых свойств объекта.
Возвращаемое значение
load(propertyNames)
Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().
load(propertyNames?: string | string[]): Excel.NamedItem;Параметры
- propertyNames
-
string | string[]
Строка с разделителями-запятыми или массив строк, которые определяют свойства для загрузки.
Возвращаемое значение
Примеры
await Excel.run(async (context) => {
const names = context.workbook.names;
const namedItem = names.getItem('MyRange');
namedItem.load('type');
await context.sync();
console.log(namedItem.type);
});
load(propertyNamesAndPaths)
Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().
load(propertyNamesAndPaths?: {
select?: string;
expand?: string;
}): Excel.NamedItem;Параметры
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
propertyNamesAndPaths.select — это строка с разделителями-запятыми, указывающая загружаемые свойства, и строка propertyNamesAndPaths.expand через запятую, указывающая свойства навигации для загрузки.
Возвращаемое значение
set(properties, options)
Задает несколько свойств объекта одновременно. Вы можете передать либо простой объект с соответствующими свойствами, либо другой объект API того же типа.
set(properties: Interfaces.NamedItemUpdateData, options?: OfficeExtension.UpdateOptions): void;Параметры
- properties
- Excel.Interfaces.NamedItemUpdateData
Объект JavaScript со свойствами, структурированными изоморфно свойствам объекта, для которого вызывается метод.
- options
- OfficeExtension.UpdateOptions
Предоставляет возможность подавления ошибок, если объект properties пытается задать какие-либо свойства только для чтения.
Возвращаемое значение
void
set(properties)
Одновременно задает несколько свойств объекта на основе существующего загруженного объекта.
set(properties: Excel.NamedItem): void;Параметры
- properties
- Excel.NamedItem
Возвращаемое значение
void
toJSON()
Переопределяет метод JavaScript toJSON() , чтобы обеспечить более полезные выходные данные при передаче объекта API в JSON.stringify(). (JSON.stringify, в свою очередь, вызывает toJSON метод переданного ему объекта.) В то время как исходный Excel.NamedItem объект является объектом API, toJSON метод возвращает простой объект JavaScript (типизированный как Excel.Interfaces.NamedItemData), который содержит неглубокие копии любых загруженных дочерних свойств исходного объекта.
toJSON(): Excel.Interfaces.NamedItemData;