princess-python-editor 0.1.1 → 0.1.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 +433 -54
- package/dist/PythonEditor.vue.d.ts +50 -5
- package/dist/editor/theme.d.ts +3 -0
- package/dist/icons.d.ts +6 -0
- package/dist/index.cjs.js +41 -5
- package/dist/index.d.ts +29 -2
- package/dist/index.es.js +3483 -852
- package/dist/runtime/PyodideRunner.d.ts +7 -1
- package/dist/runtime/files.d.ts +17 -0
- package/dist/runtime/python.d.ts +36 -0
- package/dist/runtime/sql.d.ts +41 -0
- package/dist/style.css +1 -1
- package/dist/themes.d.ts +12 -0
- package/dist/types.d.ts +198 -0
- package/package.json +3 -3
- package/README.html +0 -1013
package/README.md
CHANGED
|
@@ -9,15 +9,19 @@ Vue 3 + TypeScript 的 Python 代码编辑器组件:基于 CodeMirror 6 的编
|
|
|
9
9
|
|
|
10
10
|
- **CodeMirror 6 编辑**:语法高亮、自动补全、括号匹配、撤销重做、错误行高亮
|
|
11
11
|
- **浏览器端执行 Python**:基于 Pyodide(CPython WASM),无需后端,支持顶层 `await`
|
|
12
|
+
- **真实 Python 环境**:配置 `python-endpoint` 后可在工具栏切换“浏览器 / 服务端”,把代码交给 python-server 调用本机 Python 执行
|
|
12
13
|
- **实时语法检查**:停止输入后自动检查 Python 语法,可配置防抖时间或关闭
|
|
13
14
|
- **多文件 Tab**:新建、打开本地文件、下载、复制、清空、切换、关闭,文件名可编辑
|
|
14
15
|
- **多语言编辑**:Python、SQL、JavaScript、JSON 的语法高亮与补全
|
|
15
|
-
-
|
|
16
|
+
- **SQL 执行**:浏览器内 SQLite 直接查询,或通过 HTTP 网关连接 MySQL / PostgreSQL 等真实数据库,结果以表格展示
|
|
17
|
+
- **多连接管理**:连接配置可保存到 python-server,支持新建、保存、删除与下拉切换;密码只保存在服务端
|
|
18
|
+
- **输出面板**:stdout / stderr 分色展示,运行时异常输出完整 traceback,自动滚动,可清空;编辑器和输出之间可拖拽调整高度,双击分隔条复位
|
|
16
19
|
- **预置输入**:通过 `stdin` 属性按行提供 `input()` 数据
|
|
17
20
|
- **虚拟文件系统**:运行前自动同步 Python Tab,可在代码中 `import` 其他 Tab;内置虚拟文件面板可下载 Python 生成的文件
|
|
21
|
+
- **服务端文件**:配置 `files-endpoint` 后,工具栏可把当前文件保存到 python-server,并在“已保存文件”面板查询、打开或删除
|
|
18
22
|
- **草稿持久化**:传入 `storage-key` 后自动把全部 Tab 与当前选中项保存到 localStorage,刷新页面不丢失
|
|
19
23
|
- **预置包**:通过 `preload-packages` 在 Pyodide 就绪后自动安装常用包(如 `sqlite3`)
|
|
20
|
-
-
|
|
24
|
+
- **主题与只读**:内置明亮、深色、GitHub 浅/深、Dracula、Nord、Solarized 浅色、Monokai 共 8 套主题,支持只读模式,工具栏与输出面板均可按需显示
|
|
21
25
|
- **第三方包安装**:优先使用 Pyodide 内置 wheel,缺失时回退 micropip
|
|
22
26
|
- **可中断执行**:运行长时间计算时可停止,Worker 自动重建
|
|
23
27
|
- **Headless 能力**:额外导出 `usePyodide`、`PyodideRunner` 等 API,可在无编辑器场景下执行 Python
|
|
@@ -101,29 +105,38 @@ function onRunError(error: PyError) {
|
|
|
101
105
|
|
|
102
106
|
## Props
|
|
103
107
|
|
|
104
|
-
| 属性
|
|
105
|
-
|
|
|
106
|
-
| `modelValue`
|
|
107
|
-
| `theme`
|
|
108
|
-
| `height`
|
|
109
|
-
| `outputHeight`
|
|
110
|
-
| `placeholder`
|
|
111
|
-
| `readOnly`
|
|
112
|
-
| `autofocus`
|
|
113
|
-
| `showToolbar`
|
|
114
|
-
| `showTabs`
|
|
115
|
-
| `showOutput`
|
|
116
|
-
| `clearOutputOnRun`
|
|
117
|
-
| `lintDelay`
|
|
118
|
-
| `disableLint`
|
|
119
|
-
| `preload`
|
|
120
|
-
| `pyodideUrl`
|
|
121
|
-
| `fileName`
|
|
122
|
-
| `language`
|
|
123
|
-
| `stdin`
|
|
124
|
-
| `syncFilesOnRun`
|
|
125
|
-
| `storageKey`
|
|
126
|
-
| `preloadPackages`
|
|
108
|
+
| 属性 | 类型 | 默认值 | 说明 |
|
|
109
|
+
| ------------------- | ------------------------ | ----------- | -------------------------------------------------------- |
|
|
110
|
+
| `modelValue` | `string` | `''` | 当前 Tab 的代码内容,支持 `v-model` |
|
|
111
|
+
| `theme` | `EditorTheme` | `'light'` | 编辑器主题,见下文“主题” |
|
|
112
|
+
| `height` | `number \| string` | `520` | 组件整体高度(含工具栏、Tab 与输出面板),数字按 px 处理 |
|
|
113
|
+
| `outputHeight` | `number \| string` | `180` | 输出面板初始高度;拖动分隔条可调整,双击复位 |
|
|
114
|
+
| `placeholder` | `string` | `''` | 内容为空时的占位提示 |
|
|
115
|
+
| `readOnly` | `boolean` | `false` | 只读模式,同时禁用文件操作与语言切换 |
|
|
116
|
+
| `autofocus` | `boolean` | `false` | 挂载后自动聚焦编辑器 |
|
|
117
|
+
| `showToolbar` | `boolean` | `true` | 是否显示工具栏 |
|
|
118
|
+
| `showTabs` | `boolean` | `true` | 是否显示文件 Tab 栏 |
|
|
119
|
+
| `showOutput` | `boolean` | `true` | 是否显示输出面板 |
|
|
120
|
+
| `clearOutputOnRun` | `boolean` | `true` | 运行前是否清空输出 |
|
|
121
|
+
| `lintDelay` | `number` | `600` | 语法检查防抖毫秒数 |
|
|
122
|
+
| `disableLint` | `boolean` | `false` | 关闭实时语法检查 |
|
|
123
|
+
| `preload` | `boolean` | `false` | 挂载后立即预加载 Pyodide |
|
|
124
|
+
| `pyodideUrl` | `string` | 见下文 | 自定义 Pyodide `indexURL`,必须以 `/` 结尾 |
|
|
125
|
+
| `fileName` | `string` | `'main.py'` | 初始文件名,支持 `v-model:file-name` |
|
|
126
|
+
| `language` | `EditorLanguage` | `'python'` | 初始语法类型,支持 `v-model:language` |
|
|
127
|
+
| `stdin` | `string` | `''` | 按行提供给 `input()` / `sys.stdin` 的预置输入 |
|
|
128
|
+
| `syncFilesOnRun` | `boolean` | `true` | 运行前把 Python Tab 写入虚拟文件系统,便于跨文件 import |
|
|
129
|
+
| `storageKey` | `string` | `''` | localStorage key;非空时启用草稿持久化 |
|
|
130
|
+
| `preloadPackages` | `string[]` | `[]` | Pyodide 就绪后自动安装的包;非空时挂载后自动加载 Pyodide |
|
|
131
|
+
| `sqlConfig` | `SqlConfigInput` | 本地 SQLite | SQL 连接与执行配置,支持 `v-model:sql-config` |
|
|
132
|
+
| `sqlExecutor` | `SqlExecutor` | — | 自定义 SQL 执行器,优先于内置 sqlite / http 模式 |
|
|
133
|
+
| `showSqlConfig` | `boolean` | `true` | 是否显示工具栏“连接”入口(仅 SQL 文件可见) |
|
|
134
|
+
| `sqlEndpointLocked` | `boolean` | `false` | 隐藏服务端点输入框,由宿主通过 `sqlConfig.endpoint` 预置 |
|
|
135
|
+
| `filesEndpoint` | `string` | `''` | 服务端文件接口地址;非空时显示“保存 / 已保存文件”入口 |
|
|
136
|
+
| `filesHeaders` | `Record<string, string>` | — | 服务端文件接口附加请求头,例如鉴权 token |
|
|
137
|
+
| `pythonEndpoint` | `string` | `''` | 服务端 Python 执行端点;非空时显示环境切换 |
|
|
138
|
+
| `pythonHeaders` | `Record<string, string>` | — | 服务端 Python 接口附加请求头,例如鉴权 token |
|
|
139
|
+
| `runtime` | `PythonRuntime` | `'browser'` | Python 运行环境,支持 `v-model:runtime` |
|
|
127
140
|
|
|
128
141
|
## 事件
|
|
129
142
|
|
|
@@ -143,6 +156,10 @@ function onRunError(error: PyError) {
|
|
|
143
156
|
| `download` | `string` | 下载文件,参数为最终文件名 |
|
|
144
157
|
| `file-open` | `FileOpenEvent` | 打开本地文件 |
|
|
145
158
|
| `fs-download` | `FsDownloadEvent` | 下载虚拟文件系统中的文件 |
|
|
159
|
+
| `sql-result` | `SqlQueryResult` | SQL 执行结束(成功或失败均触发) |
|
|
160
|
+
| `sql-error` | `SqlError` | SQL 执行失败 |
|
|
161
|
+
| `update:sqlConfig` | `SqlConfig` | SQL 配置变化(配合 `v-model:sql-config`) |
|
|
162
|
+
| `update:runtime` | `PythonRuntime` | Python 运行环境变化(配合 `v-model:runtime`) |
|
|
146
163
|
| `update:modelValue` | `string` | 代码内容变化 |
|
|
147
164
|
| `update:fileName` | `string` | 文件名变化 |
|
|
148
165
|
| `update:language` | `EditorLanguage` | 语法类型变化 |
|
|
@@ -171,37 +188,295 @@ async function runAndInstall() {
|
|
|
171
188
|
</template>
|
|
172
189
|
```
|
|
173
190
|
|
|
174
|
-
| 方法 | 返回值
|
|
175
|
-
| -------------------------- |
|
|
176
|
-
| `run()` | `void`
|
|
177
|
-
| `stop()` | `void`
|
|
178
|
-
| `clearOutput()` | `void`
|
|
179
|
-
| `clearCode()` | `void`
|
|
180
|
-
| `newFile()` | `void`
|
|
181
|
-
| `switchFile(id)` | `void`
|
|
182
|
-
| `closeFile(id)` | `void`
|
|
183
|
-
| `copyCode()` | `Promise<boolean>`
|
|
184
|
-
| `download()` | `string`
|
|
185
|
-
| `openFile()` | `void`
|
|
186
|
-
| `focus()` | `void`
|
|
187
|
-
| `install(packages)` | `Promise<InstallResult>`
|
|
188
|
-
| `checkSyntax()` | `Promise<SyntaxIssue \| null>`
|
|
189
|
-
| `getEditorView()` | `EditorView \| null`
|
|
190
|
-
| `getCode()` | `string`
|
|
191
|
-
| `setCode(code)` | `void`
|
|
192
|
-
| `getFiles()` | `EditorFile[]`
|
|
193
|
-
| `getActiveFile()` | `EditorFile`
|
|
194
|
-
| `writeFile(path, content)` | `Promise<FsWriteResult>`
|
|
195
|
-
| `readFile(path)` | `Promise<FsReadResult>`
|
|
196
|
-
| `listFiles(path?)` | `Promise<FsListResult>`
|
|
197
|
-
| `downloadFile(path)` | `Promise<string \| null>`
|
|
198
|
-
| `
|
|
191
|
+
| 方法 | 返回值 | 说明 |
|
|
192
|
+
| -------------------------- | --------------------------------- | ---------------------------------------------------------- |
|
|
193
|
+
| `run()` | `void` | 运行当前 Python 文件 |
|
|
194
|
+
| `stop()` | `void` | 中断执行(终止并重建 Worker,Python 运行时状态会丢失) |
|
|
195
|
+
| `clearOutput()` | `void` | 清空输出面板 |
|
|
196
|
+
| `clearCode()` | `void` | 清空当前文件内容(保留输出) |
|
|
197
|
+
| `newFile()` | `void` | 新建文件并切换过去 |
|
|
198
|
+
| `switchFile(id)` | `void` | 切换到指定文件 |
|
|
199
|
+
| `closeFile(id)` | `void` | 关闭指定文件(关闭最后一个时自动新建空白文件) |
|
|
200
|
+
| `copyCode()` | `Promise<boolean>` | 复制当前代码到剪贴板 |
|
|
201
|
+
| `download()` | `string` | 下载当前文件,返回最终文件名 |
|
|
202
|
+
| `openFile()` | `void` | 打开本地文件选择框 |
|
|
203
|
+
| `focus()` | `void` | 聚焦编辑器 |
|
|
204
|
+
| `install(packages)` | `Promise<InstallResult>` | 安装第三方包 |
|
|
205
|
+
| `checkSyntax()` | `Promise<SyntaxIssue \| null>` | 检查当前内容语法,未就绪时返回 `null` |
|
|
206
|
+
| `getEditorView()` | `EditorView \| null` | 获取 CodeMirror `EditorView` 实例 |
|
|
207
|
+
| `getCode()` | `string` | 获取当前代码 |
|
|
208
|
+
| `setCode(code)` | `void` | 替换当前代码(保留撤销历史) |
|
|
209
|
+
| `getFiles()` | `EditorFile[]` | 获取全部文件快照 |
|
|
210
|
+
| `getActiveFile()` | `EditorFile` | 获取当前文件快照 |
|
|
211
|
+
| `writeFile(path, content)` | `Promise<FsWriteResult>` | 写入虚拟文件系统(UTF-8 文本) |
|
|
212
|
+
| `readFile(path)` | `Promise<FsReadResult>` | 读取虚拟文件系统中的文本文件 |
|
|
213
|
+
| `listFiles(path?)` | `Promise<FsListResult>` | 列出虚拟文件目录(递归,默认当前目录) |
|
|
214
|
+
| `downloadFile(path)` | `Promise<string \| null>` | 下载虚拟文件,返回下载使用的文件名 |
|
|
215
|
+
| `saveToServer()` | `Promise<ServerFile \| null>` | 保存当前文件到服务端,未配置 `filesEndpoint` 时返回 `null` |
|
|
216
|
+
| `refreshServerFiles()` | `Promise<void>` | 重新查询服务端已保存文件列表 |
|
|
217
|
+
| `executeSql(sql?)` | `Promise<SqlQueryResult \| null>` | 执行 SQL(不传参数时执行当前文件,会切换为 SQL 文件) |
|
|
218
|
+
| `getSqlConfig()` | `SqlConfig` | 获取当前 SQL 配置 |
|
|
219
|
+
| `openSqlConfig()` | `void` | 打开 SQL 连接配置面板 |
|
|
220
|
+
| `closeSqlConfig()` | `void` | 关闭 SQL 连接配置面板 |
|
|
221
|
+
| `clearPersistedState()` | `void` | 清除 localStorage 中的本地草稿(保留当前编辑内容) |
|
|
199
222
|
|
|
200
223
|
## 语言与执行说明
|
|
201
224
|
|
|
202
225
|
`language` 可选值为 `'python' | 'sql' | 'javascript' | 'json'`,用于语法高亮、补全与文件扩展名推断。
|
|
203
226
|
|
|
204
|
-
|
|
227
|
+
**Python 与 SQL 文件可以执行。** 切换到 SQL 后,运行按钮会执行当前 SQL(见下文“SQL 配置与查询”)。JavaScript / JSON 目前是纯编辑模式,运行按钮禁用,`Ctrl+Enter` 只会在输出面板提示仅支持 Python / SQL。
|
|
228
|
+
|
|
229
|
+
## Python 运行环境
|
|
230
|
+
|
|
231
|
+
默认在浏览器内通过 Pyodide 执行,无需后端。配置 `python-endpoint` 后,Python 文件工具栏会出现“浏览器 / 服务端”下拉:
|
|
232
|
+
|
|
233
|
+
```vue
|
|
234
|
+
<PythonEditor v-model="code" python-endpoint="http://localhost:8090/api/python" :stdin="'你好\n'" />
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
- 服务端模式创建常驻 Python 会话,不需要等待 Pyodide 加载,可使用服务器上已安装的第三方包;
|
|
238
|
+
- 程序调用 `input()` 时,输出面板底部会出现输入框,输入后按 Enter 发送,程序继续执行;
|
|
239
|
+
- `stdin` 属性会在会话启动时预先写入,用于自动回答前几次输入;
|
|
240
|
+
- 输出按轮询增量展示;会话空闲 5 分钟或超过最长运行时间会被服务端回收;
|
|
241
|
+
- 出错时会解析 traceback 的异常类型与行号,并在编辑器中标记错误行;
|
|
242
|
+
- 运行状态与输出按 Tab 隔离:切换文件会显示该文件自己的输出;
|
|
243
|
+
- 服务端环境支持多个 Tab 同时运行(各自独立的 Python 会话),浏览器环境共享同一个 Pyodide 实例,同一时间只能运行一个文件;
|
|
244
|
+
- 关闭最后一个 Tab 时会自动新建一个空白文件。
|
|
245
|
+
|
|
246
|
+
会话接口:
|
|
247
|
+
|
|
248
|
+
| 方法 | 路径 | 说明 |
|
|
249
|
+
| ---- | ------------------------------------------ | ----------------------- |
|
|
250
|
+
| POST | `{pythonEndpoint}/sessions` | 创建会话,返回首批输出 |
|
|
251
|
+
| GET | `{pythonEndpoint}/sessions/{id}` | 轮询增量输出 |
|
|
252
|
+
| POST | `{pythonEndpoint}/sessions/{id}/input` | 提交一行 `input()` 输入 |
|
|
253
|
+
| POST | `{pythonEndpoint}/sessions/{id}/interrupt` | 中断并释放会话 |
|
|
254
|
+
|
|
255
|
+
一次轮询响应:
|
|
256
|
+
|
|
257
|
+
```json
|
|
258
|
+
{
|
|
259
|
+
"sessionId": "1c1e...",
|
|
260
|
+
"state": "waiting",
|
|
261
|
+
"stdout": "请输入你猜的数字:",
|
|
262
|
+
"stderr": "",
|
|
263
|
+
"durationMs": 120
|
|
264
|
+
}
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
`state` 为 `running` / `waiting` / `exited`。不需要交互时也可以使用 `POST {pythonEndpoint}/run` 一次性执行接口:
|
|
268
|
+
|
|
269
|
+
```json
|
|
270
|
+
{ "code": "print(input())", "stdin": "你好\n", "timeoutSeconds": 30 }
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
```ts
|
|
274
|
+
import {
|
|
275
|
+
createPythonSession,
|
|
276
|
+
pollPythonSession,
|
|
277
|
+
sendPythonSessionInput,
|
|
278
|
+
} from 'princess-python-editor'
|
|
279
|
+
|
|
280
|
+
const session = await createPythonSession('http://localhost:8090/api/python', 'print(input())')
|
|
281
|
+
if (session.state === 'waiting') {
|
|
282
|
+
await sendPythonSessionInput('http://localhost:8090/api/python', session.sessionId, '你好')
|
|
283
|
+
}
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
> 服务端模式会在服务器上执行任意代码,请务必配置鉴权、限制网络访问,并只对内网可信用户开放。
|
|
287
|
+
|
|
288
|
+
## SQL 配置与查询
|
|
289
|
+
|
|
290
|
+
切换到 SQL 文件后,点击“运行”或按 `Ctrl+Enter` 执行当前文件中的 SQL,结果以表格展示在输出面板;多条语句会按顺序返回多个结果集。
|
|
291
|
+
|
|
292
|
+
### 执行方式
|
|
293
|
+
|
|
294
|
+
点击工具栏“连接”打开配置面板,或由宿主通过 `sqlConfig` / `v-model:sql-config` 控制:
|
|
295
|
+
|
|
296
|
+
| 模式 | 说明 |
|
|
297
|
+
| ---------------- | ----------------------------------------------------------------------------------------- |
|
|
298
|
+
| `sqlite`(默认) | 在浏览器内通过 Pyodide 的 sqlite3 执行,数据库默认为 `:memory:`,无需服务端 |
|
|
299
|
+
| `http` | 把连接信息与 SQL POST 到后端网关,由网关连接 MySQL / PostgreSQL / SQL Server 等真实数据库 |
|
|
300
|
+
|
|
301
|
+
浏览器无法直接建立数据库 TCP 连接,查询真实数据库时必须提供 HTTP 网关或自定义执行器。
|
|
302
|
+
|
|
303
|
+
### 像 Navicat 一样填写连接信息
|
|
304
|
+
|
|
305
|
+
部署方先把网关地址通过 `sqlConfig.endpoint` 固定下来,并设置 `sql-endpoint-locked`,终端用户只需要填写数据库类型、主机、端口、用户名、密码和数据库名:
|
|
306
|
+
|
|
307
|
+
```vue
|
|
308
|
+
<PythonEditor
|
|
309
|
+
v-model="code"
|
|
310
|
+
v-model:language="language"
|
|
311
|
+
:sql-config="{
|
|
312
|
+
mode: 'http',
|
|
313
|
+
endpoint: 'https://your-server.com/api/sql',
|
|
314
|
+
connection: { dialect: 'mysql' },
|
|
315
|
+
}"
|
|
316
|
+
sql-endpoint-locked
|
|
317
|
+
/>
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
配置面板底部提供“测试连接”,实际执行一条 `SELECT 1`,成功后显示耗时,失败则展示网关返回的错误。测试连接复用现有的查询接口,网关无需额外实现协议。
|
|
321
|
+
|
|
322
|
+
> 浏览器只负责收集连接信息,真实连接由远程网关建立。网关应按 `connection.dialect` 分发到对应驱动,例如 `mysql2`(MySQL)、`pg`(PostgreSQL)、`mssql`(SQL Server)、`better-sqlite3`(SQLite)。
|
|
323
|
+
|
|
324
|
+
```vue
|
|
325
|
+
<PythonEditor
|
|
326
|
+
v-model="code"
|
|
327
|
+
v-model:language="language"
|
|
328
|
+
:sql-config="{
|
|
329
|
+
mode: 'http',
|
|
330
|
+
connection: {
|
|
331
|
+
dialect: 'mysql',
|
|
332
|
+
host: '127.0.0.1',
|
|
333
|
+
port: 3306,
|
|
334
|
+
user: 'readonly',
|
|
335
|
+
password: '******',
|
|
336
|
+
database: 'demo',
|
|
337
|
+
},
|
|
338
|
+
endpoint: 'https://example.com/api/sql',
|
|
339
|
+
maxRows: 200,
|
|
340
|
+
timeoutMs: 30000,
|
|
341
|
+
}"
|
|
342
|
+
/>
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
### 多连接保存与切换
|
|
346
|
+
|
|
347
|
+
当 SQL 文件处于激活状态且配置了服务端点时,工具栏会在状态旁显示已保存连接下拉框,无需先点击“新建连接”;选择某个连接会自动切换到 HTTP 服务模式:
|
|
348
|
+
|
|
349
|
+
- 下拉框只展示已保存连接,切换连接不会打开 SQL 连接面板,名称和连接信息会自动回填;
|
|
350
|
+
- 点击工具栏“新建连接”清空表单并打开面板,填写后点击“保存”创建新连接;
|
|
351
|
+
- 下拉框旁边的“管理”按钮打开独立的“连接管理”弹窗,列出全部已保存连接,可直接编辑或删除;编辑会打开 SQL 连接面板,删除会移除该连接配置;
|
|
352
|
+
- SQL 连接面板内部不显示已保存连接选择器,操作顺序为“测试连接 → 保存 → 删除”;
|
|
353
|
+
- 选中连接后,运行 SQL 只发送 `connectionId`,密码由服务端使用保存值,不会下发到浏览器。
|
|
354
|
+
|
|
355
|
+
连接管理接口(由 python-server 提供):
|
|
356
|
+
|
|
357
|
+
| 方法 | 路径 |
|
|
358
|
+
| ------ | ----------------------------- |
|
|
359
|
+
| GET | `{endpoint}/connections` |
|
|
360
|
+
| POST | `{endpoint}/connections` |
|
|
361
|
+
| PUT | `{endpoint}/connections/{id}` |
|
|
362
|
+
| DELETE | `{endpoint}/connections/{id}` |
|
|
363
|
+
|
|
364
|
+
也可以直接调用导出的函数:
|
|
365
|
+
|
|
366
|
+
```ts
|
|
367
|
+
import { listSqlConnections, saveSqlConnection, deleteSqlConnection } from 'princess-python-editor'
|
|
368
|
+
|
|
369
|
+
const config = { mode: 'http' as const, endpoint: 'http://localhost:8090/api/sql' }
|
|
370
|
+
|
|
371
|
+
const profiles = await listSqlConnections(config)
|
|
372
|
+
await saveSqlConnection(config, {
|
|
373
|
+
name: '本地 MySQL',
|
|
374
|
+
dialect: 'mysql',
|
|
375
|
+
host: '127.0.0.1',
|
|
376
|
+
port: 3306,
|
|
377
|
+
user: 'root',
|
|
378
|
+
password: '123456',
|
|
379
|
+
database: 'demo',
|
|
380
|
+
})
|
|
381
|
+
await deleteSqlConnection(config, profiles[0].id)
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
宿主也可以直接绑定已保存连接:
|
|
385
|
+
|
|
386
|
+
```ts
|
|
387
|
+
const sqlConfig = ref<SqlConfigInput>({
|
|
388
|
+
mode: 'http',
|
|
389
|
+
endpoint: 'http://localhost:8090/api/sql',
|
|
390
|
+
connectionId: '8f0c...',
|
|
391
|
+
})
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
### HTTP 网关协议
|
|
395
|
+
|
|
396
|
+
组件向 `endpoint` 发送 `POST` 请求:
|
|
397
|
+
|
|
398
|
+
```json
|
|
399
|
+
{
|
|
400
|
+
"connection": {
|
|
401
|
+
"dialect": "mysql",
|
|
402
|
+
"host": "127.0.0.1",
|
|
403
|
+
"port": 3306,
|
|
404
|
+
"user": "readonly",
|
|
405
|
+
"password": "******",
|
|
406
|
+
"database": "demo"
|
|
407
|
+
},
|
|
408
|
+
"sql": "SELECT * FROM users LIMIT 10",
|
|
409
|
+
"maxRows": 200
|
|
410
|
+
}
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
网关返回:
|
|
414
|
+
|
|
415
|
+
```json
|
|
416
|
+
{
|
|
417
|
+
"ok": true,
|
|
418
|
+
"results": [
|
|
419
|
+
{
|
|
420
|
+
"columns": ["id", "name"],
|
|
421
|
+
"rows": [
|
|
422
|
+
[1, "张三"],
|
|
423
|
+
[2, "李四"]
|
|
424
|
+
],
|
|
425
|
+
"affectedRows": 0,
|
|
426
|
+
"truncated": false
|
|
427
|
+
}
|
|
428
|
+
],
|
|
429
|
+
"durationMs": 12
|
|
430
|
+
}
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
失败时返回 `{ "ok": false, "error": { "type": "OperationalError", "message": "..." } }`。也兼容单结果集简写:直接在顶层返回 `columns`、`rows`、`affectedRows`。`headers` 可附加认证头:
|
|
434
|
+
|
|
435
|
+
```ts
|
|
436
|
+
const sqlConfig = {
|
|
437
|
+
mode: 'http' as const,
|
|
438
|
+
endpoint: '/api/sql',
|
|
439
|
+
headers: { Authorization: 'Bearer ...' },
|
|
440
|
+
// ...
|
|
441
|
+
}
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
### 自定义执行器
|
|
445
|
+
|
|
446
|
+
如果已有现成接口,可直接传入 `sqlExecutor`,此时忽略内置的 sqlite / http 逻辑:
|
|
447
|
+
|
|
448
|
+
```ts
|
|
449
|
+
import type { SqlExecutor } from 'princess-python-editor'
|
|
450
|
+
|
|
451
|
+
const sqlExecutor: SqlExecutor = async ({ sql, connection, maxRows }, { signal }) => {
|
|
452
|
+
const response = await fetch('/api/query', {
|
|
453
|
+
method: 'POST',
|
|
454
|
+
headers: { 'Content-Type': 'application/json' },
|
|
455
|
+
body: JSON.stringify({ sql, connection, maxRows }),
|
|
456
|
+
signal,
|
|
457
|
+
})
|
|
458
|
+
const data = await response.json()
|
|
459
|
+
return { ok: true, results: data.results, durationMs: data.durationMs ?? 0 }
|
|
460
|
+
}
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
```vue
|
|
464
|
+
<PythonEditor v-model="code" v-model:language="language" :sql-executor="sqlExecutor" />
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
### 脚本调用
|
|
468
|
+
|
|
469
|
+
```ts
|
|
470
|
+
const result = await editorRef.value?.executeSql('SELECT 1 AS n')
|
|
471
|
+
console.log(result?.ok, result?.results?.[0]?.rows)
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
### 说明
|
|
475
|
+
|
|
476
|
+
- 本地 SQLite 数据库保存在当前 Worker 内存中,点击“停止”、刷新页面或 Worker 重建后会丢失。
|
|
477
|
+
- 单条语句默认最多返回 200 行,可用 `sqlConfig.maxRows` 调整;超出部分标记为 `truncated`。
|
|
478
|
+
- HTTP 模式默认超时 30 秒,可通过 `sqlConfig.timeoutMs` 调整。
|
|
479
|
+
- 连接密码不会写入 localStorage;仍建议使用只读账号、通过 HTTPS 访问网关,并由后端做权限校验与 SQL 审核。
|
|
205
480
|
|
|
206
481
|
## 文件与输入
|
|
207
482
|
|
|
@@ -225,6 +500,62 @@ const read = await editorRef.value?.readFile('output.txt')
|
|
|
225
500
|
await editorRef.value?.downloadFile('output.txt')
|
|
226
501
|
```
|
|
227
502
|
|
|
503
|
+
### 服务端文件保存与查询
|
|
504
|
+
|
|
505
|
+
配置 `files-endpoint` 后,工具栏会多出“保存”和“已保存文件”入口:保存会把当前 Tab 的文件名与内容 POST 到服务端;面板会查询已保存文件列表,可打开到新的编辑器 Tab 或删除。同名文件保存时直接覆盖。
|
|
506
|
+
|
|
507
|
+
```vue
|
|
508
|
+
<PythonEditor
|
|
509
|
+
v-model="code"
|
|
510
|
+
files-endpoint="http://localhost:8090/api/files"
|
|
511
|
+
:files-headers="{ 'X-SQL-Token': 'your-token' }"
|
|
512
|
+
/>
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
python-server 提供的接口:
|
|
516
|
+
|
|
517
|
+
| 方法 | 路径 | 说明 |
|
|
518
|
+
| ------ | ------------------------ | -------------------------- |
|
|
519
|
+
| GET | `{filesEndpoint}` | 列出已保存文件(不含内容) |
|
|
520
|
+
| POST | `{filesEndpoint}` | 保存文件,同名覆盖 |
|
|
521
|
+
| GET | `{filesEndpoint}/{name}` | 读取文件内容 |
|
|
522
|
+
| DELETE | `{filesEndpoint}/{name}` | 删除文件 |
|
|
523
|
+
|
|
524
|
+
保存请求体与列表响应示例:
|
|
525
|
+
|
|
526
|
+
```json
|
|
527
|
+
{ "name": "main.py", "content": "print('hello')\n" }
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
```json
|
|
531
|
+
{
|
|
532
|
+
"ok": true,
|
|
533
|
+
"data": {
|
|
534
|
+
"id": "main.py",
|
|
535
|
+
"name": "main.py",
|
|
536
|
+
"size": 15,
|
|
537
|
+
"updatedAt": "2026-11-13T11:37:57.435+08:00"
|
|
538
|
+
}
|
|
539
|
+
}
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
也可以直接调用导出的函数:
|
|
543
|
+
|
|
544
|
+
```ts
|
|
545
|
+
import {
|
|
546
|
+
listServerFiles,
|
|
547
|
+
saveServerFile,
|
|
548
|
+
readServerFile,
|
|
549
|
+
deleteServerFile,
|
|
550
|
+
} from 'princess-python-editor'
|
|
551
|
+
|
|
552
|
+
const endpoint = 'http://localhost:8090/api/files'
|
|
553
|
+
const files = await listServerFiles(endpoint)
|
|
554
|
+
await saveServerFile(endpoint, { name: 'main.py', content: 'print(1)' })
|
|
555
|
+
const detail = await readServerFile(endpoint, 'main.py')
|
|
556
|
+
await deleteServerFile(endpoint, 'main.py')
|
|
557
|
+
```
|
|
558
|
+
|
|
228
559
|
### 交互输入 input()
|
|
229
560
|
|
|
230
561
|
通过 `stdin` 属性按行提供输入,`input()` 会依次读取;读取完毕后再次调用会抛出 `EOFError`:
|
|
@@ -245,6 +576,10 @@ print(name, score)
|
|
|
245
576
|
|
|
246
577
|
执行出错时,输出面板会展示完整 traceback,同时保持错误行高亮;宿主也可以通过 `run-error` 事件拿到 `PyError.traceback`。
|
|
247
578
|
|
|
579
|
+
### 调整输出面板高度
|
|
580
|
+
|
|
581
|
+
编辑器和输出面板之间有分隔条,按住上下拖动即可调整输出高度;双击分隔条恢复 `outputHeight` 的初始值。聚焦分隔条后也可以用方向键微调高度。
|
|
582
|
+
|
|
248
583
|
## 草稿持久化
|
|
249
584
|
|
|
250
585
|
传入 `storageKey` 后,组件会把全部 Tab(文件名、语言、代码)和当前选中项保存到 localStorage,编辑后防抖 400ms 写入,组件卸载时再保存一次:
|
|
@@ -304,6 +639,7 @@ const result = await editorRef.value?.install(['numpy', 'pandas'])
|
|
|
304
639
|
|
|
305
640
|
- `worker-src blob:`
|
|
306
641
|
- Pyodide 资源地址对应的 `script-src` / `connect-src`
|
|
642
|
+
- SQL HTTP 网关地址对应的 `connect-src`
|
|
307
643
|
|
|
308
644
|
## 无编辑器使用 Python
|
|
309
645
|
|
|
@@ -355,22 +691,50 @@ const listed = await listFiles()
|
|
|
355
691
|
| `listFiles(path?)` | `Promise<FsListResult>` | 列出虚拟文件目录 |
|
|
356
692
|
| `ready()` | `Promise<void>` | 等待就绪 |
|
|
357
693
|
|
|
358
|
-
##
|
|
694
|
+
## 主题
|
|
695
|
+
|
|
696
|
+
内置 8 套主题,通过 `theme` 属性切换:
|
|
697
|
+
|
|
698
|
+
| 值 | 名称 | 明暗 |
|
|
699
|
+
| ----------------- | -------------- | ---- |
|
|
700
|
+
| `light` | 明亮(默认) | 浅色 |
|
|
701
|
+
| `dark` | 深色 | 深色 |
|
|
702
|
+
| `github-light` | GitHub 浅色 | 浅色 |
|
|
703
|
+
| `github-dark` | GitHub 深色 | 深色 |
|
|
704
|
+
| `dracula` | Dracula | 深色 |
|
|
705
|
+
| `nord` | Nord | 深色 |
|
|
706
|
+
| `solarized-light` | Solarized 浅色 | 浅色 |
|
|
707
|
+
| `monokai` | Monokai | 深色 |
|
|
708
|
+
|
|
709
|
+
```vue
|
|
710
|
+
<PythonEditor v-model="code" theme="dracula" />
|
|
711
|
+
```
|
|
712
|
+
|
|
713
|
+
```ts
|
|
714
|
+
import { EDITOR_THEMES, getThemeOption, isDarkTheme } from 'princess-python-editor'
|
|
715
|
+
```
|
|
716
|
+
|
|
717
|
+
### 主题定制
|
|
359
718
|
|
|
360
|
-
|
|
719
|
+
组件样式与语法高亮都通过 CSS 变量控制,可在根元素上覆盖。内置主题类名为 `.vpe-theme-{theme}`,深色主题同时带有 `.vpe-dark`:
|
|
361
720
|
|
|
362
721
|
```css
|
|
363
722
|
.vpe-root {
|
|
364
723
|
--vpe-accent: #165dff;
|
|
365
724
|
--vpe-bg: #ffffff;
|
|
725
|
+
--vpe-editor-bg: #ffffff;
|
|
366
726
|
--vpe-text: #1d2129;
|
|
367
727
|
--vpe-border: #e5e6eb;
|
|
368
728
|
--vpe-output-bg: #f7f8fa;
|
|
369
729
|
--vpe-stderr: #f53f3f;
|
|
730
|
+
/* 语法高亮 */
|
|
731
|
+
--vpe-syn-keyword: #770088;
|
|
732
|
+
--vpe-syn-string: #aa1111;
|
|
733
|
+
--vpe-syn-comment: #9a4a00;
|
|
370
734
|
}
|
|
371
735
|
```
|
|
372
736
|
|
|
373
|
-
|
|
737
|
+
完整变量包括界面色(`--vpe-bg`、`--vpe-toolbar-bg`、`--vpe-text`、`--vpe-accent` 等)、编辑器色(`--vpe-editor-bg`、`--vpe-selection`、`--vpe-active-line`、`--vpe-gutter` 等)和语法色(`--vpe-syn-keyword`、`--vpe-syn-string`、`--vpe-syn-number`、`--vpe-syn-function`、`--vpe-syn-type` 等)。新增主题只需定义一组变量并加上 `.vpe-theme-xxx` 类名。
|
|
374
738
|
|
|
375
739
|
## 类型导出
|
|
376
740
|
|
|
@@ -392,6 +756,21 @@ import type {
|
|
|
392
756
|
FsReadResult,
|
|
393
757
|
FsListResult,
|
|
394
758
|
FsDownloadEvent,
|
|
759
|
+
SqlDialect,
|
|
760
|
+
SqlMode,
|
|
761
|
+
SqlConnection,
|
|
762
|
+
SqlConfig,
|
|
763
|
+
SqlConfigInput,
|
|
764
|
+
SqlConnectionProfile,
|
|
765
|
+
SqlConnectionSaveInput,
|
|
766
|
+
SqlValue,
|
|
767
|
+
SqlResultSet,
|
|
768
|
+
SqlError,
|
|
769
|
+
SqlQueryResult,
|
|
770
|
+
SqlTestResult,
|
|
771
|
+
SqlExecuteRequest,
|
|
772
|
+
SqlExecuteContext,
|
|
773
|
+
SqlExecutor,
|
|
395
774
|
PythonEditorProps,
|
|
396
775
|
} from 'princess-python-editor'
|
|
397
776
|
```
|