打印精灵JS脚本标准库函数手册

概述

打印精灵JS脚本一系列标签设计中心中常用的工具函数，涵盖了文本处理、数值处理和日期时间处理等多个方面，旨在提高开发效率和代码可读性。

目录

1. 文本处理
   • textValue()
   • toUpper()
   • toLower()
   • desensitize()
   • extractText()
2. 数值处理
   • toPositiveInteger()
   • toDecimal()
   • roundDecimal()
   • isInRange()
   • toPercentage()
   • padStart()
   • padEnd()
   • padBoth()
   • toCustomRadix()
   • toChineseUppercase()
   • toChineseLowercase()
   • toEnglishUppercase()
   • toEnglishLowercase()
3. 日期时间处理
   • formatDate()
   • formatDateTime()
   • formatTime()
   • diffDays()
   • dateToChineseUpper()
   • dateToChineseLower()
   • dateToEnglishUpper()
   • dateToEnglishLower()
4. 其他
   • getSerial()

---

文本处理

textValue(text)

• 功能: 获取原始文本值。这个函数直接返回输入的文本，不做任何修改。
• 参数:
  • text (String): 待处理的文本。
• 返回值:
  • (String): 原始文本。
• 例子:

  1console.log(textValue("Hello World")); // 输出: Hello World
  

toUpper(text)

• 功能: 将文本转换为大写。
• 参数:
  • text (String): 待转换的文本。
• 返回值:
  • (String): 转换后的大写文本。
• 例子:

  1console.log(toUpper("hello world")); // 输出: HELLO WORLD
  

toLower(text)

• 功能: 将文本转换为小写。
• 参数:
  • text (String): 待转换的文本。
• 返回值:
  • (String): 转换后的小写文本。
• 例子:

  1console.log(toLower("HELLO WORLD")); // 输出: hello world
  

desensitize(text, prefixLen = 3, suffixLen = 4, maskChar = '*')

• 功能: 对文本进行脱敏处理，通常用于隐藏敏感信息（如手机号、身份证号等）。它会保留文本的开头和结尾部分，中间部分用指定字符替换。
• 参数:
  • text (String): 待脱敏的文本。
  • prefixLen (Number, 可选, 默认值: 3): 保留文本开头的字符数。
  • suffixLen (Number, 可选, 默认值: 4): 保留文本末尾的字符数。
  • maskChar (String, 可选, 默认值: '*')：用于替换中间部分的脱敏字符。
• 返回值:
  • (String): 脱敏后的文本。如果文本长度小于等于 prefixLen + suffixLen，则返回原始文本。
• 例子:

  1console.log(desensitize("13812345678"));        // 输出: 138****5678
  2console.log(desensitize("abcdefg", 2, 2, '-')); // 输出: ab---fg
  3console.log(desensitize("short", 3, 4));        // 输出: short (因为长度不足以脱敏)
  

extractText(text, start, end)

• 功能: 截取文本的一部分。
• 参数:
  • text (String): 原始文本。
  • start (Number): 截取的起始索引（包含）。
  • end (Number): 截取的结束索引（不包含）。
• 返回值:
  • (String): 截取后的文本。
• 例子:

  1console.log(extractText("Hello World", 0, 5)); // 输出: Hello
  2console.log(extractText("JavaScript", 4, 10)); // 输出: Script
  

数值处理

toPositiveInteger(value)

• 功能: 将值转换为正整数。如果转换失败或结果不是正整数，则返回 NaN。
• 参数:
  • value (Any): 待转换的值。
• 返回值:
  • (Number): 转换后的正整数或 NaN。
• 例子:

  1console.log(toPositiveInteger("123"));    // 输出: 123
  2console.log(toPositiveInteger(45.67));    // 输出: NaN
  3console.log(toPositiveInteger("-10"));    // 输出: NaN
  4console.log(toPositiveInteger("abc"));    // 输出: NaN
  

toDecimal(value)

• 功能: 将值转换为小数（浮点数）。
• 参数:
  • value (Any): 待转换的值。
• 返回值:
  • (Number): 转换后的小数。
• 例子:

  1console.log(toDecimal("123.45")); // 输出: 123.45
  2console.log(toDecimal(100));     // 输出: 100
  3console.log(toDecimal("abc"));   // 输出: NaN
  

roundDecimal(value, decimalPlaces = 2)

• 功能: 对小数进行四舍五入到指定的位数。
• 参数:
  • value (Number): 待处理的数值。
  • decimalPlaces (Number, 可选, 默认值: 2): 保留的小数位数。
• 返回值:
  • (Number): 四舍五入后的数值。
• 例子:

  1console.log(roundDecimal(123.4567));      // 输出: 123.46
  2console.log(roundDecimal(123.4, 0));      // 输出: 123
  3console.log(roundDecimal(123.454, 2));    // 输出: 123.45
  

isInRange(value, min, max)

• 功能: 判断数值是否在指定的范围内（包含最小值和最大值）。
• 参数:
  • value (Number): 待判断的数值。
  • min (Number): 范围的最小值。
  • max (Number): 范围的最大值。
• 返回值:
  • (Boolean): 如果在范围内返回 true，否则返回 false。
• 例子:

  1console.log(isInRange(5, 0, 10));  // 输出: true
  2console.log(isInRange(0, 0, 10));  // 输出: true
  3console.log(isInRange(10, 0, 10)); // 输出: true
  4console.log(isInRange(-2, 0, 10)); // 输出: false
  

toPercentage(value, decimalPlaces = 2)

• 功能: 将数值转换为百分比字符串。
• 参数:
  • value (Number): 待转换的数值（例如 0.5 代表 50%）。
  • decimalPlaces (Number, 可选, 默认值: 2): 百分比的小数位数。
• 返回值:
  • (String): 转换后的百分比字符串。
• 例子:

  1console.log(toPercentage(0.25));     // 输出: 25.00%
  2console.log(toPercentage(0.78912, 1)); // 输出: 78.9%
  3console.log(toPercentage(1));        // 输出: 100.00%
  

padStart(value, totalLength, padChar = '0')

• 功能: 在值的左侧填充指定字符，直到达到指定总长度。
• 参数:
  • value (Any): 待填充的值。
  • totalLength (Number): 目标总长度。
  • padChar (String, 可选, 默认值: '0'): 用于填充的字符。
• 返回值:
  • (String): 填充后的字符串。
• 例子:

  1console.log(padStart(123, 5));          // 输出: 00123
  2console.log(padStart("abc", 6, '-'));   // 输出: ---abc
  3console.log(padStart(12345, 3));        // 输出: 12345 (已超出目标长度，不填充)
  

padEnd(value, totalLength, padChar = '0')

• 功能: 在值的右侧填充指定字符，直到达到指定总长度。
• 参数:
  • value (Any): 待填充的值。
  • totalLength (Number): 目标总长度。
  • padChar (String, 可选, 默认值: '0'): 用于填充的字符。
• 返回值:
  • (String): 填充后的字符串。
• 例子:

  1console.log(padEnd(123, 5));          // 输出: 12300
  2console.log(padEnd("abc", 6, '-'));   // 输出: abc---
  3console.log(padEnd(12345, 3));        // 输出: 12345 (已超出目标长度，不填充)
  

padBoth(value, totalLength, padChar = '0')

• 功能: 在值的两侧填充指定字符，直到达到指定总长度。如果无法均匀填充，左侧会稍微少填充一个字符。
• 参数:
  • value (Any): 待填充的值。
  • totalLength (Number): 目标总长度。
  • padChar (String, 可选, 默认值: '0'): 用于填充的字符。
• 返回值:
  • (String): 填充后的字符串。
• 例子:

  1console.log(padBoth(123, 7));           // 输出: 0012300
  2console.log(padBoth("abc", 7, '-'));    // 输出: --abc--
  3console.log(padBoth("test", 9, '*'));   // 输出: **test***
  4console.log(padBoth(12345, 3));         // 输出: 12345 (已超出目标长度，不填充)
  

toCustomRadix(num, radix, charset = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ')

• 功能: 将十进制数转换为自定义进制的字符串表示。支持负数。
• 参数:
  • num (Number): 待转换的十进制数。
  • radix (Number): 目标进制（必须介于 2 和 charset 长度之间）。
  • charset (String, 可选, 默认值: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'): 用于表示数字的字符集。
• 返回值:
  • (String): 自定义进制表示的字符串。
• 抛出错误:
  • 如果 radix 超出有效范围，将抛出 Error。
• 例子:

  1console.log(toCustomRadix(10, 2));      // 输出: 1010 (二进制)
  2console.log(toCustomRadix(255, 16));     // 输出: FF (十六进制)
  3console.log(toCustomRadix(100, 36));     // 输出: 2S (36进制，使用默认字符集)
  4console.log(toCustomRadix(-10, 2));     // 输出: -1010
  5console.log(toCustomRadix(10, 5, "abcde")); // 输出: cde (使用自定义字符集)
  

toChineseUppercase(num)

• 功能: 将数字或小数转换为中文大写金额表示。
• 参数:
  • num (Number): 待转换的数字或小数。
• 返回值:
  • (String): 转换后的中文大写金额字符串。
• 例子:

  1console.log(toChineseUppercase(123.45));   // 预期输出: 壹佰贰拾叁点肆伍 (或 壹佰贰拾叁元肆角伍分)
  2console.log(toChineseUppercase(10000));    // 预期输出: 壹万元整
  3console.log(toChineseUppercase(0));        // 预期输出: 零元整
  

toChineseLowercase(num)

• 功能: 将数字或小数转换为中文小写表示。此函数会处理整数和小数部分，使用“零、一、二...”和“点”连接小数。
• 参数:
  • num (Number): 待转换的数字或小数。
• 返回值:
  • (String): 转换后的中文小写字符串。
• 例子:

  1console.log(toChineseLowercase(123));        // 输出: 一百二十三
  2console.log(toChineseLowercase(101));        // 输出: 一百零一
  3console.log(toChineseLowercase(10));         // 输出: 十
  4console.log(toChineseLowercase(123.45));     // 输出: 一百二十三点四五
  5console.log(toChineseLowercase(0));          // 输出: 零
  6console.log(toChineseLowercase(-50));        // 输出: 负五十
  7console.log(toChineseLowercase(10000));      // 输出: 一万
  8console.log(toChineseLowercase(100000000));  // 输出: 一亿
  9console.log(toChineseLowercase(10005.02));   // 输出: 一万零五点零二
  

toEnglishUppercase(num)

• 功能: 将数字或小数转换为英文大写单词表示。
• 参数:
  • num (Number): 待转换的数字或小数。
• 返回值:
  • (String): 转换后的英文大写单词字符串。
• 例子:

  1console.log(toEnglishUppercase(0));            // 输出: ZERO
  2console.log(toEnglishUppercase(123));          // 输出: ONE HUNDRED AND TWENTY-THREE
  3console.log(toEnglishUppercase(1000));         // 输出: ONE THOUSAND
  4console.log(toEnglishUppercase(1234567.89));   // 输出: ONE MILLION TWO HUNDRED AND THIRTY-FOUR THOUSAND FIVE HUNDRED AND SIXTY-SEVEN POINT EIGHT NINE
  5console.log(toEnglishUppercase(-42));          // 输出: NEGATIVE FORTY-TWO
  6console.log(toEnglishUppercase(15));           // 输出: FIFTEEN
  

toEnglishLowercase(num)

• 功能: 将数字或小数转换为英文小写单词表示。
• 参数:
  • num (Number): 待转换的数字或小数。
• 返回值:
  • (String): 转换后的英文小写单词字符串。
• 例子:

  1console.log(toEnglishLowercase(0));            // 输出: zero
  2console.log(toEnglishLowercase(123));          // 输出: one hundred and twenty-three
  3console.log(toEnglishLowercase(1000));         // 输出: one thousand
  4console.log(toEnglishLowercase(1234567.89));   // 输出: one million two hundred and thirty-four thousand five hundred and sixty-seven point eight nine
  5console.log(toEnglishLowercase(-42));          // 输出: negative forty-two
  

日期时间处理

formatDate(input, format = "YYYY-MM-DD")

• 功能: 格式化日期对象或可解析为日期的字符串。
• 参数:
  • input (Date | String | Any): 日期对象、日期字符串或任何可以被 new Date() 解析的值。如果未提供或为 null，则默认为当前日期。
  • format (String, 可选, 默认值: "YYYY-MM-DD"): 格式化字符串，支持以下占位符：
    • YYYY: 四位年份 (e.g., 2023)
    • YY: 两位年份 (e.g., 23)
    • MM: 两位月份 (e.g., 01-12)
    • M: 一位月份 (e.g., 1-12)
    • DD: 两位日期 (e.g., 01-31)
    • D: 一位日期 (e.g., 1-31)
    • HH: 两位小时 (24小时制, e.g., 00-23)
    • H: 一位小时 (24小时制, e.g., 0-23)
    • mm: 两位分钟 (e.g., 00-59)
    • m: 一位分钟 (e.g., 0-59)
    • ss: 两位秒 (e.g., 00-59)
    • s: 一位秒 (e.g., 0-59)
• 返回值:
  • (String | null): 格式化后的日期字符串。如果输入是无效日期，则返回 null。
• 例子:

  1const now = new Date();
  2console.log(formatDate(now));                       // 输出: 2023-10-27 (假设当前日期)
  3console.log(formatDate("2023-01-05", "YY/M/D"));    // 输出: 23/1/5
  4console.log(formatDate("2023-10-27 14:30:05", "YYYY年MM月DD日 HH时mm分ss秒"));
  5// 输出: 2023年10月27日 14时30分05秒
  6console.log(formatDate("invalid date string"));     // 输出: null
  

formatDateTime(input)

• 功能: 格式化日期时间为 "YYYY-MM-DD HH:mm:ss" 格式。
• 参数:
  • input (Date | String | Any): 同 formatDate 的 input 参数。
• 返回值:
  • (String | null): 格式化后的日期时间字符串。
• 例子:

  1const now = new Date();
  2console.log(formatDateTime(now));                 // 输出: 2023-10-27 14:30:05 (假设当前日期时间)
  3console.log(formatDateTime("2022-03-15T08:00:00")); // 输出: 2022-03-15 08:00:00
  

formatTime(input)

• 功能: 格式化时间为 "HH:mm:ss" 格式。
• 参数:
  • input (Date | String | Any): 同 formatDate 的 input 参数。
• 返回值:
  • (String | null): 格式化后的时间字符串。
• 例子:

  1const now = new Date();
  2console.log(formatTime(now));                       // 输出: 14:30:05 (假设当前时间)
  3console.log(formatTime("2023-10-27 09:15:30"));     // 输出: 09:15:30
  

diffDays(date1, date2)

• 功能: 计算两个日期之间的天数差异（取绝对值并向上取整）。
• 参数:
  • date1 (Date | String | Any): 第一个日期。
  • date2 (Date | String | Any): 第二个日期。
• 返回值:
  • (Number | null): 两个日期之间的天数差异（正整数）。如果任何一个日期无效，则返回 null。
• 例子:

  1const d1 = new Date("2023-01-01");
  2const d2 = new Date("2023-01-03");
  3console.log(diffDays(d1, d2));                    // 输出: 2
  4console.log(diffDays("2023-10-20", "2023-10-25")); // 输出: 5
  5console.log(diffDays("2023-10-25", "2023-10-20")); // 输出: 5 (取绝对值)
  6console.log(diffDays("invalid", d2));             // 输出: null
  

dateToChineseUpper(input)

• 功能: 将日期转换为中文大写表示（年、月、日）。
• 参数:
  • input (Date | String | Any): 待转换的日期。
• 返回值:
  • (String): 转换后的中文大写日期字符串。如果日期无效，则返回 "无效日期"。
• 例子:

  1console.log(dateToChineseUpper("2023-10-27"));   // 输出: 贰零贰叁年拾月贰柒日
  2console.log(dateToChineseUpper("2023-01-05"));   // 输出: 贰零贰叁年壹月伍日
  3console.log(dateToChineseUpper(new Date()));     // 输出: 当前日期的中文大写
  

dateToChineseLower(input)

• 功能: 将日期转换为中文小写表示（年、月、日）。
• 参数:
  • input (Date | String | Any): 待转换的日期。
• 返回值:
  • (String): 转换后的中文小写日期字符串。如果日期无效，则返回 "无效日期"。
• 例子:

  1console.log(dateToChineseLower("2023-10-27"));   // 输出: 二零二三年十月二十七日
  2console.log(dateToChineseLower("2023-01-05"));   // 输出: 二零二三年一月五日
  3console.log(dateToChineseLower(new Date()));     // 输出: 当前日期的中文小写
  

dateToEnglishUpper(input)

• 功能: 将日期转换为英文大写表示（例如：OCTOBER 27, 2023）。
• 参数:
  • input (Date | String | Any): 待转换的日期。
• 返回值:
  • (String): 转换后的英文大写日期字符串。如果日期无效，则返回 "INVALID DATE"。
• 例子:

  1console.log(dateToEnglishUpper("2023-10-27"));   // 输出: OCTOBER 27, 2023
  2console.log(dateToEnglishUpper("2023-01-05"));   // 输出: JANUARY 5, 2023
  3console.log(dateToEnglishUpper(new Date()));     // 输出: 当前日期的英文大写
  

dateToEnglishLower(input)

• 功能: 将日期转换为英文小写表示（例如：october 27, 2023）。
• 参数:
  • input (Date | String | Any): 待转换的日期。
• 返回值:
  • (String): 转换后的英文小写日期字符串。如果日期无效，则返回 "invalid date"。
• 例子:

  1console.log(dateToEnglishLower("2023-10-27"));   // 输出: october 27, 2023
  2console.log(dateToEnglishLower("2023-01-05"));   // 输出: january 5, 2023
  3console.log(dateToEnglishLower(new Date()));     // 输出: 当前日期的英文小写