slugify

`sindresorhus/slugify` 可将多语言字符串转写为适合网址、文件名和标识使用的安全短标识,并支持自定义转换规则与分隔符。

开源项目

项目信息

文章目录

这是什么

sindresorhus/slugify 是一个把普通字符串整理成 slug 的开源工具。这里的 slug 不是随机哈希,而是保留可读语义、适合放入网址、文件名和标识中的文本。默认情况下,它会统一小写、使用连字符分隔单词,并清理符号、空格和多余分隔符,例如把 Déjà Vu! 变成 deja-vu,把 fooBar 123 $#% 变成 foo-bar-123。

它的价值不只是“去掉特殊字符”。项目支持德语变音符号、越南语、阿拉伯语、俄语等主要语言,并可通过 locale 选择语言相关的转写结果。瑞典语 Räksmörgås 在指定 locale: 'sv' 后可得到 raksmorgas。驼峰命名也会被拆成独立单词,让变量名、业务标题和文章标题更易读。

该项目主要使用 JavaScript,采用 MIT 许可证,最新版本为 v3.0.2,在 GitHub 上获得 2710 个 Star。其流程可以概括为“先转写,再清理,最后输出”:Unicode 内容先转换为可接受的字符,再由选项控制大小写、分隔符和保留规则,适合作为 URL 路由、文章锚点、对象 ID 或文件名生成流程中的基础工具。仓库地址为 https://github.com/sindresorhus/slugify。

适合谁用

适合需要在 Node.js 或其他 JavaScript 环境中处理 slug 的开发者。后台收到带空格、中文或标点的标题,需要生成 URL 片段;文档系统需要把章节标题转换为锚点;业务代码希望把名称整理成便于复制和传递的标识,都可以把它作为统一的前置步骤。

如果项目需要保留驼峰原貌、下划线开头、结尾短横线或某个 URL 片段字符,也有对应开关。对于重复标题,可用带计数器的实例生成 foo-bar、foo-bar-2,让同一文档中的多个小节拥有不同锚点。

亮点

  • 多语言转写:支持德语变音符号、越南语、阿拉伯语和俄语等,并可按 locale 调整。
  • 默认结果易读:自动小写、拆分驼峰,并以连字符连接单词。
  • 输出规则可配置:separator、lowercase、decamelize 和 transliterate 可分别调整。
  • 特殊语义可保留:可保留下划线开头、结尾短横线及指定字符。
  • 重复值有计数器:slugifyWithCounter 可为重复结果追加序号并重置。

怎么用

先通过 npm 安装这个包:

npm install @sindresorhus/slugify

安装后,在使用 ES Module 的 JavaScript 项目中导入默认函数即可。slugify() 接收字符串和可选配置,返回处理后的字符串:

import slugify from '@sindresorhus/slugify';

slugify('I ♥ Dogs');
//=> 'i-love-dogs'

slugify('  Déjà Vu!  ');
//=> 'deja-vu'

slugify('я люблю единорогов');
//=> 'ya-lyublyu-edinorogov'

slugify('fooBar', {decamelize: false});
//=> 'foobar'

基础调用会使用默认配置。需要自定义时,可通过 separator 改用下划线或取消分隔符,通过 lowercase 控制大小写,通过 decamelize 决定是否拆分驼峰。customReplacements 会在其他转换前执行,默认包含 &、🦄 和 ♥ 的替换;传入相同键即可覆盖默认项,替换值两侧的空格会影响最终分隔符。

slugify('BAR and baz', {separator: '_'});
//=> 'bar_and_baz'

slugify('Déjà Vu!', {lowercase: false});
//=> 'Déjà-Vu'

slugify('Foo@unicorn', {
	customReplacements: [
		['@', ' at ']
	]
});
//=> 'foo-at-unicorn'

转写层面,locale 可以选择特定语言的规则;关闭 transliterate 后,非 ASCII 字符会直接保留。对于有特殊含义的边界字符,还可以选择保留下划线开头、结尾短横线,以及不能与分隔符重复的指定字符。

slugify('Räksmörgås', {locale: 'sv'});
//=> 'raksmorgas'

slugify('Déjà Vu', {transliterate: false});
//=> 'déjà-vu'

slugify('_foo_bar', {preserveLeadingUnderscore: true});
//=> '_foo-bar'

slugify('foo-bar-', {preserveTrailingDash: true});
//=> 'foo-bar-'

slugify('foo_bar#baz', {preserveCharacters: ['#']});
//=> 'foo-bar#baz'

如果同一份文档中存在重复标题,可以使用 slugifyWithCounter() 创建带计数的新实例。实例会为重复结果追加序号,调用 reset() 后重新开始计数。

import {slugifyWithCounter} from '@sindresorhus/slugify';

const uniqueSlug = slugifyWithCounter();

uniqueSlug('foo bar');
//=> 'foo-bar'

uniqueSlug('foo bar');
//=> 'foo-bar-2'

uniqueSlug.reset();

uniqueSlug('foo bar');
//=> 'foo-bar'

注意事项

  • customReplacements 会在其他转换之前执行,相同键会覆盖默认替换;替换值两侧是否留空格也会影响最终分隔符。preserveCharacters 不能包含 separator,而且即使保留撇号,词尾的 's 或 't 仍会被删除。
  • 该项目解决的是可读 slug 生成,不等同于通用安全过滤或严格的文件系统文件名校验。若必须得到合法且安全的文件名,可关注仓库列出的 filenamify;带计数器的实例则应在其自身生命周期内使用,并在需要时调用 reset()。

国内镜像下载

这个项目已经镜像到站长自己的服务器,GitHub 打不开、或者下载太慢的时候,直接从这里拿。

项目与资料

整理自本文的外部链接,请以来源页面说明为准。

slugify · 阿凡达博客