Chen-KChartPro

UniApp Android/iOS 专业 K 线图原生插件

Chen-KChartPro 是基于 Flutter KChart 渲染引擎封装的 uni-app App 原生插件，提供 Android 和 iOS 双端一致的 K 线、深度图、技术指标、绘图工具及交易叠加能力。

插件提供两种使用方式：

1. 使用 <chen-kchart-pro> 将 KChart 作为原生组件嵌入 .nvue 页面，页面、行情数据和工具栏由 uni-app 业务层控制。
2. 使用 openDemo() 直接打开完整 Flutter KChart Demo，用于功能体验和效果对照。

如有接入问题、功能需求或商业合作，请添加VX：Chen-Taurus-0510（添加时请备注 KChart）。

在线体验

平台要求

当前插件版本：1.0.0。

主要功能

• 支持蜡烛图、分时图、深度图和成交量图。
• 支持 MA、EMA、BOLL、SAR、MACD、KDJ、RSI、WR、CCI、OBV、StochRSI 等指标。
• 支持拖动浏览、双指缩放、十字线、回到最新、指定时间跳转和自定义价格范围。
• 支持趋势线、趋势角、箭头、垂直线、水平线、水平射线、射线和十字线绘图。
• 支持磁铁吸附、连续绘图、撤销、重做、清空和绘图数据恢复。
• 支持买卖 B/S 标记、订单线、持仓线、开仓价、强平价、止盈止损和未实现盈亏。
• 支持历史行情分页、实时 K 线更新、亮色/深色主题和色觉友好模式。
• 支持通过 Props、ref 方法和事件与 uni-app 页面进行双向交互。

插件接入

1. 复制插件文件

将以下目录完整复制到业务项目：

nativeplugins/Chen-KChartPro/  
uni_modules/chen-kchart/

其中：

• nativeplugins/Chen-KChartPro 包含 Android/iOS 原生插件产物。
• uni_modules/chen-kchart 包含可直接在 .nvue 页面使用的组件封装。

2. 配置本地原生插件

在 HBuilderX 中打开：

manifest.json -> App 原生插件配置 -> 选择本地插件

勾选 Chen-KChartPro，保存后重新制作 Android/iOS 自定义基座。新增或更新本地原生插件后，旧基座不会自动包含新插件，必须重新制作基座或重新云打包。

3. 页面中使用组件

该组件用于 uni-app App 端 .nvue 页面。将组件放入页面并设置明确的宽高：

<template>  
  <view class="page">  
    <chen-kchart-pro  
      ref="chart"  
      :data="bars"  
      :options="chartOptions"  
      theme="light"  
      mainIndicator="MA"  
      secondaryIndicator="KDJ"  
      :showVolume="true"  
      :tradeMarkers="tradeMarkers"  
      :tradingOverlay="tradingOverlay"  
      chartStyle="width:750rpx;height:900rpx;"  
      @ready="onChartReady"  
      @crosshair="onCrosshair"  
      @viewport-change="onViewportChange"  
      @load-more="onLoadMore"  
      @error="onChartError"  
    />  
  </view>  
</template>  

<script>  
export default {  
  data() {  
    return {  
      bars: [],  
      tradeMarkers: [],  
      tradingOverlay: {},  
      chartOptions: {  
        showNowPrice: true,  
        showInfoDialog: true,  
        enableDrawingTools: true,  
        precision: 4,  
        minScale: 0.35,  
        maxScale: 5  
      }  
    }  
  },  
  methods: {  
    onChartReady() {  
      this.$refs.chart.setData(this.bars)  
    },  
    onCrosshair(event) {  
      console.log('crosshair:', event)  
    },  
    onViewportChange(event) {  
      console.log('viewport:', event)  
    },  
    onLoadMore(event) {  
      if (event && event.history) this.loadHistory()  
    },  
    onChartError(event) {  
      console.error('KChart error:', event)  
    }  
  }  
}  
</script>

K 线数据格式

每根 K 线至少需要以下字段：

{  
  time: 1790481600000, // Unix 毫秒时间戳  
  open: 50000,  
  high: 50200,  
  low: 49800,  
  close: 50100,  
  vol: 123.45  
}

数据要求：

• time 使用 Unix 毫秒时间戳，建议直接使用行情服务返回的 UTC 时间戳。
• open、high、low、close、vol 必须是有效数字。
• 完整数据应按时间从旧到新排列。
• 业务端负责根据当前周期请求或生成 OHLCV，插件不负责将逐笔成交聚合为 K 线。
• 切换交易对或周期后，应重新请求数据并调用 setData()。

组件属性

options 配置

指标设置

indicatorConfigs 会直接传入纯 Flutter KChart 指标计算和渲染层，支持
MA/EMA/BOLL/SAR/VOL/MACD/KDJ/RSI/WR/CCI/OBV/STOCH_RSI：

chartOptions: {  
  indicatorConfigs: [  
    {  
      id: 'BOLL',  
      parameters: { period: 20, multiplier: 2 },  
      colors: { mb: '#2962ff', up: '#ff9800', dn: '#7e57c2' },  
      hiddenSeries: [],  
      enabled: true  
    },  
    {  
      id: 'KDJ',  
      parameters: { period: 9, kSmoothing: 3, dSmoothing: 3 },  
      colors: { k: '#2962ff', d: '#ff9800', j: '#7e57c2' },  
      hiddenSeries: ['j']  
    }  
  ]  
}

绑定的 options 支持深度响应式更新，也可以显式调用
this.$refs.chart.setOptions(this.chartOptions)。完整设置面板实现可直接复用
pages/sample/kchart-module.nvue 中的指标设置数据结构与方法。

数据更新方法

// 第一次加载或切换周期  
this.$refs.chart.setData(bars)  

// 加载更早历史数据  
this.$refs.chart.appendData(olderBars)  

// WebSocket/轮询更新最新 K 线  
this.$refs.chart.updateLastData(realtimeBar)

注意：

• appendData() 不应传入已经存在的重复时间数据，业务端应先按 time 去重。
• updateLastData() 只用于当前最后一根或新生成的一根 K 线，不要传入早于当前最后时间的数据。
• Props 响应式更新和 ref 方法更新应选择一种，不要在同一次行情更新中同时修改 :data 并调用 updateLastData()，否则会同时触发全量和增量更新。
• 用户正在浏览历史区域时，实时更新不会强制拉回最新位置；可通过 viewport-change 的 isAtLatest 判断当前状态。

图表控制方法

基础配置

深度与交易

绘图工具

支持的绘图类型：

trendLine、trendAngle、arrow、verticalLine、horizontalLine、  
horizontalRay、ray、crossLine、NONE

setDrawingOptions() 支持：

this.$refs.chart.setDrawingOptions({  
  continuous: true,  
  magnet: true,  
  magnetThreshold: 50,  
  color: '#f2b84b',  
  strokeWidth: 2,  
  lineStyle: 'solid', // solid/dashed/dotted  
  visible: true  
})

视口与十字线

深度与交易数据

深度图

this.$refs.chart.setDepthData({  
  bids: [  
    { price: 50000, volume: 10 },  
    { price: 49990, volume: 18 }  
  ],  
  asks: [  
    { price: 50010, volume: 8 },  
    { price: 50020, volume: 15 }  
  ]  
})

volume 建议传入从盘口中心向外累计后的数量。

成交标记

this.$refs.chart.setTradeMarkers([  
  {  
    id: 'buy-1',  
    time: 1790481600000,  
    price: 50000,  
    side: 'buy', // buy/sell  
    label: 'B',  
    style: 'badge', // badge/arrow  
    color: '#00c087',  
    size: 12,  
    visible: true  
  }  
])

订单与持仓线

this.$refs.chart.setTradingOverlay({  
  visible: true,  
  showOrders: true,  
  showPositions: true,  
  showLiquidationPrice: true,  
  showTakeProfitStopLoss: true,  
  showTradeHistory: true,  
  lines: [  
    {  
      id: 'position-1',  
      price: 50000,  
      kind: 'position',  
      side: 'buy',  
      label: '多仓',  
      quantity: '0.50 BTC',  
      unrealizedPnl: 42.8,  
      unrealizedPnlPercent: 1.72  
    },  
    {  
      id: 'tp-1',  
      price: 51000,  
      kind: 'takeProfit',  
      side: 'sell',  
      label: '止盈',  
      draggable: true,  
      dashed: true  
    }  
  ]  
})

kind 支持 order、position、liquidation、takeProfit、stopLoss。订单 status 支持 pending、open、partiallyFilled、filled、canceled、rejected。

组件事件

可拖动交易线在松手后会先显示价格修改确认弹窗，用户确认后才触发 trading-line-drag-end。

打开完整 Flutter Demo

通过 js_sdk 调用

import { openDemo } from '@/nativeplugins/Chen-KChartPro/js_sdk/index.js'  

openDemo({}, result => {  
  console.log('open demo:', result.success)  
})

直接引用原生模块

const kchartModule = uni.requireNativePlugin('Chen-KChartPro')  

kchartModule.openDemo({}, result => {  
  console.log(result)  
})

打包说明

• 本地调试必须使用包含 Chen-KChartPro 的自定义基座，普通标准基座不包含该插件。
• 正式发布时需要在 manifest.json 中勾选插件后重新云打包。
• Android 插件保留 armeabi-v7a、arm64-v8a、x86_64 三种 ABI。
• 不要把 Flutter、Android 的 build 目录或 uni-app 的旧 unpackage 缓存当作插件依赖提交。
• 如果替换了插件原生产物，需要重新制作自定义基座后再验证。

完整示例

项目中的完整 uni-app 自定义交易页可参考：

pages/sample/kchart-module.nvue

可复用组件封装位于：

uni_modules/chen-kchart/components/chen-kchart-pro/chen-kchart-pro.nvue