Some features are not available in custom series

[Clarkkkk]

In custom series, there are several features not available at all, including itemStyle, labelLine, labelLayout, selectMode, seriesLayoutBy etc. Those sections should be removed. Plus, there is some features that are marked as deprecated in ECharts 5, such as api.style() and api.styleEmphasis(). Those are not documented either.

Since the custom series is kind of a hard part in echarts, I think this part of document need to be reviewed and revised carefully.

[pissang]

Thanks for the suggestion. Agree we should enhance our docs about custom series. But itemStyle, labelLine, labelLayout, selectMode, seriesLayoutBy should work in custom series. Feel free to provide your demo if it doesn't work in your case.

[Clarkkkk]

Thanks for the suggestion. Agree we should enhance our docs about custom series. But itemStyle, labelLine, labelLayout, selectMode, seriesLayoutBy should work in custom series. Feel free to provide your demo if it doesn't work in your case.

Really? Then I must have misunderstood something. I add itemStyle in the official example, and it didn't work. Check this.

[pissang]

In this example, fill is fixed in renderItem. You can try another simpler example https://echarts.apache.org/examples/zh/editor.html?c=custom-cartesian-polygon
api.visual('color') will pick color from itemStyle or color palette. We should mention it in the doc

[Clarkkkk]

In this example, fill is fixed in renderItem. You can try another simpler example https://echarts.apache.org/examples/zh/editor.html?c=custom-cartesian-polygon
api.visual('color') will pick color from itemStyle or color palette. We should mention it in the doc

So here is two conclusions:

1. The color in itemStyle is covered by fill in renderItem, whether fill is specified or not.
2. I need to use api.visual() in renderItem to reference the itemStyle config.

Am I right?

How about the other properties in itemStyle, like shadowBlur etc? I just looked up the source code roughly. It seems that only 'color' and 'borderColor' is supported in api.visual(). Or is it better to use style in renderItem instead of itemStyle?

[Clarkkkk]

In this example, fill is fixed in renderItem. You can try another simpler example https://echarts.apache.org/examples/zh/editor.html?c=custom-cartesian-polygon
api.visual('color') will pick color from itemStyle or color palette. We should mention it in the doc

So here is two conclusions:

1. The color in itemStyle is covered by fill in renderItem, whether fill is specified or not.
2. I need to use api.visual() in renderItem to reference the itemStyle config.

Am I right?

How about the other properties in itemStyle, like shadowBlur etc? I just looked up the source code roughly. It seems that only 'color' and 'borderColor' is supported in api.visual(). Or is it better to use style in renderItem instead of itemStyle?

Oh I discover that I can specify style: api.style() in renderItem to get other properties defined in itemStyle. Why is this deprecated, this is exactly what I need🤣.

As for the label, it is because I didn't get the styles correctly that I would consider that the label relavant properties are not available--The label is invisible without styles. Another fact that misleads me is that there is no label property in custom series doc. Now I discover that specifying style: api.style() also acts on labels, making styles defined in series.label take effect, which is also not documented.

My misunderstanding of selectMode is similar--selected styles are not working. And I didn't find apis that reflect the itemStyle defined in select and blur. I may set those styles in renderItem.

It turns out that if I continue to use itemStyle, it would be inconsistent since itemStyle and styles defined in renderItem.return.select, renderItem.return.blur etc are in different syntax. I think that's why api.style() and api.styleEmphasis() are deprecated--developers are encouraged to set styles right in renderItem. For consistency, itemStyle should be discouraged maybe?

Anyway, my questions are solved generally. There is much work to do with the document though. If you don't have further comments, you can close this issue. Thanks for your patience!😀

[100pah]

@Clarkkkk

Since v5, in custom series, it is recommended to set graphic element style directly rather than in itemStyle.
For example:

var option = {
    xAxis: {
        max: 200
    },
    yAxis: {
        min: 0,
        max: 200
    },
    series: {
        type: 'custom',
        selectedMode: true,
        renderItem: function (params, api) {
            return {
                type: 'circle',
                x: 100,
                y: 100,
                shape: {
                    cx: 0, cy: 0, r: 50
                },
                style: {
                    fill: 'orange'
                },
                textContent: {
                    style: {
                        text: 'this is a label'
                    }
                },
                textConfig: {
                    // label position
                    position: 'top'
                },
                // style for the "selected" state
                select: {
                    style: {
                        fill: 'blue'
                    }
                },
                // style for the "hover" state.
                emphasis: {
                    style: {
                      fill: 'red'
                    }
                }
            }
        },
        data: [[1]]
    }

};

In fact, the final style of a graphic element is always determined by the style: { ... } declaration.
The settings in series.itemStyle are only read by api.style() and works only if assigning the return of api.style() to style: ....

Because it's not easy to keep completely backward compatibility of api.style() if some of the properties in itemStyle, label changed in future, and style can not cover all of the features of itemStyle, label since v5, we decorated api.style() and keep thinking about is there any better way for applying label layout.

[Clarkkkk]

In fact, the final style of a graphic element is always determined by the style: { ... } declaration.
The settings in series.itemStyle are only read by api.style() and works only if assigning the return of api.style() to style: ....

Because it's not easy to keep completely backward compatibility of api.style() if some of the properties in itemStyle, label changed in future, and style can not cover all of the features of itemStyle, label since v5, we decorated api.style() and keep thinking about is there any better way for applying label layout.

Thanks for your detailed explanation.

I don't know too much about the implementation details, but I'd like to share some thoughts as a user. For me, api.style() and api.styleEmphasis() have another advantage: they offer a way to make use of the decent default styles. For example, I can apply the default color list to different series like this:

const series = [{
  type: 'custom',
  name: 'category1',
  renderItem(params, api) {
    return {
      type: 'rect',
      shape: {
        // shape settings
      },
      style: {
      	fill: api.style().fill  // defaultColorList[0]
      }
    }
  }
}, {
  type: 'custom',
  name: 'category2',
  renderItem(params, api) {
    return {
      type: 'rect',
      shape: {
        // shape settings
      },
      style: {
      	fill: api.style().fill  // defaultColorList[1]
      }
    }
  }
}];

Without api.style(), I have to pay extra efforts to achieve this. So maybe something like api.defaultStyle(type) would be good if you totally abandon api.style() and itemStyle:

const series = {
  type: 'custom',
  renderItem(params, api) {
    return {
      type: 'rect',
      shape: {
        // shape settings
      },
      style: {
      	fill: api.defaultStyle('item').fill  // a color of the default color list
        // other custom styles
      },
      emphasis: api.defaultStyle('emphasis'),  // default emphasis styles
      blur: api.defaultStyle('blur'),  // default blur styles
      select: api.defaultStyle('select'),  // default select styles
      label: {
        // default label styles
        textStyle: api.defaultStyle('labelText'),
        boxStyle: api.defaultStyle('labelBox')
      }
    }
  }
};

The api.defaultStyle() doesn't have to cover all of the default styles if there is difficulty in keeping compatibility, because it is used for a so-called "progressive" customization. In this way, there is no need to keep itemStyle and api.style(). I can use the default styles directly. If they don't meet my demand, I should write my own. It is "custom" series after all.