Highlight Row, Cell

This is a distinctive feature of the table, used to set highlights after real-time data updates to alert users.

You can highlight rows or cells by calling the instance methods setHighlightDimRow & setHighlightDimCell.

TIP

• Highlighted rows and cells use animation (el.animate() method to trigger animation) by default. To customize the animation, you can pass the option parameter. See MDN for Animation API details, and MDN for compatibility.
• Highlight colors do not change in real-time with the theme.
• Highlight not working? Check if props.rowKey is specified.

Built-in Highlight Animation

// 高亮行，可传入key数组，一次性高亮多行，利于性能
stkTableRef.current?.setHighlightDimRow(['id0']); 
// 高亮单元格
stkTableRef.current?.setHighlightDimCell('id1', 'age');

loading

Global Highlight Configuration

props.highlightConfig

type HighlightConfig = {
    /** 持续时间 */
    duration?: number;
    /** 高亮动画帧率 */
    fps?: number;
}

TIP

• Reducing the highlight frame rate is beneficial for performance.
• If you want to specify the animation frame rate, refer to the easing: 'step(xx)' implementation of the Animation API. (Same as CSS animation-timing-function: step)

WARNING

If you customize the keyframe, HighlightConfig.fps will be invalid!

Custom Highlight Animation via Animation API

stkTableRef.current?.setHighlightDimRow([id], {
    keyframe: [
        { backgroundColor: '#1e4c99', transform: 'translateY(-30px) scale(0.6)', opacity: 0, easing: 'cubic-bezier(.11,.1,.03,.98)' },
        { backgroundColor: '#1B1B24', transform: 'translateY(0) scale(1)', opacity: 1 },
    ],
    duration: 1000,
});

stkTableRef.current?.setHighlightDimCell('id1', 'age', {
    keyframe: {
        color: ['#fff', '#C70000', '#fff'],
        transform: ['scale(1)', 'scale(1.1)', 'scale(1)'],
        boxShadow: ['unset', '0 0 10px #aaa', 'unset'],
        easing: 'cubic-bezier(.11,.1,.03,.98)',
    },
});

loading

Custom Highlight Animation via CSS

This API is an older animation implementation method. It is still retained due to the advantages of css animations such as convenience, good compatibility, and ease of understanding.

stkTableRef.current?.setHighlightDimRow(['id1'], { 
    method: 'css',
    className: 'special-highlight-row',
    duration: 2000
});

WARNING

Here duration is set to 2000 to clear the class from the element after the animation ends, which needs to be consistent with the CSS animation duration.

@keyframes my-highlight-row {
    from { background-color: #bd7201; }
}
.special-highlight-row {
    animation: my-highlight-row 2s linear;
}

loading

Custom Highlight Animation via JS (deprecated)

Click to view

stkTableRef?.setHighlightDimRow(['id1'], { 
    method: 'js',
    duration: 2000
});

Not recommended as it requires manual color calculation and has poor performance. Depends on `d3-interpolate`.

API

Highlight Row setHighlightDimRow

/**
 * 高亮一行
 * @param rowKeyValues 行唯一键的数组
 * @param option.method css-使用css渲染，animation-使用animation api。默认animation
 * @param option.className 自定义css动画的class。
 * @param option.keyframe 如果自定义keyframe，则 highlightConfig.fps 将会失效。
 * @param option.duration 动画时长。method='css'状态下，用于移除class，如果传入了className则需要与自定义的动画时间一致。。
 */
setHighlightDimRow(rowKeyValues: UniqKey[], option: HighlightDimRowOption = {}): void;

Highlight Cell setHighlightDimCell

/**
 * 高亮一个单元格。暂不支持虚拟滚动高亮状态记忆。
 * @param rowKeyValue 一行的key
 * @param colKeyValue 列key
 * @param options.method css-使用css渲染，animation-使用animation api。默认animation;
 * @param option.className 自定义css动画的class。
 * @param option.keyframe 如果自定义keyframe，则 highlightConfig.fps 将会失效。
 * @param option.duration 动画时长。method='css'状态下，用于移除class，如果传入了className则需要与自定义的动画时间一致。
 */
setHighlightDimCell(rowKeyValue: UniqKey, colKeyValue: string, option: HighlightDimCellOption = {}): void;

Parameter Types

type HighlightDimBaseOption = {
    duration?: number;
    /**
     * 忽略不可见元素。为 true 时：
     * - 调用 setHighlightDimRow 时，若获取不到对应 DOM 则直接丢弃，不放入 store 循环计算；
     * - 若 store 中已存在该 key，也会被删除。
     * - 在循环计算过程中，若某行 DOM 已不存在，也会从 store 中删除，不再继续计算。
     */
    ignoreInvisible?: boolean;
};

type HighlightDimAnimationOption = HighlightDimBaseOption & {
    /** use Animation API */
    method: 'animation';
    /**
     * same as https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats
     */
    keyframe?: Parameters<Animatable['animate']>['0'];
};
type HighlightDimCssOption = HighlightDimBaseOption & {
    method: 'css';
    /** class name with css animation */
    className?: string;
    /** control delay time to remove className */
    duration?: number;
};

export type HighlightDimCellOption = HighlightDimBaseOption | HighlightDimAnimationOption | HighlightDimCssOption;
export type HighlightDimRowOption = HighlightDimBaseOption | HighlightDimAnimationOption | HighlightDimCssOption;