richtext-icons

RtiIcons · 富文本编辑器图标库

一套面向富文本编辑器（WYSIWYG）场景的 SVG 图标库，基于 Vite 8 + Vue 3， 以 纯 ESM 发布（仅支持 Vue 3，内置 TypeScript 类型声明）。

核心设计：SVG 是唯一事实来源。 你只负责往 icons/ 里放画好的 SVG 文件， 生成器负责把它编译成 Vue 组件、类型声明和预览清单 —— 不需要手写任何包装代码。

快速开始（库使用者）

npm install richtext-icons

<script setup lang="ts">
import { RtiBold } from 'richtext-icons'
</script>

<template>
  <RtiBold style="font-size: 20px" />
</template>

完整文档（介绍 / 安装 / 使用 / 图标浏览）见预览站，npm run dev 后访问 http://127.0.0.1:5273。

预览站支持：分类浏览、中英文/关键词搜索（按 / 聚焦）、 颜色与深浅色主题切换、点击图标查看详情并一键复制 SVG / 组件用法。

命令

目录结构

richtext-icons/
├── icons/                 ★ 图标源文件，目录即分类
│   ├── format/bold.svg
│   └── color/background.svg
├── icons-meta.json        可选：中文名 / 关键词 / 状态
├── icon.config.mjs        前缀、分类清单
├── scripts/
│   ├── generate.mjs       生成器入口
│   └── lib/svg.mjs        SVG 解析与规范化
├── src/
│   ├── icons/             生成：Vue 组件（勿手改）
│   ├── generated/         生成：库入口 + 预览清单（勿手改）
│   ├── components/        预览站 UI
│   ├── composables/useIconLibrary.ts
│   ├── styles/base.css    设计令牌（亮/暗主题）
│   └── types.ts           IconMeta 等公共类型
└── dist/                  库构建产物

添加一个图标

1. 把 SVG 放进对应分类目录，例如 icons/align/align-left.svg

2. （可选）在 icons-meta.json 里补中文名和搜索关键词：

   "align/align-left": {
     "zh": "左对齐",
     "keywords": ["align left", "左对齐", "靠左"]
   }
   

3. 运行 npm run gen，组件 RtiAlignLeft 自动生成并出现在预览站

新增分类：在 icon.config.mjs 的 categories 数组里加一行，并创建同名目录。

SVG 文件约定

• 画布统一 viewBox="0 0 24 24"
• 颜色一律用 currentColor，不要写死色值（预览站的颜色调节依赖它）
• 描边风格：fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"；填充风格直接 fill="currentColor" （描边宽度统一写在源文件根节点的 stroke-width="1.5"，随尺寸等比缩放，生成器直接透传）
• 不要写死 width/height（会被替换为固定的 1em）、不要带 id/class/内联样式
• 生成器会自动丢弃无用根属性、剔除 <title>/<desc>/注释，并在 仅描边时补 fill="none"、无 fill/stroke 时按 currentColor 填充处理

组件用法

import { RtiBold, RtiAlignLeft, iconList } from 'richtext-icons'

<RtiBold />
<RtiBold style="color: #2f6feb; font-size: 20px" />
<RtiAlignLeft style="font-size: 1.5em" />

<!-- 动态渲染：iconList 以组件名为键 -->
<component :is="iconList['RtiBold']" />

图标没有 prop：宽高固定 1em，尺寸跟随所在元素的 font-size；颜色跟随 color；描边宽度固定 1.5 用户单位。其余 SVG 属性（class、style、事件等） 透传到 <svg> 根节点。

构建产物

dist/
├── index.js               纯 ESM 组件库（vue 为 peerDependency）
├── index.d.ts             类型声明（随图标自动更新）
├── metadata.js            纯元数据入口（零 Vue 依赖，供 AI / 工具链检索）
├── metadata.d.ts          轻量元数据类型（IconMetaLite）
└── types.d.ts             公共类型（IconMeta 等）

dist/ 内没有嵌套 package.json —— 发布从仓库根目录进行， 根 package.json 的 files: ["dist"] 与 exports 指向 ./dist/* 即为唯一真身。

纯元数据入口（供 AI / 工具链检索）

不引入 Vue 组件、不含 SVG 源码，可直接在 Node 中按语义检索图标：

import { icons, categories, total } from 'richtext-icons/metadata'

// 按用途标签（tags）检索：找所有「行操作」的表格图标
const rowOps = icons.filter((i) => i.tags.includes('行操作'))

每个条目包含 name / path / component / zh / en / keywords / tags / category / status / style / viewBox。tags 是用途语义标签（如「表格」「行操作」 「主题」「协作」），用于 AI 按场景理解图标用途，区别于 keywords 的近义词检索。

发布

发布组件库到 npm

前置检查

• Node ≥ 22.12（engines 约束）
• 已登录 npm：npm login；CI 上改用 NPM_TOKEN 环境变量
• 根目录有 LICENSE 文件，且与 package.json 的 license 字段（MIT）一致
• 工作树干净，npm run typecheck 通过

步骤

# 1. 递增版本号（默认会一并提交并打 git tag；只想改文件加 --no-git-tag-version）
npm version patch          # patch / minor / major

# 2. 构建 + 核对将被发布的文件清单（不会真的发布）
npm run build:lib
npm publish --dry-run

# 3. 发布
npm publish

# 4. 验证
npm view richtext-icons version

要点

• 从仓库根目录发布：files: ["dist"] 决定打包内容，exports 指向 ./dist/*。 dist/ 里不要放嵌套 package.json，否则会打包出双层包结构。
• prepublishOnly 已挂 npm run build:lib，所以 npm publish 一定会带上最新产物， 不会发出过期构建；但不会替你做前置检查，typecheck 还得自己先跑。
• vue 是 peerDependencies（^3.0.0），不进产物；使用时由宿主的 Vue 提供。
• 发布后对外共三个入口：.（组件）、./metadata（纯元数据，零 Vue 依赖）、./types。
• 图标有增删时记得同步文档里的计数（README.md 概述段 + 分类表、AGENTS.md 规模行）， 以 npm run gen 输出的「图标 N 个 · 分类 M 个」为准。

部署文档站

./deploy.sh

等价于 npm run build:site 构建到 dist-site/，再 rsync 同步到静态托管目录， 访问 https://richtext-icons.wzt.zone/。

deploy.sh 内含服务器地址，未纳入版本库（见 .gitignore）；换机器部署需自行重建。

分类规划

全部 14 个分类已建成，共 155 个图标，统一为线性描边风格 （24×24 画布、圆角端点、currentColor，描边宽度固定 1.5 用户单位）。

缺图标时把 SVG 放进对应目录、在 icons-meta.json 补中文名，npm run gen 即可。 待补清单见 docs/icon-gaps.md。