数字格式
JavaScript/TypeScript应用程序中格式化编号的公用工具集合.
使用量
在内部,软件包要求一个用于格式化数字(平面),货币,紧凑数字等格式化方法的前置关闭/构件. 关闭处理地处地州.
import { setLocale, formatNumber } from '@automattic/number-formatters';
setLocale( 'de' ); // See notes below about locale state
formatNumber( 1000 ); // Returns "1.000"
setLocale( 'en' );
formatNumber( 1000 ); // Returns "1,000"
在未来的版本中,我们可能会揭露那些接受一种 locale 参数代替。 见 Dev/Setup 注释如下.
注释: 本地状态 / setLocale
包输出 a setLocale 方法(见下文"方法"),它允许设置用于将数字定位的地方变量。 默认值有一个后退链,这可能足以满足许多情况(因此不需要在代码中手动设置) setLocale) (中文(简体) ).
后退地被定义为:
- 当前 WordPress 用户语言,如果通过
@wordpress/date设置( 假设在 WordPress 上下文中运行) 。 请注意,这源于 用户设置,不是网站的. - 浏览器的用地,如果通过
window.navigator.language - 内部回落方位常数( q)
en- 可以切换到en-US(中文(简体) )
如果通过调用设置到 setLocale那么这显然将优先.
方法
如下所述各种TS类型,见我们 类型定义。 。 。 .
创建数字格式
createNumberFormatters(): NumberFormatters
以下列所有方法返回实例/对象的主要工厂方法。 大部分情况下,称这个是没有必要的,因为软件包已经创建了默认物. 如果消费者需要更多的控制,例如多例用于单独处理当地国家处理的地物,将是有益的.
格式( )
formatNumber(
number: number,
options?: Omit< NumberFormatParams, 'browserSafeLocale' >
): string;
这个 formatNumber 方法用于使用已装入的地语设置(即特定地语千和小数分隔符)格式化数字。 您通过数字(整数或浮点数)和(可选择的)您想要的小数位数(或一个选项对象),然后返回一个字符串,其格式符合当前装入的地块。 如果有必要,您还可以将第二个参数扩展为带有您想要覆盖的属性的对象,从而覆盖特定数字的语言设置.
实例
// These examples assume a 'de' (German) locale to demonstrate
formatNumber( 2500.25 ); // '2.500'
formatNumber( 2500.33, { decimals: 3 } ); // '2.500,330'
格式 编号 契约 ()
formatNumberCompact 将使用带有小数点1的紧凑符号格式化和本地化数字,如1K、1.5M等。 它的工作原理与 formatNumber (同数与辩相.
格式紧迫( C)
formatCurrency(
number: number,
currency: string,
options: FormatCurrencyOptions = {}
): string
使用给定的货币代码格式化货币.
货币将定义用于这种格式化的属性,但这些属性可以使用选项被覆盖. 这样做要小心.
对于包括小数的货币,这总能将包含小数的金额还原出,即使这些小数是零. 要排除零,请使用 stripZeros 选项。 例如,该函数通常会格式化 10.00 内 USD 作为 $10.00 但是,当这个选项是真的, 它会返回 $10 换句话说.
由于四舍五入误差在浮动点数学中很常见,因此有时会以货币最小单位的整数(如:美元一分钱或日元一分钱)提供价格. 设定 isSmallestUnit 来更改函数以在整数上运行。 如果此选项没有设置或错误, 函数将格式化该金额 1025 内 USD 作为 $1,025.00,但当选项是真实的, 它会返回 $10.25 换句话说.
要显示一个固定的十进制数而不是货币本身的(例如:商店的价格小数设置),通过 decimals数字 : formatCurrency( 92, 'USD', { decimals: 0 } ) 返回时 $92,以及 formatCurrency( 92, 'JPY', { decimals: 2 } ) 返回时 ¥92.00。它需要从 0 到 20 的整数,而忽略了其他任何东西,它不会改变 isSmallestUnit 除以数量. getCurrencyObject() 选择相同.
页:1
- 我们总是显示
US$当用户的地理位置不在美国境内时, 这一点很重要,因为其他货币使用$对于它们的货币,有时感到惊讶,如果它们实际上以美元计费(这是许多用户的违约)。 我们无法安全展示US$对每个人来说,因为我们发现美国用户 被这种风格所迷惑 并降低了对产品的信心. - 从货币最小单位格式化货币的选项(如:美元分,日元分). 这一点很重要,因为用代码中浮点数进行价格数学会产生出乎意料的四舍五入错误,所以大多数货币金额应该作为整数提供并被操纵.
获取当前对象( )
这是一种可选的API,可以分别返回价格中格式化的片段,因此消费者可以决定如何最好地制作出(例如:这用于将不同的HTML标记以价格和货币符号来包装). 联合来文已经将这一特征列为: Intl.NumberFormat.formatToParts() 但是,我们的API还必须包括这里列出的其他特征以及货币符号位置等额外信息(数字之前或之后).
getCurrencyObject(
number: number,
currency: string,
options: FormatCurrencyOptions = {}
): CurrencyObject
返回格式化的价格对象。 有关该对象属性的详情,见下文.
货币将定义用于这种格式化的属性,但这些属性可以使用选项被覆盖. 这样做要小心.
对于包括小数的货币,这总能将包含小数的金额还原出,即使这些小数是零. 要排除零,请使用 stripZeros 选项。 例如,该函数通常会格式化 10.00 内 USD 作为 $10.00 但是,当这个选项是真的, 它会返回 $10 换句话说 或者,你可以使用 hasNonZeroFraction 返回值以决定是否显示小数节.
由于四舍五入误差在浮动点数学中很常见,因此有时会以货币最小单位的整数(如:美元一分钱或日元一分钱)提供价格. 设定 isSmallestUnit 来更改函数以在整数上运行。 如果此选项没有设置或错误, 函数将格式化该金额 1025 内 USD 作为 $1,025.00,但当选项是真实的, 它会返回 $10.25 换句话说.
设置本地( C)
setLocale( locale: string ): void
一个函数,可用于设置默认的地块,供各种格式化者使用.
设置GeoLocation ()
setGeoLocation( geoLocation: string ): void
默认情况下,USD的货币符号将基于地籍(不同于使用硬编码的首字母列表的其他货币代码) en-US编号 :en 这将是 $ 对于其他所有的地方来说 US$然而,如果地理定位确定该国不在美国境内,则美元符号为: US$ 不论地方。 这是为了防止非美国国家使用英语地语的用户产生混淆.
在美国,用户会看到美元价格用货币符号表示 $然而,还有许多其他货币使用 $ 作为其货币符号(例如: CAD) (中文(简体) ). 此套件试图防止这些符号之间的混淆,在地语不匹配货币时使用国际版本的符号. 所以如果你的地址是 en-CA,美元价格将随文号而产生 US$。 。 。 .
然而,这取决于用户是否将其界面语言设定为非 en-US编号 :en,许多说英语的非美国用户仍然有这种界面语言(例如:我们的设置中没有可供阿根廷英语使用的英语语言),因此这些用户很可能仍然有 en) (中文(简体) ). 因此,这些用户将看到一个价格 $ 并且可能会被误导 关于什么货币正在显示。 设置 geoLocation 帮助通过显示来防止这种情况发生 US$ 这些用户.
关于实际用法,参见wp-calypso monorepo.
德维
设置
我们试图保持类似的功能分离 与 Intl.NumberFormat( ... ).format( ... )数字 :
src/
├── number-format-currency/index.ts
├── number-format.ts { numberformat, numberFormatCompact }
- 它们带回缓存实例
Intl.NumberFormat() - 单项出口,需要
locale作为参数通过(我们目前不导出这些参数,但我们可以下行) - 以上情况还不是
number-format-currency。它返回格式化编号,所以基本上是一个完整的Intl.NumberFormat( ... ).format( ... )电话 它可能会收到一个重新同步到下行的功能,希望这能改善一些代码共享
src/
├── create-number-formatters.ts { formatNumber, formatNumberCompact, formatCurrency, etc.}
- 关闭处理
locale状态,在数字格式化器上返回抽象,称为formatNumber, (中文(简体) ),formatNumberCompact等 (中文(简体) ). - 方法接受参数化基本格式化参数的参数,并允许方便于通用(例如方便)
decimals圆柱形)
在混音中添加一个新的前题, 说"格式百分比", 基本上只是重复我们为“ compact” 数字所做的: 一个方法从 create-number-formatters.ts 函数在 number-format.ts (或如果有比几个简单的默认更深的东西,则单独文件).
工作流程
修改时,该软件包可以通过 jetpack build -v js-packages/number-formatters (假定 CLI 工具 )或 pnpm run build (JP 用途) pnpm)),最新版本通过npm/yarn链接到相应的外部 repo来测试,例如wp-calypso.
一旦提交/合并更改,就应遵循典型的Jetpack工作流程,公布对国家预防机制的更改.