format — Formatting
17:43Description
$u.formatNumber, $u.formatName, $u.timeFormat and $u.padZero handle number, name, time and zero-padding formats: numbers drop trailing zeros by default and optionally add thousands separators, names are masked by length, time is replaced by tokens, and padding adds leading 0 up to a total width.
Examples
Number formatting
Covers default trailing-zero removal, explicit decimals, rounding to an integer, thousands separators and custom decimal points; the fifth argument controls whether trailing zeros are kept.
View source
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in numberList"
:key="index"
:title="item.desc"
:value="item.result"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';
type Row = {
desc: string;
result: string;
last: boolean;
};
// 参数顺序:数字、小数位、小数点符号、千位分隔符、是否保留尾零
const numberList: Row[] = [
{ desc: '$u.formatNumber(1234)', result: $u.formatNumber(1234), last: false },
// 默认去尾零:虽然给了 2 位,结果仍是 1234
{ desc: '$u.formatNumber(1234, 2)', result: $u.formatNumber(1234, 2), last: false },
{ desc: '$u.formatNumber(1234.5678, 2)', result: $u.formatNumber(1234.5678, 2), last: false },
// 0 位即四舍五入取整
{ desc: "$u.formatNumber(5321.5, 0, '.', ',')", result: $u.formatNumber(5321.5, 0, '.', ','), last: false },
{ desc: "$u.formatNumber(1234567.891, 2, '.', ',')", result: $u.formatNumber(1234567.891, 2, '.', ','), last: false },
// 第五个参数传 true 保留尾零
{ desc: "$u.formatNumber(1234, 2, '.', ',', true)", result: $u.formatNumber(1234, 2, '.', ',', true), last: false },
// 自定义小数点与千位分隔符(欧式写法)
{ desc: "$u.formatNumber(1234.5, 2, ',', '.')", result: $u.formatNumber(1234.5, 2, ',', '.'), last: true }
];
</script>Name masking
A single-character name is returned as-is, two-character names keep the first character, three or more keep the first and last, and an empty string stays empty.
View source
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in nameList"
:key="index"
:title="item.desc"
:value="item.result"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';
type Row = {
desc: string;
result: string;
last: boolean;
};
// 一字原样返回,两字保留首字,三字以上保留首末字
const nameList: Row[] = [
{ desc: '$u.formatName("张")', result: $u.formatName('张'), last: false },
{ desc: '$u.formatName("张三")', result: $u.formatName('张三'), last: false },
{ desc: '$u.formatName("欧阳修")', result: $u.formatName('欧阳修'), last: false },
{ desc: '$u.formatName("司马相如")', result: $u.formatName('司马相如'), last: false },
{ desc: '$u.formatName("")', result: $u.formatName(''), last: true }
];
</script>Time formatting
The same timestamp is rendered with different templates: m is the month and M the minute, two-letter tokens are zero-padded, and a 10-digit string is treated as a second-level timestamp.
View source
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in timeList"
:key="index"
:title="item.desc"
:value="item.result"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';
type Row = {
desc: string;
result: string;
last: boolean;
};
// token:y 年 / m 月 / d 日 / h 时 / M 分 / s 秒,注意 m 是月、M 是分
// 连续两位自动补零,单个字符不补零;结果随设备时区变化
const timeList: Row[] = [
{ desc: '$u.timeFormat(1700000000000)', result: $u.timeFormat(1700000000000), last: false },
{ desc: "$u.timeFormat(1700000000000, 'yyyy-mm-dd hh:MM:ss')", result: $u.timeFormat(1700000000000, 'yyyy-mm-dd hh:MM:ss'), last: false },
// 10 位字符串按秒级时间戳处理
{ desc: "$u.timeFormat('1700000000', 'yyyy-mm-dd')", result: $u.timeFormat('1700000000', 'yyyy-mm-dd'), last: false },
{ desc: "$u.timeFormat(1700000000000, 'yy-m-d h:M:s')", result: $u.timeFormat(1700000000000, 'yy-m-d h:M:s'), last: true }
];
</script>Zero padding
padZero left-pads with 0 up to the total width, returns the number unchanged when it is already longer, and floors decimals first.
View source
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in padZeroList"
:key="index"
:title="item.desc"
:value="item.result"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';
type Row = {
desc: string;
result: string;
last: boolean;
};
// 第二参数为补零后的总位数,小数先被 Math.floor 取整
const padZeroList: Row[] = [
{ desc: '$u.padZero(5)', result: $u.padZero(5), last: false },
{ desc: '$u.padZero(5, 3)', result: $u.padZero(5, 3), last: false },
{ desc: '$u.padZero(123, 2)', result: $u.padZero(123, 2), last: false },
{ desc: '$u.padZero(7.9)', result: $u.padZero(7.9), last: true }
];
</script>API
formatNumber
Parameters:
| Parameter | Description | Type | Default | Version |
|---|---|---|---|---|
| num | The number or numeric string to format | number | string | null | - | - |
| decimals | Number of decimal places | number | string | null | 0 | - |
| decimalPoint | Decimal point character | number | string | null | '.' | - |
| separator | Thousands separator; no separator is added when empty or numeric | string | null | '' | - |
| keepTrailingZeros | Whether to keep trailing decimal zeros | boolean | false | - |
Returns:
| Type | Description |
|---|---|
string | The formatted number string |
formatName
Parameters:
| Parameter | Description | Type | Default | Version |
|---|---|---|---|---|
| name | The name to mask | string | - | - |
Returns:
| Type | Description |
|---|---|
string | The masked name; two characters keep the first, three or more keep the first and last, others are returned as-is |
timeFormat
Parameters:
| Parameter | Description | Type | Default | Version |
|---|---|---|---|---|
| dateTime | Timestamp (number or string); null uses the current time | number | string | null | - | - |
| fmt | Format template supporting y / m / d / h / M / s | string | 'yyyy-mm-dd' | - |
Returns:
| Type | Description |
|---|---|
string | The time string after token replacement |
padZero
Parameters:
| Parameter | Description | Type | Default | Version |
|---|---|---|---|---|
| num | The number to pad, floored with Math.floor first | number | - | - |
| width | Total width after padding | number | 2 | - |
Returns:
| Type | Description |
|---|---|
string | The padded string at the requested width; a longer original number is returned as-is |
Notes
formatNumberdrops trailing decimal zeros by default throughparseFloat(toFixed());keepTrailingZerosmust betrueto keep them.formatNumberskips thousands separators whenseparatoris an empty string or a numeric string.timeFormatusesmfor month andMfor minute, the reverse of common convention; a 10-digit string timestamp is treated as seconds and results follow the device time zone.formatNamekeeps the first character for two-character names and the first plus last for longer names; a single character and an empty string are returned as-is.