ReadonlyisFor runtime type checking.
ReadonlyisFor runtime type checking.
Iterates the collection's items.
The unfiltered walk — for (const sheet of wb.getSheets()). Every other iterable surface in
the SDK (ICellRange, ICellRegions, ICellRanges) reads this way, so a collection that did
not was a trap: for…of over one is the obvious line to write and it threw at runtime with
nothing in the types to warn first.
getItems remains the call that takes options — filtering, ordering, anything parameterized. This is sugar over the unfiltered case, not a replacement for it.
Define a name.
The name. Case insensitive, must be unique, and must not contain spaces.
The expression to bind it to, with or without a leading =. A plain range
address (Sheet1!$A$1:$B$2) is simply a reference expression.
OptionalreplaceExisting: boolean
If true, redefine an existing name instead of throwing. default false.
Add Listeners.
Optionaloptions: IListener.OptionsReturns the item at the given index, or undefined if there is none.
The position in iteration order. A negative index counts back from the end, as
Array.prototype.at does.
Close the record and cleans resources. Can't be undone.
Returns a new valid name given the name return a valid name that closely matches. This function works by incrementing either the last number or append a number.
The range to used as a template.
Optionalscope: string
The scope of the range. If null then this will look for a globally scoped. default null.
OptionalignoreExisting: boolean
If true then won't check to see if the name is already used. default false.
A valid name. If the name used is valid then will return the same name.
Lookup a named item by its unique stable id.
The id returned by INamed.getId.
Lookup a named range with a given name.
Case insensitive name to lookup.
Optionalglobal: boolean
If true then will search all scopes. default false.
The reference text for every name that designates exactly the given ranges.
The ranges to match. Unqualified coords are read as being on the current scope (the selected sheet), which is what lets a sheet's own selection be passed straight through.
Optionaloptions: GetByRangesOptions
includeParts additionally matches the insides of an item — see
INamedCollection.GetByRangesOptions.includeParts.
The names, whole-item matches first, then part references. Empty when nothing matches.
The inverse of resolving a name: given a region, what is it called? This is what lets a name
box show Sales in place of $B$2:$C$3, and what lets a formula editor substitute the name
for an address the user picked by dragging.
Exact, not containing. A selection inside Sales is not Sales — the ranges must
coincide. Multi-range names match irrespective of the order the ranges are given in.
Text, not items. A part has no INamed to return (Sales[Amount] is a structured
reference, not an entry in this collection), so every match comes back as the text a formula
would use. Several names may share one region, hence an array; callers wanting a single answer
take the first.
Return the named items. These are sorted by type then by name.
Optionaloptions: INamedCollection.GetItemsOptionsReturns the index of the item in iteration order, or -1 if it is not in the collection.
The item to find.
Returns true if no more operations are allowed.
Returns the items as a fresh array, in iteration order.
Validates a name is valid. This is a convenience method That calls findValidName
and throws an error if the name returned is not the same.
Optionalscope: stringOptionalignoreExisting: boolean
A collection of
INameditems — defined names AND tables.Remarks
Which items it holds is decided by where you got it from, not by an option. There is no scope argument anywhere on this interface:
The two exist because the two consumers genuinely differ: a name manager lists everything that exists, while a formula editor may only offer what a formula written here can actually refer to. Both get it from
getItems()with no arguments, which is the point — the scope question is answered by the call you make, so it cannot be got wrong by omitting an option.Scope is visibility, never location. A defined name lives on no sheet and may be visible everywhere or on exactly one sheet. A table lives ON a sheet but its name is always visible everywhere and workbook-unique — so
getScope()isnullfor every table, and tables appear in BOTH collections. That is not a special case: they are globally visible, so they turn up wherever globally visible items do. For the tables anchored to one sheet, askISheet.getTables()— that is the location question, and it has its own call.Porting from Excel's Office Scripts. Deliberately close but not identical. There,
Workbook.getNames()is global-scoped names ONLY andWorksheet.getNames()is that sheet's own ONLY, with tables kept out of names entirely. Both of ours are supersets of their counterpart, so a direct port is over-inclusive rather than wrong — it will never see another sheet's private names. Filter on INamed.getScope (null= global) for exact parity.