更新记录

1.0.0（2026-09-07） 下载此版本

首次发布，面向 uni-app x App Vapor 的高性能原生图表组件。

• 支持 iOS 17+、Android API 21+；iOS 使用 SwiftUI / Swift Charts，Android 使用硬件加速 Canvas。
• 提供折线、平滑折线、面积、堆叠折线、堆叠面积、分组柱状、堆叠柱状、横向柱状、饼图、环形图、雷达、散点和仪表盘共 13 类图表。
• 提供统一 option 配置，支持对象、JSON 字符串、单序列和多序列数据。
• 提供 setOption、setData、resetData、reload、clear 方法及 ready、select、error 事件。
• 支持原生入场与数据过渡动画、动画开关、缓动及饼环起始角和顺逆时针配置。
• 支持深浅主题、标题、图例、坐标轴、提示卡片、数据选择、圆角和渐变样式。
• 合并同轮更新、跳过重复配置，缓存绘制数据并复用动画缓冲；清空或销毁时取消待执行任务。
• 支持负值横柱、正负堆叠、长图例滚动、空状态和无效数据校验。
• 提供完整示例页、接入文档、配置与原生模型测试。

平台兼容性

uni-app x(3.8.3)

其他

原生图表 · kongbai-native-chart

面向 uni-app x App Vapor 的高性能原生图表组件，支持 iOS / Android，提供折线、柱状、饼图、环形、雷达、仪表盘等 13 类图表。适用于经营报表、数据看板、趋势分析和进度展示。

原生渲染与性能

• 原生绘制：iOS 使用 SwiftUI / Swift Charts，Android 使用硬件加速 Canvas，不依赖 WebView 或网页图表库。
• 原生动画：支持入场动画与数据过渡，可配置动画时长、缓动和饼环展开方向。
• 减少重复渲染：合并同一轮数据更新，跳过内容相同的配置，减少原生桥接调用。
• 绘制缓存：Android 缓存坐标范围、图例宽度并复用动画缓冲；iOS 在数据更新时准备绘制数据，减少动画与交互期间的重复计算。
• 交互与样式：支持数据选择、提示卡片、可滚动图例、深浅主题、圆角和渐变。
• 接入简洁：通过一个 option 配置图表，支持对象或 JSON 字符串，使用 setData 更新数据。

性能取决于设备、数据量和更新频率。大量数据建议限制展示窗口，并按需关闭动画与数据点标记。

安装与运行

1. 将 kongbai-native-chart 导入项目的 uni_modules 目录。

2. 使用 HBuilderX 5.21.0 或以上版本，并在 manifest.json 中启用 Vapor：

   { "uni-app-x": { "vapor": true } }

3. 使用包含本插件的自定义基座运行示例，正式发布时重新打包 App。

4. 组件支持 easycom 自动注册；在页面中设置明确的高度后即可使用。

插件信息

• 版本：1.0.0
• 作者：空白人吗
• QQ：6864952
• 邮箱：kongbai0804@163.com
• 不含广告，不采集或上传用户数据，无需申请系统权限。

最简使用

<template>
  <kongbai-native-chart ref="chartRef" style="height: 300px" :option="option" />
</template>

<script setup lang="uts">
  import { ref } from 'vue'

  const chartRef = ref<any | null>(null)
  const option = ref<UTSJSONObject>({
    type: 'line',
    title: '每月收入',
    labels: ['一月', '二月', '三月'],
    data: [18, 26, 22]
  })
</script>

默认显示图例、坐标轴、tooltip，并使用 800ms 的缓出动画。支持 easycom，必须给组件可用高度。

多序列沿用常见的 series 写法：

const option: UTSJSONObject = {
  type: 'bar',
  labels: ['一月', '二月', '三月'],
  series: [
    { name: '收入', data: [18, 26, 22], color: '#3B82F6' },
    { name: '成本', data: [12, 17, 19], color: '#22C55E' }
  ],
  legend: true,
  tooltip: true,
  animation: false
}

series 也接受单个序列对象或数字数组。图表类型统一放在根级 type；本组件使用独立的配置 API，不兼容完整 ECharts 配置，不支持混合类型、formatter 函数或 dataset。

更新与生命周期

// 单序列：保留当前第一条序列的名称、颜色和线条样式。
chartRef.value?.setData([22, 30, 28])
chartRef.value?.setData([22, 30, 28], ['四月', '五月', '六月'])

// 多序列：替换整个序列集合。
chartRef.value?.setData([
  { name: '收入', data: [22, 30, 28] },
  { name: '成本', data: [14, 19, 21] }
])

// 替换完整配置，不做深度合并。
chartRef.value?.setOption({ type: 'donut', labels: ['搜索', '推荐'], data: [60, 40] })
// 也可传入 JSON 字符串。
chartRef.value?.setOption(JSON.stringify({ type: 'line', data: [1, 2, 3] }))

• setData(data, labels?)：省略 labels 保留当前标签；传 [] 清除标签。数据传 [] 显示空状态。数字数组会替换为单序列；序列对象/对象数组会替换全部序列及其样式。
• option 支持替换对象和深层响应式修改；大数组推荐整批替换或调用 setData，避免高频逐点修改。
• resetData()：取消数据覆盖，恢复当前完整 option 的数据。
• reload()：强制重新应用当前配置，不承诺重播入场动画。
• clear()：取消尚未执行的渲染并清空画面；reload() 可恢复当前数据覆盖。
• 同一轮更新只跨一次原生桥；内容相同的更新跳过。销毁后取消任务与原生动画。

数值只接受有限 number。null、数字字符串、缺失值会报错；无效数据不会被自动删除或补零。请先在业务侧处理缺失值；当前不支持断点折线。

动画与方向

const option: UTSJSONObject = {
  type: 'donut',
  labels: ['搜索', '推荐', '其他'],
  data: [48, 32, 20],
  animation: { duration: 700, easing: 'ease-out' },
  pie: { startAngle: -90, clockwise: false }
}

• 折线、面积、竖柱从零轴向目标值展开；横柱在固定数值范围内伸展，负值朝零轴左侧展开。
• 饼图/环图通过角度展开，默认从顶部顺时针；pie.startAngle 以右侧为 0 度、下侧为 90 度，clockwise: false 为逆时针。
• 仪表盘从 gauge.min 起步。endAngle > startAngle 顺时针，反之逆时针；建议跨度不超过 360 度。
• 雷达按各指标半径变化，iOS 通过可插值数值向量接续快速更新，Android 从当前呈现值插值。
• animation: false 或 duration: 0 立即显示终态。iOS 尊重系统“减弱动态效果”。两端由各自原生引擎执行，缓动细节并非逐像素相同。

两端均支持横向滑动长图例。点击/拖动图表可选择数据；关闭 tooltip 只隐藏提示卡片，仍会触发 select。饼环外侧和环内空白不选中扇区。

支持类型

Option 字段

以下为字段说明；页面中可直接使用 UTSJSONObject 对象字面量。

type ChartOption = {
  type?: 'line' | 'smooth-line' | 'area' | 'stacked-line' | 'stacked-area'
    | 'bar' | 'stacked-bar' | 'horizontal-bar'
    | 'pie' | 'donut' | 'radar' | 'scatter' | 'gauge';
  theme?: 'light' | 'dark' | 'auto';
  colors?: string[];
  labels?: string[];
  name?: string; // data 简写的序列名
  data?: number[]; // 单序列简写，series 优先
  series?: ChartSeries[] | ChartSeries | number[];
  title?: string | { text?: string; subtext?: string; color?: string };
  legend?: boolean | { show?: boolean; position?: 'top' | 'bottom'; textColor?: string };
  tooltip?: boolean | { show?: boolean };
  animation?: boolean | {
    enabled?: boolean;
    duration?: number; // 0..3000 ms；0 立即显示终态
    easing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
  };
  xAxis?: { show?: boolean; data?: string[]; labelColor?: string; gridColor?: string };
  yAxis?: { show?: boolean; min?: number; max?: number; labelColor?: string; gridColor?: string };
  line?: { smooth?: boolean; width?: number; showSymbol?: boolean; symbolSize?: number; areaOpacity?: number };
  bar?: { width?: number; radius?: number };
  pie?: { innerRadius?: number; padAngle?: number; cornerRadius?: number; showLabel?: boolean; startAngle?: number; clockwise?: boolean };
  radar?: {
    indicators?: Array<{ name: string; max: number }>;
    splitNumber?: number;
    shape?: 'polygon' | 'circle';
    fillOpacity?: number;
  };
  gauge?: { min?: number; max?: number; unit?: string; startAngle?: number; endAngle?: number };
  backgroundColor?: string;
  emptyText?: string;
  padding?: number;
};

type ChartSeries = {
  name?: string;
  data: number[];
  color?: string;
  smooth?: boolean;
  areaOpacity?: number;
  lineWidth?: number;
  symbolSize?: number;
};

xAxis.data 与 labels 等价，优先使用 xAxis.data。series.data 是推荐字段；解析器也接受 values，方便已有数据结构迁移。

默认视觉采用同色相明暗渐变、圆角柱体、带高光的数据点和渐隐面积；所有 13 类图表共享这套绘制风格。显式传入的颜色、柱宽、圆角与透明度仍然优先。

• 柱图默认 bar.width = 18、bar.radius = 6。
• 环图默认 pie.innerRadius = 54（外半径的百分比），分段间隔 padAngle = 2 度。
• 饼图/环图支持 pie.cornerRadius = 6（Android dp / iOS pt，范围 0–24）；设为 0 可恢复直角。圆角自动受环厚和切片角度限制，不扩大数据扇区；仅一个非零切片时绘制完整圆周。
• iOS 使用柔和投影，Android 使用矢量偏移底层与边缘高光，避免为阴影切换软件渲染。两端不承诺像素级相同。

事件

• ready：配置已应用，参数 { token }；不代表动画结束。
• select：参数 { index, seriesIndex, value }，下标从 0 开始，value 为原始数据。
• error：参数 { token, message }。无效更新保留之前可用的图表；标签不足时会提示并使用默认标签。

过期 token 回调在桥接层过滤。setOption 或新的 prop 会清除 setData 覆盖。

平台与性能边界

• 仅支持 uni-app x App，项目需启用 manifest.json -> uni-app-x.vapor: true；HBuilderX 5.21+、Android API 21+、iOS 17+。
• 不支持 Web、HarmonyOS、小程序和普通 uni-app；不使用 WebView，不采集或上传数据。
• 颜色支持 #RGB、#RRGGBB、transparent。
• 饼、环、仪表盘使用第一条序列；饼环按数值绝对值计算占比。雷达值映射到 0..指标上限，指标数应与数据长度一致。
• 散点图当前是“类目索引 + 数值”，不是任意 (x,y) 坐标散点。
• 尚无 dataZoom、分页或自动降采样；大量点应在业务侧限制展示窗口，并按需设置 line.showSymbol: false、animation: false。
• Android 缓存坐标范围、点数、图例宽度；每帧复用插值和正负堆叠缓冲。iOS 在数据更新时准备点、扇区和指标上限，避免选中和动画期间反复展开原始数据。
• 发布前请使用自定义基座，在目标设备上验证实际数据量下的帧率、内存和触摸体验。

示例与测试

pages/index/index.uvue 提供 13 类图表切换、动态更新、深浅主题、清空恢复、无动画负值横柱和逆时针环图示例。页面数值为演示数据。

配置与生命周期测试：

node uni_modules/kongbai-native-chart/tests/option.test.cjs

需要 TypeScript，可通过 CHART_TYPESCRIPT_PATH 指定模块路径。macOS 安装 Xcode 后，可执行 Swift 模型与几何测试：

python3 uni_modules/kongbai-native-chart/tests/native-model.test.py

以上测试覆盖配置和原生模型逻辑；完整 App 的桥接、动画和手势需要在运行环境中验证。