react-d3-speedometer

授权协议 MIT License
开发语言 JavaScript
所属分类 Web应用开发、 常用JavaScript包
软件类型 开源软件
地区 不详
投 递 者 欧阳博文
操作系统 跨平台
开源组织
适用人群 未知
 软件概览

react-d3-speedometer

React library for showing speedometer like gauge using d3.

react-d3-speedometer

Note: v1.x is compatible with React 17. Please use latest v0.x (v0.14.1 at the time of writing) if you are using React 16.

react-d3-speedometer

Getting Started:

Install with yarn or npm.

Yarn:

yarn add react-d3-speedometer

npm:

npm install --save react-d3-speedometer

And, use it like

// import the component
import ReactSpeedometer from "react-d3-speedometer"
// and just use it
<ReactSpeedometer />

Live Examples

Configuration Options:

prop type default comments
value Number 0 Make sure your value is between your minValue and maxValue
minValue Number 0
maxValue Number 1000
segments Number 5 Number of segments in the speedometer. Please note, segments is calculated with d3-ticks which is an approximate count that is uniformly spaced between min and max. Please refer to d3-ticks and d3-array ticks for more detailed info.
maxSegmentLabels Number value from 'segments' prop Limit the number of segment labels to displayed. This is useful for acheiving a gradient effect by giving arbitrary large number of segments and limiting the labels with this prop. See Live Example. Please note, maxSegmentLabels is calculated with d3-ticks which is an approximate count that is uniformly spaced between min and max. Please refer to d3-ticks and d3-array ticks for more detailed info.
forceRender Boolean false After initial rendering/mounting, when props change, only the value is changed and animated to maintain smooth visualization. But, if you want to force rerender the whole component like change in segments, colors, dimensions etc, you can use this option to force rerender of the whole component on props change.
width Number 300 diameter of the speedometer and the width of the svg element
height Number 300 height of the svg element. Height of the speedometer is always half the width since it is a semi-circle. For fluid width, please refere to fluidWidth config
dimensionUnit String px Default to px for width/height. Possible values - "em" , "ex" , "px" , "in" , "cm" , "mm" , "pt" , ,"pc" ... Please refer to specification for more details
fluidWidth Boolean false If true takes the width of the parent component. See Live Example for more details
needleColor String steelblue Should be a valid color code - colorname, hexadecimal name or rgb value. Should be a valid input for d3.interpolateHsl
startColor String #FF471A Should be a valid color code - colorname, hexadecimal name or rgb value. Should be a valid input for d3.interpolateHsl
endColor String #33CC33 Should be a valid color code - colorname, hexadecimal name or rgb value. Should be a valid input for d3.interpolateHsl
segmentColors Array (of colors) [] Custom segment colors can be given with this option. Should be an array of valid color codes. If this option is given startColor and endColor options will be ignored.
needleTransition String (JS) / Transition (TS) easeQuadInOut d3-easing-identifiers - easeLinear, easeQuadIn, easeQuadOut, easeQuadInOut, easeCubicIn, easeCubicOut, easeCubicInOut, easePolyIn, easePolyOut, easePolyInOut, easeSinIn, easeSinOut, easeSinInOut, easeExpIn, easeExpOut, easeExpInOut, easeCircleIn, easeCircleOut, easeCircleInOut, easeBounceIn, easeBounceOut, easeBounceInOut, easeBackIn, easeBackOut, easeBackInOut, easeElasticIn, easeElasticOut, easeElasticInOut, easeElastic. There is a helper Object/Type 'Transtion', which you can import like import { Transition } from 'react-d3-speedometer' and use it like Transition.easeElastic. This works for both JS and Typescript. For type(script) definitions, please refer here.
needleTransitionDuration Number 500 Time in milliseconds.
needleHeightRatio Float (between 0 and 1) 0.9 Control the height of the needle by giving a number/float between 0 and 1. Default height ratio is 0.9.
ringWidth Number 60 Width of the speedometer ring.
textColor String #666 Should be a valid color code - colorname, hexadecimal name or rgb value. Used for both showing the current value and the segment values
valueFormat String should be a valid format for d3-format. By default, no formatter is used. You can use a valid d3 format identifier (for eg: d to convert float to integers), to format the values. Note: This formatter affects all the values (current value, segment values) displayed in the speedometer
currentValueText String ${value} Should be provided a string which should have ${value} placeholder which will be replaced with current value. By default, current value is shown (formatted with valueFormat). For example, if current Value is 333 if you would like to show Current Value: 333, you should provide a string Current Value: ${value}. See Live Example
currentValuePlaceholderStyle String ${value} Should be provided a placeholder string which will be replaced with current value in currentValueTextProp. For example: you can use ruby like interpolation by giving following props - <ReactSpeedometer currentValueText="Current Value: #{value}" currentValuePlaceholderStyle={"#{value}"} />. This is also helpful if you face no-template-curly-in-string eslint warnings and would like to use different placeholder for current value
customSegmentStops Array [] Array of values starting at min value, and ending at max value. This configuration is useful if you would like to split the segments at custom points or have unequal segments at preferred values. If the values does not begin and end with min and max value respectively, an error will be thrown. This configuration will override segments prop, since total number of segments will be length - 1 of customSegmentProps. For example, [0, 50, 75, 100] value will have three segments - 0-50, 50-75, 75-100. See Live Example
customSegmentLabels Array<CustomSegmentLabel> [] Takes an array of CustomSegmentLabel objects. Each object has following keys for custom rendering of labels - text, fontSize, color, position: OUTSIDE/INSIDE. For position, there is a helper CustomSegmentLabelPosition Object/Type which you can import like import { CustomSegmentLabelPosition } from 'react-d3-speedometer', and use it like CustomSegmentLabelPosition.Inside / CustomSegmentLabelPosition.Outside. This works for both JS and Typescript. For type(script) definitions, please refer here.
labelFontSize String 14px Font size for segment labels/legends
valueTextFontSize String 16px Font size for current value text
valueTextFontWeight String bold Font weight for current value text. Any valid font weight identifier (500, bold etc) can be used.
paddingHorizontal Number 0 Provides right/left space for the label text. Takes a number (without explicit unit, unit will be taken from dimensionUnit config which defaults to px). Helpful when using a bigger font size for label texts.
paddingVertical Number 0 Provides top/bottom space for the current value label text below the needle. Takes a number (without explicit unit, unit will be taken from dimensionUnit config which defaults to px). Helpful when using a bigger font size for label texts.

Examples

You can view Live Examples here

Default with no config - Live Example

<ReactSpeedometer />

With configurations - Live Example

<ReactSpeedometer
  maxValue={500}
  value={473}
  needleColor="red"
  startColor="green"
  segments={10}
  endColor="blue"
/>

Custom Segment Colors - Live Example

<ReactSpeedometer
  value={333}
  segments={5}
  segmentColors={[
    "#bf616a",
    "#d08770",
    "#ebcb8b",
    "#a3be8c",
    "#b48ead",
  ]}
  // startColor will be ignored
  // endColor will be ignored
/>

Custom Segment Labels - Live Example

// 'customSegmentLabels' prop takes an array of 'CustomSegmentLabel' Object
  /*
  type CustomSegmentLabel = {
    text?: string
    position?: OUTSIDE/INSIDE
    fontSize?: string
    color?: string
  }
  */

  <ReactSpeedometer
    value={777}
    currentValueText="Happiness Level"
    customSegmentLabels={[
      {
        text: "Very Bad",
        position: "INSIDE",
        color: "#555",
      },
      {
        text: "Bad",
        position: "INSIDE",
        color: "#555",
      },
      {
        text: "Ok",
        position: "INSIDE",
        color: "#555",
        fontSize: "19px",
      },
      {
        text: "Good",
        position: "INSIDE",
        color: "#555",
      },
      {
        text: "Very Good",
        position: "INSIDE",
        color: "#555",
      },
    ]}
  />

Custom Segment Stops - Live Example

<ReactSpeedometer
    customSegmentStops={[0, 500, 750, 900, 1000]}
    segmentColors={["firebrick", "tomato", "gold", "limegreen"]}
    value={333}
  />
  // `segments` prop will be ignored since it will be calculated from `customSegmentStops`
  // In this case there will be `4` segments (0-500, 500-750, 750-900, 900-1000)
/>

Fluid Width Example - Live Example

// Speedometer will take the width of the parent div (500)
// any width passed will be ignored
<div style={{
  width: "500px",
  height: "300px",
  background: "#EFEFEF"
}}>
  <ReactSpeedometer
    fluidWidth={true}
    minValue={100}
    maxValue={500}
    value={473}
    needleColor="steelblue"
  />
</div>

Needle Transition Example - Live Example

<ReactSpeedometer
  value={333}
  needleColor="steelblue"
  needleTransitionDuration={4000}
  needleTransition="easeElastic"
/>

Force Render component on props change - Live Example

// By default, when props change, only the value prop is updated and animated. 
// This is to maintain smooth visualization and to ignore breaking appearance changes like segments, colors etc. 
// You can override this behaviour by giving forceRender: true

// render a component initially
<ReactSpeedometer
  width={200}
  height={200}
/>
// Now, if given forceRender: true, and change the appearance all together, the component will rerender completely on props change
<ReactSpeedometer
  forceRender={true}
  segments={15}
  width={500}
  height={500}
/>

Needle Height Configuration Example - Live Example

<ReactSpeedometer
  value={333}
  needleHeightRatio={0.7}
/>

You can give a value between 0 and 1 to control the needle height.

Gradient Like Effect - Live Example

<ReactSpeedometer
  value={333}
  maxSegmentLabels={5}
  segments={1000}
/>

FAQ:

  1. How to use with nextjs?

    react-d3-speedometer uses lodash-es dependency for better tree shaking. For nextjs, please use next-transpile-modules, so that ES module exports from lodash-es package is properly transpiled.

  2. How to use with React 17?

    Please use latest v1.x (v1.0.0 at the time of writing). v1.x is compatible with React 17.

  3. How to use with React 16?

    Please use latest v0.x (v0.14.x at the time of writing). v0.x is compatible with React 16.


Ports:


Todos:

  • Test coverage (with enzyme)
  • Convert entire code base to ES6
  • Split core from lifecycles
  • Typescript support

Tests:

react-d3-speedometer comes with a test suite using enzyme.

// navigate to root folder and run
npm test
// or 'yarn test' if you are using yarn

Feature Updates:

  • [v1.0.0] React v17 support. d3 v6 support. Live Example

  • [v0.14.0] valueTextFontWeight config to control font weight of current value

  • [v0.10.0] Custom labels. Live Example

  • [v0.9.0] Typescript support

  • [v0.8.0] paddingHorizontal, paddingVertical configuration to control spacing around text. Live Example

  • [v0.7.0] Custom segment stops. Live Example

  • [v0.6.0] Custom segment colors. Live Example


Changelog:

View Changelog


Credits:

react-d3-speedometer was started as a react port of the following d3 snippet - http://bl.ocks.org/msqr/3202712. Component template was initially bootstrapped with React CDK. Also, many thanks to react and d3 ecosystem contributors.


Contributing:

PRs are welcome. Please create a issue/bugfix/feature branch and create an issue with your branch details. Probably I will create a similar branch in the upstream repo so that PRs can be raised against that branch instead of master. master-v0.x is the main branch for React 16 compatible changes.

Notes

  • 1.x versions are compatible with React & React DOM Versions v17.x
  • 0.x versions are compatible with React & React DOM Versions v16.xFor every subsequent major react upgrade, react-d3-speedometer will be bumped to next major versions. For example 1.x will be compatible with React 17.x so on and so forth ...

For similar library for VueJS, please check out vue-speedometer.

For similar library for Svelte, please check out svelte-speedometer.

License:

MIT

 相关资料
  • 视图移动以及缩放是一种将用户注意力聚焦在感兴趣区域的一种流行的交互技术。操作直接,容易理解: 点击并拖拽平移,使用滚轮进行缩放,当然也可以通过触摸进行。平移和缩放被广泛的应用在地图中,但是也可被应用到其他的可视化比如时间序列以及散点图中。 缩放行为通过 d3-zoom 模块实现,能方便且灵活到 selections 上。它处理了许多 Installing NPM 安装: npm install d

  • 这个模块实现了用来计算一组二维点 Voronoi diagram(泰森多边形) 或 Delaunay triangulation(德劳内三角剖分) 的 Steven J. Fortune’s algorithm 算法。这个模块的实现大多是基于 Raymond Hill 的工作。 泰森多边形不仅仅在视觉上具有吸引力,在交互方面也非常实用,比如在散点图中增加点的目标面积。参考 “Strikeouts

  • transition 是一个类 selection 的接口,用来对 DOM 进行动画修改。这种修改不是立即修改,而是在规定的事件内平滑过渡到目标状态。 应用过渡,首先要选中元素,然后调用 selection.transition,并且设置期望的改变,例如: d3.select("body") .transition() .style("background-color", "red")

  • 这个模块提供了一个高效的队列,能管理上千并发动画同时保证与并发或分段动画一致的同步时序。在内部使用 requestAnimationFrame 进行 fluid animation(如果支持的话),否则切换使用 setTimeout来实现。 Installing NPM 安装: npm install d3-timer. 此外还可以下载 latest release。也可以直接从 d3js.org

  • 在可视化时间序列数据、分析时间模式或处理一般时间时,常规时间单位的不规则性很快就变得明显起来。在 Gregorian calendar(公历) 中,大多数月份有 31 天但是有些月份只有 28 或者 29、30 天。大多数年份有 365 天但是 leap years(闰年) 有 366 天。在 daylight saving(夏令时) 中一天可能有 23 25 小时。更复杂的是世界各地的夏时制不同

  • 可视化通常由离散图形标记组成, 比如 symbols, arcs, lines 和 areas。虽然条形的矩形可以很容易的使用 SVG 或者 Canvas 来生成, 但是其他的比如圆形的扇形以及向心 Catmull-Rom 样条曲线就很复杂。这个模块提供了许多图形生成器以便使用。 与 D3 的其他特性一样,这些图形也是又数据驱动的: 每个图形生成器都暴露了一个如何将数据映射到可视化表现的访问器。例