GreatJoy-Input 组件文档

一个基于 antd-mobile 的增强型 React 输入组件，提供更多功能和更好的用户体验。

组件说明

GreatJoy-Input 是一个功能增强的 React 输入组件库，基于 antd-mobile 组件进行二次封装，提供了以下特性：

• 基础输入框功能（文本、密码、搜索、电话、邮箱、数字等）
• 数字输入框，支持千分位分隔符、小数位控制、金额单位提示
• 虚拟输入框，可用于自定义键盘场景
• 手动样式引入（避免自动注入可能引起的冲突问题）
• 完整的 TypeScript 类型支持
• 支持 ref 调用内部方法（focus、blur、clear等）

安装

使用 npm 安装：

npm install greatjoy-input

使用 yarn 安装：

yarn add greatjoy-input

使用方法

基础用法

import { GreatJoyInput } from 'greatjoy-input';

// 必须手动引入样式
import 'greatjoy-input/dist/index.css';

function App() {
  return (
    <GreatJoyInput 
      placeholder="请输入内容"
      onChange={(value) => console.log(value)}
    />
  );
}

数字输入框

import { GreatJoyInput } from 'greatjoy-input';

// 必须手动引入样式
import 'greatjoy-input/dist/index.css';

function App() {
  return (
    <GreatJoyInput.InputNumber
      placeholder="请输入金额"
      suffix="元"
      thousandsSeparators
      precision={2}
      priceTips
      onChange={(value) => console.log(value)}
    />
  );
}

虚拟输入框

import { GreatJoyInput } from 'greatjoy-input';

// 必须手动引入样式
import 'greatjoy-input/dist/index.css';

function App() {
  return (
    <GreatJoyInput.VirtualInput
      placeholder="请输入内容"
      onChange={(value) => console.log(value)}
    />
  );
}

样式引入方式

手动引入（当前版本唯一支持方式）

从 1.0.23 版本开始，组件库只支持手动引入样式文件：

// 引入组件
import { GreatJoyInput } from 'greatjoy-input';

// 必须手动引入样式
import 'greatjoy-input/dist/index.css';

为什么移除自动样式注入？

在之前的版本中，我们尝试通过自动注入样式来简化使用流程，但这种方式可能导致以下问题：

1. Invalid hook call 错误：当组件库和宿主应用使用不同版本的 React 时，会引发此错误
2. React 上下文为 null：在某些构建配置下，可能导致 React hooks 无法正常工作
3. 版本冲突：多个 React 实例可能导致不可预测的行为

为了确保组件库的稳定性和兼容性，我们决定移除自动样式注入功能，改为手动引入方式。

React 版本要求

组件库要求使用 React 18.2.0 版本，这是为了确保与组件库内部使用的 React API 兼容。

"peerDependencies": {
  "react": "18.2.0",
  "react-dom": "18.2.0"
}

API 接口

GreatJoyInputProps

继承自 antd-mobile 的 InputProps，但覆盖了部分属性：

| 属性 | 说明 | 类型 | 默认值 | |------|------|------|--------| | value | 输入框内容 | string \| number | - | | onChange | 输入框内容变化时触发 | (val: string \| number) => void | - | | type | 输入框类型 | "text" \| "password" \| "search" \| "tel" \| "email" \| "number" | "text" | | suffix | 输入框后缀 | string \| React.ReactNode | - | | thousandsSeparators | 是否显示千分符 | boolean | false | | precision | 小数位数 | number | 0 | | contentAlign | 内容对齐方式 | "left" \| "right" | "right" | | ref | 组件 ref | React.RefObject<GreatJoyInputRef> | - |

GreatJoyInputRef

组件 ref 对象，包含以下方法：

| 方法名 | 说明 | 类型 | |--------|------|------| | focus | 使输入框获得焦点 | () => void | | blur | 使输入框失去焦点 | () => void | | clear | 清空输入框内容 | () => void | | nativeElement | 原生输入框元素 | HTMLInputElement \| null |

GreatJoyInputNumberProps

数字输入框特有的属性，继承自 GreatJoyInputProps：

| 属性 | 说明 | 类型 | 默认值 | |------|------|------|--------| | priceTips | 是否显示金额提示词 | boolean | true |

GreatJoyVirtualInputProps

虚拟输入框属性，继承自 antd-mobile 的 VirtualInputProps：

| 属性 | 说明 | 类型 | 默认值 | |------|------|------|--------| | contentAlign | 内容对齐方式 | "left" \| "right" | "right" |

子组件

GreatJoyInput.InputNumber

数字输入框组件，适用于金额、数量等数字输入场景。

特点：

• 支持千分位分隔符显示
• 可控制小数位数
• 自动显示金额单位提示（个、十、百、千、万等）
• 右对齐显示（默认）

GreatJoyInput.VirtualInput

虚拟输入框组件，适用于需要自定义键盘的场景。

特点：

• 可自定义键盘组件
• 默认使用 NumberKeyboard 数字键盘
• 右对齐显示（默认）

工具函数

numberFormatter

对数值按照指定小数点位数和取整方式进行格式化。

function numberFormatter(
  value: number,
  point: number,
  roundingType?: RoundingType
): number

thousandSymbol

对数值进行千分位格式化。

function thousandSymbol(value: number | string): string

deThousandSymbol

将千分位格式化的字符串转化为数字。

function deThousandSymbol(value: string): number

precision

对数值进行精度控制。

function precision(value: number | string, point: number): string

isValidNumber

判断字符串是否为有效数字。

function isValidNumber(str: any): boolean

常量

UNIT_MULTIPLE_MAP

金额单位与倍数的映射关系：

{
  元: 1,
  十元: 10,
  百元: 100,
  千元: 1000,
  万元: 10000,
  十万元: 100000,
  百万元: 1000000,
  千万元: 10000000
}

AMOUNT_THRESHOLDS

金额单位的阈值定义：

{
  YUAN: 1,
  TENYUAN: 10,
  ONEHUNDREDYUAN: 100,
  THOUSAND: 1000,
  TEN_THOUSAND: 10000,
  HUNDRED_THOUSAND: 100000,
  MILLION: 1000000,
  TEN_MILLION: 10000000
}