SheetXL - v0.8.0-beta.9+sites.210.e2d420901
    Preparing search index...

    Interface IPersonCollection

    Holds the people a workbook knows: everyone who authored or is mentioned in a comment.

    Keyed by id. Adding a person whose id, or whose display name, is already here returns the existing one rather than a second copy, which is what lets a legacy note's author (a display name with no id) and a threaded comment's author (an id) land on one person.

    interface IPersonCollection {
        isICollection: true;
        isIPersonCollection: true;
        "[iterator]"(): IterableIterator<IPerson>;
        add(person: string | IPerson.Properties): IPerson;
        addListeners(
            listeners: ICollection.IListeners,
            options?: IListener.Options,
        ): Remove;
        at(index: number): IPerson | undefined;
        every(
            predicate: (
                value: IPerson,
                index: number,
                items: readonly IPerson[],
            ) => boolean,
        ): boolean;
        filter<S extends IPerson>(
            predicate: (
                value: IPerson,
                index: number,
                items: readonly IPerson[],
            ) => value is S,
        ): S[];
        filter(
            predicate: (
                value: IPerson,
                index: number,
                items: readonly IPerson[],
            ) => boolean,
        ): IPerson[];
        find<S extends IPerson>(
            predicate: (
                value: IPerson,
                index: number,
                items: readonly IPerson[],
            ) => value is S,
        ): S | undefined;
        find(
            predicate: (
                value: IPerson,
                index: number,
                items: readonly IPerson[],
            ) => boolean,
        ): IPerson | undefined;
        findIndex(
            predicate: (
                value: IPerson,
                index: number,
                items: readonly IPerson[],
            ) => boolean,
        ): number;
        forEach(
            fn: (value: IPerson, index: number, items: readonly IPerson[]) => void,
        ): void;
        getByDisplayName(displayName: string): IPerson | null;
        getById(id: string): IPerson | null;
        getCount(): number;
        getCurrent(): IPerson;
        getItems(options?: ICollection.GetItemsOptions): IPerson[];
        indexOf(item: IPerson): number;
        isClosed(): boolean;
        map<U>(
            fn: (value: IPerson, index: number, items: readonly IPerson[]) => U,
        ): U[];
        setCurrent(person: string | IPerson | IPerson.Properties | null): void;
        some(
            predicate: (
                value: IPerson,
                index: number,
                items: readonly IPerson[],
            ) => boolean,
        ): boolean;
        toArray(): IPerson[];
        toJSON(): IPerson.JSON[] | null;
    }

    Hierarchy (View Summary)

    Implemented by

    Index
    isICollection isIPersonCollection
    [iterator] add addListeners at every filter find findIndex forEach getByDisplayName getById getCount getCurrent getItems indexOf isClosed map setCurrent some toArray toJSON
    isICollection: true

    For runtime type checking.

    isIPersonCollection: true

    For runtime type checking.

    • Iterates the collection's items.

      Returns IterableIterator<IPerson>

      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.

    • Adds a person, or returns the one already here with the same id or display name.

      Parameters

      • person: string | IPerson.Properties

        The person's properties, or a display name alone.

      Returns IPerson

    • Returns the item at the given index, or undefined if there is none.

      Parameters

      • index: number

        The position in iteration order. A negative index counts back from the end, as Array.prototype.at does.

      Returns IPerson | undefined

    • Returns true if the predicate accepts every item, including when there are none.

      Parameters

      • predicate: (value: IPerson, index: number, items: readonly IPerson[]) => boolean

        Called once per item in iteration order until it returns false.

      Returns boolean

    • Returns the items the predicate accepts, in iteration order.

      Type Parameters

      Parameters

      • predicate: (value: IPerson, index: number, items: readonly IPerson[]) => value is S

        Called once per item.

      Returns S[]

    • Returns the items the predicate accepts, in iteration order.

      Parameters

      • predicate: (value: IPerson, index: number, items: readonly IPerson[]) => boolean

        Called once per item.

      Returns IPerson[]

    • Returns the first item the predicate accepts, or undefined if it accepts none.

      Type Parameters

      Parameters

      • predicate: (value: IPerson, index: number, items: readonly IPerson[]) => value is S

        Called once per item in iteration order until it returns true.

      Returns S | undefined

    • Returns the first item the predicate accepts, or undefined if it accepts none.

      Parameters

      • predicate: (value: IPerson, index: number, items: readonly IPerson[]) => boolean

        Called once per item in iteration order until it returns true.

      Returns IPerson | undefined

    • Returns the index of the first item the predicate accepts, or -1 if it accepts none.

      Parameters

      • predicate: (value: IPerson, index: number, items: readonly IPerson[]) => boolean

        Called once per item in iteration order until it returns true.

      Returns number

    • Calls the function once per item, in iteration order.

      Parameters

      • fn: (value: IPerson, index: number, items: readonly IPerson[]) => void

        Called once per item.

      Returns void

    • Returns the person with the given display name, or null if there is none.

      Parameters

      • displayName: string

        The display name. Case sensitive, as Excel keeps it.

      Returns IPerson | null

    • Returns the person with the given id, or null if there is none.

      Parameters

      • id: string

      Returns IPerson | null

    • Returns the total items available.

      Returns number

      returns the total number of items available.

    • The person a new comment is authored by when none is named.

      Returns IPerson

      Excel uses the signed-in user; SheetXL has no user, so this is whoever setCurrent named, and otherwise a person called Author, added on first use.

    • Returns the index of the item in iteration order, or -1 if it is not in the collection.

      Parameters

      Returns number

    • Returns true once the collection has been closed.

      Returns boolean

      A closed collection is empty and announces nothing further. Collections that are closed by their owner (the workbook's names, functions and modules, when the workbook closes) announce it once with ICollection.Events.onClose; the others are never closed and always return false.

    • Returns the result of calling the function on every item, in iteration order.

      Type Parameters

      • U

      Parameters

      • fn: (value: IPerson, index: number, items: readonly IPerson[]) => U

        Called once per item.

      Returns U[]

    • Names the person new comments are authored by.

      Parameters

      • person: string | IPerson | IPerson.Properties | null

        A person, a person's properties, a display name, or null to forget the choice. A person not yet in the collection is added.

      Returns void

    • Returns true if the predicate accepts at least one item.

      Parameters

      • predicate: (value: IPerson, index: number, items: readonly IPerson[]) => boolean

        Called once per item in iteration order until it returns true.

      Returns boolean

    • Returns the items as a fresh array, in iteration order.

      Returns IPerson[]

      The call to make when an array is really wanted. The array is the caller's: changing it does not change the collection, and it does not follow later changes to the collection.

    • Serializes to JSON, or null if there is no one to write.

      Returns IPerson.JSON[] | null

    Settings
    Member Visibility

    On This Page
    Properties
    Methods