princess-python-editor 0.3.2 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -201,46 +201,54 @@ function onRunError(error: PyError) {
201
201
 
202
202
  ### 双向绑定
203
203
 
204
- | 绑定 | 类型 | 说明 |
205
- | ------------------- | ---------------- | ------------------------------------ |
206
- | `v-model` | `string` | 当前 Tab 的代码内容 |
207
- | `v-model:file-name` | `string` | 当前 Tab 的文件名,切换 Tab 时同步 |
208
- | `v-model:language` | `EditorLanguage` | 当前 Tab 的语法类型,切换 Tab 时同步 |
204
+ | 绑定 | 类型 | 说明 |
205
+ | -------------------- | ---------------- | ------------------------------------- |
206
+ | `v-model` | `string` | 当前 Tab 的代码内容 |
207
+ | `v-model:file-name` | `string` | 当前 Tab 的文件名,切换 Tab 时同步 |
208
+ | `v-model:language` | `EditorLanguage` | 当前 Tab 的语法类型,切换 Tab 时同步 |
209
+ | `v-model:theme` | `EditorTheme` | 当前主题,工具栏切换主题时同步 |
210
+ | `v-model:runtime` | `PythonRuntime` | Python 运行环境:`browser` / `server` |
211
+ | `v-model:sql-config` | `SqlConfig` | SQL 连接与执行配置 |
209
212
 
210
213
  ## Props
211
214
 
212
- | 属性 | 类型 | 默认值 | 说明 |
213
- | ------------------- | ------------------------ | ----------- | -------------------------------------------------------- |
214
- | `modelValue` | `string` | `''` | 当前 Tab 的代码内容,支持 `v-model` |
215
- | `theme` | `EditorTheme` | `'light'` | 编辑器主题,见下文“主题” |
216
- | `height` | `number \| string` | `520` | 组件整体高度(含工具栏、Tab 与输出面板),数字按 px 处理 |
217
- | `outputHeight` | `number \| string` | `180` | 输出面板初始高度;拖动分隔条可调整,双击复位 |
218
- | `placeholder` | `string` | `''` | 内容为空时的占位提示 |
219
- | `readOnly` | `boolean` | `false` | 只读模式,同时禁用文件操作与语言切换 |
220
- | `autofocus` | `boolean` | `false` | 挂载后自动聚焦编辑器 |
221
- | `showToolbar` | `boolean` | `true` | 是否显示工具栏 |
222
- | `showTabs` | `boolean` | `true` | 是否显示文件 Tab 栏 |
223
- | `showOutput` | `boolean` | `true` | 是否显示输出面板 |
224
- | `clearOutputOnRun` | `boolean` | `true` | 运行前是否清空输出 |
225
- | `lintDelay` | `number` | `600` | 语法检查防抖毫秒数 |
226
- | `disableLint` | `boolean` | `false` | 关闭实时语法检查 |
227
- | `preload` | `boolean` | `false` | 挂载后立即预加载 Pyodide |
228
- | `pyodideUrl` | `string` | 见下文 | 自定义 Pyodide `indexURL`,必须以 `/` 结尾 |
229
- | `fileName` | `string` | `'main.py'` | 初始文件名,支持 `v-model:file-name` |
230
- | `language` | `EditorLanguage` | `'python'` | 初始语法类型,支持 `v-model:language` |
231
- | `stdin` | `string` | `''` | 按行提供给 `input()` / `sys.stdin` 的预置输入 |
232
- | `syncFilesOnRun` | `boolean` | `true` | 运行前把 Python Tab 写入虚拟文件系统,便于跨文件 import |
233
- | `storageKey` | `string` | `''` | localStorage key;非空时启用草稿持久化 |
234
- | `preloadPackages` | `string[]` | `[]` | Pyodide 就绪后自动安装的包;非空时挂载后自动加载 Pyodide |
235
- | `sqlConfig` | `SqlConfigInput` | 本地 SQLite | SQL 连接与执行配置,支持 `v-model:sql-config` |
236
- | `sqlExecutor` | `SqlExecutor` | — | 自定义 SQL 执行器,优先于内置 sqlite / http 模式 |
237
- | `showSqlConfig` | `boolean` | `true` | 是否显示工具栏“连接”入口(仅 SQL 文件可见) |
238
- | `sqlEndpointLocked` | `boolean` | `false` | 隐藏服务端点输入框,由宿主通过 `sqlConfig.endpoint` 预置 |
239
- | `filesEndpoint` | `string` | `''` | 服务端文件接口地址;非空时显示“保存 / 已保存文件”入口 |
240
- | `filesHeaders` | `Record<string, string>` | — | 服务端文件接口附加请求头,例如鉴权 token |
241
- | `pythonEndpoint` | `string` | `''` | 服务端 Python 执行端点;非空时显示环境切换 |
242
- | `pythonHeaders` | `Record<string, string>` | — | 服务端 Python 接口附加请求头,例如鉴权 token |
243
- | `runtime` | `PythonRuntime` | `'browser'` | Python 运行环境,支持 `v-model:runtime` |
215
+ | 属性 | 类型 | 默认值 | 说明 |
216
+ | ------------------- | ------------------------ | ----------- | ------------------------------------------------------------ |
217
+ | `modelValue` | `string` | `''` | 当前 Tab 的代码内容,支持 `v-model` |
218
+ | `theme` | `EditorTheme` | `'light'` | 编辑器主题,见下文“主题” |
219
+ | `height` | `number \| string` | `520` | 组件整体高度(含工具栏、Tab 与输出面板),数字按 px 处理 |
220
+ | `outputHeight` | `number \| string` | `180` | 输出面板初始高度;拖动分隔条可调整,双击复位 |
221
+ | `placeholder` | `string` | `''` | 内容为空时的占位提示 |
222
+ | `readOnly` | `boolean` | `false` | 只读模式,同时禁用文件操作与语言切换 |
223
+ | `autofocus` | `boolean` | `false` | 挂载后自动聚焦编辑器 |
224
+ | `showToolbar` | `boolean` | `true` | 是否显示工具栏 |
225
+ | `showSubmit` | `boolean` | `false` | 是否显示底部提交按钮,点击后触发 `submit` 事件,不会自动保存 |
226
+ | `showNewFile` | `boolean` | `true` | 是否显示工具栏新建按钮及 Tab 栏的新建入口 |
227
+ | `showOpenFile` | `boolean` | `true` | 是否显示工具栏打开本地文件按钮 |
228
+ | `showDownload` | `boolean` | `true` | 是否显示工具栏下载当前文件按钮 |
229
+ | `showVirtualFiles` | `boolean` | `true` | 是否显示工具栏虚拟文件入口 |
230
+ | `showTabs` | `boolean` | `true` | 是否显示文件 Tab 栏 |
231
+ | `showOutput` | `boolean` | `true` | 是否显示输出面板 |
232
+ | `clearOutputOnRun` | `boolean` | `true` | 运行前是否清空输出 |
233
+ | `lintDelay` | `number` | `600` | 语法检查防抖毫秒数 |
234
+ | `disableLint` | `boolean` | `false` | 关闭实时语法检查 |
235
+ | `preload` | `boolean` | `false` | 挂载后立即预加载 Pyodide |
236
+ | `pyodideUrl` | `string` | 见下文 | 自定义 Pyodide `indexURL`,必须以 `/` 结尾 |
237
+ | `fileName` | `string` | `'main.py'` | 初始文件名,支持 `v-model:file-name` |
238
+ | `language` | `EditorLanguage` | `'python'` | 初始语法类型,支持 `v-model:language` |
239
+ | `stdin` | `string` | `''` | 按行提供给 `input()` / `sys.stdin` 的预置输入 |
240
+ | `syncFilesOnRun` | `boolean` | `true` | 运行前把 Python Tab 写入虚拟文件系统,便于跨文件 import |
241
+ | `storageKey` | `string` | `''` | localStorage key;非空时启用草稿持久化 |
242
+ | `preloadPackages` | `string[]` | `[]` | Pyodide 就绪后自动安装的包;非空时挂载后自动加载 Pyodide |
243
+ | `sqlConfig` | `SqlConfigInput` | 本地 SQLite | SQL 连接与执行配置,支持 `v-model:sql-config` |
244
+ | `sqlExecutor` | `SqlExecutor` | — | 自定义 SQL 执行器,优先于内置 sqlite / http 模式 |
245
+ | `showSqlConfig` | `boolean` | `true` | 是否显示工具栏“连接”入口(仅 SQL 文件可见) |
246
+ | `sqlEndpointLocked` | `boolean` | `false` | 隐藏服务端点输入框,由宿主通过 `sqlConfig.endpoint` 预置 |
247
+ | `filesEndpoint` | `string` | `''` | 服务端文件接口地址;非空时显示“保存 / 已保存文件”入口 |
248
+ | `filesHeaders` | `Record<string, string>` | — | 服务端文件接口附加请求头,例如鉴权 token |
249
+ | `pythonEndpoint` | `string` | `''` | 服务端 Python 执行端点;非空时显示环境切换 |
250
+ | `pythonHeaders` | `Record<string, string>` | — | 服务端 Python 接口附加请求头,例如鉴权 token |
251
+ | `runtime` | `PythonRuntime` | `'browser'` | Python 运行环境,支持 `v-model:runtime` |
244
252
 
245
253
  ## 事件
246
254
 
@@ -256,6 +264,8 @@ function onRunError(error: PyError) {
256
264
  | `new-file` | `EditorFile` | 新建文件 |
257
265
  | `file-switch` | `EditorFile` | 切换文件 |
258
266
  | `file-close` | `EditorFile` | 关闭文件 |
267
+ | `submit` | `code: string, file: EditorFile` | 提交当前代码及文件快照,由宿主处理保存或业务请求 |
268
+ | `update:theme` | `EditorTheme` | 工具栏主题切换(配合 `v-model:theme`) |
259
269
  | `copy` | `string` | 复制代码成功 |
260
270
  | `download` | `string` | 下载文件,参数为最终文件名 |
261
271
  | `file-open` | `FileOpenEvent` | 打开本地文件 |
@@ -292,37 +302,38 @@ async function runAndInstall() {
292
302
  </template>
293
303
  ```
294
304
 
295
- | 方法 | 返回值 | 说明 |
296
- | -------------------------- | --------------------------------- | ---------------------------------------------------------- |
297
- | `run()` | `void` | 运行当前 Python 文件 |
298
- | `stop()` | `void` | 中断执行(终止并重建 Worker,Python 运行时状态会丢失) |
299
- | `clearOutput()` | `void` | 清空输出面板 |
300
- | `clearCode()` | `void` | 清空当前文件内容(保留输出) |
301
- | `newFile()` | `void` | 新建文件并切换过去 |
302
- | `switchFile(id)` | `void` | 切换到指定文件 |
303
- | `closeFile(id)` | `void` | 关闭指定文件(关闭最后一个时自动新建空白文件) |
304
- | `copyCode()` | `Promise<boolean>` | 复制当前代码到剪贴板 |
305
- | `download()` | `string` | 下载当前文件,返回最终文件名 |
306
- | `openFile()` | `void` | 打开本地文件选择框 |
307
- | `focus()` | `void` | 聚焦编辑器 |
308
- | `install(packages)` | `Promise<InstallResult>` | 安装第三方包 |
309
- | `checkSyntax()` | `Promise<SyntaxIssue \| null>` | 检查当前内容语法,未就绪时返回 `null` |
310
- | `getEditorView()` | `EditorView \| null` | 获取 CodeMirror `EditorView` 实例 |
311
- | `getCode()` | `string` | 获取当前代码 |
312
- | `setCode(code)` | `void` | 替换当前代码(保留撤销历史) |
313
- | `getFiles()` | `EditorFile[]` | 获取全部文件快照 |
314
- | `getActiveFile()` | `EditorFile` | 获取当前文件快照 |
315
- | `writeFile(path, content)` | `Promise<FsWriteResult>` | 写入虚拟文件系统(UTF-8 文本) |
316
- | `readFile(path)` | `Promise<FsReadResult>` | 读取虚拟文件系统中的文本文件 |
317
- | `listFiles(path?)` | `Promise<FsListResult>` | 列出虚拟文件目录(递归,默认当前目录) |
318
- | `downloadFile(path)` | `Promise<string \| null>` | 下载虚拟文件,返回下载使用的文件名 |
319
- | `saveToServer()` | `Promise<ServerFile \| null>` | 保存当前文件到服务端,未配置 `filesEndpoint` 时返回 `null` |
320
- | `refreshServerFiles()` | `Promise<void>` | 重新查询服务端已保存文件列表 |
321
- | `executeSql(sql?)` | `Promise<SqlQueryResult \| null>` | 执行 SQL(不传参数时执行当前文件,会切换为 SQL 文件) |
322
- | `getSqlConfig()` | `SqlConfig` | 获取当前 SQL 配置 |
323
- | `openSqlConfig()` | `void` | 打开 SQL 连接配置面板 |
324
- | `closeSqlConfig()` | `void` | 关闭 SQL 连接配置面板 |
325
- | `clearPersistedState()` | `void` | 清除 localStorage 中的本地草稿(保留当前编辑内容) |
305
+ | 方法 | 返回值 | 说明 |
306
+ | -------------------------- | --------------------------------- | ---------------------------------------------------------------- |
307
+ | `submit()` | `void` | 触发 `submit(code, file)` 事件;不自动保存,也不要求显示提交按钮 |
308
+ | `run()` | `void` | 运行当前 Python / SQL 文件,Python 使用当前选定的运行环境 |
309
+ | `stop()` | `void` | 中断执行(终止并重建 Worker,Python 运行时状态会丢失) |
310
+ | `clearOutput()` | `void` | 清空输出面板 |
311
+ | `clearCode()` | `void` | 清空当前文件内容(保留输出) |
312
+ | `newFile()` | `void` | 新建文件并切换过去 |
313
+ | `switchFile(id)` | `void` | 切换到指定文件 |
314
+ | `closeFile(id)` | `void` | 关闭指定文件(关闭最后一个时自动新建空白文件) |
315
+ | `copyCode()` | `Promise<boolean>` | 复制当前代码到剪贴板 |
316
+ | `download()` | `string` | 下载当前文件,返回最终文件名 |
317
+ | `openFile()` | `void` | 打开本地文件选择框 |
318
+ | `focus()` | `void` | 聚焦编辑器 |
319
+ | `install(packages)` | `Promise<InstallResult>` | 安装第三方包 |
320
+ | `checkSyntax()` | `Promise<SyntaxIssue \| null>` | 检查当前内容语法,未就绪时返回 `null` |
321
+ | `getEditorView()` | `EditorView \| null` | 获取 CodeMirror `EditorView` 实例 |
322
+ | `getCode()` | `string` | 获取当前代码 |
323
+ | `setCode(code)` | `void` | 替换当前代码(保留撤销历史) |
324
+ | `getFiles()` | `EditorFile[]` | 获取全部文件快照 |
325
+ | `getActiveFile()` | `EditorFile` | 获取当前文件快照 |
326
+ | `writeFile(path, content)` | `Promise<FsWriteResult>` | 写入虚拟文件系统(UTF-8 文本) |
327
+ | `readFile(path)` | `Promise<FsReadResult>` | 读取虚拟文件系统中的文本文件 |
328
+ | `listFiles(path?)` | `Promise<FsListResult>` | 列出虚拟文件目录(递归,默认当前目录) |
329
+ | `downloadFile(path)` | `Promise<string \| null>` | 下载虚拟文件,返回下载使用的文件名 |
330
+ | `saveToServer()` | `Promise<ServerFile \| null>` | 保存当前文件到服务端,未配置 `filesEndpoint` 时返回 `null` |
331
+ | `refreshServerFiles()` | `Promise<void>` | 重新查询服务端已保存文件列表 |
332
+ | `executeSql(sql?)` | `Promise<SqlQueryResult \| null>` | 执行 SQL(不传参数时执行当前文件,会切换为 SQL 文件) |
333
+ | `getSqlConfig()` | `SqlConfig` | 获取当前 SQL 配置 |
334
+ | `openSqlConfig()` | `void` | 打开 SQL 连接配置面板 |
335
+ | `closeSqlConfig()` | `void` | 关闭 SQL 连接配置面板 |
336
+ | `clearPersistedState()` | `void` | 清除 localStorage 中的本地草稿(保留当前编辑内容) |
326
337
 
327
338
  ## 语言与执行说明
328
339
 
@@ -584,6 +595,48 @@ console.log(result?.ok, result?.results?.[0]?.rows)
584
595
 
585
596
  ## 文件与输入
586
597
 
598
+ ### Tab 文件操作
599
+
600
+ - 单击 Tab 切换文件;双击文件名或聚焦 Tab 后按 `F2` 进入重命名。
601
+ - 重命名时按 Enter 或失去焦点保存,按 Esc 取消;文件名会过滤非法字符,缺少扩展名时按当前语言补全。
602
+ - 右键 Tab 可选择运行、重命名、清空、删除、关闭当前、关闭其它、关闭所有;操作针对右键点击的文件。
603
+ - 清空与删除会弹出浏览器原生二次确认。清空只移除该文件的代码并保留输出;删除移除编辑器中的 Tab 及其输出,不删除服务端、本地磁盘或虚拟文件系统中的文件。
604
+ - 关闭文件会停止该文件正在执行的任务;关闭所有后自动保留一个空白文件。
605
+ - 只读模式下禁用重命名、清空、删除和关闭操作;运行仅支持 Python / SQL 文件。
606
+
607
+ ### 提交与按钮显隐
608
+
609
+ 通过 `showSubmit` 显示底部提交按钮,并监听 `submit` 接收当前代码与文件快照:
610
+
611
+ ```vue
612
+ <script setup lang="ts">
613
+ import { ref } from 'vue'
614
+ import { PythonEditor } from 'princess-python-editor'
615
+ import type { EditorFile } from 'princess-python-editor'
616
+
617
+ const code = ref('print("hello")')
618
+
619
+ function handleSubmit(code: string, file: EditorFile) {
620
+ console.log(file.name, code)
621
+ // 在此调用宿主的保存或提交接口
622
+ }
623
+ </script>
624
+
625
+ <template>
626
+ <PythonEditor
627
+ v-model="code"
628
+ show-submit
629
+ :show-new-file="false"
630
+ :show-open-file="false"
631
+ :show-download="false"
632
+ :show-virtual-files="false"
633
+ @submit="handleSubmit"
634
+ />
635
+ </template>
636
+ ```
637
+
638
+ 按钮显隐属性仅控制对应入口,不限制实例方法调用;例如隐藏新建按钮后仍可调用 `newFile()`,隐藏提交按钮后仍可调用 `submit()`。
639
+
587
640
  ### 虚拟文件系统
588
641
 
589
642
  Python 运行在 Pyodide 的浏览器内存文件系统中,默认工作目录为 `/home/pyodide`:
@@ -1,6 +1,8 @@
1
1
  import { EditorView } from '@codemirror/view';
2
- import { EditorFile, EditorLanguage, EditorTheme, PythonRuntime, ServerFile, SqlConfig, SqlConfigInput, SqlExecutor, SqlQueryResult } from './types';
2
+ import { EditorFile, FileConfirmAction, EditorLanguage, EditorTheme, PythonRuntime, ServerFile, SqlConfig, SqlConfigInput, SqlExecutor, SqlQueryResult } from './types';
3
3
  export interface Props {
4
+ /** 自定义工具栏清空及 Tab 清空/删除确认;返回 true 执行,默认使用 window.confirm */
5
+ confirmAction?: FileConfirmAction;
4
6
  /** 绑定的代码内容(当前 Tab 的文件内容,v-model) */
5
7
  modelValue?: string;
6
8
  /** 编辑器主题 */
@@ -96,7 +98,7 @@ declare function newFile(): void;
96
98
  declare function switchFile(id: number): void;
97
99
  /** 关闭 Tab;关闭最后一个文件时自动补一个空白文件 */
98
100
  declare function closeFile(id: number): void;
99
- /** 清空当前文件内容(保留输出面板) */
101
+ /** 清空当前文件内容(保留输出面板;实例方法不弹出确认) */
100
102
  declare function clearCode(): void;
101
103
  /** 复制当前代码到剪贴板,成功后按钮短暂显示对勾 */
102
104
  declare function copyCode(): Promise<boolean>;
@@ -177,6 +179,7 @@ declare const _default: import('vue').DefineComponent<Props, {
177
179
  height: number | string;
178
180
  stdin: string;
179
181
  pyodideUrl: string;
182
+ confirmAction: FileConfirmAction;
180
183
  modelValue: string;
181
184
  theme: EditorTheme;
182
185
  outputHeight: number | string;
package/dist/icons.d.ts CHANGED
@@ -27,5 +27,5 @@ export declare const IconPlus: FunctionalComponent<{}, {}, any, {}>;
27
27
  export declare const IconDatabase: FunctionalComponent<{}, {}, any, {}>;
28
28
  /** 保存(软盘) */
29
29
  export declare const IconSave: FunctionalComponent<{}, {}, any, {}>;
30
- /** 服务端文件(两层机架) */
31
- export declare const IconServer: FunctionalComponent<{}, {}, any, {}>;
30
+ /** 已保存文件(归档盒) */
31
+ export declare const IconFiles: FunctionalComponent<{}, {}, any, {}>;