Skip to content

format — Formatting ​

17:43

Description ​

$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
vue
<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
vue
<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
vue
<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
vue
<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:

ParameterDescriptionTypeDefaultVersion
numThe number or numeric string to formatnumber | string | null--
decimalsNumber of decimal placesnumber | string | null0-
decimalPointDecimal point characternumber | string | null'.'-
separatorThousands separator; no separator is added when empty or numericstring | null''-
keepTrailingZerosWhether to keep trailing decimal zerosbooleanfalse-

Returns:

TypeDescription
stringThe formatted number string

formatName ​

Parameters:

ParameterDescriptionTypeDefaultVersion
nameThe name to maskstring--

Returns:

TypeDescription
stringThe masked name; two characters keep the first, three or more keep the first and last, others are returned as-is

timeFormat ​

Parameters:

ParameterDescriptionTypeDefaultVersion
dateTimeTimestamp (number or string); null uses the current timenumber | string | null--
fmtFormat template supporting y / m / d / h / M / sstring'yyyy-mm-dd'-

Returns:

TypeDescription
stringThe time string after token replacement

padZero ​

Parameters:

ParameterDescriptionTypeDefaultVersion
numThe number to pad, floored with Math.floor firstnumber--
widthTotal width after paddingnumber2-

Returns:

TypeDescription
stringThe padded string at the requested width; a longer original number is returned as-is

Notes ​

  • formatNumber drops trailing decimal zeros by default through parseFloat(toFixed()); keepTrailingZeros must be true to keep them.
  • formatNumber skips thousands separators when separator is an empty string or a numeric string.
  • timeFormat uses m for month and M for minute, the reverse of common convention; a 10-digit string timestamp is treated as seconds and results follow the device time zone.
  • formatName keeps 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.