# @happyvertical/smrt-tags 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-tags/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:54:09.832Z
中文译文更新时间：2026-11-17T09:31:48.248Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/smrt-tags
原文对照：https://npmcn.com/package/%40happyvertical/smrt-tags/?lang=original
项目主页：https://github.com/happyvertical/smrt#readme
源码仓库：https://github.com/happyvertical/smrt

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：275 kB，31 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2026-06-23T01:18:52.063Z
- 最新版本发布：2026-11-17T07:54:09.634Z
- 近 30 天下载量：32992（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：365（近 12 个月 365 个）

## 中文简介

可重复使用的标记系统,其等级、上下文和多种语言支持SMRT框架

## 安装

```sh
npm install @happyvertical/smrt-tags
```

也可以使用：`pnpm add @happyvertical/smrt-tags`、`yarn add @happyvertical/smrt-tags`、`bun add @happyvertical/smrt-tags`

## README

# @happyvertical/ smrt-tags (欢快的垂直)

以上下文镜所标注的鼻涕、多语种别名和鼻涕装置进行分级标记.

## 安装

```bash
pnpm add @happyvertical/smrt-tags
```

## 使用量

```typescript
import { Tag, TagCollection, TagAlias, TagAliasCollection } from '@happyvertical/smrt-tags';
import { sanitizeSlug, validateSlug, generateUniqueSlug } from '@happyvertical/smrt-tags';

// Create a tag hierarchy
const collection = await TagCollection.create();

// `collection.create(...)` returns the saved row, so use it directly
// instead of `new Tag()` + a separate `.create(...)` step. The returned
// instance has its persisted `id` set for use as a parent reference.
const tech = await collection.create({
  slug: 'technology',
  name: 'Technology',
  context: 'blog', // defaults to 'global' if omitted
});

// Children reference their parent by UUID (`parentId`). With `tech`
// already saved, pass `tech.id` directly. `level` is recalculated by
// `TagCollection.moveTag` / `mergeTag` for later moves; you can pass it
// explicitly on create or let it stay at 0 and call moveTag later.
const ai = await collection.create({
  slug: 'artificial-intelligence',
  name: 'Artificial Intelligence',
  context: 'blog',
  parentId: tech.id,
  level: 1,
});

// Traverse hierarchy
const children = await tech.getChildren();
const ancestors = await ai.getAncestors();

// Context scoping -- same slug, different contexts
const blogNews = new Tag({ slug: 'news', name: 'News', context: 'blog' });
const forumNews = new Tag({ slug: 'news', name: 'Forum News', context: 'forum' });

// Multi-language aliases
const aliasCollection = await TagAliasCollection.create();
const alias = new TagAlias({
  tagSlug: 'technology',
  alias: 'Tecnologia',
  language: 'es',
  context: 'blog',
});
await aliasCollection.create(alias);

// Collection operations. Slug args resolve through (slug, context) —
// pass an explicit context when the same slug exists in multiple
// contexts, otherwise the resolver throws on ambiguity.
await collection.moveTag('artificial-intelligence', 'technology', 'blog'); // cycle-checked
await collection.mergeTag('source', 'target', 'blog');                     // moves children + aliases, deletes source
await collection.cleanupUnused();                                          // deletes tags with no children and no aliases

// Slug utilities
sanitizeSlug('My Cool Tag!');   // 'my-cool-tag'
validateSlug('my-tag-123');     // true
```

## API 密码

### 模型( smrt 对象)

| 导出 | 说明 |
| --- | --- |
| `Tag` | 已确认 `slug` + 键 `context`。通过 `parentId` (UUID,从 `SmrtHierarchical`) (中文(简体) ). 非正常状态 `level` 重新计算 `TagCollection.moveTag` 编号 : `mergeTag`贾森 `metadata`继承的等级方法: `getParent()`, (中文(简体) ), `getChildren()`, (中文(简体) ), `getAncestors()`, (中文(简体) ), `getDescendants()`, (中文(简体) ), `getHierarchy()`, (中文(简体) ), `moveTo()`。拥有帮助者: `getMetadata()`, (中文(简体) ), `setMetadata()`, (中文(简体) ), `updateMetadata()` |
| `TagAlias` | 特定语文翻译: `tagSlug`, (中文(简体) ), `alias`, (中文(简体) ), `language` (ISO 639-1),可选 `context` |

### 收藏( 收藏)

| 导出 | 说明 |
| --- | --- |
| `TagCollection` | CRUD + 软件 `getOrCreate()`, (中文(简体) ), `moveTag()`, (中文(简体) ), `mergeTag()`, (中文(简体) ), `cleanupUnused()`, (中文(简体) ), `findWithGlobals()` |
| `TagAliasCollection` | 标记别名的 CRUD |

### 公用事业

| 导出 | 说明 |
| --- | --- |
| `sanitizeSlug(input)` | 干净并格式化 switch 字符串 |
| `validateSlug(slug)` | 验证 sattle 格式( 小写, 字母数 + 连字符) |
| `generateUniqueSlug(name, context, collection)` | 自动编号独有的弹片生成 |
| `calculateLevel(parentSlug, collection)` | 从父定义等级深度 |
| `hasCircularReference(slug, parentSlug, collection)` | 检测循环父引用 |

### 类型

| 导出 | 说明 |
| --- | --- |
| `TagOptions` | 备选方案 `Tag` 构造器 |
| `TagAliasOptions` | 备选方案 `TagAlias` 构造器 |
| `TagMetadata` | 灵活的元数据结构(颜色、图标、统计) |
| `TagHierarchy` | 完整的等级结果(祖先、现世、后代) |

## 依赖关系

| 软件包 | 目的 |
| --- | --- |
| `@happyvertical/smrt-core` | ORM 基础( Smrt Object, Smrt Collection) |
| `@happyvertical/smrt-tenancy` | 备选租户范围界定 |

## 常见问题

### @happyvertical/smrt-tags 是什么？

可重复使用的标记系统,其等级、上下文和多种语言支持SMRT框架

### 如何安装 @happyvertical/smrt-tags？

在项目目录运行 npm install @happyvertical/smrt-tags，或使用 pnpm add / yarn add / bun add。

### @happyvertical/smrt-tags 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @happyvertical/smrt-tags 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @happyvertical/smrt-tags 可以商用吗？

@happyvertical/smrt-tags 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @happyvertical/smrt-tags 的下载量有多少？

根据 npm 官方下载统计，@happyvertical/smrt-tags 在 2026/10/17 – 2026/11/15 这 30 天内被下载 32,992 次，日均约 1,100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @happyvertical/smrt-tags 还在维护吗？

最新版本 0\.62\.1 发布于 2026/11/17（今天）；至今共发布 365 个版本，其中过去 12 个月发布了 365 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

