SheetXL - v1.0.2
    Preparing search index...

    Interface IComment

    A comment on a cell: the root of a thread, with its replies, or a note.

    Follows Office Scripts' Comment: one per cell, the thread's root, resolved as a whole, with replies (IComment.IReply) that borrow its cell. A note — Excel's older yellow box — is a comment that says so: it has no replies, no resolved state and no creation date, and its content may carry formatting runs where a thread's is plain text.

    Anchored to its cell, so it follows a row or column insert or delete and is deleted when its cell is.

    A note is also the content of a movable: the box it is shown in.

    interface IComment {
        isIAnchored: true;
        isIComment: true;
        acceptFlip?(flip: Flip): Flip;
        acceptRotation?(degrees: number): number;
        addListeners(
            listeners: IComment.IListeners,
            options?: IListener.Options,
        ): Remove;
        addReply(content: IComment.Content, options?: AddReplyOptions): IReply;
        close(): void;
        delete(options?: ITransaction.OperationOptions): void;
        getAnchorType?(): IAnchored.Type;
        getAuthor(): IPerson | null;
        getConnections?(
            width: number,
            height: number,
            options?: ConnectionsOptions,
        ): readonly Connection[] | null;
        getContent(): string;
        getCreationDate(): Date | null;
        getDefaultAnchorType?(): IAnchored.Type;
        getDescription(): string | null;
        getId(): string;
        getMovable(): IMovable | null;
        getName?(): string | null;
        getRange(options?: ICellRange.GetRangeOptions): ICellRange;
        getRanges(options?: ICellRange.GetRangeOptions): ICellRanges;
        getReferences(): ICellRanges | null;
        getReplies(): IReply[];
        getReply(id: string): IReply | null;
        getRichContent(): IRichText.JSON | null;
        getStyle(): IShapeStyle | null;
        getType(): string;
        getTypeDescription(): string;
        getWorksheet(): IWorksheet;
        isClosed(): boolean;
        isDefaultLockAspectRatio?(): boolean;
        isDeleted(): boolean;
        isNote(): boolean;
        isProtected(): boolean;
        isResolved(): boolean;
        setContent(
            content: IComment.Content,
            options?: ITransaction.OperationOptions,
        ): this;
        setDescription(description: string | null): this;
        setName?(name: string): this;
        setResolved(
            resolved: boolean,
            options?: ITransaction.OperationOptions,
        ): this;
        toJSON(): IComment.JSON | null;
        update(
            properties: IComment | Partial<IComment.Properties>,
            options?: ITransaction.OperationOptions,
        ): this;
    }

    Hierarchy (View Summary)

    Index
    isIAnchored isIComment
    acceptFlip? acceptRotation? addListeners addReply close delete getAnchorType? getAuthor getConnections? getContent getCreationDate getDefaultAnchorType? getDescription getId getMovable getName? getRange getRanges getReferences getReplies getReply getRichContent getStyle getType getTypeDescription getWorksheet isClosed isDefaultLockAspectRatio? isDeleted isNote isProtected isResolved setContent setDescription setName? setResolved toJSON update
    isIAnchored: true

    For runtime type checking.

    isIComment: true

    For runtime type checking.

    • The flip this content takes when asked to mirror as flip states.

      Parameters

      Returns Flip

      Defined by content that can be mirrored, such as a shape or a picture; absent, the content cannot: a frame dragged through its opposite edge is moved there but not mirrored, as Excel does with a chart. Must be pure, as acceptRotation is. A connector may accept each axis on its own.

    • The rotation this content takes when asked to turn by degrees, clockwise.

      Parameters

      • degrees: number

      Returns number

      Defined by content that can be turned, such as a shape or a picture; absent, the content cannot and no rotate handle is offered. Must be pure: it is asked throughout a gesture to draw its preview, and the answer is what the movable stores.

    • Similar to delete but cleans resources and can't be undone.

      Returns void

    • The person who wrote the comment, or null if the workbook does not know them.

      Returns IPerson | null

    • The points a connector's end may be glued to, in a width by height frame of this content, before the frame is placed.

      Parameters

      Returns readonly Connection[] | null

      Absent, the four edge midpoints — top, left, bottom, right, numbered in that order, each leaving straight out — as Excel offers on a picture, a chart, a slicer or a control. A shape is the exception and answers its geometry's own sites (a triangle's three, a connector's none); a group answers none, since Excel glues to a group's members and never to the group. Must be synchronous: null means the content cannot answer yet and will call options.onReady when it can.

    • The content as plain text.

      Returns string

      A note's formatting runs are joined; see getRichContent for them.

    • When the comment was written, or null for a note, which Excel does not date.

      Returns Date | null

    • Returns the alternative text used by assistive technologies, or null if none has been set.

      Returns string | null

    • The comment's identifier, unique within the workbook.

      Returns string

    • The box a note is shown in, or null for a threaded comment, which has none.

      Returns IMovable | null

      The box is an ordinary movable: it is selected, moved and resized like a picture's, and is among the sheet's getMovables(). Its content is this comment.

      • Placement. A box that has not been moved sits where Excel puts a new note, beside its cell, and stores nothing. Moving or resizing it stores where it is, relative to its cell, so a note copied to another cell keeps its box beside it.
      • Shown or on hover. isHidden() is true for a box that appears only while its cell is pointed at, which is how a note starts and which a view decides. setHidden(false) keeps it on the sheet.

      A reply converts a note to a threaded comment, and its box goes with it.

      const note = sheet.getComments().add('B2', 'Check this', { asNote: true });
      const box = note.getMovable();
      box.setHidden(false); // always shown
      box.setBounds({ width: 240 });

    • The name of the anchor or null if it has none.

      Returns string | null

    • Returns the ranges this object is anchored to, in authored order.

      Parameters

      Returns ICellRanges

      • Never null. An item whose last range was removed by a row/column delete returns an invalid ranges — ask ICellRanges.isInvalid, the same contract as ITable.getDataRange.
      • This is the general accessor. Most anchored types hold exactly one range and declare their own getRange() for it, but data validations, conditional formats and protected ranges are authored as several, and any single range can become several when a delete splits it.

    • Returns the cells the content names - a chart's series, a control's linked cell, a slicer's column - or null when it names none.

      Returns ICellRanges | null

      Not where the movable sits: that is IMovable.getRange. The references are formulas the calculation engine holds, so they follow the cells they name through inserts, deletes, cuts, sheet renames and undo, and ContentEvents.onReferencesChange is announced when they have. A reference to deleted cells is left out. Without a running engine the references read as they were set.

    • The replies, oldest first.

      Returns IReply[]

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

      Parameters

      • id: string

      Returns IReply | null

    • The content with its formatting runs, or null when it is plain text.

      Returns IRichText.JSON | null

    • The fill and line of a note's box, or null for a threaded comment, which has no box.

      Returns IShapeStyle | null

      A note that states neither draws Excel's default: the system tooltip background (IColor.Named.InfoBk) and a thin line in the tooltip text color. Excel takes only literal colors here; a theme color is written to a file as the color it resolves to.

      const note = sheet.getComments().add('B2', 'Check this', { asNote: true });
      note.getStyle()!.setFill('#ccffcc');
      note.getStyle()!.getStroke().setWidth(2.25);

    • 'note' for a note, 'comment' for a threaded comment.

      Returns string

    • Returns a label for the kind of content, such as Chart or Picture.

      Returns string

    • Returns if the model has been closed

      Returns boolean

    • Whether a movable of this content keeps its aspect ratio when resized from a corner, when it states no lock of its own.

      Returns boolean

      Absent, it does not. A picture does.

    • Returns if the model has been deleted

      Returns boolean

    • If the anchor is unable to be modified.

      Returns boolean

    • Whether the thread is resolved.

      Returns boolean

      Always false for a note.

    • Set the alternative text used by assistive technologies.

      Parameters

      • description: string | null

      Returns this

    • Set the name.

      Parameters

      • name: string

        The name of the content.

      Returns this

    • Returns IComment.JSON | null

      The current state as a JSON object, or null if there is no state.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods