NumFlop

An express deition number flip animation library by canvas.

it can be used on any web packag, what ever react or vue.

Next I will improve it:

1.add prefix and suffix.

2.this packag can accept num or img.

3.I will complete the document.

if you have any question, pelease send email to [email protected]..

use

import { useEffect, useRef } from "react";
import NumFlop from "num-flop";
import { option } from "./numFlop/flopData";
import { getRandomNum } from "./numFlop/tool";

const Index = () => {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const value = 123456;
  const numflopInst = useRef<NumFlop | null>(null);

  useEffect(() => {
    if (!canvasRef.current) {
      return;
    }

    numflopInst.current = new NumFlop(canvasRef.current, option, value);

    setInterval(() => {
      const number = getRandomNum(10001, 99999);
      // console.log("number---", number);
      if (numflopInst.current) numflopInst.current.setNum(number);
    }, 18000);
  }, []); // eslint-disable-line

  return <canvas ref={canvasRef} style={{ background: "black" }} />;
};

export default Index; 

numFlop

NumFlop Usage Guide

This document explains how to use the Canvas flip-card component found in src/numberFlop/: what to pass in, which fields are required vs optional, and how they relate to the text / mixin / option in flopData.ts.

1. Which configuration should you use?

| Object | Can it be passed to new NumFlop(canvas, options, num)? | Notes | |------|-----------------------------------------------|------| | text / mixin (see flopData.ts) | Yes | Contains attr and config, consistent with current implementation. | | option (only global + font) | No | Lacks config / attr and will throw at runtime. |

Below, “configuration” refers to a full screen object like text, or any object you construct that follows the same structure.

2. Minimal usage steps

1. Prepare a <canvas> DOM node.
2. Prepare a complete options object (you can import { text } from "./numberFlop/flopData" and adjust attr.width, etc.).
3. const app = new NumFlop(canvas, options, 12345).
4. Update the number: app.setNum(99999).
5. Replace skin/layout: app.setOptions(newOptions).

3. Configuration tree and required/optional overview

The implementation reads these paths directly: options.attr, options.config (and its global, prefix, suffix, flop). Other top-level fields (like alias, dataConfig, code) are business metadata and are not required by the flip logic; keep or omit them as you like (provided other code doesn’t expect them).

3.1 Top-level

| Field | Required? | Notes | |------|:------:|------| | config | Required | Contains global alignment, prefix, main body, suffix. Missing this will immediately throw. | | attr | Required | At minimum attr.width is used for canvas width, clearRect, centering/left/right layout. Other fields like left, top, height are mostly determined by the outer page layout; the library mainly uses width. |

3.2 config.global

| Field | Required? | Notes | |------|:------:|------| | textAlign | Required | Values: "left" | "center" | "right". Prefix, main digits, and suffix horizontal positions depend on this. |

3.3 config.prefix

| Field | Required? | Notes | |------|:------:|------| | type | Required | "text": text prefix; "img": image prefix. |

If type === "text" (recommended to supply):

| Field | Required? | Notes | |------|:------:|------| | text | Strongly recommended | The prefix string. Used for width measurement and drawing; an empty string may result in zero width. | | font | Required (if text is displayed) | Canvas font style (e.g. fontSize, fontFamily, fontWeight, color, textShadow), consistent with utils/getCtxFontOption. | | top / left | Optional | Default can be 0; affects each character’s draw offset. |

If type === "img":

| Field | Required? | Notes | |------|:------:|------| | url | Required (if image is shown) | Image URL; the code will loadImg then measure width/height. | | imgzoom / left | Optional | Scale and offset; missing values are often handled with || 1 or || 0. |

3.4 config.suffix

Symmetric to prefix: type is required; when "text" provide text + font (and optional top/left); when "img" provide url, etc.

Note: suffixCom.getSuffixHeightAndWidth contains an unused parameter in the source; the img branch does not depend on that parameter and it can be ignored.

3.5 config.flop (main numeric body)

| Field | Required? | Notes | |------|:------:|------| | type | Required | "text": vector digits; "img": a single digit-strip image sliced into 12 frames. | | transitiontime | Strongly recommended | Animation duration coefficient (internally multiplied by 60 and frame counts). Missing this can yield NaN and abnormal animation. | | isThousand | Optional | Whether to format with thousand separators; affects format string. | | isPoint / decimalCount | Optional | Controls decimal display logic; there are defaults, but it's recommended to set explicitly. | | animate | Optional | The image-digit scroll branch checks for === true. | | letterSpacing | Optional | Used only for text-mode layout. |

If type === "text":

| Field | Required? | Notes | |------|:------:|------| | font | Required | Used to measure character like "8", comma height, and for fillText style. |

If type === "img":

| Field | Required? | Notes | |------|:------:|------| | backgroundImage | Required | Digit-strip image URL; will be loadImged to compute numHeight / oneNumWidth. | | imgzoom | Optional | Defaults to 1. | | pointoffset / numoffset / isThousand | Layout-dependent | Affect per-character x-offsets and thousand separators in image mode; follow the mixin examples. |

4. Minimal usable configuration example (text-based)

A minimal structure that “just works” and is smaller than text, to illustrate the minimum required fields (you can add dataConfig or other business fields as needed):

const minimalOptions = {
  attr: {
    width: 800, // required: logical canvas width
    left: 0,
    top: 0,
    height: 200,
    angle: 0,
    scale: [1, 1],
    lock: false,
    opacity: 1,
  },
  config: {
    global: { textAlign: "center" },
    prefix: {
      type: "text",
      text: "¥",
      top: 0,
      left: 0,
      font: {
        fontSize: 24,
        color: "#fff",
        fontFamily: "sans-serif",
        fontWeight: "normal",
        lineHeight: 1,
        textShadow: "",
      },
    },
    flop: {
      type: "text",
      isThousand: true,
      isPoint: false,
      transitiontime: 0.75,
      font: {
        fontSize: 48,
        color: "#fff",
        fontFamily: "sans-serif",
        fontWeight: "normal",
        lineHeight: 1,
        textShadow: "",
        letterSpacing: 0,
      },
      animate: true,
      decimalCount: "0.0",
    },
    suffix: {
      type: "text",
      text: "",
      top: 0,
      left: 0,
      font: {
        fontSize: 24,
        color: "#fff",
        fontFamily: "sans-serif",
        fontWeight: "normal",
        lineHeight: 1,
        textShadow: "",
      },
    },
  },
};

For image-based usage, refer to mixin: switch type to "img" for prefix/suffix/flop and provide url or backgroundImage accordingly.

5. API Overview

| Method | Description | |------|------| | new NumFlop(canvas, options, initialNumber) | Create an instance and asynchronously initialize size and the first frame. | | setNum(n: number) | Update the number and drive the scrolling animation (uses internal requestAnimationFrame). | | setOptions(options) | Replace the entire configuration, re-measure sizes, and re-render. |

6. Relationship to the npm package num-flop

The num-flop referenced in package.json points to the published UMD/ES builds; the runtime entry shape and configuration may differ from the current numberFlop source. For published docs, prefer the type declarations in dist; this document only describes the behavior of src/numberFlop/.

7. FAQ

Q: Cannot read properties of undefined (reading 'config')
A: You passed an incomplete screen object (for example, an option that only has global + font).

Q: Number doesn’t update
A: This relates to internal animation timing and setNum call timing; ensure initialization completes before using setInterval, or adjust setNum / drawFlop logic in the source (see inline source comments).

Q: Fonts look blurry
A: Use document.fonts.ready or pre-render a hidden node using the same font as flop.font.fontFamily (see useFontLoad.ts and Index.tsx for reference).

8. Source index

| File | Purpose | |------|------| | src/numberFlop/numFlop/index.ts | NumFlop class, setNum / setOptions | | src/numberFlop/flopData.ts | Example text, mixin, option data | | src/numberFlop/utils/flopCom.ts | Main digit layout and animation | | src/numberFlop/utils/prefixCom.ts / suffixCom.ts | Prefix and suffix handling |

Copying text or mixin and locally adjusting attr.width and fonts is the least error-prone way to integrate.