跳转到正文

RChart 与 useChart ​

RChart 接收 ECharts options,负责创建实例、更新主题、监听尺寸与清理。需要确定的容器高度;height="100%" 依赖父元素的高度。图表数据和 series 配置由页面管理。

tsx
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] }],
        }}
      />
    )
  },
})

交互示例 ​

查看示例源码
tsx
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,以及标题、提示、网格、数据集、图例等基础模块。
intersectionObservertrue进入观察范围后挂载图表;隐藏区域的实例可能尚不可用;浏览器不支持观察时直接挂载。
intersectionObserverTarget / intersectionOptions容器 / { threshold: 0.1 }自定义观察目标与参数。
autoResize / autoResizeObserverTargettrue / 绘图容器容器尺寸变化后节流 resize。
watchOptions / watchDeeptrue / true是否订阅 options,是否深层观察。
watchOptionsThrottleWait500options 更新节流间隔(毫秒)。
nextTicktrue初始化前等待 Vue 更新。
setChartOptions{ notMerge: true, lazyUpdate: true, silent: false, replaceMerge: [] }ECharts setOption 的控制参数。
theme / autoChangeThemenull / true默认跟随应用的四套风格及明暗设置。固定主题请传注册名。
loading / loadingOptionsfalse / 当前图表主题是否显示 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 接受 ECharts getDataURL 参数和可选 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。图表随组件卸载清理。

Props · 组件实现 · useChart