# @dschz/solid-uplot 中文文档 规范地址：https://npmcn.com/package/%40dschz/solid-uplot/ 版本：0\.5\.2 npm 元数据更新时间：2026-02-04T15:48:22.738Z 中文译文更新时间：2026-11-12T22:28:46.176Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40dschz/solid-uplot 原文对照：https://npmcn.com/package/%40dschz/solid-uplot/?lang=original 项目主页：https://github.com/dsnchz/solid-uplot#readme 源码仓库：https://github.com/dsnchz/solid-uplot ## 关键信息（来自 npm 元数据） - 包体积（解压后）：76.7 kB，13 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：solid-js \>=1\.6\.0，uplot \>=1\.6\.32 - 首次发布：2025-05-27T18:28:10.794Z - 最新版本发布：2026-02-04T15:48:22.604Z - 近 30 天下载量：3861（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：14（近 12 个月 5 个） ## 中文简介 用于 uPlot 的 SolidJS 包装器 — 超快, 极小的时间序列和图表库 ## 安装 ```sh npm install @dschz/solid-uplot ``` 也可以使用：`pnpm add @dschz/solid-uplot`、`yarn add @dschz/solid-uplot`、`bun add @dschz/solid-uplot` ## README ![@dschz/solid-uplot banner](https://assets.solidjs.com/banner?project=solid-uplot&type=Ecosystem&background=tiles) # @dschz/ 固态升起 [![License](https://img.shields.io/badge/license-MIT-green)](https://npmcn.com/package/%40dschz/solid-uplot/LICENSE) [![uPlot](https://img.shields.io/badge/uPlot-%3E%3D1.6.32-orange)](https://github.com/leeoniya/uPlot) [![npm](https://img.shields.io/npm/v/@dschz/solid-uplot?color=blue)](https://www.npmjs.com/package/@dschz/solid-uplot) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/@dschz/solid-uplot)](https://bundlephobia.com/package/@dschz/solid-uplot) [![JSR](https://jsr.io/badges/@dschz/solid-uplot/score)](https://jsr.io/@dschz/solid-uplot) [![CI](https://github.com/dsnchz/solid-uplot/actions/workflows/ci.yaml/badge.svg)](https://github.com/dsnchz/solid-uplot/actions/workflows/ci.yaml) [![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white)](https://discord.gg/6wkpXQCNn6) > 固态JS包装器 [uPlot 地图](https://github.com/leeoniya/uPlot) ——用于时间序列数据的超快小脚印图库. ## \* 特性 - uPlot周围的全反应固体JS包装器 - 插件系统支持与插件间通信 - 对图表生命周期的精细控制 - 轻而易举 - 框外的 QQ 类型脚本支持 - QQ 用于工具提示、 传说、 光标跟踪和系列焦点的内置插件 - \* 以自动调整规模的能力响应规模支持 ## \* 安装 ```bash npm install solid-js uplot @dschz/solid-uplot pnpm install solid-js uplot @dschz/solid-uplot yarn install solid-js uplot @dschz/solid-uplot bun install solid-js uplot @dschz/solid-uplot ``` ## 现场直播 这艘反转船有一个 **直播,操场** ——全面展示图书馆每个特色. 这是最快的方法 `solid-uplot` 并探索图表、插件、响应大小和外部集成等真实的、可行的实例. ### 运行游戏场 ```bash git clone https://github.com/dsnchz/solid-uplot.git cd solid-uplot # Install dependencies bun install # Start the playground bun start ``` 游乐场运行在 `http://localhost:3000` 并包括交互式演示: - 所有内置插件( 曲线、 工具提示、 传说、 焦点系列) - 响应和自动调整图型 - 自定义插件开发 - 通过插件总线进行外部组件集成 ## QQ 软件包结构 这个软件包为不同的功能提供了三个主要导出路径: ### `@dschz/solid-uplot` 核心组件和插件系统 : ```tsx import { SolidUplot, createPluginBus } from "@dschz/solid-uplot"; import type { SolidUplotPluginBus, UplotPluginFactory, UplotPluginFactoryContext, } from "@dschz/solid-uplot"; ``` ### `@dschz/solid-uplot/plugins` 此导出路径提供了四个插件(其中三个可以被认为是原始的). - `cursor`: 传送光标位置数据 - `focusSeries`: 传送在视觉上强调的系列 - `tooltip`: 允许您在光标周围显示自定义 JSX 工具提示的插件 - `legend`: 插件, 允许您在画布绘制区域上将自定义 JSX 组件作为您的传说 . ```tsx import { cursor, tooltip, legend, focusSeries } from "@dschz/solid-uplot/plugins"; import type { CursorPluginMessageBus, FocusSeriesPluginMessageBus, TooltipProps, LegendProps, } from "@dschz/solid-uplot/plugins"; ``` ### `@dschz/solid-uplot/utils` 从 a 获取某些位点数据的便利工具函数 `uPlot` 实例(除 `getColorString` 翻译系列 `stroke` 或者说 `fill` 输入颜色值). ```tsx import { getSeriesData, getCursorData, getColorString, getNewCalendarDayIndices, } from "@dschz/solid-uplot/utils"; import type { SeriesDatum, CursorData } from "@dschz/solid-uplot/utils"; ``` ## QQ 快速启动 ```tsx import { SolidUplot, createPluginBus } from "@dschz/solid-uplot"; import { cursor, tooltip, legend } from "@dschz/solid-uplot/plugins"; import type { CursorPluginMessageBus, TooltipProps, LegendProps } from "@dschz/solid-uplot/plugins"; // Create a tooltip component const MyTooltip = (props: TooltipProps) => (
X: {props.cursor.xValue}
{(series) => { const value = props.u.data[series.seriesIdx]?.[props.cursor.idx]; return (
{series.label}: {value}
); }}
); // Create a legend component const MyLegend = (props: LegendProps) => (
{(series) => (
{series.label}
)}
); const MyChart = () => { const bus = createPluginBus(); return ( ); }; ``` ## 响应大小 对于自动适应容器大小变化的响应性图表,使用 `autoResize` 道具 : ```tsx
``` 对于更先进的响应模式,您可以将这个库与 [@dschz/ 固态自动喷雾器](https://github.com/dsnchz/solid-auto-sizer)数字 : ```bash npm install @dschz/solid-auto-sizer pnpm install @dschz/solid-auto-sizer yarn install @dschz/solid-auto-sizer bun install @dschz/solid-auto-sizer ``` ```tsx import { AutoSizer } from "@dschz/solid-auto-sizer"; {({ width, height }) => } ; ``` 或者,你可以使用 [`createElementSize`](https://github.com/solidjs-community/solid-primitives/tree/main/packages/resize-observer) 从 `@solid-primitives/resize-observer` 基于信号的方法: ```bash npm install @solid-primitives/resize-observer ``` ```tsx import { createElementSize } from "@solid-primitives/resize-observer"; const ResponsiveChart = () => { let container!: HTMLDivElement; const size = createElementSize(() => container); return (
); }; ``` ## 增强插件系统 其基本特征是: `SolidUplot` 是其精细的插件系统,通过反应性消息总线,能够扩展功能并进行插件间通信. ### 插件总线架构 插件总线系统使插件能够通过反应存储器相互和外部组件通信. 这一架构提供: - **安全型通信**: 所有插件信件已全部输入 - **反应更新**: 插件状态的变化自动触发更新 - **脱钩组件**: 插件可以在没有直接依赖的情况下相互作用 - **广泛**: 方便添加与现有插件相融合的新插件 ### 内置插件 #### 光标插件 跟踪光标位置和跨图表的交互状态: ```tsx import { cursor } from "@dschz/solid-uplot/plugins"; import type { CursorPluginMessageBus } from "@dschz/solid-uplot/plugins"; const cursorPlugin = cursor(); ``` 光标插件提供光标位置数据,其他插件可以通过总线消耗. #### 焦点系列插件 基于光标相近性的突出显示系列 : ```tsx import { focusSeries } from "@dschz/solid-uplot/plugins"; import type { FocusSeriesPluginMessageBus } from "@dschz/solid-uplot/plugins"; const focusPlugin = focusSeries({ pxThreshold: 15, // Distance threshold for focusing (default: 15) }); ``` #### 工具提示插件 装有自动定位和外溢处理的自定义工具提示: ```tsx import { tooltip } from "@dschz/solid-uplot/plugins"; import type { TooltipProps } from "@dschz/solid-uplot/plugins"; const MyTooltip: Component = (props) => { return (
X: {props.cursor.xValue}
{(series) => { const value = () => props.u.data[series.seriesIdx]?.[props.cursor.idx]; return (
{series.label}: {value()?.toFixed(2)}
); }}
); }; const tooltipPlugin = tooltip(MyTooltip, { placement: "top-left", // "top-left" | "top-right" | "bottom-left" | "bottom-right" zIndex: 20, }); ``` #### 图例插件 添加具有智能定位和交互特性的自定义的传说 : ```tsx import { legend } from "@dschz/solid-uplot/plugins"; import type { LegendProps } from "@dschz/solid-uplot/plugins"; const MyLegend: Component = (props) => { // Access cursor data for interactive features const cursorVisible = () => props.bus.data.cursor?.state[props.u.root.id]?.visible; return (
Legend
{(series) => (
{series.label}
)}
); }; const legendPlugin = legend(MyLegend, { placement: "top-left", // "top-left" | "top-right" pxOffset: 8, // Distance from chart edges (default: 8) zIndex: 10, }); ``` **图例插件特征 :** - **简单定位**: 只有左上或右上角避免轴冲突 - **大小限制**: 图例不能超过图表绘图区域维度 - **布局不可知**: 控制内部布局和样式 - **非干涉**: 设计与图表互动和谐工作 - **插件总线集成**: 获取光标和焦点数据进行智能互动 - **自动清理**: 适当的内存管理和DOM清理 ### 插件总线类型安全 在使用多个插件时,通过正确打入插件总线确保类型安全: ```tsx import { createPluginBus } from "@dschz/solid-uplot"; import type { CursorPluginMessageBus, FocusSeriesPluginMessageBus, } from "@dschz/solid-uplot/plugins"; // Create a bus that includes all plugin message types const bus = createPluginBus(); const MyChart = () => { return ( ); }; ``` ### 创建自定义插件 插件系统可扩展。 编写用于公共消费的插件时,遵循此模式: ```tsx import type { UplotPluginFactory } from "@dschz/solid-uplot"; import type { CursorPluginMessageBus } from "@dschz/solid-uplot/plugins"; // 1. Define your plugin's message type export type MyPluginMessage = { value: number; timestamp: number; }; // 2. Define your plugin's message bus export type MyPluginMessageBus = { myPlugin?: MyPluginMessage; }; // 3. Export your plugin factory export const myPlugin = ( options = {}, ): UplotPluginFactory => { return ({ bus }) => { if (!bus) { console.warn("[my-plugin]: A plugin bus is required"); return { hooks: {} }; } return { hooks: { ready: (u) => { // Initialize plugin state bus.setData("myPlugin", { value: 0, timestamp: Date.now(), }); }, setData: (u) => { // Update plugin state bus.setData("myPlugin", "value", (prev) => prev + 1); }, }, }; }; }; ``` ### 外部构成部分 插件总线可以在图表和外部组件之间实现强大的集成: ```tsx import { createPluginBus } from "@dschz/solid-uplot"; import type { FocusSeriesPluginMessageBus } from "@dschz/solid-uplot/plugins"; const bus = createPluginBus(); // External component that can trigger series focus const DataGrid = (props: { bus: typeof bus }) => { const handleRowHover = (seriesLabel: string) => { props.bus.setData("focusSeries", { sourceId: "data-grid", targets: [{ label: seriesLabel }], }); }; return {/* Grid implementation */}
; }; // Chart and grid interact through shared bus const MyDashboard = () => { return (
); }; ``` ## API 参考 ### SolidUplot 组件 ```tsx type SolidUplotEvents = { /** Callback fired when the uPlot instance is created */ readonly onCreate?: (u: uPlot, meta: OnCreateMeta) => void; /** Callback fired when the cursor moves */ readonly onCursorMove?: (params: OnCursorMoveParams) => void; }; // Main component props (extends all uPlot.Options except plugins, width, height) type SolidUplotProps = SolidUplotOptions & SolidUplotEvents & { // Ref callback to access the chart container element ref?: Ref; // CSS class name for the chart container (default: "solid-uplot") // Additional classes will be appended to the default class class?: string; // CSS styles for the chart container (position is managed internally) style?: Omit; // Enable automatic resizing to fit container (default: false) autoResize?: boolean; // Whether to reset scales when chart data is updated (default: true) resetScales?: boolean; // Where to place children components relative to the chart (default: "top") childrenPlacement?: "top" | "bottom"; }; // Configuration options extending uPlot.Options with SolidJS enhancements type SolidUplotOptions = Omit< uPlot.Options, "plugins" | "width" | "height" > & { // Chart dimensions width?: number; // default: 600 height?: number; // default: 300 // Plugin configuration plugins?: SolidUplotPlugin[]; pluginBus?: SolidUplotPluginBus; }; // Plugin type (can be standard uPlot plugin or factory function) type SolidUplotPlugin = uPlot.Plugin | UplotPluginFactory; ``` ### 插件总线 ```tsx // Plugin bus type (derived from createPluginBus return type) type SolidUplotPluginBus = ReturnType>; // Create a plugin bus const createPluginBus: ( initialData?: T, ) => SolidUplotPluginBus; ``` ### 内建插件选项 ```tsx // Cursor Plugin const cursor = (): UplotPluginFactory; // Focus Series Plugin const focusSeries = (options?: { pxThreshold?: number; // default: 15 }): UplotPluginFactory; // Tooltip Plugin const tooltip = ( Component: Component, options?: { placement?: "top-left" | "top-right" | "bottom-left" | "bottom-right"; id?: string; class?: string; style?: JSX.CSSProperties; zIndex?: number; // default: 20 } ): UplotPluginFactory; // Legend Plugin const legend = ( Component: Component, options?: { placement?: "top-left" | "top-right"; // default: "top-left" pxOffset?: number; // default: 8 id?: string; class?: string; style?: JSX.CSSProperties; zIndex?: number; // default: 10 } ): UplotPluginFactory; ``` ## 实例 ### 基本图表 ```tsx import { SolidUplot } from "@dschz/solid-uplot"; const BasicChart = () => { return ( ); }; ``` ### 带有全部插件的图表 ```tsx import { SolidUplot, createPluginBus } from "@dschz/solid-uplot"; import { cursor, tooltip, legend, focusSeries } from "@dschz/solid-uplot/plugins"; import type { CursorPluginMessageBus, FocusSeriesPluginMessageBus, TooltipProps, LegendProps, } from "@dschz/solid-uplot/plugins"; const MyTooltip: Component = (props) => (
Time: {new Date(props.cursor.xValue * 1000).toLocaleTimeString()}
{(series) => { const value = props.u.data[series.seriesIdx]?.[props.cursor.idx]; return (
{series.label}: {value?.toFixed(2)}
); }}
); const MyLegend: Component = (props) => { const cursorVisible = () => props.bus.data.cursor?.state[props.u.root.id]?.visible; return (
{(series) => (
{series.label}
)}
); }; const FullFeaturedChart = () => { const bus = createPluginBus(); return ( ); }; ``` ### 响应图表 ```tsx const ResponsiveChart = () => { return (
); }; ``` ### 外部一体化 ```tsx const Dashboard = () => { const bus = createPluginBus(); const handleSeriesToggle = (seriesLabel: string) => { bus.setData("focusSeries", { sourceId: "external-control", targets: [{ label: seriesLabel }], }); }; return (
); }; ``` ## 捐款 欢迎捐款! 请随意提交拉力请求. 还有看 [解析器](https://discord.gg/6wkpXQCNn6) 社区. ## 许可证 麻省理工学院 ## 常见问题 ### @dschz/solid-uplot 是什么？ 用于 uPlot 的 SolidJS 包装器 — 超快, 极小的时间序列和图表库 ### 如何安装 @dschz/solid-uplot？ 在项目目录运行 npm install @dschz/solid-uplot，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：solid-js（\>=1\.6\.0）、uplot（\>=1\.6\.32）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @dschz/solid-uplot 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @dschz/solid-uplot 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @dschz/solid-uplot 可以商用吗？ @dschz/solid-uplot 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @dschz/solid-uplot 的下载量有多少？ 根据 npm 官方下载统计，@dschz/solid-uplot 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,861 次，日均约 129 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @dschz/solid-uplot 还在维护吗？ 最新版本 0\.5\.2 发布于 2026/02/04（9 个月前）；至今共发布 14 个版本，其中过去 12 个月发布了 5 个；首次发布于 2025/05/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。