# @adonisjs/lucid-slugify 中文文档 规范地址：https://npmcn.com/package/%40adonisjs/lucid-slugify/ 版本：4\.0\.0 npm 元数据更新时间：2026-06-25T11:01:41.152Z 中文译文更新时间：2026-11-05T23:26:50.309Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40adonisjs/lucid-slugify 原文对照：https://npmcn.com/package/%40adonisjs/lucid-slugify/?lang=original 项目主页：https://github.com/adonisjs/lucid-slugify#readme 源码仓库：https://github.com/adonisjs/lucid-slugify ## 关键信息（来自 npm 元数据） - 包体积（解压后）：46.5 kB，17 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=24\.0\.0 - 运行依赖：1 个 - peer 依赖：@adonisjs/core ^7\.0\.0-next\.21 \|\| ^7\.0\.0，@adonisjs/lucid ^22\.0\.0-next\.1 \|\| ^22\.0\.0 - 首次发布：2018-02-24T08:20:29.461Z - 最新版本发布：2026-06-25T11:01:40.760Z - 近 30 天下载量：9638（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：18（近 12 个月 1 个） ## 中文简介 通过 Lucid 模型在您的数据库中生成并坚持独特的 swits ## 安装 ```sh npm install @adonisjs/lucid-slugify ``` 也可以使用：`pnpm add @adonisjs/lucid-slugify`、`yarn add @adonisjs/lucid-slugify`、`bun add @adonisjs/lucid-slugify` ## README # @ adonisjs/ lucid- sluglife( 污名) > 使用 Lucid 模型创建 URL 安全独有的 swits,并在数据库中坚持使用. [![gh-workflow-image](https://img.shields.io/github/actions/workflow/status/adonisjs/lucid-slugify/checks.yml?style=for-the-badge)](https://github.com/adonisjs/lucid-slugify/actions/workflows/checks.yml "Github action") [![npm-image](https://img.shields.io/npm/v/@adonisjs/lucid-slugify.svg?style=for-the-badge&logo=npm)](https://npmjs.org/package/@adonisjs/lucid-slugify "npm") ![](https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript) [![license-image](https://img.shields.io/npm/l/@adonisjs/lucid-slugify?color=blueviolet&style=for-the-badge)](https://npmcn.com/package/%40adonisjs/lucid-slugify/LICENSE.md "license") ## 导言 产生弹道很容易,但保持其独特性很困难. 此软件包将硬块摘要化, 并给出一个简单的 API , 用于创建和粘住数据库中独特的 satters . Lucid 为导出 `@slugify` 装饰器,您可以在模型字段上将其标记为 sults并定义产生 sults 的源字段. 在车盖下,装饰者登记 `beforeCreate` 财务报告和审定财务报表 `beforeUpdate` 钩来计算弹壳 并坚持到数据库. 在下面的例子中,我们指出: `slug` 字段,并使用 `title` 字段。 我们也使用 [db 增加数](https://npmcn.com/package/%40adonisjs/lucid-slugify/#readme-dbincrement) 保持喷口的独特性. ```ts import { PostSchema } from '#database/schema' import { slugify } from '@adonisjs/lucid-slugify' export default class Post extends PostSchema { @slugify({ strategy: 'dbIncrement', fields: ['title'], }) declare slug: string } ``` ## 安装和使用 你可以安装 `@adonisjs/lucid-slugify` npm 软件包注册处的软件包。 确保您的应用程序使用 `@adonisjs/core@7` 财务报告和审定财务报表 `@adonisjs/lucid@22`。 。 。 . ```sh npm i @adonisjs/lucid-slugify ``` ```sh yarn add @adonisjs/lucid-slugify ``` ```sh pnpm add @adonisjs/lucid-slugify ``` 完成后,可以使用 `@slugify` 装饰师. 确定要指定源字段来生成流星 . ```ts import { PostSchema } from '#database/schema' // 👇 Import decorator import { slugify } from '@adonisjs/lucid-slugify' export default class Post extends PostSchema { // 👇 Use it on a column @slugify({ fields: ['title'], }) declare slug: string } ``` 装饰者仅在柱子尚未有值时才计算出弹簧. 如果您手动为 sullet 列分配一个值, 您的值将保持不变 . ## 流涕的独特性 在前一个例子中,如果设立两个员额时使用相同的员额 `title`,他们会有相同的 `slug` 数值. 如果你是唯一的博客作者. 然而,如果这是一个社区博客或论坛,创建两个或两个以上同名文章的机会相当高. 您可以使用以下策略之一来防止重复的弹簧,即使标题相同. ### db 增加数 这个 `dbIncrement` 策略执行一个选择的查询,在找到重复的 sattle 时查找类似的 sattle 并附加一个计数器。 鉴于您有一个有下列弹片的数据库表: - 创建员额 `slug=hello-world` 将会导致 `hello-world-6`。 。 。 . - 类似地,设立一个员额 `slug=introduction-to-social-auth` 将会导致 `introduction-to-social-auth-5`。 。 。 . ``` +----+-----------------------------+-------------------------------+ | id | title | slug | +----+-----------------------------+-------------------------------+ | 1 | Hello world | hello-world | | 2 | Hello world | hello-world-5 | | 3 | Hello world | hello10world | | 4 | Hello world | hello-10-world | | 5 | Introduction to social auth | introduction-to-social-auth | | 6 | Introduction to social auth | introduction-to-social-auth-4 | | 7 | Hello world | hello-world-2 | | 8 | Hello world fanny | hello-world-fanny | | 9 | Hello world | post-hello-world | | 10 | Hello world | post-11am-hello-world11 | | 11 | Hello world | post-11am-hello-world | | 12 | Introduction to social auth | introdUction-to-Social-auTH-1 | +----+-----------------------------+-------------------------------+ ``` 这一策略使用与正在坚持的模型相同的数据库连接,并与PostgreSQL,MySQL(包括5.7),SQLite,和SQL Server合作. 使用它与任何其他方言抛出 [`E_UNSUPPORTED_DB_DIALECT`](https://npmcn.com/package/%40adonisjs/lucid-slugify/#readme-errors) 除外. ### 缩写 这个 `shortId` 战略附件a **10 个字符短 id** 让它变得独一无二 此策略不执行任何额外的数据库查询. ```ts export default class Post extends PostSchema { @slugify({ strategy: 'shortId', fields: ['title'], }) declare slug: string } ``` ``` +----+-------------+------------------------+ | id | title | slug | +----+-------------+------------------------+ | 1 | Hello world | hello-world-yRPZZIWGgC | +----+-------------+------------------------+ ``` ### 无战略 当您没有指定策略时, 弹壳会生成并持续不变, 没有任何独特的保证 。 这是默认的行为,在源字段已经独一无二(例如SKU或电子邮件地址)时是合适的. ## 更新语句 默认情况下,在更新模型实例时不会更新 sults,在使用 sults 查找记录时应该如此,因为改变 sults 会导致 URL 损坏. 然而,如果不主要用来查阅记录,你可能想要更新记录. 您可以通过使用 `allowUpdates` 旗帜. ```ts export default class Post extends PostSchema { @slugify({ strategy: 'dbIncrement', fields: ['title'], allowUpdates: true, // 👈 }) declare slug: string } ``` 启用更新时, 仅当其中一个来源时才会重算 sattle `fields` 已修改。 如果手动突变了弹道柱,则你的值优先,而弹道柱不重算. 您也可以将一个函数传递给 `allowUpdates` 以在运行时决定是否应该为特定模型实例更新弹出. ```ts @slugify({ fields: ['title'], allowUpdates: (post) => post.status === 'draft', }) declare slug: string ``` ## 无效值和弹片生成 这个 `slugify` 当一个或多个源字段的值是时,装饰器不会生成 satters `undefined` 或者说 `null`。 。 。 . ## 可用选项 以下是秘书处接受的现有备选方案清单 `@slugify` 装饰师.
{
"fields":

用于生成弹片的源字段数组 。 使用 config.separator 属性. 这是唯一必要的选择.

"strategy":

用来保持鼻涕的策略 它可以是先前已有的战略名称之一(英语:"dbIncrement" 或者说 "shortId")或返回自定义策略执行的工厂函数。 默认不处理独有性 .

"allowUpdates":

启用更新的布尔, 或接收模型实例并返回布尔的函数 . 默认更新已禁用。 。 。 .

"maxLength":

生成的弹簧的最大长度 。 最后的弹出值可以略高于定义 maxLength (b) 在下列各种情况下.

默认情况下没有应用最大长度 .

  • 何时 completeWords 被设定为真实.
  • 使用时 dbIncrement 战略。 计数器在切换 maxLength。 。 。 .
"completeWords":

一个布尔,在应用 maxLength 属性。 完成单词将产生比 maxLength因此,在最大Length属性和数据库存储大小之间保持一些缓冲.

完整的单词默认被禁用 .

"separator":

用来创建弹壳的分隔符 . 一个破折号 - 默认使用.

"transformer":

将非字符串源值转换为字符串的自定义函数,然后将其击出 。 它接收模型实例,字段名称,和字段值,必须返回字符串.

默认情况下,布尔转换为 "1" 或者说 "0", (中文(简体) ), Date 使用 date.toJSON(),其他所有东西都使用 String(value)。 。 。 .

}
### 从多字段生成弹片 当指定多个字段时,它们的值会使用 `separator` (以定律为序)而结果为浊. ```ts @slugify({ fields: ['seriesName', 'title'], separator: '-', }) declare slug: string ``` ### 自定义变压器 这个 `transformer` 当一个源字段拥有一个丰富的数据类型,而该类型不应使用默认规则被字符串时,它是有用的. ```ts @slugify({ fields: ['title', 'publishedAt'], transformer: (post, field, value) => { if (field === 'publishedAt' && value instanceof DateTime) { return value.toFormat('yyyy-MM-dd') } return String(value) }, }) declare slug: string ``` ## 使用自定义策略 自定义策略可以使用,如果您想要自己处理流涕的独特性. 战略必须执行 [`SlugifyStrategyContract`](https://npmcn.com/package/%40adonisjs/lucid-slugify/#readme-slugifystrategycontract) 接口. ```ts import { LucidRow } from '@adonisjs/lucid/types/model' import { SlugifyStrategyContract } from '@adonisjs/lucid-slugify/types' export class MyCustomStrategy implements SlugifyStrategyContract { maxLengthBuffer: number = 0 async makeSlugUnique(modelInstance: LucidRow, field: string, value: string) { return value } } ``` 这个 `makeSlugUnique` 方法收到下列参数. - `modelInstance`: 参考数据库中将持续存在的模型实例. - `field`: 将创建出独有的弹簧的字段名称. - `value`: 转换为唯一值的基准值. 一旦你创造了战略,你可以使用它与 `@slugify` 通过将它注册为工厂功能来装饰. 工厂接收了模型类,地产名和已解析的装饰者配置,允许您以相同的配置构建策略. ```ts export default class Post extends PostSchema { @slugify({ strategy: (model, propertyName, config) => { return new MyCustomStrategy() }, fields: ['title'], }) declare slug: string } ``` 内置的策略类也被输出出,因此可以从工厂函数中再用或扩展. ```ts import { DbIncrementStrategy, ShortIdStrategy } from '@adonisjs/lucid-slugify/strategies' ``` ## 自行创建弹片 Lucid srushify 用于创建 srushs 的默认执行用英语单词很有效 。 然而,如果您正在使用非拉丁字母,请用自定义的字母替换创建 swits 的执行 . 您可以覆盖静态 `slugify` 方法 `Slugifier` 课。 以下代码只能执行一次(例如,在服务提供商内部). ```ts import { Slugifier } from '@adonisjs/lucid-slugify' /** * Make sure to install the "transliteration" package */ import { slugify } from 'transliteration' Slugifier.slugify = function (value, options) { return slugify(value, { separator: options.separator, lowercase: options.lower, }) } ``` ## API 参考 ### 入境点 | 导入路径 | 出口 | | --- | --- | | `@adonisjs/lucid-slugify` | [`slugify`](https://npmcn.com/package/%40adonisjs/lucid-slugify/#readme-slugify-config) 装饰者, [`Slugifier`](https://npmcn.com/package/%40adonisjs/lucid-slugify/#readme-slugifier) 班级, [`errors`](https://npmcn.com/package/%40adonisjs/lucid-slugify/#readme-errors) | | `@adonisjs/lucid-slugify/strategies` | `DbIncrementStrategy`, (中文(简体) ), `ShortIdStrategy` | | `@adonisjs/lucid-slugify/types` | `SlugifyConfig`, (中文(简体) ), `SlugifierConfig`, (中文(简体) ), [`SlugifyStrategyContract`](https://npmcn.com/package/%40adonisjs/lucid-slugify/#readme-slugifystrategycontract) | ### 拼写( 配置) 一个将Lucid模型柱标为"一发"的财产装饰. 登记 `beforeCreate` 财务报告和审定财务报表 `beforeUpdate` 在模型上悬钩来计算并坚持弹道. ```ts import { slugify } from '@adonisjs/lucid-slugify' @slugify({ fields: ['title'], strategy: 'dbIncrement' }) declare slug: string ``` 见 [可用选项](https://npmcn.com/package/%40adonisjs/lucid-slugify/#readme-available-options) 用于完整的已接受的配置属性列表. ### 分解器 那种能产生弹子的阶级 你通常不直接与它互动—— `@slugify` 装饰器创建和管理 a `Slugifier` 每个弹出字段的实例. 与最终用户有关的一个成员是静态 `slugify` 方法,将一个字符串转换成一个 URL-安全的 swit。 覆盖它以插入自定义的 spotification 常规( 见 [自行创建弹片](https://npmcn.com/package/%40adonisjs/lucid-slugify/#readme-self-creating-slugs)) (中文(简体) ). ```ts Slugifier.slugify(value: string, options: { separator: string; lower: boolean }): string ``` ### 战略合同 每个策略(内置或自定义)执行的接口. ```ts interface SlugifyStrategyContract { /** * The number of characters the strategy may add to the slug to make it * unique. The slugifier reserves this many characters when applying the * `maxLength` option, so the final value stays within the column size. */ maxLengthBuffer: number /** * Convert the computed slug value into a unique value that is safe to * persist to the database. */ makeSlugUnique(modelInstance: LucidRow, field: string, value: string): Promise | string } ``` ### 错误 软件包输出其例外 `errors` 名称空间. ```ts import { errors } from '@adonisjs/lucid-slugify' errors.E_UNSUPPORTED_DB_DIALECT ``` | 例外 | 升起时 | | --- | --- | | `E_UNSUPPORTED_DB_DIALECT` | 这个 `dbIncrement` 战略使用它不支持的数据库方言. | ## 捐款 AdonisJS的主要目标之一是建立一个充满活力的用户和贡献者社区,他们相信框架的原则. 我们鼓励你读 [捐款指南](https://github.com/adonisjs/.github/blob/main/docs/CONTRIBUTING.md) 在对框架作出贡献之前. ## 行为守则 为确保AdonisJS社区欢迎所有人,请审查并遵守 [行为守则](https://github.com/adonisjs/.github/blob/main/docs/CODE_OF_CONDUCT.md)。 。 。 . ## 许可证 阿多尼斯·贾克 Lucid switify是开源软件,根据该软件许可 [麻省理工学院许可证](https://npmcn.com/package/%40adonisjs/lucid-slugify/LICENSE.md)。 。 。 . ## 常见问题 ### @adonisjs/lucid-slugify 是什么？ 通过 Lucid 模型在您的数据库中生成并坚持独特的 swits ### 如何安装 @adonisjs/lucid-slugify？ 在项目目录运行 npm install @adonisjs/lucid-slugify，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@adonisjs/core（^7\.0\.0-next\.21 \|\| ^7\.0\.0）、@adonisjs/lucid（^22\.0\.0-next\.1 \|\| ^22\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @adonisjs/lucid-slugify 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @adonisjs/lucid-slugify 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @adonisjs/lucid-slugify 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @adonisjs/lucid-slugify 可以商用吗？ @adonisjs/lucid-slugify 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @adonisjs/lucid-slugify 的下载量有多少？ 根据 npm 官方下载统计，@adonisjs/lucid-slugify 在 2026/10/05 – 2026/11/03 这 30 天内被下载 9,638 次，日均约 321 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @adonisjs/lucid-slugify 还在维护吗？ 最新版本 4\.0\.0 发布于 2026/06/25（4 个月前）；至今共发布 18 个版本，其中过去 12 个月发布了 1 个；首次发布于 2018/02/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。