博客Dashboard
Utility FunctionsFormatting

formatCutoff

使用支持 locale 感知终止符的独立函数来截断字符串

概览

独立的 formatCutoff 函数可以根据各个 locale 使用合适的结尾标记来截断字符串，而不需要 GT 实例。 它提供了具备 locale 感知能力的文本截断功能，能够遵循不同语言在省略号字符和空格上的使用规范。

import { formatCutoff } from 'generaltranslation';

const formatted = formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: 8
});
// 返回："Hello, w…"

参考

参数

名称类型描述
valuestring要截断的字符串
optionsCutoffFormatOptions & { locales?: string | string[] }截断配置选项

CutoffFormatOptions

NameTypeDescription
locales?string | string[]用于选择终止符的 locales
maxChars?number要显示的最大字符数。undefined 表示不截断。负数表示从末尾开始截取
style?'ellipsis' | 'none'终止符样式。默认值为 'ellipsis'
terminator?string自定义终止符，用于覆盖 locale 默认值
separator?string终止符与文本之间的自定义分隔符

返回值

string - 应用了适当终止符号的截断字符串。

行为

字符数限制

  • 正数 maxChars：从开头开始截断，并在末尾追加终止符号
  • 负数 maxChars：从结尾开始截取，并在开头添加终止符号
  • 零值 maxChars：返回空字符串
  • 未定义的 maxChars：不进行截断

按 locale 区分的结束符号

不同 locale 对省略号有不同的约定：

  • 法语：…，前加窄不换行空格（\u202F）
  • 中文/日文：双省略号 ……，中间不加分隔符
  • 默认：单个省略号 …，中间不加分隔符

边界情况

  • 如果 terminator + separator 的长度超过 maxChars，则返回空字符串
  • 原始字符串长度小于 maxChars 时将原样返回
  • 'none' 样式截断时不添加任何 terminator

示例

基本用法

import { formatCutoff } from 'generaltranslation';

// 基本截断
console.log(formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: 8
}));
// 输出："Hello, w…"

// 无需截断
console.log(formatCutoff('Short', {
  locales: 'en-US', 
  maxChars: 10
}));
// 输出："Short"

负字符数限制

// 从末尾截取
console.log(formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: -3
}));
// 输出:"…ld!"

// 更大的负数截取
console.log(formatCutoff('JavaScript', {
  locales: 'en-US',
  maxChars: -6
}));
// 输出:"…Script"

特定 locale 的终止符

// 法语格式
console.log(formatCutoff('Bonjour le monde', {
  locales: 'fr-FR',
  maxChars: 10
}));
// 输出:"Bonjour\u202F…"(省略号前的窄空格)

// 中文格式
console.log(formatCutoff('你好世界', {
  locales: 'zh-CN',
  maxChars: 3
}));
// 输出:"你好……"

// 日语格式  
console.log(formatCutoff('こんにちは', {
  locales: 'ja-JP',
  maxChars: 4
}));
// 输出:"こん……"

自定义终止符

// 自定义终止符
console.log(formatCutoff('Long text here', {
  locales: 'en-US',
  maxChars: 10,
  terminator: '...'
}));
// 输出："Long te..."

// 带分隔符的自定义终止符
console.log(formatCutoff('Another example', {
  locales: 'en-US',
  maxChars: 12,
  terminator: '[more]',
  separator: ' '
}));
// 输出："Anoth [more]"

// 无终止符
console.log(formatCutoff('Clean cut', {
  locales: 'en-US',
  maxChars: 5,
  style: 'none'
}));
// 输出："Clean"

工具函数

import { formatCutoff } from 'generaltranslation';

// 截断文本以便在 UI 中显示
function displayText(text: string, maxLength: number, locale = 'en-US') {
  return formatCutoff(text, {
    locales: locale,
    maxChars: maxLength
  });
}

// 多语言截断
function truncateByLocale(text: string, locale: string) {
  const limits = {
    'en': 50,
    'de': 45, // 德语单词通常较长
    'zh': 30, // 中文字符信息密度更高
  };
  
  return formatCutoff(text, {
    locales: locale,
    maxChars: limits[locale] || 50
  });
}

console.log(displayText('This is a very long description', 15));
// 输出:"This is a ve…"

console.log(truncateByLocale('Eine sehr lange deutsche Beschreibung', 'de'));
// 输出:"Eine sehr lange deutsche Besch…"

注意事项

  • 与 GT class 的方法不同，locales 参数是可选的，默认值为 'en'
  • 对于重复的 locale/options 组合，结果会在内部进行缓存，以提升性能
  • 在字符数上限的计算中会将终止符的长度计入在内
  • 自定义终止符会覆盖基于 locale 的默认值
  • 当没有终止符时，会忽略分隔符

后续步骤

本指南如何?

standardizeLocale

GT standardizeLocale 方法 API 参考

formatDateTime

独立函数，用于按照 locale 习惯格式化日期和时间

本页目录

概览
参考
参数
CutoffFormatOptions
返回值
行为
字符数限制
按 locale 区分的结束符号
边界情况
示例
基本用法
负字符数限制
特定 locale 的终止符
自定义终止符
工具函数
注意事项
后续步骤