更新记录

1.0.0（2026-10-27）

• 首次发布 Chen KChart Pro UTS 组件。
• 支持蜡烛图、空心蜡烛图、分时线和买卖深度图，并提供深色、浅色主题切换。
• 支持 MA、EMA、BOLL、SAR 主图指标，以及 VOL、MACD、KDJ、RSI、WR、CCI、OBV、STOCH RSI 副图指标。
• 支持行情全量替换、历史数据追加、最新 K 线实时更新及滚动加载更多历史数据。
• 支持十字线、双指缩放、拖动浏览、视口复位、内容适配、定位最新数据，以及按索引或时间跳转。
• 支持趋势线、水平线、垂直线等画线交互，并提供撤销、重做、清空和绘图数据同步能力。
• 支持买卖成交标记、订单线、持仓线、止盈止损线，以及点击和拖动事件回调。
• 提供完整的 uni-app nvue 示例页面、组件属性、Ref 方法和事件回调文档。

平台兼容性

uni-app(4.25)

uni-app x

其他

Chen KChart Pro UTS Demo

uni-app 专业 K 线图组件

在线体验

功能概览

• 支持蜡烛图、空心蜡烛图、分时图、成交量图和买卖深度图。
• 支持浅色、深色及色觉友好配色。
• 支持 MA、EMA、BOLL、SAR 主图指标。
• 支持 VOL、MACD、KDJ、RSI、WR、CCI、OBV、STOCH RSI 副图指标。
• 支持指标参数、线条颜色和序列显隐配置。
• 支持拖动浏览、双指缩放、十字线、回到最新、内容适配和指定时间跳转。
• 支持趋势线、趋势角、箭头、垂直线、水平线、水平射线、射线和十字线绘图。
• 支持连续绘图、磁铁吸附、显示/隐藏、撤销、重做、清空和绘图恢复。
• 支持买卖 B/S 标记、订单线、持仓线、强平线、止盈止损线和未实现盈亏。
• 支持历史行情分页加载、全量替换和最新 K 线实时更新。
• 支持通过 Props、Ref 方法和事件与 uni-app 页面双向交互。

运行环境

当前插件不支持普通 App Vue 页面、H5 和各类小程序。

项目结构

uniapp-plugin-demo/
├── pages/
│   └── sample/
│       └── kchart-module.nvue       # 完整 KChart 交易页 Demo
├── uni_modules/
│   └── chen-kchart/
│       ├── package.json             # UTS 插件清单
│       ├── readme.md                # 插件市场说明
│       ├── changelog.md             # 版本日志
│       └── utssdk/
│           ├── app-android/         # Android UTS
│           └── app-ios/             # iOS UTS
├── manifest.json
├── pages.json
└── README.md

运行当前 Demo

1. 使用 HBuilderX 打开项目

打开本仓库根目录：

/Users/victor/UniProjects/uniapp-plugin-demo

入口页面已在 pages.json 中配置为：

pages/sample/kchart-module.nvue

Demo 默认使用 500 根本地模拟 OHLCV 数据，不依赖网络即可验证 K 线、指标和交互。页面右上角可切换到实盘模式，实盘模式会由 Demo 页面请求 Binance 的 BTC/USDT 行情和深度数据。

2. 重新制作自定义基座

首次运行、升级插件，或修改以下内容后，需要重新制作自定义基座：

• uni_modules/chen-kchart/utssdk 中的 UTS、Java、Swift 代码；
• Android libs 中的 AAR/JAR；
• iOS Frameworks；
• 插件 config.json 或原生依赖配置。

在 HBuilderX 中执行：

运行 -> 运行到手机或模拟器 -> 制作自定义调试基座

制作完成后，选择对应自定义基座运行到已连接的真机。只修改普通 .nvue 页面逻辑和样式时，通常可以热更新，不必重复制作基座。

3. 验证功能

Demo 页面可直接验证：

• 模拟/实盘行情切换；
• 分时以及 1m、5m、15m、30m、1h、4h、1d、1w 周期；
• K 线、深度图、亮暗主题和色觉友好模式；
• 主副图指标及指标参数设置；
• 画线、撤销、重做、磁铁和连续绘图；
• 成交标记、订单/持仓及止盈止损线；
• 实时更新和左滑加载历史行情。

接入业务项目

1. 复制插件

将整个目录复制到业务项目，不要遗漏原生依赖：

uni_modules/chen-kchart/

不需要再复制或勾选 nativeplugins/Chen-KChartPro。复制后重新制作包含该 UTS 组件的自定义基座。

2. 在 nvue 页面使用

组件可通过 easycom 自动注册，无需手动 import。原生组件必须设置明确的宽高：

<template>
  <view class="page">
    <chen-kchart
      ref="chart"
      style="width:750rpx;height:900rpx;"
      :dataJson="barsJson"
      :optionsJson="chartOptionsJson"
      theme="dark"
      mainIndicator="MA"
      secondaryIndicator="KDJ"
      candleBodyMode="solid"
      :showVolume="true"
      :lineMode="false"
      mode="KLINE"
      :depthJson="depthJson"
      :tradeMarkersJson="tradeMarkersJson"
      :tradingOverlayJson="tradingOverlayJson"
      @ready="onChartReady"
      @crosshair="onCrosshair"
      @viewport-change="onViewportChange"
      @load-more="onLoadMore"
      @error="onChartError"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      bars: [],
      depth: { bids: [], asks: [] },
      tradeMarkers: [],
      tradingOverlay: { visible: false, lines: [] },
      chartOptions: {
        showNowPrice: true,
        showInfoDialog: true,
        enableDrawingTools: true,
        precision: 4,
        minScale: 0.35,
        maxScale: 5
      }
    }
  },
  computed: {
    barsJson() {
      return JSON.stringify(this.bars)
    },
    depthJson() {
      return JSON.stringify(this.depth)
    },
    tradeMarkersJson() {
      return JSON.stringify(this.tradeMarkers)
    },
    tradingOverlayJson() {
      return JSON.stringify(this.tradingOverlay)
    },
    chartOptionsJson() {
      return JSON.stringify(this.chartOptions)
    }
  },
  methods: {
    onChartReady() {
      this.$refs.chart.scrollToLatest()
    },
    onCrosshair(event) {
      console.log('crosshair:', event.detail || event)
    },
    onViewportChange(event) {
      console.log('viewport:', event.detail || event)
    },
    onLoadMore(event) {
      console.log('load more:', event.detail || event)
    },
    onChartError(event) {
      console.error('KChart error:', event.detail || event)
    }
  }
}
</script>

为什么推荐 JSON 字符串接口

classic uni-app/nvue 将对象数组传入 UTS 组件时，复杂对象的内部字段可能被序列化为空对象 {}。表现通常是 K 线没有蜡烛实体、只出现一条直线，或指标全部基于零值计算。

因此，复杂数据应在页面 JavaScript 层先调用 JSON.stringify()，再通过以下属性或方法跨越 UTS 边界：

• dataJson / replaceDataJson() / appendDataJson() / updateLastDataJson()；
• optionsJson / applyOptionsJson()；
• depthJson / setDepthDataJson()；
• tradeMarkersJson / applyTradeMarkersJson()；
• tradingOverlayJson / applyTradingOverlayJson()；
• setDrawingsJson()。

组件仍保留对象/数组形式的兼容接口，但 classic uni-app/nvue 项目应优先使用 JSON 字符串接口。

K 线数据格式

每根 K 线使用以下字段：

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

数据要求：

• time 必须是 Unix 毫秒时间戳；
• open、high、low、close、vol 必须是有效数字；
• high 不应低于 open 和 close，low 不应高于 open 和 close；
• 数据按时间从旧到新排列；
• 业务端负责根据周期生成或请求 OHLCV，组件不负责把逐笔成交聚合为 K 线；
• 切换交易对或周期后，使用 replaceDataJson() 全量替换数据。

组件属性

options 配置

指标配置示例：

const options = {
  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'],
      enabled: true
    }
  ]
}

this.$refs.chart.applyOptionsJson(JSON.stringify(options))

完整指标编辑数据结构可参考 pages/sample/kchart-module.nvue。

Ref 方法

行情数据

// 首次加载、刷新、切换交易对或周期
this.$refs.chart.replaceDataJson(JSON.stringify(bars))

// 左滑加载更早历史数据
this.$refs.chart.appendDataJson(JSON.stringify(olderBars))

// WebSocket 或轮询更新当前 K 线
this.$refs.chart.updateLastDataJson(JSON.stringify(realtimeBar))

同一次更新不要既修改 dataJson 又调用增量方法，否则可能同时触发全量和增量更新。用户浏览历史区域时，实时更新不会强制拉回最新位置，可根据 viewport-change 中的 isAtLatest 决定是否显示“回到最新”。

基础配置

深度与交易

绘图工具

支持的绘图类型：

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

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

视口与十字线

深度与交易数据

深度图

const depth = {
  bids: [
    { price: 50000, volume: 10 },
    { price: 49990, volume: 18 }
  ],
  asks: [
    { price: 50010, volume: 8 },
    { price: 50020, volume: 15 }
  ]
}

this.$refs.chart.setDepthDataJson(JSON.stringify(depth))
this.$refs.chart.setChartMode('DEPTH')

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

成交标记

const markers = [
  {
    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.applyTradeMarkersJson(JSON.stringify(markers))

订单与持仓线

const overlay = {
  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
    }
  ]
}

this.$refs.chart.applyTradingOverlayJson(JSON.stringify(overlay))

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

组件事件

不同 uni-app/HBuilderX 版本可能会把事件内容再包装在 detail 中，可使用：

const detail = event && event.detail !== undefined ? event.detail : event

权限、数据与广告说明

• Android Demo 在 manifest.json 中声明 android.permission.INTERNET，用于实盘模式请求行情；该权限不是危险权限。
• iOS 不需要额外申请系统权限。
• 插件自身不采集、不存储、不上传用户数据，只渲染宿主传入的数据。
• 插件不包含广告。
• Demo 的 Binance 网络请求由示例页面发起，不属于插件的数据采集行为。

打包与发布

• 本地调试必须使用包含 chen-kchart 的自定义基座，标准基座不包含原生产物。
• 更新 UTS 或原生产物后，旧基座不会自动更新，必须重新制作基座或重新打包。
• Android manifest.json 中只保留一条 android.permission.INTERNET，避免 HBuilderX 报权限重复。
• 不要删除 utssdk/app-android/libs 或 utssdk/app-ios/Frameworks 中的文件。
• 发布插件前，在 HBuilderX 中右键 uni_modules/chen-kchart/package.json，选择“发布到插件市场”。
• 插件类型选择“UTS 插件 / uni-app 兼容模式组件”。
• 按插件市场要求，将 package.json 的 id 调整为“作者 ID-插件名称”，并确保 package.json 与 changelog.md 的发布版本一致。

常见问题

1. 页面空白或组件完全不显示

依次检查：

1. 页面是否为 .nvue；
2. <chen-kchart> 是否设置了明确的宽度和高度；
3. 是否重新制作并选择了包含当前插件的自定义基座；
4. 真机系统版本是否满足 Android API 24 或 iOS 13.0；
5. 是否收到组件的 ready 或 error 事件。

2. 只显示一条线，没有正常蜡烛图

通常是复杂数组跨 UTS 边界后元素变成 {}。不要直接传 :data="bars"，改用：

<chen-kchart :dataJson="JSON.stringify(bars)" />

实时更新使用：

this.$refs.chart.updateLastDataJson(JSON.stringify(bar))

同时确认每根数据都包含有效的 time/open/high/low/close/vol，且价格没有被传成 undefined、null 或非数字字符串。

3. 修改插件后真机仍是旧效果

UTS 原生组件、Java/Swift 代码产物都编译在基座内。修改这些内容后仅刷新页面不够，需要重新制作自定义基座，并确认运行时选择的是新基座。

4. 实盘模式无法加载

检查网络、Android 的 INTERNET 权限及 Binance 接口在当前网络环境中的可访问性。实盘请求失败时，当前 Demo 会自动切回模拟数据；该问题不影响插件使用业务方自行提供的行情。

5. 图表初始化后被重复刷新

同一种数据选择一种更新路径：响应式更新 dataJson，或调用 Ref 方法。不要在同一个行情回调中同时修改完整数组并调用 updateLastDataJson()。

相关文档

• 插件使用说明
• 版本更新日志
• 完整示例页面

技术支持

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