@tuoyuan/code-editor 1.0.0

package/README.md

@@ -0,0 +1,505 @@
+# @tuoyuan/code-editor
+
+基于 Monaco Editor 的 Vue3 代码编辑器组件，支持多种编程语言的代码高亮、格式化和压缩功能。
+
+## ✨ 特性
+
+- 🎨 **多语言支持**：JavaScript、JSON、SQL
+- 🌈 **语法高亮**：Monaco Editor 内置语法高亮
+- 📝 **代码格式化**：使用 js-beautify 和 sql-formatter
+- 🗜️ **代码压缩**：一键压缩代码
+- 🎯 **TypeScript 支持**：完整的类型定义
+- 🌓 **主题切换**：浅色、深色、高对比度主题
+- 💾 **保存功能**：支持保存事件和 Ctrl+S 快捷键
+- 📊 **状态栏**：显示光标位置、行数、字符数等统计信息
+- 📋 **复制代码**：一键复制编辑器内容
+- 💿 **下载代码**：导出为文件
+- 🖥️ **全屏模式**：支持全屏编辑，ESC 退出
+- 🔧 **零配置**：内置 Worker 配置，无需额外设置
+- 📦 **轻量级封装**：参考了 devops-platform 和 dashboard-manage.web 的最佳实践
+
+## 安装
+
+```bash
+npm install @tuoyuan/code-editor monaco-editor
+# or
+pnpm add @tuoyuan/code-editor monaco-editor
+# or
+yarn add @tuoyuan/code-editor monaco-editor
+```
+
+## 📖 使用
+
+### 基本用法
+
+```vue
+<template>
+  <CodeEditor
+    v-model="code"
+    language="javascript"
+    height="400px"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { CodeEditor } from '@tuoyuan/code-editor'
+import '@tuoyuan/code-editor/dist/style.css'
+
+const code = ref('console.log("Hello World")')
+</script>
+```
+
+### 完整示例（带所有功能）
+
+```vue
+<template>
+  <div>
+    <!-- 外部操作按钮 -->
+    <div style="margin-bottom: 10px;">
+      <button @click="copyCode">复制代码</button>
+      <button @click="downloadCode">下载代码</button>
+      <button @click="toggleFullscreen">全屏</button>
+    </div>
+
+    <!-- 代码编辑器 -->
+    <CodeEditor
+      ref="editorRef"
+      v-model="code"
+      v-model:language="language"
+      v-model:theme="theme"
+      height="500px"
+      :show-toolbar="true"
+      @change="onChange"
+      @save="onSave"
+      @format="onFormat"
+      @minify="onMinify"
+      @copy="onCopy"
+      @download="onDownload"
+      @fullscreen="onFullscreenChange"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { CodeEditor } from '@tuoyuan/code-editor'
+import type { CodeEditorInstance } from '@tuoyuan/code-editor'
+import '@tuoyuan/code-editor/dist/style.css'
+
+const editorRef = ref<CodeEditorInstance>()
+const code = ref('console.log("Hello World")')
+const language = ref<'javascript' | 'json' | 'sql'>('javascript')
+const theme = ref<'vs' | 'vs-dark' | 'hc-black'>('vs')
+
+// 复制代码
+const copyCode = async () => {
+  const success = await editorRef.value?.copyCode()
+  if (success) {
+    alert('代码已复制')
+  }
+}
+
+// 下载代码
+const downloadCode = () => {
+  editorRef.value?.downloadCode('my-code.js')
+}
+
+// 切换全屏
+const toggleFullscreen = () => {
+  editorRef.value?.toggleFullscreen()
+}
+
+// 事件处理
+const onChange = (value: string) => {
+  console.log('代码变化:', value)
+}
+
+const onSave = (value: string) => {
+  console.log('保存代码:', value)
+  // 在这里处理保存逻辑，如保存到服务器
+}
+
+const onFormat = (value: string) => {
+  console.log('格式化完成')
+}
+
+const onMinify = (value: string) => {
+  console.log('压缩完成')
+}
+
+const onCopy = (value: string) => {
+  console.log('代码已复制')
+}
+
+const onDownload = (value: string) => {
+  console.log('代码已下载')
+}
+
+const onFullscreenChange = (isFullscreen: boolean) => {
+  console.log('全屏状态:', isFullscreen)
+}
+</script>
+```
+
+### 语言和主题切换
+
+```vue
+<template>
+  <CodeEditor
+    v-model="code"
+    v-model:language="currentLanguage"
+    v-model:theme="currentTheme"
+    height="400px"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+import { CodeEditor } from '@tuoyuan/code-editor'
+import '@tuoyuan/code-editor/dist/style.css'
+
+const code = ref('')
+const currentLanguage = ref<'javascript' | 'json' | 'sql'>('javascript')
+const currentTheme = ref<'vs' | 'vs-dark' | 'hc-black'>('vs-dark')
+
+// 监听语言变化
+watch(currentLanguage, (newLang) => {
+  console.log('语言已切换为:', newLang)
+  // 可以根据语言加载不同的代码模板
+})
+
+// 监听主题变化
+watch(currentTheme, (newTheme) => {
+  console.log('主题已切换为:', newTheme)
+})
+</script>
+```
+
+### 只读模式
+
+```vue
+<template>
+  <CodeEditor
+    v-model="code"
+    language="javascript"
+    :readonly="true"
+    :show-toolbar="false"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { CodeEditor } from '@tuoyuan/code-editor'
+import '@tuoyuan/code-editor/dist/style.css'
+
+const code = ref('console.log("只读模式")')
+</script>
+```
+
+## 📋 API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| modelValue | 代码内容（支持 v-model） | `string` | `''` |
+| language | 编程语言（支持 v-model:language） | `'javascript' \| 'json' \| 'sql'` | `'javascript'` |
+| theme | 编辑器主题（支持 v-model:theme） | `'vs' \| 'vs-dark' \| 'hc-black'` | `'vs'` |
+| height | 编辑器高度 | `string` | `'400px'` |
+| readonly | 只读模式 | `boolean` | `false` |
+| showToolbar | 显示工具栏（包含语言/主题选择器、格式化、压缩按钮） | `boolean` | `true` |
+| options | Monaco Editor 原生配置项 | `editor.IStandaloneEditorConstructionOptions` | `{}` |
+
+**主题说明：**
+- `vs`：浅色主题（白色背景）
+- `vs-dark`：深色主题（黑色背景）
+- `hc-black`：高对比度主题（无障碍模式）
+
+### Events
+
+| 事件名 | 说明 | 回调参数 | 触发时机 |
+| --- | --- | --- | --- |
+| update:modelValue | 代码内容变化（v-model） | `(value: string) => void` | 每次编辑时 |
+| update:language | 语言变化（v-model:language） | `(language: string) => void` | 切换语言时 |
+| update:theme | 主题变化（v-model:theme） | `(theme: string) => void` | 切换主题时 |
+| change | 代码内容变化 | `(value: string) => void` | 每次编辑时 |
+| blur | 编辑器失焦 | `(value: string) => void` | 失去焦点时 |
+| save | 保存代码 | `(value: string) => void` | 点击保存按钮或按下 Ctrl+S |
+| format | 格式化完成 | `(value: string) => void` | 点击格式化按钮后 |
+| minify | 压缩完成 | `(value: string) => void` | 点击压缩按钮后 |
+| copy | 复制代码 | `(value: string) => void` | 调用 copyCode 方法时 |
+| download | 下载代码 | `(value: string) => void` | 调用 downloadCode 方法时 |
+| fullscreen | 全屏状态变化 | `(isFullscreen: boolean) => void` | 进入/退出全屏时 |
+
+### Methods（实例方法）
+
+通过 ref 可以调用组件的实例方法：
+
+```vue
+<template>
+  <CodeEditor ref="editorRef" v-model="code" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { CodeEditor } from '@tuoyuan/code-editor'
+import type { CodeEditorInstance } from '@tuoyuan/code-editor'
+import '@tuoyuan/code-editor/dist/style.css'
+
+const editorRef = ref<CodeEditorInstance>()
+</script>
+```
+
+**可用方法列表：**
+
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| `format()` | 格式化代码 | - | `void` |
+| `minify()` | 压缩代码 | - | `void` |
+| `getValue()` | 获取编辑器内容 | - | `string` |
+| `setValue(value)` | 设置编辑器内容 | `value: string` | `void` |
+| `refresh()` | 刷新编辑器布局 | - | `void` |
+| `copyCode()` | 复制代码到剪贴板 | - | `Promise<boolean>` |
+| `downloadCode(filename?)` | 下载代码为文件 | `filename?: string` | `void` |
+| `toggleFullscreen()` | 切换全屏状态 | - | `void` |
+| `enterFullscreen()` | 进入全屏模式 | - | `void` |
+| `exitFullscreen()` | 退出全屏模式 | - | `void` |
+| `editor` | 获取 Monaco Editor 实例 | - | `editor.IStandaloneCodeEditor` |
+
+**方法示例：**
+
+```typescript
+// 格式化代码
+editorRef.value?.format()
+
+// 压缩代码
+editorRef.value?.minify()
+
+// 获取代码内容
+const code = editorRef.value?.getValue()
+
+// 设置代码内容
+editorRef.value?.setValue('console.log("new code")')
+
+// 复制代码
+const success = await editorRef.value?.copyCode()
+
+// 下载代码（自动根据语言生成文件名）
+editorRef.value?.downloadCode()
+
+// 下载代码（指定文件名）
+editorRef.value?.downloadCode('my-script.js')
+
+// 全屏相关
+editorRef.value?.toggleFullscreen()  // 切换全屏
+editorRef.value?.enterFullscreen()   // 进入全屏
+editorRef.value?.exitFullscreen()    // 退出全屏
+
+// 刷新布局（在容器大小变化时使用）
+editorRef.value?.refresh()
+
+// 获取原生 Monaco Editor 实例
+const monacoEditor = editorRef.value?.editor
+```
+
+## ⚙️ 配置
+
+### 样式导入
+
+**必须**导入组件样式才能正常显示：
+
+```typescript
+import '@tuoyuan/code-editor/dist/style.css'
+```
+
+### Vite 配置（可选）
+
+如果在使用 Vite 时遇到构建问题，可以在 `vite.config.ts` 中添加以下配置：
+
+```typescript
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  optimizeDeps: {
+    exclude: ['monaco-editor'], // 排除 Monaco Editor 的预构建
+  },
+})
+```
+
+**注意：** 本组件已经内置了 Monaco Editor 的 Worker 配置，**无需额外配置**，开箱即用！
+
+## 🎨 功能详解
+
+### 工具栏
+
+组件内置工具栏包含以下功能：
+
+**左侧：**
+- **语言选择器**：下拉框切换 JavaScript / JSON / SQL
+- **主题选择器**：下拉框切换 浅色 / 深色 / 高对比度
+
+**右侧：**
+- **美化代码按钮**：格式化当前代码
+- **压缩代码按钮**：压缩当前代码（移除空格和换行）
+
+### 状态栏
+
+编辑器底部状态栏显示以下信息：
+
+**左侧：**
+- 当前光标位置（行号、列号）
+- 总行数
+- 总字符数
+
+**右侧：**
+- 保存按钮（支持 Ctrl+S 快捷键）
+- 当前语言
+- 编码格式（UTF-8）
+
+### 代码格式化
+
+支持以下语言的代码格式化：
+
+- **JavaScript**：使用 `js-beautify`，支持缩进、换行等配置
+- **JSON**：使用 `js-beautify`，自动格式化 JSON 结构
+- **SQL**：使用 `sql-formatter`，格式化 SQL 语句
+
+### 快捷键
+
+| 快捷键 | 功能 |
+| --- | --- |
+| `Ctrl + S` / `Cmd + S` | 保存代码（触发 save 事件） |
+| `ESC` | 退出全屏模式 |
+
+### 全屏模式
+
+- 调用 `toggleFullscreen()` 或 `enterFullscreen()` 进入全屏
+- 全屏时编辑器会覆盖整个屏幕（`position: fixed`, `z-index: 9999`）
+- 按 `ESC` 键或调用 `exitFullscreen()` 退出全屏
+- 进入/退出全屏时会自动刷新编辑器布局
+
+## 💡 常见问题
+
+### 1. Monaco Editor Worker 错误？
+
+本组件已经内置了 Worker 配置，**无需额外配置**。如果仍然看到 worker 相关警告，可以忽略，不影响功能使用。
+
+### 2. 如何自定义编辑器配置？
+
+可以通过 `options` 属性传入 Monaco Editor 的原生配置：
+
+```vue
+<CodeEditor
+  v-model="code"
+  :options="{
+    fontSize: 16,
+    lineHeight: 24,
+    minimap: { enabled: true },
+    wordWrap: 'on'
+  }"
+/>
+```
+
+完整配置项参考：[Monaco Editor API](https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.IStandaloneEditorConstructionOptions.html)
+
+### 3. 如何监听代码变化？
+
+有两种方式：
+
+```vue
+<!-- 方式1: v-model -->
+<CodeEditor v-model="code" />
+
+<!-- 方式2: @change 事件 -->
+<CodeEditor @change="handleChange" />
+```
+
+### 4. 如何实现代码保存功能？
+
+监听 `save` 事件，在回调中实现保存逻辑：
+
+```vue
+<CodeEditor @save="handleSave" />
+
+<script setup>
+const handleSave = async (code) => {
+  // 保存到服务器
+  await api.saveCode(code)
+  message.success('保存成功')
+}
+</script>
+```
+
+### 5. 如何设置编辑器的初始语言和主题？
+
+```vue
+<CodeEditor
+  v-model="code"
+  language="sql"
+  theme="vs-dark"
+/>
+```
+
+### 6. 复制和下载功能如何使用？
+
+这些功能需要通过 ref 调用：
+
+```vue
+<template>
+  <CodeEditor ref="editorRef" v-model="code" />
+  <button @click="editorRef?.copyCode()">复制</button>
+  <button @click="editorRef?.downloadCode('script.js')">下载</button>
+</template>
+```
+
+### 7. 如何隐藏工具栏？
+
+设置 `show-toolbar` 为 `false`：
+
+```vue
+<CodeEditor :show-toolbar="false" />
+```
+
+## 🏗️ 设计参考
+
+本组件参考了以下项目的实现：
+
+1. **devops-platform** (`/src/components/code-editor/`) - Monaco Editor 基础实现
+2. **dashboard-manage.web** (`/src/components/common/Codemirror*`) - UI 设计和功能交互
+
+结合了两者的优点：
+- 使用 Monaco Editor 提供强大的编辑器功能和更好的性能
+- 参考 Codemirror 组件的 UI 设计和用户交互体验
+- 内置 Worker 配置，零配置即可使用
+
+## 📝 版本历史
+
+### 1.0.0 (2024-12)
+- ✅ 初始版本发布
+- ✅ 支持 JavaScript、JSON、SQL 语言
+- ✅ 支持代码高亮、格式化、压缩
+- ✅ 内置工具栏（语言/主题选择器、格式化、压缩）
+- ✅ 底部状态栏（光标位置、统计信息、保存按钮）
+- ✅ 支持主题切换（浅色、深色、高对比度）
+- ✅ 支持复制、下载、全屏功能
+- ✅ 支持 Ctrl+S 保存快捷键
+- ✅ 完整的 TypeScript 类型定义
+- ✅ 内置 Monaco Editor Worker 配置
+
+## 📄 License
+
+ISC
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 🔗 相关链接
+
+- [Monaco Editor 官方文档](https://microsoft.github.io/monaco-editor/)
+- [Monaco Editor API](https://microsoft.github.io/monaco-editor/api/index.html)
+- [js-beautify](https://github.com/beautify-web/js-beautify)
+- [sql-formatter](https://github.com/sql-formatter-org/sql-formatter)