|
29 | 29 | | | | |
30 | 30 | | :--- | :--- | |
31 | 31 | | **🌏 Multi-Charset Support**<br>Supports CJK, Numbers, Emojis, and mixed text rolling. Auto-adjusts spacing based on Unicode width. | **🧠 Smart Diff Animation**<br>Uses Levenshtein algorithm to find the shortest change path; identical characters remain static. | |
32 | | -| **⚡ Smooth Interruption**<br>Seamlessly transitions to new targets if the value changes dynamically during animation. | **📈 Rich Motion**<br>Built-in `linear`, `bounce`, `easeInOut` easings. Supports `charWidth` for fine-tuning. | |
33 | | -| **🦄 Dual Framework**<br>Provides both React (Hooks) and Vue 3 (Composition) components with a unified API. | **🚀 High Performance**<br>Powered by `RAF`, removing DOM overhead, optimized for high-frequency data streams. | |
| 32 | +| **⚡ Smooth Interruption**<br>Seamlessly transitions to new targets if the value changes dynamically during animation. | **📈 Rich Motion**<br>Built-in variety of easings.Supports custom easing function. Supports `charWidth` fine-tuning. | |
| 33 | +| **🦄 Dual Framework**<br>Provides both React (Hooks) and Vue 3 (Composition) components with a unified API. | **🚀 High Performance**<br>Powered by `RAF`, supporting **Auto-scale**, **Fading Edge**, and **Disable Animation**. | |
34 | 34 |
|
35 | 35 | ## 📦 Installation |
36 | 36 |
|
@@ -138,50 +138,59 @@ The component uses the system monospace stack by default. To use a custom font ( |
138 | 138 |
|
139 | 139 | | Prop | Type | Default | Description | |
140 | 140 | |------|------|--------|------| |
141 | | -| `value` | `string` | - | The text value to display (Required) | |
| 141 | +| `value` | `string`\|`number` | - | The text value to display (Required) | |
142 | 142 | | `duration` | `number` | `500` | Animation duration (ms) | |
143 | 143 | | `easing` | `EasingName \| function` | `'easeInOut'` | Easing: `linear`, `easeIn`, `easeOut`, `easeInOut`, `bounce`, or custom `(t: number) => number` | |
144 | 144 | | `direction` | `string` | `'ANY'` | Scroll direction: `UP`, `DOWN`, `ANY` (shortest path) | |
145 | 145 | | `charWidth` | `number` | `1` | Character width multiplier (base 0.8em) | |
146 | 146 | | `characterLists` | `string[]` | `['0123456789']` | Allowed character sets | |
147 | 147 | | `className` | `string` | `''` | Custom CSS class name | |
148 | 148 | | `animateOnMount` | `boolean` | `false` | Animate on initial render | |
149 | | -| `disabled` | `boolean` | `false` | Disable animation, show final value immediately | |
| 149 | +| `disableAnimation` | `boolean` | `false` | Disable animation, show final value immediately | |
| 150 | +| `autoScale` | `boolean` | `false` | Enable auto-scaling to fit container width | |
| 151 | +| `fadingEdge` | `boolean` | `false` | Enable top/bottom fading edge effect | |
150 | 152 | | `prefix` | `string` | - | Static prefix (not animated) | |
151 | 153 | | `suffix` | `string` | - | Static suffix (not animated) | |
| 154 | +| `numberFormat` | `Intl.NumberFormat` | - | Intl formatter number `value` | |
152 | 155 | | `onAnimationEnd` | `() => void` | - | Callback when animation ends (Vue: `@animation-end`) | |
153 | 156 |
|
154 | | -### Built-in Character Lists |
155 | 157 |
|
156 | | -```ts |
157 | | -import { TickerUtils } from './components/Ticker'; |
| 158 | +### 🧩 Character Configuration (characterLists) |
158 | 159 |
|
159 | | -TickerUtils.provideNumberList() // '0123456789' |
160 | | -TickerUtils.provideAlphabeticalList() // 'abc...zABC...Z' |
| 160 | +`characterLists` controls the core animation logic. It accepts an array of strings, where each string represents a group of characters that can **scroll into each other**. |
161 | 161 |
|
162 | | -### 🧩 Character Configuration |
| 162 | +#### Presets (Common Character Lists) |
| 163 | +For convenience, we provide built-in constants for common character sets: |
163 | 164 |
|
164 | | -`characterLists` controls the core animation logic. It accepts an array of strings, where each string represents a group of characters that can **scroll into each other**. |
| 165 | +```ts |
| 166 | +import { Presets } from '@tombcato/smart-ticker'; |
165 | 167 |
|
166 | | -**Rules:** |
167 | | -1. **Scroll**: If both the old and new characters belong to the same group string (e.g., `0` to `9` in `'0123456789'`), they will scroll. |
168 | | -2. **Switch**: If they are in different groups, or if a character is not in any list (e.g., Chinese characters), they will switch instantly without scrolling. |
| 168 | +Presets.NUMBER // '0123456789' |
| 169 | +Presets.ALPHABET // 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ' |
| 170 | +Presets.ALPHANUMERIC // '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ' |
| 171 | +Presets.CURRENCY // '0123456789.,' |
| 172 | +``` |
169 | 173 |
|
170 | | -**Configuration Tips:** |
| 174 | +#### Animation Rules |
| 175 | +1. **Scroll**: If both the old and new characters belong to the same group string (e.g., `0` to `9` in `Presets.NUMBER`), they will scroll. |
| 176 | +2. **Switch**: If they are in different groups, or if a character is not in any list (e.g., Chinese characters), they will switch instantly (fade/flip) without scrolling. |
171 | 177 |
|
172 | | -* `TickerUtils.provideAlphabeticalList()` includes both `a-z` and `A-Z`. |
173 | | -* To prevent scrolling between cases (e.g., `a` -> `A`), provide them as separate strings: `['abc...', 'ABC...']`. |
| 178 | +#### Configuration Tips |
| 179 | +* **Common Use Case**: Simply use `Presets.ALPHANUMERIC` to support most alphanumeric scrolling. |
| 180 | +* **Case Isolation**: To prevent scrolling between cases (e.g., `a` -> `A`), list them as separate groups: `[Presets.NUMBER, 'abc...', 'ABC...']`. |
174 | 181 |
|
175 | | -**Example:** |
| 182 | +**Code Example:** |
176 | 183 |
|
177 | | -```javascript |
178 | | -characterLists={[ |
179 | | - 'abcdefghijklmnopqrstuvwxyz', // Lowercase group |
180 | | - 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', // Uppercase group |
181 | | - '0123456789', // Number group |
182 | | - '.,!@#$%^&*' // Symbol group |
183 | | -]} |
184 | | -``` |
| 184 | +```tsx |
| 185 | +<Ticker |
| 186 | + value={val} |
| 187 | + characterLists={[ |
| 188 | + Presets.NUMBER, // Numbers |
| 189 | + 'abcdefghijklmnopqrstuvwxyz', // Lowercase Group |
| 190 | + 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', // Uppercase Group |
| 191 | + '.,!@#$%^&*' // Symbols |
| 192 | + ]} |
| 193 | +/> |
185 | 194 | ``` |
186 | 195 |
|
187 | 196 | ## 💻 Running Demos |
|
0 commit comments