更新记录

2.0.9（2026-07-11）

• 修复：Android 编译下载后的加密试用插件时，可能出现 resolveVisualAppearance 或 createRuntimeState 未定义的问题。

2.0.8（2026-07-11）

• 重构：Android、iOS、HarmonyOS 改由各自的 utssdk/app-*/index.uts 薄入口调用同一套 UTS 图表核心，删除插件根 index.uts，避免它遮蔽平台入口选择。
• 重构：iOS 删除 JavaScriptCore、Swift 混编运行时和生成脚本，图表算法由 UTS 直接编译为 Swift，与 Android、HarmonyOS 保持同源。
• 修复：每个 <hans-chart> 使用独立 runtime 保存 scene，并在卸载时释放；复杂原生 model 在所属 UTS runtime 内序列化，避免 iOS JS proxy 无法读取嵌套对象。
• 修复：金融指标可空数组在平台入口归一化为 JSON 兼容数据，图例按跨代理 JSON 属性规则读取，恢复 iOS 首页、金融图表与图例渲染。
• 兼容：最低 HBuilderX / uni-app x 编译器版本调整为 5.15。

2.0.7（2026-07-10）

• 修复：iOS 组件与 Android/鸿蒙统一通过插件根入口调用公开 JSON API，不再导入发布试用包后会被加密的 components/**/ios-runtime/*.uts。
• 修复：恢复 iOS 平台入口的场景和交互运行时实现，使用加密 Swift 混编桥执行现有图表核心，buildHansChartSceneJson / resolveHansChartRuntimeJson 不再返回不可用占位结果，也不再把整套 UTS 引擎编译为 Swift。
• 维护：发布审计、README 与加密试用包边界文档统一为“组件仅可导入 interface.uts 和插件根入口”的规则。

平台兼容性

uni-app x(5.15)

hans-charts 图表组件

hans-charts 是面向 uni-app x App 的 Canvas 2D 图表组件。使用 <hans-chart> 渲染图表，通过类型化 model 传入数据；需要图例时，可搭配无状态组件 <hans-chart-legend>。

兼容性

插件不申请系统权限，不依赖第三方原生 SDK。公开类型、常量和 helper 统一从 @/uni_modules/hans-charts 导入，不要直接引用插件内部文件。

安装与使用

从插件市场导入插件，或将完整插件目录放到项目的 uni_modules/hans-charts。组件符合 easycom 目录规范，页面中可以直接使用 <hans-chart> 和 <hans-chart-legend>，无需手动注册组件。

加密试用版包含 UTS 原生插件。首次导入或升级版本后，需要重新打包自定义基座并选择该基座运行；标准基座提示“uts插件[hans-charts]不存在”表示基座未包含插件，不是图表源码编译失败。

快速开始

<template>
  <view class="chart-host">
    <hans-chart
      class="chart"
      :model="chartModel"
      :interaction="interaction"
      @selection-change="ionChange"
      @tooltip-change="onTooltipChange"
    />
  </view>

  <hans-chart-legend
    :items="legendItems"
    marker-shape="line"
  />
</template>

<script setup lang="uts">
import type {
  HansChartInteraction,
  HansChartLegendItem,
  HansChartSelectionChangeEvent,
  HansChartTooltipChangeEvent,
  HansLineChartModel,
  HansLineModelFromValuesOptions
} from '@/uni_modules/hans-charts'
import {
  createLineModelFromValues,
  resolveSeriesLegendItems
} from '@/uni_modules/hans-charts'

const options: HansLineModelFromValuesOptions = {
  title: '周访问趋势',
  subtitle: '最近四天',
  labels: ['周一', '周二', '周三', '周四'],
  seriesId: 'visits',
  seriesName: '访问量',
  valueFormat: '{label}: {value}'
}

const chartModel: HansLineChartModel = createLineModelFromValues(
  [42, 68, 59, 84],
  options
)

const interaction: HansChartInteraction = {
  tooltip: true,
  selection: true,
  rangeSelection: false
}

const legendItems: HansChartLegendItem[] = resolveSeriesLegendItems(
  chartModel.series,
  null
)

function ionChange(event: HansChartSelectionChangeEvent): void {
  console.log('selection', event.selected, event.item)
}

function onTooltipChange(event: HansChartTooltipChangeEvent): void {
  console.log('tooltip', event.visible, event.title, event.rows)
}
</script>

<style>
.chart-host {
  width: 100%;
  height: 280px;
}

.chart {
  width: 100%;
  height: 100%;
}
</style>

<hans-chart> 会读取组件的实际宽高绘制 Canvas，因此宿主容器必须有明确且非零的高度。若图表位于弹窗、折叠面板或条件区域中，请在容器完成布局后再挂载组件。

支持的图表

构造 Model

推荐使用 create*ModelFromValues helper 将业务数据转换为标准 model，再传给 <hans-chart>。所有 helper 和对应的 options 类型都可以从插件根目录导入。

多系列 helper 的 options 使用 HansMultiSeriesModelFromValuesOptions：

import type {
  HansLineChartModel,
  HansMultiSeriesModelFromValuesOptions
} from '@/uni_modules/hans-charts'
import { createGroupedLineModelFromSeriesValues } from '@/uni_modules/hans-charts'

const options: HansMultiSeriesModelFromValuesOptions = {
  title: '渠道趋势',
  labels: ['周一', '周二', '周三'],
  seriesIds: ['organic', 'paid'],
  seriesNames: ['自然流量', '付费流量'],
  colors: ['#3F7DED', '#22A8A3'],
  valueFormat: '{name} · {label}: {value}'
}

const model: HansLineChartModel = createGroupedLineModelFromSeriesValues(
  [
    [32, 48, 61],
    [18, 27, 35]
  ],
  options
)

数值格式

大多数图表的 valueFormat 支持以下占位符：

Scatter 额外支持 {x}、{y}，Bubble 额外支持 {x}、{y}、{r}。

更新数据与动画

图表由 model 驱动。数据变化时重新生成 model，并替换绑定对象。不要长期原地修改旧 model 的深层字段。

import { ref } from 'vue'
import type {
  HansChartAnimation,
  HansLineChartModel,
  HansLineModelFromValuesOptions
} from '@/uni_modules/hans-charts'
import { createLineModelFromValues } from '@/uni_modules/hans-charts'

const options: HansLineModelFromValuesOptions = {
  labels: ['周一', '周二', '周三'],
  seriesName: '访问量'
}

const chartModel = ref<HansLineChartModel>(
  createLineModelFromValues([32, 48, 61], options)
)

const animation = ref<HansChartAnimation>({
  enabled: true,
  duration: 450,
  replayKey: 0
})

function replaceValues(values: number[]): void {
  chartModel.value = createLineModelFromValues(values, options)
  animation.value = {
    enabled: true,
    duration: 450,
    replayKey: animation.value.replayKey + 1
  }
}

模板中绑定 :animation="animation"。replayKey 变化时会重新播放动画；duration 必须大于 0。未传 animation 时，默认启用约 700ms 的首次渲染动画。

交互

未传 interaction 时，默认开启 tooltip 和 selection，关闭 range selection：

const interaction: HansChartInteraction = {
  tooltip: true,
  selection: true,
  rangeSelection: false
}

开启 rangeSelection 后，拖动手势优先用于区间选择。支持区间选择的图表包括 line family、bar family、histogram、waterfall、candlestick 和 OHLC；其他图表使用数据项直接命中。

事件 Payload

item 的类型为 HansChartEventItem，包含 chartType、seriesId、seriesIndex、dataId、dataIndex、label、value 和 color。金融图表使用 visibleWindow 时，事件中的 dataIndex 仍是原始行情数组索引。

图例

<hans-chart-legend> 只负责展示和点击事件，不会自动隐藏或显示系列。业务侧需要根据点击结果生成新的 model。

<hans-chart-legend
  :items="legendItems"
  direction="horizontal"
  marker-shape="line"
  appearance="light"
  @item-tap="onLegendItemTap"
/>

Legend Helper

当 model 或 palette 变化时，应重新调用对应 resolver 生成图例，确保图例颜色与图表一致。

图表摘要

resolve*ChartSummary helper 可以根据 model 生成稳定的文本摘要，适合用于无障碍说明、业务概览、日志或快照。摘要只读取 model，不会修改图表状态。

import { resolveLineChartSummary } from '@/uni_modules/hans-charts'

const chartSummary: string = resolveLineChartSummary(chartModel)

可用 helper：

外观与颜色

import type {
  HansChartPalette,
  HansFinanceStyle
} from '@/uni_modules/hans-charts'

const palette: HansChartPalette = {
  colors: ['#3F7DED', '#22A8A3', '#E8A03A', '#D85C96']
}

const financeStyle: HansFinanceStyle = {
  riseColor: '#39A96B',
  fallColor: '#E2685E',
  markerBuyColor: '#39A96B',
  markerSellColor: '#E2685E',
  markerEventColor: '#3F7DED'
}

颜色支持 hex、rgb() 和 rgba()。也可以使用 createHansDefaultPalette() 和 createHansDefaultFinanceStyle() 获取默认配置。

金融图表

Candlestick 和 OHLC 使用相同的数据行格式：[open, high, low, close, volume?]。也可以通过 options 的 volumes 单独传入成交量。

import type {
  HansCandlestickChartModel,
  HansCandlestickModelFromValuesOptions
} from '@/uni_modules/hans-charts'
import {
  HANS_CANDLESTICK_INDICATOR_SMA,
  HANS_CANDLESTICK_MARKER_BUY,
  HANS_CANDLESTICK_MARKER_EVENT,
  HANS_CANDLESTICK_MARKER_SELL,
  createCandlestickModelFromValues
} from '@/uni_modules/hans-charts'

const rows: number[][] = [
  [106, 112, 103, 109, 18200],
  [109, 114, 105, 108, 17600],
  [108, 118, 107, 116, 21100],
  [116, 120, 112, 117, 19800]
]

const options: HansCandlestickModelFromValuesOptions = {
  title: '价格走势',
  labels: ['05/20', '05/21', '05/22', '05/23'],
  movingAverages: [
    { period: 3, color: '#7A6FF0', label: 'MA3' }
  ],
  indicatorOverlays: [
    {
      kind: HANS_CANDLESTICK_INDICATOR_SMA,
      period: 3,
      color: '#39A96B',
      label: 'SMA3'
    }
  ],
  markers: [
    { candleIndex: 0, label: '买入', kind: HANS_CANDLESTICK_MARKER_BUY, color: null },
    { candleIndex: 2, label: '卖出', kind: HANS_CANDLESTICK_MARKER_SELL, color: null },
    { candleIndex: 3, label: '公告', kind: HANS_CANDLESTICK_MARKER_EVENT, color: '#5E73E8' }
  ],
  visibleWindow: { startIndex: 0, endIndex: 3 },
  valueFormat: '{label}: {value}'
}

const model: HansCandlestickChartModel = createCandlestickModelFromValues(
  rows,
  options
)

买入/卖出/事件交易标记通过 candlestick/OHLC 的 markers 表达，只渲染当前 visibleWindow 内的标记。可用指标常量包括 SMA、EMA、Bollinger、RSI 和 MACD；指标始终基于完整行情历史计算，再按窗口裁剪显示。

常用金融 helper：

指标 helper 返回的预热区间可能包含 null。createFinance*ModelFromSeries 会跳过这些预热值，并保持标签与原始行情索引对齐。

<hans-chart> API

Props

Events

<hans-chart-legend> API

Props

Events

常见问题

提示“uts插件[hans-charts]不存在”

加密试用版属于 UTS 原生插件。首次导入或升级插件后，需要重新打包自定义基座，并在运行配置中选择新基座。继续使用标准基座或旧自定义基座时，基座内没有当前版本的插件，会出现该提示。

图表空白

先检查宿主容器是否有明确宽高，并避免在高度为 0 或尚未展开的容器中挂载组件。异步数据未准备好时，可以先不挂载 <hans-chart>，等 model 创建完成后再通过 v-if 显示。

数据更新后没有重新播放动画

替换 model 的同时递增 animation.replayKey。只更新 model 会重绘图表，但不会重复已经播放过的入场动画。

图表构建失败

设置 :debug="true" 并监听 render-debug，优先查看 failureCode 和 failureMessage。常见原因包括：model 缺少必填字段、数据中包含非有限数值、金融 OHLC 顺序非法、颜色格式不受支持，或 animation.duration <= 0。

Line、Bar、Pie 的空数据会被视为无效 model。异步列表尚未返回时，建议先展示业务侧空态或 loading，拿到有效数据后再创建并挂载图表。

真机正常但浏览器不显示

该插件当前支持 uni-app x App Android、iOS 和 HarmonyOS，不支持 Web 或小程序预览。请运行到已支持的 App 平台验证。