# smo-editor

**Repository Path**: sanmokeji/smo-editor

## Basic Information

- **Project Name**: smo-editor
- **Description**: 富文本
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-03
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @sanmokeji/smo-editor

🚀 **SmoEditor** 是一款基于 Vue 3 和 Tiptap 打造的轻量、高效、开箱即用的富文本编辑器组件。具备完美的 TypeScript 类型支持。

---

## ✨ 特性

- 🎯 **开箱即用** — 内置完整工具栏，引入即可使用
- 🪶 **轻量高效** — 基于 Tiptap 3 ProseMirror，按需扩展
- 💪 **TypeScript 优先** — 完善的类型推导，IDE 智能提示丝滑
- 🎨 **图片增强** — 支持上传、拖拽、粘贴图片，浮动菜单调整对齐与宽度
- 🔗 **链接编辑** — 行内链接设置弹窗，自动识别 URL
- 📐 **文字对齐** — 左对齐 / 居中 / 右对齐
- 📋 **丰富格式** — 加粗、斜体、删除线、行内代码、代码块、引用、分割线
- 🔤 **标题层级** — H1 \~ H6 完整支持
- 📝 **列表** — 有序列表、无序列表
- ↩️ **撤销重做** — 内置历史记录操作
- 🔌 **可扩展** — 基于 Tiptap 扩展机制，轻松添加自定义节点和标记

## 📦 安装

```bash
# pnpm
pnpm add @sanmokeji/smo-editor

# npm
npm install @sanmokeji/smo-editor

# yarn
yarn add @sanmokeji/smo-editor
```

## 🚀 快速开始

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { SmoEditor, type SmoEditorOptions } from '@sanmokeji/smo-editor'
import '@sanmokeji/smo-editor/css'

const content = ref('<p>Hello SmoEditor!</p>')
</script>

<template>
  <SmoEditor v-model="content" />
</template>
```

## 📖 使用指南

### v-model 双向绑定

`SmoEditor` 使用 `v-model` 进行 HTML 内容的双向绑定：

```vue
<template>
  <SmoEditor v-model="html" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
const html = ref('<p>初始内容</p>')
</script>
```

### Props

| 属性            | 类型                                                              | 默认值 | 说明                        |
| --------------- | ----------------------------------------------------------------- | ------ | --------------------------- |
| `modelValue`    | `string`                                                          | `''`   | 编辑器 HTML 内容（v-model） |
| `editable`      | `boolean`                                                         | `true` | 是否为可编辑状态            |
| `placeholder`   | `string`                                                          | `''`   | 占位符文本                  |
| `height`        | `string \| number`                                                | —      | 编辑器容器高度              |
| `onImageUpload` | `(file: File) => ImageUploadResult \| Promise<ImageUploadResult>` | —      | 图片上传回调                |

### 图片上传

传入 `onImageUpload` 回调函数，返回图片 URL 即可。支持工具栏上传、拖拽、粘贴三种方式：

```vue
<template>
  <SmoEditor v-model="content" :on-image-upload="uploadImage" />
</template>

<script setup lang="ts">
import type { ImageUploadResult } from '@sanmokeji/smo-editor'

const uploadImage = async (file: File): Promise<ImageUploadResult> => {
  const formData = new FormData()
  formData.append('file', file)

  const res = await fetch('/api/upload', {
    method: 'POST',
    body: formData,
  })
  const { url, alt } = await res.json()
  return { url, alt }
}
</script>
```

图片上传到编辑器后，选中图片会出现 **浮动菜单（Bubble Menu）**，支持调整：

- **对齐**：左对齐 / 居中 / 右对齐
- **宽度**：自动 / 25% / 50% / 75% / 100%
- **Alt 文本**：编辑图片替代文字

### 只读模式（待定）

```vue
<template>
  <SmoEditor v-model="content" :editable="false" />
</template>
```

### 占位符

```vue
<template>
  <SmoEditor v-model="content" placeholder="请输入文章内容..." />
</template>
```

## 🧩 TypeScript 类型

库提供完整的 TypeScript 类型声明：

```ts
import { SmoEditor, type SmoEditorOptions, type ImageUploadResult } from '@sanmokeji/smo-editor'
```

`SmoEditorOptions` 和 `ImageUploadResult` 接口定义：

```ts
export interface ImageUploadResult {
  url: string
  alt?: string
}

export interface SmoEditorOptions {
  content?: string | object
  height?: string | number
  editable?: boolean
  placeholder?: string
  onImageUpload?: (file: File) => ImageUploadResult | Promise<ImageUploadResult>
}
```

## 🎨 样式导入

编辑器和工具栏的样式已内置，需要手动导入 CSS 文件：

```ts
// 在你的入口文件或组件中
import '@sanmokeji/smo-editor/css'
```

CSS 文件中包含 `.smot-editor-` 前缀的类名，不会污染全局样式。

## ⌨️ 工具栏功能

内置工具栏提供以下功能：

| 分组 | 功能                               |
| ---- | ---------------------------------- |
| 标题 | H1 / H2 / H3 / H4 / H5 / H6 / 正文 |
| 内联 | 加粗 / 斜体 / 删除线 / 行内代码    |
| 块级 | 引用 / 代码块 / 分割线             |
| 列表 | 有序列表 / 无序列表                |
| 对齐 | 左对齐 / 居中 / 右对齐             |
| 媒体 | 图片上传（含浮动编辑菜单）         |
| 链接 | 设置 / 编辑超链接                  |
| 历史 | 撤销 / 重做                        |

## 📄 License

MIT

---

Made with ❤️ by SanMoKeJi