RChart 与 useChart
RChart 接收 ECharts options,负责创建实例、更新主题、监听尺寸与清理。需要确定的容器高度;height="100%" 依赖父元素的高度。图表数据和 series 配置由页面管理。
import { RChart, useChart } from '@/components'
import { defineComponent } from 'vue'
export default defineComponent({
setup() {
const [register] = useChart()
return () => (
<RChart
onRegister={register}
preset="card"
title="周订单量"
height={300}
options={{
xAxis: { type: 'category', data: ['周一', '周二', '周三'] },
yAxis: { type: 'value' },
series: [{ type: 'bar', data: [12, 19, 14] }],
}}
/>
)
},
})交互示例
查看示例源码
import DemoPage from '../components/DemoPage'
import DemoResult from '../components/DemoResult'
import './index.scss'
import { getDemoCharts } from '@/api/demo/data'
import type { DemoCharts } from '@/api/demo/data'
import { useI18n } from '@/hooks'
import { RChart, useChart } from '@ray-template/ui/chart'
import { NButton, NCard, NFlex, NSwitch } from 'naive-ui'
const Echart = defineComponent({
name: 'REchart',
setup() {
const [register, { dispose, render }] = useChart()
const [register2, { dispose: dispose2, render: render2 }] = useChart()
const { t } = useI18n('demoDetails.chart')
const chartData = shallowRef<DemoCharts>()
const requestController = new AbortController()
onScopeDispose(() => requestController.abort())
const chartLoading = ref(false)
const chartAria = ref(false)
const state = reactive({
loading: false,
loading1: false,
lineReady: false,
lineVisible: false,
barReady: false,
barVisible: false,
revision: 1,
})
const baseOptions = computed<GlobalEChartsCoreOption>(() => ({
legend: { type: 'scroll', top: 0 },
tooltip: { trigger: 'axis' },
grid: { left: 44, right: 14, top: 42, bottom: 26 },
xAxis: {
type: 'category',
data: chartData.value?.days ?? [],
},
yAxis: { type: 'value' },
series: [
{
name: t('orders'),
data: chartData.value?.orders ?? [],
type: 'bar',
barMaxWidth: 24,
},
{
name: t('visits'),
data: chartData.value?.visits ?? [],
type: 'bar',
barMaxWidth: 24,
},
],
}))
const pieOptions = computed<GlobalEChartsCoreOption>(() => ({
tooltip: { trigger: 'item' },
legend: { type: 'scroll', bottom: 0 },
series: [
{
type: 'pie',
radius: ['40%', '68%'],
center: ['50%', '46%'],
label: { show: false },
data: (chartData.value?.sources ?? []).map(({ key, value }) => ({
value,
name: t(key),
})),
},
],
}))
const baseLineOptions = computed(() => ({
tooltip: { trigger: 'axis', axisPointer: { type: 'cross' } },
legend: { type: 'scroll', bottom: 0 },
grid: { left: 52, right: 20, top: 20, bottom: 58 },
xAxis: [
{
type: 'category',
boundaryGap: false,
data: chartData.value?.days ?? [],
},
],
yAxis: [{ type: 'value' }],
series: (chartData.value?.lines ?? []).map((line) => ({
name: line.name,
type: 'line',
stack: 'Total',
areaStyle: {},
emphasis: { focus: 'series' },
data: line.values,
})),
}))
const handleLoadingShow = (bool: boolean) => {
state.loading = bool
}
const handleAriaShow = (bool: boolean) => {
chartAria.value = bool
}
const unmountChart = () => {
dispose()
state.lineVisible = false
}
const loadCharts = async (refresh = false) => {
state.loading1 = true
try {
chartData.value = await getDemoCharts(refresh, requestController.signal)
if (refresh) state.revision += 1
} catch {
if (!requestController.signal.aborted)
window.$message.error(t('loadFailed'))
} finally {
state.loading1 = false
}
}
void loadCharts()
const updateChartOptions = () => {
void loadCharts(true)
}
return {
baseOptions,
chartLoading,
handleLoadingShow,
chartAria,
handleAriaShow,
pieOptions,
baseLineOptions,
...toRefs(state),
mountChart: render,
unmountChart,
updateChartOptions,
register,
register2,
dispose2,
render2,
}
},
render() {
const { register, register2, dispose2, render2, loading1 } = this
return (
<DemoPage
title={this.$t('menu.Echart')}
description={this.$t('showcase.chartDescription')}
eyebrow="RAY TEMPLATE / EXAMPLES"
>
<div class="echart">
<section class="echart__lead">
<NFlex align="center">
<NButton
disabled={!this.lineReady || this.lineVisible}
onClick={this.mountChart}
>
{this.$t('demoDetails.chart.mount')}
</NButton>
<NButton disabled={!this.lineVisible} onClick={this.unmountChart}>
{this.$t('demoDetails.chart.dispose')}
</NButton>
<NButton
disabled={!this.lineVisible || loading1}
onClick={this.updateChartOptions}
>
{this.$t('demoDetails.chart.update')}
</NButton>
<NButton
onClick={() => {
this.loading1 = !this.loading1
}}
>
{this.$t(
loading1
? 'demoDetails.chart.stopLoading'
: 'demoDetails.chart.showLoading',
)}
</NButton>
</NFlex>
<div class="chart--container">
<RChart
onRegister={register}
onSuccess={() => {
this.lineReady = true
this.lineVisible = true
}}
title={this.$t('demoDetails.chart.sales')}
autoChangeTheme
options={this.baseLineOptions}
showAria={this.chartAria}
preset="card"
loading={loading1}
/>
</div>
<DemoResult label={this.$t('demoDetails.chart.series')}>
{this.lineVisible
? this.$t('demoDetails.chart.revision', {
value: this.revision,
})
: this.$t('demoDetails.chart.unmounted')}
</DemoResult>
</section>
<div class="echart__examples">
<NCard title={this.$t('demoDetails.chart.fixedTheme')}>
<NFlex vertical>
<NFlex>
<NButton
disabled={!this.barReady || this.barVisible}
onClick={render2}
>
{this.$t('demoDetails.chart.mount')}
</NButton>
<NButton
disabled={!this.barVisible}
onClick={() => {
dispose2()
this.barVisible = false
}}
>
{this.$t('demoDetails.chart.dispose')}
</NButton>
</NFlex>
<div class="chart--container">
<RChart
onRegister={register2}
onSuccess={() => {
this.barReady = true
this.barVisible = true
}}
theme="ray-naive"
options={this.baseOptions}
/>
</div>
</NFlex>
</NCard>
<NCard title={this.$t('demoDetails.chart.showLoading')}>
<NSwitch
v-model:value={this.chartLoading}
onUpdateValue={this.handleLoadingShow.bind(this)}
style={['padding: 18px 0']}
>
{{
checked: () => this.$t('demoDetails.chart.stopLoading'),
unchecked: () => this.$t('demoDetails.chart.showLoading'),
}}
</NSwitch>
<div class="chart--container">
<RChart loading={this.loading} options={this.pieOptions} />
</div>
</NCard>
<NCard title={this.$t('demoDetails.chart.pattern')}>
<NSwitch
v-model:value={this.chartAria}
onUpdateValue={this.handleAriaShow.bind(this)}
style={['padding: 18px 0']}
>
{{
checked: () => this.$t('demoDetails.chart.hidePattern'),
unchecked: () => this.$t('demoDetails.chart.pattern'),
}}
</NSwitch>
<div class="chart--container">
<RChart options={this.baseOptions} showAria={this.chartAria} />
</div>
</NCard>
</div>
</div>
</DemoPage>
)
},
})
export default Echart渲染、主题与更新
| 属性 | 默认 | 说明 |
|---|---|---|
options | {} | ECharts 配置。showAria 默认 false,组件控制 aria.enabled 和 aria.decal.show,保留其余 ARIA 配置。 |
width / height | '100%' | CSS 尺寸,数字按像素。 |
use | [] | 额外 ECharts 注册项。内置柱、线、饼、K 线、散点、象形柱、Canvas,以及标题、提示、网格、数据集、图例等基础模块。 |
intersectionObserver | true | 进入观察范围后挂载图表;隐藏区域的实例可能尚不可用;浏览器不支持观察时直接挂载。 |
intersectionObserverTarget / intersectionOptions | 容器 / { threshold: 0.1 } | 自定义观察目标与参数。 |
autoResize / autoResizeObserverTarget | true / 绘图容器 | 容器尺寸变化后节流 resize。 |
watchOptions / watchDeep | true / true | 是否订阅 options,是否深层观察。 |
watchOptionsThrottleWait | 500 | options 更新节流间隔(毫秒)。 |
nextTick | true | 初始化前等待 Vue 更新。 |
setChartOptions | { notMerge: true, lazyUpdate: true, silent: false, replaceMerge: [] } | ECharts setOption 的控制参数。 |
theme / autoChangeTheme | null / true | 默认跟随应用的四套风格及明暗设置。固定主题请传注册名。 |
loading / loadingOptions | false / 当前图表主题 | 是否显示 ECharts 加载层;传入的字段覆盖默认样式。 |
默认使用 ray-modern、ray-naive、ray-material 或 ray-plain,各有 -dark 变体。theme="default" 使用 ECharts 内建主题,autoChangeTheme=true 时随应用明暗变化;显式指定其他注册名时固定使用该主题。设置 autoChangeTheme=false 可禁用自动选择暗色变体。旧版 macarons 与 macarons-dark 已移除。
八套主题的画布、文本、图例、坐标轴、提示层和数据配色成组设计,并与对应风格的卡片表面对齐。现代化使用冷色系,Naive 以绿色起始,Material 使用紫色与柔和色组,朴素使用低饱和分类色;切换应用主色不会单独改写数据色。页面 options 的显式样式仍优先于主题。
默认加载层使用当前图表配色。自定义主题的透明或无效背景会回退到相应明暗表面色,避免透明背景被转换为黑色遮罩;可通过 loadingOptions 显式覆盖遮罩、文字或旋转图标。
切换主题会调用 ECharts 6 的 setTheme,保留实例和事件监听。ECharts 会重建内部选项模型,图例选择、缩放和通过合并模式写入的增量配置可能被重置。需要保留这些值时,将它们作为完整 options 提供。
卡片预设和回调
preset="card"使用 Naive UI Card,支持title(字符串或渲染函数)、bordered(默认true)、contentStyle。cardExtra插槽可替换右上角。- 默认菜单含图片下载;
downloadOptions接受 EChartsgetDataURL参数和可选filename。传入dropdownOptions会替换菜单,选择项通过onDropdownSelect(key, option)通知。 - 初始化成功后依次触发
onRegister(instance, render, dispose)、onSuccess(instance)和onFinally()。初始化失败会释放实例,调用onError()和onFinally(),并通过 Vue 错误处理链报告异常。首次应用 options 同步渲染,使注册回调能立即读取图表;后续更新按setChartOptions处理。
useChart() 返回 [register, actions]。getChartInstance() 返回 { echartInst, render, dispose },注册前会抛错。isDisposed() 检查底层实例,dispose() 释放图表并停止观察,render() 恢复挂载;已存在实例时不要用它替代更新 options 或 setOption。图表随组件卸载清理。