NChart 图表
轻量级简易图表：柱状图 / 折线图 / 饼图三种形态，一份 series 数据驱动；支持多系列、图例、坐标轴网格与刻度、数值标注、平滑曲线、环形饼图与环心文字；深浅主题文字自动换色，属性变化即时重绘，数据项可点选。
平台兼容性
| App(ANDROID) | App(IOS) | App(HARMONY) | WEB | 微信小程序 |
|---|---|---|---|---|
| ✓ | ✓ | ✓ | ✓ | ✓ |
- 绘制通道分端：Web 端画布元素直取上下文，小程序端组件作用域选择器取节点，App 端异步上下文载体。
- 定位为轻量级简易图表：不含动画过渡、触摸十字提示与负值之外的轴定制；复杂分析场景建议使用专业图表库。
- 数值轴以整洁数刻度（1/2/5×10ⁿ 档位）自动取整，支持负值（0 线基准、负柱/负点向下）。
基本使用
柱状图（多系列）：
html
<template>
<n-chart
type="column"
:categories="['一月', '二月', '三月', '四月']"
:series="series"
/>
</template>
<script setup lang="uts">
import { type NChartSeriesItem } from "@/uni_modules/new-ui/components/n-chart/props";
const series: NChartSeriesItem[] = [
{ name: "销售额", data: [320, 410, 380, 520] },
{ name: "成本", data: [210, 260, 240, 300], color: "#3b82f6" }
];
</script>折线图（平滑曲线 + 数值标注）：
html
<n-chart type="line" smooth show-value :categories="week" :series="visits" />饼图与环形（环心文字）：
html
<n-chart type="pie" :radius="90" :series="sources" />
<n-chart type="pie" :radius="90" ring ring-text="流量" :series="sources" />数据项点选（返回被点选的数据项信息）：
html
<template>
<n-chart type="column" :categories="cats" :series="series" @select="onSelect" />
</template>
<script setup lang="uts">
import { type NChartSelectDetail } from "@/uni_modules/new-ui/components/n-chart/props";
function onSelect(detail: NChartSelectDetail) {
// index 类目下标 / name 系列名 / value 数值 / seriesIndex 系列下标
}
</script>导出图片：
html
<script setup lang="uts">
const chartRef = ref<NChartComponentPublicInstance | null>(null);
async function save() {
const url = await chartRef.value!.toPng();
}
</script>API
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| type | string | "column" | 图表类型："column" 柱状图 / "line" 折线图 / "pie" 饼图 |
| categories | string[] | [] | 类目轴标签（柱状图/折线图 X 轴），饼图忽略 |
| series | NChartSeriesItem[] | [] | 数据系列：柱/折线 data 为与 categories 对齐的数值数组；饼图 data 为 {name, value, color?} 数组 |
| width | number | string | 300 | 画布宽度 px（数字）或 px/rpx 字符串 |
| height | number | string | 200 | 画布高度 px（数字）或 px/rpx 字符串 |
| showLegend | boolean | true | 是否显示顶部图例 |
| showValue | boolean | false | 是否绘制数值标注（柱顶 / 折线数据点上方；饼图不标注） |
| showAxis | boolean | true | 是否显示坐标轴、水平网格线与刻度值（柱状图/折线图） |
| colors | string[] | [] | 色板覆盖：系列无 color 时按序取用，空数组时用内置色板 |
| smooth | boolean | false | 折线是否绘制平滑曲线 |
| radius | number | 90 | 饼图半径 px |
| ring | boolean | false | 饼图是否绘制为环形（环心透明） |
| centerRadius | number | 0 | 环形内径 px；0 表示自动取 0.6×radius，非环形时忽略 |
| ringText | string | "" | 环形中心的文字（环形时居中绘制，空串不绘制） |
| textColor | string | "" | 轴/刻度/类目/图例/标注文字颜色；空串表示跟随深浅主题自动换色 |
| customClass | string | "" | 根节点类名（类须定义在使用方样式域） |
| customStyle | string | "" | 根节点行内样式，拼接在内部默认值之后可覆盖 |
事件
| 事件 | 参数 | 说明 |
|---|---|---|
| select | detail: NChartSelectDetail |
数据项被点选时触发：index 类目（扇区）下标、name 系列名（扇区名）、value 数值、seriesIndex 系列下标 |
| error | message: string |
数据非法（value 非有限数值）或画布通道失败时触发，不绘制 |
实例方法
（通过 ref 直调）
| 方法 | 参数 | 返回 | 说明 |
|---|---|---|---|
| toPng | — | Promise<string> | 导出当前图表为 png dataURL；未绘制成功时返回空串 |
数据非法行为
- 系列为空或全部 data 为空数组：清空画布，不报错（未配置状态）。
- value 非有限数值（NaN / Infinity）：发
error，不绘制。 - 饼图 value≤0 的项不绘制扇区（图例仍列出）；全部 ≤0 时空画布。
实现说明（参考做法 vs 本库做法）
指定参考源（柱/折/饼三件）在本地与互联网全渠道核实为加密壳化发行（源码空壳、演示页占位、公开文档无此分类），可核实的只有饼图壳内残留与组件定位自述。本组件按残留依据 + 图表领域通用语义（uni 生态通行图表库的稳定约定）保守自研，逐项对照如下；无法核实项如实标注。
| 机制 | 参考做法 | 本库做法 | 分歧理由 |
|---|---|---|---|
| 组件形态 | 三件独立组件（柱/折/饼各一） | 单组件 type 三形态 |
队列为单组件；数据面与绘制基建高度同构，单组件收敛降低接入成本（同 n-barcode 多码型收敛先例） |
| 饼图数据项 | 壳内 dataset 每项含 color 与角度（数据入口已壳化不可见） | series[0].data = {name, value}[]，色由系列色板分配 | 数据结构取行业通用形态 |
| 饼图实现 | view 扇区旋转 + clip 裁剪拼合（非 canvas） | canvas 弧路径直接绘制，环形用外弧+内弧反向路径填充 | 残留实现中心圆需背景盖板色（background 应与页面背景一致，深浅主题下失真）；弧路径环心天然透明，删去盖板色 prop |
| 饼图尺寸 | radius（rpx 200）/ centerRadius（rpx 120） | radius（px 90）/ centerRadius（px，0 = 自动 0.6×radius） | 尺寸语义统一画布族约定（数字 = px）；默认值换算为等效 px；0.6 比例为残留默认的等效关系 |
| 环心文字 | 残留无 | ringText | 环形图环心信息位为通用形态，低成本低风险收录 |
| 数据项点击 | 壳内扇区绑定 itemClick(index) | select 事件，参数 {index, name, value, seriesIndex}；柱/折线同享（带区间 / 最近点 ≤12px 命中） | 事件名全小写（小程序端事件名兼容惯例）；参数结构化三形态一致；命中几何与绘制共用同一布局函数 |
| 类目轴 + 系列 | 不可核实 | categories + series({name, data, color}) | 行业通用数据形态（通行图表库同构） |
| 刻度取整 | 不可核实 | 整洁数步长（1/2/5×10ⁿ），4 条网格线，0 线加重 | 刻度标注可整除不留长尾小数，通行做法 |
| 负值 | 不可核实 | 支持（vMin < 0 时 0 线偏移，负柱向下） | 数据轴 0 基准的自然延伸 |
| 图例 / 数值标注 | 不可核实 | showLegend / showValue 开关 | 行业通用开关语义（legend / dataLabel） |
| 平滑曲线 | 不可核实 | smooth（相邻中点二次贝塞尔） | 行业通用形态 |
| 色板 | dataset 每项带 color | 系列可显式 color；缺省按 colors 色板或内置 8 色按序分配 | 显式色优先 + 自动色板兜底 |
| 主题适配 | 不可核实 | textColor 空 = 深浅主题自动（isDark watch 重绘），显式传值覆盖 | 库主题系统一致体验（同水印深浅换色机制） |
| 动画 / 触摸提示 | 不可核实 | 不收录 | 定位为轻量级简易图表；参考源残留亦无动画痕迹；复杂场景建议专业图表库 |
| 导出 | 不可核实 | toPng png dataURL | 库内画布组件（二维码/条码）一致能力，海报合成等场景依赖 |
| 错误暴露 | 不可核实 | error 事件（数据非法 / 画布通道失败显式暴露） | 静默失败违背库内画布组件一致性 |
| 响应式 | 不可核实（残留 setRadius 空函数，疑似手动重绘入口） | 全 props 指纹 watch 自动重绘 | 手动重绘入口在属性驱动的声明式用法下多余（同条码收敛决策） |