Custom series enhance (next)

[100pah]

Brief Information

This pull request is in the type of:

• bug fixing
• new feature
• others

What does this PR do?

• Support the new APIs about attached text and transform (follow zr-next).
• Modify emphasis setting.
• Provide backward compat for custom series since zr-next change the APIs about attached text and transform.
• Support "clipPath" defined on element.
• Support transition animation related setting in custom series, including transition attrs, shape, style animation, clipPath, and during, and "enter"/"leave" animation.
• Fix and publish "$mergeChildren" (by name or by index) for "group element".

textContent and textPosition

renderItem(params, api) {
    return {
        type: 'rect',
        textContent: {
            // type: 'text' can be ignored
            style: {
                text: 'xxxx',
                fill: 'red'
            }
        },
        textPosition: {
            ...
        }
    }
}

emphasis config

renderItem(params, api) {
    return {
        type: 'rect',
        textContent: {
            // type: 'text' can be ignored
            style: {
                text: 'xxxx',
                fill: 'red'
            },
            emphasis: {
                style: {
                    ...
                }
            }
        },
        textPosition: {
            ...
        },
        emphasis: {
            style: {
                ...
            },
            textPosition: {
                ...
            },
            // z2 can also be specified in emphasis.
            z2: 100
        }
    }
}

renderItem(params, api) {
    return {
        type: 'rect',
        emphasis: {
            // Set false to disable default emphasis behavior.
            style: false,
        }
    }
}

Transform attr

renderItem(params, api) {
    return {
        type: 'rect',
        x: 12,
        y: 11,
        scaleX: 2,
        scaleY: 2,
        originX: 10,
        originY: 32,
        rotation: 1.57
    }
}

clipPath

renderItem(params, api) {
    return {
        type: 'group',
        clipPath: {
            type: 'rect',
            shape: { ... }
        }
    }
}

during

renderItem(params, api) {
    return {
        type: 'rect',
        shape: {
            myAttr: 123,
            $transition: 'myAttr'
        },
        during: function (apiDuring) {
            var x = apiDuring.getAttr('x');
            var myVal = apiDuring.getShape('myAttr');
            apiDuring.setStyle('opacity', 0.5);
            ...
        }
    }
}

transition config

renderItem(params, api) {
    return {
        type: 'rect',
        scaleX: 123,
        scaleY: 123,
        // Means `scaleX` and `scaleY` will be interpolated and
        // have transition animation if series animation related
        // option configured.
        // By default `x` and `y` (and the legacy prop `position`) will
        // be transitioned. But if `$transition` specified, only props
        // in `$transition` will be transitioned.
        $transition: ['x', 'y'],
        shape: {
            myAttr1: 123,
            myAttr2: 123,
            // Means `myAttr1` and `myAttr2` will be interpolated and
            // have transition animation if series animation related
            // option configured.
            $transition: ['myAttr1', 'myAttr2']
        },
        style: {
            // `opacity` will be interpolate and transitioned.
            // for "Image" and "Text", `x`, `y` can also be specified in
            // style, so style transition might be needed.
            $transition: 'opacity'
        },
        clipPath: {
            type: 'circle',
            x: 100
            $transition: 'x'
        }
    }
}

enterFrom laveTo animation config

renderItem(params, api) {
    return {
        type: 'rect',
        rotation: 2 * Math.PI,
        // Means `rotation` will have enter animation from value `0`.
        $enterFrom: {
            rotation: 0
        },
        // Have leave animation to value `0.4`.
        $leaveTo: {
            rotation: 0.4
        },
        shape: {
            myAttr1: 123,
            // Have enter animation from value `10`.
            $enterFrom: {
                myAttr1: 10
            },
            // Have leave animation to value `5`.
            $leaveTo: {
                myAttr1: 5
            },
        },
        style: {
            // Have enter animation from value `0`.
            $enterFrom: {
                opacity: 0
            },
            // Have leave animation to value `0`.
            $leaveTo: {
                opacity: 0
            }
        }
    }
}

$mergeChildren

By default, group children will be merged by index.
Users can also specify $mergeChildren: 'byName' to merge children by name on each child element.
Merge children will happen when each time renderItem called. For example, if there is some condition
variables in renderItem which results in different returned children.

renderItem(params, api) {
    var condition = getCondition();
    var children;
    if (condition === 'm') {
        children = [{
            type: 'circle',
            name: 'name_1',
            ...
        }, {
            type: 'circle',
            name: 'name_2',
            ...
        }, {
            type: 'circle',
            name: 'name_3',
            ...
        }];
    }
    else {
        children = [{
            type: 'circle',
            name: 'name_3',
            ...
        }, {
            type: 'circle',
            name: 'name_1',
            ...
        }]
    }

    return {
        type: 'group',
        $mergeChildren: 'byName',
        children: children
    }
}

Deprecated and break change

• api.style and api.styleEmphasis are deprecated.
• The behavior of api.style and api.styleEmphasis are slightly different (impossible to totally compat).
• position, scale, origin are deprecated.
• diffChildrenByName is deprecated.

Others

Related test cases or examples to use the new APIs

<test/custom-text-content.html>
<test/custom-text-transition.html>

Related issues

#5988

[echarts-bot]

Thanks for your contribution!
The community will review it ASAP. In the meanwhile, please checkout the coding standard and Wiki about How to make a pull request.

The pull request is marked to be PR: author is committer because you are a committer of this project.

[HanochFnag]

Why is there no relevant explanation in the official configuration manual on the website after the update of the "clipPath" configuration option?