# @canutin/svelte-currency-input 中文文档

规范地址：https://npmcn.com/package/%40canutin/svelte-currency-input/

版本：1\.1\.2
npm 元数据更新时间：2026-06-22T16:17:27.830Z
中文译文更新时间：2026-11-09T12:19:00.645Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40canutin/svelte-currency-input
原文对照：https://npmcn.com/package/%40canutin/svelte-currency-input/?lang=original
项目主页：https://svelte-currency-input.fernando.is/
源码仓库：https://github.com/fmaclen/svelte-currency-input

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：43.4 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：svelte ^5\.0\.0
- 首次发布：2022-09-15T04:58:28.089Z
- 最新版本发布：2026-06-22T16:17:27.469Z
- 近 30 天下载量：2792（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 6 个）

## 中文简介

Svelte 5 的全功能货币输入组件,处理格式化、本地化和验证

## 安装

```sh
npm install @canutin/svelte-currency-input
```

也可以使用：`pnpm add @canutin/svelte-currency-input`、`yarn add @canutin/svelte-currency-input`、`bun add @canutin/svelte-currency-input`

## README

# 丝绒-货币投入

用于 Svelte 5 的全特有货币输入组件,处理格式化,本地化,以及您键入时的验证.

![svelte-currency-input examples](https://npmcn.com/package/%40canutin/svelte-currency-input/static/svelte-currency-input-examples.png)

玩着它 [现场演示](https://svelte-currency-input.fernando.is/)

* * *

-   [特征](https://npmcn.com/package/%40canutin/svelte-currency-input/#readme-features)
-   [安装](https://npmcn.com/package/%40canutin/svelte-currency-input/#readme-installation)
-   [使用量](https://npmcn.com/package/%40canutin/svelte-currency-input/#readme-usage)
-   [如何运作](https://npmcn.com/package/%40canutin/svelte-currency-input/#readme-how-it-works)
-   [API 密码](https://npmcn.com/package/%40canutin/svelte-currency-input/#readme-api)
-   [实例](https://npmcn.com/package/%40canutin/svelte-currency-input/#readme-examples)
-   [样式](https://npmcn.com/package/%40canutin/svelte-currency-input/#readme-styling)
-   [出口公用事业](https://npmcn.com/package/%40canutin/svelte-currency-input/#readme-exported-utilities)
    -   [格式值选项](https://npmcn.com/package/%40canutin/svelte-currency-input/#readme-formatvalue-options)
-   [Svelte 4/移徙指南](https://npmcn.com/package/%40canutin/svelte-currency-input/#readme-svelte-4)
-   [捐款](https://npmcn.com/package/%40canutin/svelte-currency-input/#readme-contributing)

## 特征

-   格式 **正数** 财务报告和审定财务报表 **负数** 数值
-   积分 [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) 页:1 **本地化** 货币面额
-   支助 **缩略语** (k、m、b) 快速投入
-   可配置 **小数精度** 有多个控制选项
-   **最小/最大制约因素** 用箭头键步
-   自定义 **前缀** 财务报告和审定财务报表 **后缀** 支助
-   **零内置样式** - 与Tailwind、vanilla CSS或任何框架合作
-   简单,单身 `<input>` 元素( 无包装)
-   满 **类型脚本** 支助
-   **轻巧** - ~3.6KB 无运行时间依赖
-   API和逻辑的灵感很大 [@cchanxzy (英语)](https://github.com/cchanxzy)是因为 [反应-货币-输入-域](https://github.com/cchanxzy/react-currency-input-field)

## 安装

```bash
# bun
bun add @canutin/svelte-currency-input

# pnpm
pnpm add @canutin/svelte-currency-input

# npm
npm install @canutin/svelte-currency-input

# yarn
yarn add @canutin/svelte-currency-input
```

## 使用量

```svelte
<script lang="ts">
    import { CurrencyInput } from '@canutin/svelte-currency-input';

    let value = $state('1234.56');
</script>

<CurrencyInput bind:value intlConfig={{ locale: 'en-US', currency: 'USD' }} />
```

输入显示 `$1,234.56` 时 `value` 包含原始字符串 `"1234.56"`。 。 。 .

## 如何运作

该部分是单一的 `<input>` 键。 这个 `value` 道具是一个 **字符串** 表示未格式化编号:

-   `""` = 空输入
-   `"0"` = 0 = 零 (单位:千美元)
-   `"1234.56"` = 号码1234.56

格式化显示(例如, `$1,234.56`由内部处理。 对于需要原始值的窗体提交,可以添加隐藏输入:

```svelte
<form>
    <CurrencyInput bind:value name="display" />
    <input type="hidden" name="amount" {value} />
</form>
```

## API 密码

### 道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `value` | `string` | `''` | 可绑定活性值(例如, `"1234.56"`(中文(简体) ) |
| `intlConfig` | `IntlConfig` | `undefined` | 地方和货币配置 |
| `prefix` | `string` | 从本地 | 覆盖货币前缀 |
| `suffix` | `string` | `''` | 覆盖货币后缀 |
| `decimalSeparator` | `string` | 从本地 | 覆盖小数分隔符 |
| `groupSeparator` | `string` | 从本地 | 覆盖分组分隔符 |
| `disableGroupSeparators` | `boolean` | `false` | 禁用千位分隔符 |
| `allowDecimals` | `boolean` | `true` | 允许小数值 |
| `decimalsLimit` | `number` | `2` | 输入时最大小数位数 |
| `decimalScale` | `number` | `undefined` | 模糊的平分/小数 |
| `fixedDecimalLength` | `number` | `undefined` | 固定小数输入(例如, `2`: 输入 `123` → `1.23`(中文(简体) ) |
| `allowNegativeValue` | `boolean` | `true` | 允许负值 |
| `min` | `number` | `undefined` | 最小值( 在箭头按键步骤上强制) |
| `max` | `number` | `undefined` | 最大值( 在箭头按键步骤上强制) |
| `maxLength` | `number` | `undefined` | 最大字符( 不包括格式化) |
| `step` | `number` | `undefined` | 箭头增减 |
| `disableAbbreviations` | `boolean` | `false` | 禁用 k/ m/ b 缩写 |
| `formatValueOnBlur` | `boolean` | `true` | 当输入失去焦点时应用格式 |
| `transformRawValue` | `(value: string) => string` | `undefined` | 处理前转换原始值 |
| `oninputvalue` | `(values: CurrencyInputValues) => void` | `undefined` | 每一次输入更改都召回 |
| `onchangevalue` | `(values: CurrencyInputValues) => void` | `undefined` | 在模糊/承诺下召回 |
| `ref` | `HTMLInputElement | null` | `null` | 可绑定输入元素的引用 |
| `class` | `string` | `undefined` | 输入的 CSS 类 |
| `...restProps` | `HTMLInputAttributes` | —— 说 | 所有标准输入属性(ID,名称,占位符,已禁用,需要等) |

### 类型

```typescript
interface IntlConfig {
    locale: string;
    currency?: string;
    // Also accepts other Intl.NumberFormatOptions
}

interface CurrencyInputValues {
    float: number | null; // Parsed number or null if empty
    formatted: string; // Display value: "$1,234.56"
    value: string; // Raw value: "1234.56"
}
```

## 实例

### 国际货币

```svelte
<CurrencyInput bind:value intlConfig={{ locale: 'de-DE', currency: 'EUR' }} />
<!-- Displays: 1.234,56 € -->
```

### 十进制精度

```svelte
<!-- Limit to 2 decimals while typing, pad to 2 on blur -->
<CurrencyInput
    bind:value
    intlConfig={{ locale: 'en-US', currency: 'USD' }}
    decimalsLimit={2}
    decimalScale={2}
/>
```

### 最小、最大和步数

```svelte
<!-- Use arrow keys to increment/decrement by 10, constrained to 0-100 -->
<CurrencyInput
    bind:value
    intlConfig={{ locale: 'en-US', currency: 'USD' }}
    min={0}
    max={100}
    step={10}
/>
```

### 自定义前缀和后缀

```svelte
<!-- Points system -->
<CurrencyInput bind:value suffix=" pts" decimalsLimit={0} />

<!-- Bitcoin -->
<CurrencyInput bind:value prefix="₿ " decimalsLimit={8} />
```

### 简称

类型 `1k`, (中文(简体) ), `2.5m`,或 `1b` 快速输入大数 :

```svelte
<CurrencyInput
    bind:value
    intlConfig={{ locale: 'en-US', currency: 'USD' }}
    placeholder="Try 1k, 2.5m, or 1b"
/>
<!-- Typing "2.5m" results in value="2500000" -->
```

### 回电

```svelte
<CurrencyInput
    bind:value
    intlConfig={{ locale: 'en-US', currency: 'USD' }}
    oninputvalue={({ float, formatted, value }) => {
        console.log('On input:', { float, formatted, value });
    }}
    onchangevalue={({ float, formatted, value }) => {
        console.log('On blur:', { float, formatted, value });
    }}
/>
```

### 输入元素参考

```svelte
<script>
    let inputRef = $state(null);

    function focusInput() {
        inputRef?.focus();
    }
</script>

<CurrencyInput bind:ref={inputRef} bind:value />
<button onclick={focusInput}>Focus</button>
```

## 样式

该部分是单一的 `<input>` 没有内置样式的元素。 你可以用这个 `class` 用于样式的道具 :

```svelte
<!-- Tailwind CSS -->
<CurrencyInput bind:value class="rounded border px-3 py-2 focus:ring-2 focus:ring-blue-500" />

<!-- Custom CSS class -->
<CurrencyInput bind:value class="my-currency-input" />
```

对于基于数值的动态样式(正/负/正),使用回调:

```svelte
<script>
    let value = $state('');
    let colorClass = $state('');

    function updateStyle({ float }) {
        if (float === null || float === 0) colorClass = 'text-gray-500';
        else if (float > 0) colorClass = 'text-green-600';
        else colorClass = 'text-red-600';
    }
</script>

<CurrencyInput bind:value class="border px-3 py-2 {colorClass}" oninputvalue={updateStyle} />
```

## 出口公用事业

软件包输出用于组件外的公用功能:

```typescript
import {
    formatValue,
    getLocaleConfig,
    cleanValue,
    parseAbbrValue,
    abbrValue
} from '@canutin/svelte-currency-input';

// Format a value with locale
const formatted = formatValue({
    value: '1234.56',
    intlConfig: { locale: 'en-US', currency: 'USD' }
});
// → "$1,234.56"

// Get locale configuration
const config = getLocaleConfig({ locale: 'de-DE', currency: 'EUR' });
// → { decimalSeparator: ',', groupSeparator: '.', prefix: '', suffix: ' €', ... }

// Parse abbreviations
const expanded = parseAbbrValue('2.5m', 'en-US');
// → "2500000"
```

### 格式值选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `value` | `string` | —— 说 | 格式的值 |
| `intlConfig` | `IntlConfig` | `undefined` | 地方和货币配置 |
| `decimalScale` | `number` | `undefined` | 小数位数 |
| `decimalSeparator` | `string` | 从本地 | 覆盖小数分隔符 |
| `groupSeparator` | `string` | 从本地 | 覆盖分组分隔符 |
| `disableGroupSeparators` | `boolean` | `false` | 禁用千位分隔符 |
| `prefix` | `string` | 从本地 | 覆盖货币前缀 |
| `suffix` | `string` | `''` | 覆盖货币后缀 |
| `roundValue` | `boolean` | `false` | 回合改为 `decimalScale` 而不是切换 |

默认, `formatValue` 将小数切入到 `decimalScale`设置 `roundValue: true` 改为取而代之,在用浮点精密工艺品格式化计算值时有用:

```typescript
// Default: truncates
formatValue({
    value: '87.5',
    intlConfig: { locale: 'en-US', currency: 'USD' },
    decimalScale: 0
});
// → "$87"

// With roundValue: rounds
formatValue({
    value: '87.5',
    intlConfig: { locale: 'en-US', currency: 'USD' },
    decimalScale: 0,
    roundValue: true
});
// → "$88"

// Useful for computed values with floating-point issues
const sum = 500.75 + 300.5 - 200.25 - 150.33; // = 450.66999999999996
formatValue({
    value: String(sum),
    intlConfig: { locale: 'en-US', currency: 'USD' },
    decimalScale: 2,
    roundValue: true
});
// → "$450.67" (without roundValue, would be "$450.66")
```

## 第4节

对于 Svelte 4 支持,请使用 [0.x 版本](https://github.com/fmaclen/svelte-currency-input/tree/v0.13.0)数字 :

```bash
npm install @canutin/svelte-currency-input@0
```

如果你正在升级 从v [移徙指南](https://npmcn.com/package/%40canutin/svelte-currency-input/MIGRATION.md)。 。 。 .

## 捐款

见 [捐款额](https://npmcn.com/package/%40canutin/svelte-currency-input/CONTRIBUTING.md) 用于建立、测试和贡献准则.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40canutin/svelte-currency-input/LICENSE)

## 常见问题

### @canutin/svelte-currency-input 是什么？

Svelte 5 的全功能货币输入组件,处理格式化、本地化和验证

### 如何安装 @canutin/svelte-currency-input？

在项目目录运行 npm install @canutin/svelte-currency-input，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：svelte（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @canutin/svelte-currency-input 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @canutin/svelte-currency-input 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @canutin/svelte-currency-input 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @canutin/svelte-currency-input 可以商用吗？

@canutin/svelte-currency-input 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @canutin/svelte-currency-input 的下载量有多少？

根据 npm 官方下载统计，@canutin/svelte-currency-input 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,792 次，日均约 93 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @canutin/svelte-currency-input 还在维护吗？

最新版本 1\.1\.2 发布于 2026/06/23（4 个月前）；至今共发布 43 个版本，其中过去 12 个月发布了 6 个；首次发布于 2022/09/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。