princess-python-editor 0.0.0-stage → 0.1.1
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/LICENSE +21 -0
- package/README.html +1013 -0
- package/README.md +461 -2
- package/dist/PythonEditor.vue.d.ts +157 -0
- package/dist/editor/createEditor.d.ts +18 -0
- package/dist/editor/pythonLint.d.ts +8 -0
- package/dist/icons.d.ts +23 -0
- package/dist/index.cjs.js +228 -0
- package/dist/index.d.ts +76 -0
- package/dist/index.es.js +1582 -0
- package/dist/languages.d.ts +15 -0
- package/dist/runtime/PyodideRunner.d.ts +66 -0
- package/dist/runtime/usePyodide.d.ts +42 -0
- package/dist/runtime/workerSource.d.ts +8 -0
- package/dist/style.css +1 -0
- package/dist/types.d.ts +115 -0
- package/package.json +90 -4
package/README.md
CHANGED
|
@@ -1,3 +1,462 @@
|
|
|
1
|
-
#
|
|
1
|
+
# princess-python-editor
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Vue 3 + TypeScript 的 Python 代码编辑器组件:基于 CodeMirror 6 的编辑体验,通过 Pyodide 在浏览器端执行 Python,并支持实时语法检查。
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/princess-python-editor)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
## 特性
|
|
9
|
+
|
|
10
|
+
- **CodeMirror 6 编辑**:语法高亮、自动补全、括号匹配、撤销重做、错误行高亮
|
|
11
|
+
- **浏览器端执行 Python**:基于 Pyodide(CPython WASM),无需后端,支持顶层 `await`
|
|
12
|
+
- **实时语法检查**:停止输入后自动检查 Python 语法,可配置防抖时间或关闭
|
|
13
|
+
- **多文件 Tab**:新建、打开本地文件、下载、复制、清空、切换、关闭,文件名可编辑
|
|
14
|
+
- **多语言编辑**:Python、SQL、JavaScript、JSON 的语法高亮与补全
|
|
15
|
+
- **输出面板**:stdout / stderr 分色展示,运行时异常输出完整 traceback,自动滚动,可清空
|
|
16
|
+
- **预置输入**:通过 `stdin` 属性按行提供 `input()` 数据
|
|
17
|
+
- **虚拟文件系统**:运行前自动同步 Python Tab,可在代码中 `import` 其他 Tab;内置虚拟文件面板可下载 Python 生成的文件
|
|
18
|
+
- **草稿持久化**:传入 `storage-key` 后自动把全部 Tab 与当前选中项保存到 localStorage,刷新页面不丢失
|
|
19
|
+
- **预置包**:通过 `preload-packages` 在 Pyodide 就绪后自动安装常用包(如 `sqlite3`)
|
|
20
|
+
- **主题与只读**:浅色 / 深色主题,只读模式,工具栏与输出面板均可按需显示
|
|
21
|
+
- **第三方包安装**:优先使用 Pyodide 内置 wheel,缺失时回退 micropip
|
|
22
|
+
- **可中断执行**:运行长时间计算时可停止,Worker 自动重建
|
|
23
|
+
- **Headless 能力**:额外导出 `usePyodide`、`PyodideRunner` 等 API,可在无编辑器场景下执行 Python
|
|
24
|
+
|
|
25
|
+
## 环境要求
|
|
26
|
+
|
|
27
|
+
- Vue `>= 3.3.0`
|
|
28
|
+
- 支持 WebAssembly 与 Web Worker 的现代浏览器
|
|
29
|
+
- 首次加载 Pyodide 需要访问 CDN(默认 jsDelivr),也可以自托管
|
|
30
|
+
|
|
31
|
+
> 组件执行代码时运行在 Web Worker 中,无法直接访问页面 DOM。
|
|
32
|
+
|
|
33
|
+
## 安装
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pnpm add princess-python-editor
|
|
37
|
+
# 或
|
|
38
|
+
npm install princess-python-editor
|
|
39
|
+
# 或
|
|
40
|
+
yarn add princess-python-editor
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## 快速开始
|
|
44
|
+
|
|
45
|
+
在应用入口引入组件样式:
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
// main.ts
|
|
49
|
+
import 'princess-python-editor/style.css'
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
在页面中使用:
|
|
53
|
+
|
|
54
|
+
```vue
|
|
55
|
+
<script setup lang="ts">
|
|
56
|
+
import { ref } from 'vue'
|
|
57
|
+
import { PythonEditor } from 'princess-python-editor'
|
|
58
|
+
import type { EditorLanguage, PyError, RunResult } from 'princess-python-editor'
|
|
59
|
+
|
|
60
|
+
const code = ref(`# 点击工具栏“运行”或按 Ctrl+Enter
|
|
61
|
+
def greet(name):
|
|
62
|
+
return f"Hello, {name}!"
|
|
63
|
+
|
|
64
|
+
print(greet("Pyodide"))
|
|
65
|
+
`)
|
|
66
|
+
const fileName = ref('main.py')
|
|
67
|
+
const language = ref<EditorLanguage>('python')
|
|
68
|
+
|
|
69
|
+
function onRunFinish(result: RunResult) {
|
|
70
|
+
console.log(result.ok ? `执行完成,耗时 ${result.durationMs}ms` : '执行失败')
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function onRunError(error: PyError) {
|
|
74
|
+
console.error(error.type, error.message)
|
|
75
|
+
}
|
|
76
|
+
</script>
|
|
77
|
+
|
|
78
|
+
<template>
|
|
79
|
+
<PythonEditor
|
|
80
|
+
v-model="code"
|
|
81
|
+
v-model:file-name="fileName"
|
|
82
|
+
v-model:language="language"
|
|
83
|
+
height="100%"
|
|
84
|
+
:output-height="220"
|
|
85
|
+
placeholder="# 在这里编写 Python 代码"
|
|
86
|
+
@run-finish="onRunFinish"
|
|
87
|
+
@run-error="onRunError"
|
|
88
|
+
/>
|
|
89
|
+
</template>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
> `height="100%"` 需要父容器具有明确高度;也可以直接传入数字(按 px 处理)。
|
|
93
|
+
|
|
94
|
+
### 双向绑定
|
|
95
|
+
|
|
96
|
+
| 绑定 | 类型 | 说明 |
|
|
97
|
+
| ------------------- | ---------------- | ------------------------------------ |
|
|
98
|
+
| `v-model` | `string` | 当前 Tab 的代码内容 |
|
|
99
|
+
| `v-model:file-name` | `string` | 当前 Tab 的文件名,切换 Tab 时同步 |
|
|
100
|
+
| `v-model:language` | `EditorLanguage` | 当前 Tab 的语法类型,切换 Tab 时同步 |
|
|
101
|
+
|
|
102
|
+
## Props
|
|
103
|
+
|
|
104
|
+
| 属性 | 类型 | 默认值 | 说明 |
|
|
105
|
+
| ------------------ | ------------------- | ----------- | -------------------------------------------------------- |
|
|
106
|
+
| `modelValue` | `string` | `''` | 当前 Tab 的代码内容,支持 `v-model` |
|
|
107
|
+
| `theme` | `'light' \| 'dark'` | `'light'` | 编辑器主题 |
|
|
108
|
+
| `height` | `number \| string` | `520` | 组件整体高度(含工具栏、Tab 与输出面板),数字按 px 处理 |
|
|
109
|
+
| `outputHeight` | `number \| string` | `180` | 输出面板高度 |
|
|
110
|
+
| `placeholder` | `string` | `''` | 内容为空时的占位提示 |
|
|
111
|
+
| `readOnly` | `boolean` | `false` | 只读模式,同时禁用文件操作与语言切换 |
|
|
112
|
+
| `autofocus` | `boolean` | `false` | 挂载后自动聚焦编辑器 |
|
|
113
|
+
| `showToolbar` | `boolean` | `true` | 是否显示工具栏 |
|
|
114
|
+
| `showTabs` | `boolean` | `true` | 是否显示文件 Tab 栏 |
|
|
115
|
+
| `showOutput` | `boolean` | `true` | 是否显示输出面板 |
|
|
116
|
+
| `clearOutputOnRun` | `boolean` | `true` | 运行前是否清空输出 |
|
|
117
|
+
| `lintDelay` | `number` | `600` | 语法检查防抖毫秒数 |
|
|
118
|
+
| `disableLint` | `boolean` | `false` | 关闭实时语法检查 |
|
|
119
|
+
| `preload` | `boolean` | `false` | 挂载后立即预加载 Pyodide |
|
|
120
|
+
| `pyodideUrl` | `string` | 见下文 | 自定义 Pyodide `indexURL`,必须以 `/` 结尾 |
|
|
121
|
+
| `fileName` | `string` | `'main.py'` | 初始文件名,支持 `v-model:file-name` |
|
|
122
|
+
| `language` | `EditorLanguage` | `'python'` | 初始语法类型,支持 `v-model:language` |
|
|
123
|
+
| `stdin` | `string` | `''` | 按行提供给 `input()` / `sys.stdin` 的预置输入 |
|
|
124
|
+
| `syncFilesOnRun` | `boolean` | `true` | 运行前把 Python Tab 写入虚拟文件系统,便于跨文件 import |
|
|
125
|
+
| `storageKey` | `string` | `''` | localStorage key;非空时启用草稿持久化 |
|
|
126
|
+
| `preloadPackages` | `string[]` | `[]` | Pyodide 就绪后自动安装的包;非空时挂载后自动加载 Pyodide |
|
|
127
|
+
|
|
128
|
+
## 事件
|
|
129
|
+
|
|
130
|
+
| 事件 | 参数 | 说明 |
|
|
131
|
+
| ------------------- | ------------------------------------------------ | -------------------------------------------------------- |
|
|
132
|
+
| `ready` | — | Pyodide 加载完成 |
|
|
133
|
+
| `status-change` | `PyodideStatus` | 运行器状态变化:`idle` / `loading` / `ready` / `running` |
|
|
134
|
+
| `run-start` | — | 开始执行 |
|
|
135
|
+
| `run-output` | `{ stream: 'stdout' \| 'stderr'; text: string }` | 执行期间的实时输出 |
|
|
136
|
+
| `run-error` | `PyError` | 执行过程中抛出 Python 异常 |
|
|
137
|
+
| `run-finish` | `RunResult` | 本次执行结束(成功、失败或中断) |
|
|
138
|
+
| `load-error` | `string` | Pyodide 加载失败 |
|
|
139
|
+
| `new-file` | `EditorFile` | 新建文件 |
|
|
140
|
+
| `file-switch` | `EditorFile` | 切换文件 |
|
|
141
|
+
| `file-close` | `EditorFile` | 关闭文件 |
|
|
142
|
+
| `copy` | `string` | 复制代码成功 |
|
|
143
|
+
| `download` | `string` | 下载文件,参数为最终文件名 |
|
|
144
|
+
| `file-open` | `FileOpenEvent` | 打开本地文件 |
|
|
145
|
+
| `fs-download` | `FsDownloadEvent` | 下载虚拟文件系统中的文件 |
|
|
146
|
+
| `update:modelValue` | `string` | 代码内容变化 |
|
|
147
|
+
| `update:fileName` | `string` | 文件名变化 |
|
|
148
|
+
| `update:language` | `EditorLanguage` | 语法类型变化 |
|
|
149
|
+
|
|
150
|
+
## 实例方法
|
|
151
|
+
|
|
152
|
+
通过模板 `ref` 调用:
|
|
153
|
+
|
|
154
|
+
```vue
|
|
155
|
+
<script setup lang="ts">
|
|
156
|
+
import { ref } from 'vue'
|
|
157
|
+
import { PythonEditor } from 'princess-python-editor'
|
|
158
|
+
|
|
159
|
+
const editorRef = ref<InstanceType<typeof PythonEditor> | null>(null)
|
|
160
|
+
|
|
161
|
+
async function runAndInstall() {
|
|
162
|
+
editorRef.value?.run()
|
|
163
|
+
editorRef.value?.setCode('print("hello")')
|
|
164
|
+
const result = await editorRef.value?.install(['numpy'])
|
|
165
|
+
console.log(result?.ok)
|
|
166
|
+
}
|
|
167
|
+
</script>
|
|
168
|
+
|
|
169
|
+
<template>
|
|
170
|
+
<PythonEditor ref="editorRef" v-model="code" />
|
|
171
|
+
</template>
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
| 方法 | 返回值 | 说明 |
|
|
175
|
+
| -------------------------- | ------------------------------ | ------------------------------------------------------ |
|
|
176
|
+
| `run()` | `void` | 运行当前 Python 文件 |
|
|
177
|
+
| `stop()` | `void` | 中断执行(终止并重建 Worker,Python 运行时状态会丢失) |
|
|
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>` | 检查当前内容语法,未就绪时返回 `null` |
|
|
189
|
+
| `getEditorView()` | `EditorView \| null` | 获取 CodeMirror `EditorView` 实例 |
|
|
190
|
+
| `getCode()` | `string` | 获取当前代码 |
|
|
191
|
+
| `setCode(code)` | `void` | 替换当前代码(保留撤销历史) |
|
|
192
|
+
| `getFiles()` | `EditorFile[]` | 获取全部文件快照 |
|
|
193
|
+
| `getActiveFile()` | `EditorFile` | 获取当前文件快照 |
|
|
194
|
+
| `writeFile(path, content)` | `Promise<FsWriteResult>` | 写入虚拟文件系统(UTF-8 文本) |
|
|
195
|
+
| `readFile(path)` | `Promise<FsReadResult>` | 读取虚拟文件系统中的文本文件 |
|
|
196
|
+
| `listFiles(path?)` | `Promise<FsListResult>` | 列出虚拟文件目录(递归,默认当前目录) |
|
|
197
|
+
| `downloadFile(path)` | `Promise<string \| null>` | 下载虚拟文件,返回下载使用的文件名 |
|
|
198
|
+
| `clearPersistedState()` | `void` | 清除 localStorage 中的本地草稿(保留当前编辑内容) |
|
|
199
|
+
|
|
200
|
+
## 语言与执行说明
|
|
201
|
+
|
|
202
|
+
`language` 可选值为 `'python' | 'sql' | 'javascript' | 'json'`,用于语法高亮、补全与文件扩展名推断。
|
|
203
|
+
|
|
204
|
+
**只有 Python 文件可以执行。** 切换到 SQL / JavaScript / JSON 后,运行按钮会被禁用,`Ctrl+Enter` 也只会在输出面板提示“仅支持执行 Python 代码”。这些语言目前是纯编辑模式,不具备运行时。
|
|
205
|
+
|
|
206
|
+
## 文件与输入
|
|
207
|
+
|
|
208
|
+
### 虚拟文件系统
|
|
209
|
+
|
|
210
|
+
Python 运行在 Pyodide 的浏览器内存文件系统中,默认工作目录为 `/home/pyodide`:
|
|
211
|
+
|
|
212
|
+
- `open()`、`os`、`pathlib`、`csv`、`json`、`zipfile`、`tempfile` 等均可正常使用,支持文本与二进制读写。
|
|
213
|
+
- 运行前会自动把全部 Python Tab 写入虚拟文件系统(可用 `:sync-files-on-run="false"` 关闭)。因此 `main.py` 可以直接 `import utils`,只要 `utils.py` 是另一个 Python Tab。
|
|
214
|
+
- Python 会缓存已导入的模块。修改被导入的 Tab 后,需要在代码中 `importlib.reload(utils)`,或点击“停止”重建 Worker 后再运行。
|
|
215
|
+
- 同一 Worker 内,变量会在多次运行之间保留;点击“停止”、刷新页面或调用 `interrupt()` 后全部重置。
|
|
216
|
+
- 虚拟文件只存在于当前 Worker 内存中:点击“停止”、刷新页面或调用 `interrupt()` 后全部丢失。
|
|
217
|
+
- “打开本地文件”只是把文本载入编辑器 Tab,不会进入虚拟文件系统。需要预置数据文件时,使用实例方法 `writeFile(path, content)` 写入。
|
|
218
|
+
- Python 生成的文件可通过工具栏“虚拟文件”面板下载,也可以调用 `listFiles()`、`readFile()`、`downloadFile(path)` 自行处理。
|
|
219
|
+
- 面板下载仅支持 UTF-8 文本;二进制文件可以在 Python 内部读写,但无法通过面板下载。
|
|
220
|
+
|
|
221
|
+
```ts
|
|
222
|
+
await editorRef.value?.writeFile('data.csv', 'name,score\n张三,95\n')
|
|
223
|
+
const listed = await editorRef.value?.listFiles()
|
|
224
|
+
const read = await editorRef.value?.readFile('output.txt')
|
|
225
|
+
await editorRef.value?.downloadFile('output.txt')
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### 交互输入 input()
|
|
229
|
+
|
|
230
|
+
通过 `stdin` 属性按行提供输入,`input()` 会依次读取;读取完毕后再次调用会抛出 `EOFError`:
|
|
231
|
+
|
|
232
|
+
```vue
|
|
233
|
+
<PythonEditor v-model="code" :stdin="'张三\n95'" />
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
```python
|
|
237
|
+
name = input('姓名:')
|
|
238
|
+
score = int(input('成绩:'))
|
|
239
|
+
print(name, score)
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
不支持运行中途暂停等待键盘输入。如果需要动态收集输入,请在每次运行前更新 `stdin`。
|
|
243
|
+
|
|
244
|
+
### 运行时异常
|
|
245
|
+
|
|
246
|
+
执行出错时,输出面板会展示完整 traceback,同时保持错误行高亮;宿主也可以通过 `run-error` 事件拿到 `PyError.traceback`。
|
|
247
|
+
|
|
248
|
+
## 草稿持久化
|
|
249
|
+
|
|
250
|
+
传入 `storageKey` 后,组件会把全部 Tab(文件名、语言、代码)和当前选中项保存到 localStorage,编辑后防抖 400ms 写入,组件卸载时再保存一次:
|
|
251
|
+
|
|
252
|
+
```vue
|
|
253
|
+
<PythonEditor v-model="code" storage-key="my-python-draft" />
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
- 挂载时若存在同 key 的草稿,会在创建编辑器前恢复,并通过 `update:modelValue`、`update:fileName`、`update:language` 同步给宿主。
|
|
257
|
+
- 存储结构带版本号;版本不兼容或内容损坏时自动忽略,不影响组件启动。
|
|
258
|
+
- 调用 `editorRef.value?.clearPersistedState()` 可清除草稿,仅删除存储,不改动当前编辑内容;之后继续编辑会重新写入。
|
|
259
|
+
- 不传 `storageKey` 时完全关闭该能力,不产生任何读写。
|
|
260
|
+
- 草稿只保存编辑内容,不包含虚拟文件系统与运行状态。
|
|
261
|
+
|
|
262
|
+
## Pyodide 配置
|
|
263
|
+
|
|
264
|
+
### 默认 CDN
|
|
265
|
+
|
|
266
|
+
默认从 jsDelivr 加载 Pyodide `v0.27.2`:
|
|
267
|
+
|
|
268
|
+
```ts
|
|
269
|
+
import { DEFAULT_PYODIDE_URL } from 'princess-python-editor'
|
|
270
|
+
// https://cdn.jsdelivr.net/pyodide/v0.27.2/full/
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
### 自托管
|
|
274
|
+
|
|
275
|
+
将 Pyodide 发行包放到静态资源目录,然后传入以 `/` 结尾的 URL:
|
|
276
|
+
|
|
277
|
+
```vue
|
|
278
|
+
<PythonEditor v-model="code" pyodide-url="/pyodide/v0.27.2/full/" />
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
> 底层运行器是模块级单例,`pyodideUrl` 只在页面中第一次初始化前生效;之后再传入会被忽略并输出警告。
|
|
282
|
+
|
|
283
|
+
### 安装第三方包
|
|
284
|
+
|
|
285
|
+
```ts
|
|
286
|
+
const result = await editorRef.value?.install(['numpy', 'pandas'])
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
优先使用 Pyodide 内置 wheel,未内置的包会回退到 micropip 从 PyPI 下载。
|
|
290
|
+
|
|
291
|
+
### 预置包
|
|
292
|
+
|
|
293
|
+
`preloadPackages` 会在组件挂载后自动开始加载 Pyodide,就绪后安装指定包,安装日志输出到输出面板:
|
|
294
|
+
|
|
295
|
+
```vue
|
|
296
|
+
<PythonEditor v-model="code" :preload-packages="['sqlite3']" />
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
常用可预置的 Pyodide 内置包有 `sqlite3`、`numpy`、`pandas`、`matplotlib` 等。`sqlite3` 不会随 Pyodide 默认加载,必须安装后才能 `import sqlite3`。安装期间运行器状态为 `running`,运行按钮暂不可用;安装完成后即可正常导入。
|
|
300
|
+
|
|
301
|
+
### CSP 提示
|
|
302
|
+
|
|
303
|
+
组件通过 Blob URL 创建 Worker,并在 Worker 中加载 Pyodide。使用严格 CSP 时需要允许:
|
|
304
|
+
|
|
305
|
+
- `worker-src blob:`
|
|
306
|
+
- Pyodide 资源地址对应的 `script-src` / `connect-src`
|
|
307
|
+
|
|
308
|
+
## 无编辑器使用 Python
|
|
309
|
+
|
|
310
|
+
`usePyodide` 与编辑器共享同一个 Pyodide 实例,支持 `pyodideUrl`、`preload` 与 `preloadPackages` 选项:
|
|
311
|
+
|
|
312
|
+
```ts
|
|
313
|
+
import { usePyodide } from 'princess-python-editor'
|
|
314
|
+
|
|
315
|
+
const {
|
|
316
|
+
status,
|
|
317
|
+
version,
|
|
318
|
+
outputs,
|
|
319
|
+
runPython,
|
|
320
|
+
install,
|
|
321
|
+
checkSyntax,
|
|
322
|
+
interrupt,
|
|
323
|
+
clearOutputs,
|
|
324
|
+
writeFile,
|
|
325
|
+
readFile,
|
|
326
|
+
listFiles,
|
|
327
|
+
} = usePyodide({ preload: true })
|
|
328
|
+
|
|
329
|
+
const result = await runPython('print(1 + 1)')
|
|
330
|
+
console.log(result.ok, result.value, result.durationMs)
|
|
331
|
+
|
|
332
|
+
// 提供 input() 输入
|
|
333
|
+
await runPython('name = input()\nprint(name)', { stdin: '张三\n' })
|
|
334
|
+
|
|
335
|
+
// 虚拟文件系统
|
|
336
|
+
await writeFile('data.txt', 'hello')
|
|
337
|
+
const read = await readFile('data.txt')
|
|
338
|
+
const listed = await listFiles()
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
返回内容包括:
|
|
342
|
+
|
|
343
|
+
| 字段 | 类型 | 说明 |
|
|
344
|
+
| --------------------------- | ------------------------------ | ---------------------------------- |
|
|
345
|
+
| `status` | `Ref<PyodideStatus>` | 运行器状态 |
|
|
346
|
+
| `version` | `Ref<string>` | Pyodide 版本 |
|
|
347
|
+
| `outputs` | `Ref<OutputLine[]>` | 输出行(失败时包含完整 traceback) |
|
|
348
|
+
| `runPython(code, options?)` | `Promise<RunResult>` | 执行代码,`options.stdin` 提供输入 |
|
|
349
|
+
| `install(packages)` | `Promise<InstallResult>` | 安装包 |
|
|
350
|
+
| `checkSyntax(code)` | `Promise<SyntaxIssue \| null>` | 语法检查 |
|
|
351
|
+
| `interrupt()` | `void` | 中断执行 |
|
|
352
|
+
| `clearOutputs()` | `void` | 清空输出 |
|
|
353
|
+
| `writeFile(path, content)` | `Promise<FsWriteResult>` | 写入虚拟文件系统 |
|
|
354
|
+
| `readFile(path)` | `Promise<FsReadResult>` | 读取虚拟文件 |
|
|
355
|
+
| `listFiles(path?)` | `Promise<FsListResult>` | 列出虚拟文件目录 |
|
|
356
|
+
| `ready()` | `Promise<void>` | 等待就绪 |
|
|
357
|
+
|
|
358
|
+
## 主题定制
|
|
359
|
+
|
|
360
|
+
组件样式通过 CSS 变量控制,可在 `.vpe-root` 上覆盖:
|
|
361
|
+
|
|
362
|
+
```css
|
|
363
|
+
.vpe-root {
|
|
364
|
+
--vpe-accent: #165dff;
|
|
365
|
+
--vpe-bg: #ffffff;
|
|
366
|
+
--vpe-text: #1d2129;
|
|
367
|
+
--vpe-border: #e5e6eb;
|
|
368
|
+
--vpe-output-bg: #f7f8fa;
|
|
369
|
+
--vpe-stderr: #f53f3f;
|
|
370
|
+
}
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
深色主题使用 `.vpe-root.vpe-dark` 下的变量,覆盖时注意同时处理两种主题。
|
|
374
|
+
|
|
375
|
+
## 类型导出
|
|
376
|
+
|
|
377
|
+
```ts
|
|
378
|
+
import type {
|
|
379
|
+
EditorLanguage,
|
|
380
|
+
EditorFile,
|
|
381
|
+
PyodideStatus,
|
|
382
|
+
OutputStream,
|
|
383
|
+
OutputLine,
|
|
384
|
+
PyError,
|
|
385
|
+
SyntaxIssue,
|
|
386
|
+
RunResult,
|
|
387
|
+
InstallResult,
|
|
388
|
+
RunOutputEvent,
|
|
389
|
+
FileOpenEvent,
|
|
390
|
+
FsEntry,
|
|
391
|
+
FsWriteResult,
|
|
392
|
+
FsReadResult,
|
|
393
|
+
FsListResult,
|
|
394
|
+
FsDownloadEvent,
|
|
395
|
+
PythonEditorProps,
|
|
396
|
+
} from 'princess-python-editor'
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
## 本地开发
|
|
400
|
+
|
|
401
|
+
```bash
|
|
402
|
+
pnpm install
|
|
403
|
+
pnpm dev # 启动 playground(含 Vue DevTools)
|
|
404
|
+
pnpm build # 构建组件库到 dist
|
|
405
|
+
pnpm lint
|
|
406
|
+
pnpm format
|
|
407
|
+
pnpm typecheck
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
## 发布到 npm
|
|
411
|
+
|
|
412
|
+
发布前确认:
|
|
413
|
+
|
|
414
|
+
1. 包名 `princess-python-editor` 在 npm 上可用。
|
|
415
|
+
2. 已在 npm 官方源登录:`npm whoami --registry=https://registry.npmjs.org/`。
|
|
416
|
+
3. 代码已提交,工作区没有未提交改动(推荐)。
|
|
417
|
+
|
|
418
|
+
```bash
|
|
419
|
+
# 1. 登录官方 npm(如果本机 registry 配置的是镜像,需要显式指定)
|
|
420
|
+
npm login --registry=https://registry.npmjs.org/
|
|
421
|
+
|
|
422
|
+
# 2. 更新版本号(会创建 commit 与 tag,也可手动修改 package.json)
|
|
423
|
+
npm version patch # 或 minor / major
|
|
424
|
+
|
|
425
|
+
# 3. 构建并检查将要发布的文件
|
|
426
|
+
pnpm build
|
|
427
|
+
npm pack --dry-run
|
|
428
|
+
|
|
429
|
+
# 4. 发布(package.json 的 publishConfig 已指定官方 registry)
|
|
430
|
+
npm publish --registry=https://registry.npmjs.org/
|
|
431
|
+
|
|
432
|
+
# 5. 验证
|
|
433
|
+
npm view princess-python-editor version --registry=https://registry.npmjs.org/
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
如果账号开启了 2FA,发布时需要提供动态验证码:
|
|
437
|
+
|
|
438
|
+
```bash
|
|
439
|
+
npm publish --registry=https://registry.npmjs.org/ --otp=123456
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
如果希望发布时免验证码,可以创建 Granular Access Token,创建时必须:
|
|
443
|
+
|
|
444
|
+
- 权限选择 `Read and write`,不能选 `Read and write (stage only)`
|
|
445
|
+
- 勾选 `Bypass 2FA`
|
|
446
|
+
|
|
447
|
+
然后替换用户级 `~/.npmrc` 中的 Token:
|
|
448
|
+
|
|
449
|
+
```bash
|
|
450
|
+
npm config set //registry.npmjs.org/:_authToken "npm_你的token"
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
说明:
|
|
454
|
+
|
|
455
|
+
- `prepublishOnly` 会自动执行 `pnpm build`,无需手动构建。
|
|
456
|
+
- npm 正在收紧 Bypass 2FA Token 的直接发布权限;CI 发布建议使用 Trusted Publishing (OIDC),或使用 stage-only Token 配合 `npm stage publish` 人工审批。
|
|
457
|
+
- 如果包名被占用,可以改为作用域包,例如 `@your-scope/princess-python-editor`,并执行 `npm publish --access public`。
|
|
458
|
+
- 发布后建议在空目录中执行 `npm i princess-python-editor` 做一次安装冒烟测试。
|
|
459
|
+
|
|
460
|
+
## License
|
|
461
|
+
|
|
462
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
import { EditorView } from '@codemirror/view';
|
|
2
|
+
import { EditorFile, EditorLanguage } from './types';
|
|
3
|
+
export interface Props {
|
|
4
|
+
/** 绑定的代码内容(当前 Tab 的文件内容,v-model) */
|
|
5
|
+
modelValue?: string;
|
|
6
|
+
/** 编辑器主题 */
|
|
7
|
+
theme?: 'light' | 'dark';
|
|
8
|
+
/** 编辑器整体高度(含工具栏、Tab 栏与输出面板;数字按 px 处理,传 '100%' 可撑满父容器) */
|
|
9
|
+
height?: number | string;
|
|
10
|
+
/** 输出面板高度 */
|
|
11
|
+
outputHeight?: number | string;
|
|
12
|
+
/** 空内容时的占位提示 */
|
|
13
|
+
placeholder?: string;
|
|
14
|
+
/** 只读模式 */
|
|
15
|
+
readOnly?: boolean;
|
|
16
|
+
/** 挂载后自动聚焦 */
|
|
17
|
+
autofocus?: boolean;
|
|
18
|
+
/** 是否显示工具栏 */
|
|
19
|
+
showToolbar?: boolean;
|
|
20
|
+
/** 是否显示文件 Tab 栏 */
|
|
21
|
+
showTabs?: boolean;
|
|
22
|
+
/** 是否显示输出面板 */
|
|
23
|
+
showOutput?: boolean;
|
|
24
|
+
/** 运行前是否清空输出 */
|
|
25
|
+
clearOutputOnRun?: boolean;
|
|
26
|
+
/** 语法检查防抖毫秒数 */
|
|
27
|
+
lintDelay?: number;
|
|
28
|
+
/** 关闭实时语法检查 */
|
|
29
|
+
disableLint?: boolean;
|
|
30
|
+
/** 挂载后立即预加载 Pyodide(提前获得语法检查与更快的首次运行) */
|
|
31
|
+
preload?: boolean;
|
|
32
|
+
/** 自定义 Pyodide indexURL(以 / 结尾),默认 jsDelivr CDN;仅首次初始化生效 */
|
|
33
|
+
pyodideUrl?: string;
|
|
34
|
+
/** 初始文件名(支持 v-model:file-name) */
|
|
35
|
+
fileName?: string;
|
|
36
|
+
/** 初始语法类型(支持 v-model:language) */
|
|
37
|
+
language?: EditorLanguage;
|
|
38
|
+
/** 提供给 input() / sys.stdin 的预置文本,按行切分;留空则读取时立即 EOF */
|
|
39
|
+
stdin?: string;
|
|
40
|
+
/** 运行前把 Python Tab 写入虚拟文件系统,便于跨文件 import;默认开启 */
|
|
41
|
+
syncFilesOnRun?: boolean;
|
|
42
|
+
/** 非空时启用草稿持久化(localStorage key),保存全部 Tab 与当前选中项 */
|
|
43
|
+
storageKey?: string;
|
|
44
|
+
/** Pyodide 就绪后自动安装的包列表;非空时挂载后自动开始加载 Pyodide */
|
|
45
|
+
preloadPackages?: string[];
|
|
46
|
+
}
|
|
47
|
+
/** 清除本地草稿(不影响当前编辑内容) */
|
|
48
|
+
declare function clearPersistedState(): void;
|
|
49
|
+
/** 读取当前编辑器内容 */
|
|
50
|
+
declare function getCode(): string;
|
|
51
|
+
/** 替换编辑器内容(保留撤销历史) */
|
|
52
|
+
declare function setCode(code: string): void;
|
|
53
|
+
/** 运行当前编辑器中的代码 */
|
|
54
|
+
declare function run(): void;
|
|
55
|
+
/** 中断当前执行(Pyodide 限制:通过终止并重建 Worker 实现) */
|
|
56
|
+
declare function stop(): void;
|
|
57
|
+
/** 清空输出面板 */
|
|
58
|
+
declare function clearOutput(): void;
|
|
59
|
+
/** 新建文件 Tab(继承当前语言),并切换到新文件 */
|
|
60
|
+
declare function newFile(): void;
|
|
61
|
+
/** 切换 Tab */
|
|
62
|
+
declare function switchFile(id: number): void;
|
|
63
|
+
/** 关闭 Tab(始终保留至少一个文件) */
|
|
64
|
+
declare function closeFile(id: number): void;
|
|
65
|
+
/** 清空当前文件内容(保留输出面板) */
|
|
66
|
+
declare function clearCode(): void;
|
|
67
|
+
/** 复制当前代码到剪贴板,成功后按钮短暂显示对勾 */
|
|
68
|
+
declare function copyCode(): Promise<boolean>;
|
|
69
|
+
/** 下载当前文件 */
|
|
70
|
+
declare function download(): string;
|
|
71
|
+
/** 下载虚拟文件系统中的文本文件,返回下载文件名 */
|
|
72
|
+
declare function downloadFile(path: string): Promise<string | null>;
|
|
73
|
+
/** 写入虚拟文件系统(供宿主预置数据文件) */
|
|
74
|
+
declare function writeFile(path: string, content: string): Promise<import('./types').FsWriteResult>;
|
|
75
|
+
/** 读取虚拟文件系统中的文本文件 */
|
|
76
|
+
declare function readFile(path: string): Promise<import('./types').FsReadResult>;
|
|
77
|
+
/** 列出虚拟文件系统目录 */
|
|
78
|
+
declare function listFiles(path?: string): Promise<import('./types').FsListResult>;
|
|
79
|
+
/** 打开本地文件选择框 */
|
|
80
|
+
declare function openFile(): void;
|
|
81
|
+
/** 聚焦编辑器 */
|
|
82
|
+
declare function focus(): void;
|
|
83
|
+
/** 安装第三方包(内置 wheel 优先,回退 micropip),输出写入面板 */
|
|
84
|
+
declare function install(packages: string[]): Promise<import('./types').InstallResult | {
|
|
85
|
+
ok: boolean;
|
|
86
|
+
durationMs: number;
|
|
87
|
+
error: {
|
|
88
|
+
type: string;
|
|
89
|
+
message: string;
|
|
90
|
+
};
|
|
91
|
+
}>;
|
|
92
|
+
/** 语法检查(运行器未就绪时返回 null) */
|
|
93
|
+
declare function checkSyntax(): Promise<import('./types').SyntaxIssue | null>;
|
|
94
|
+
declare function getEditorView(): EditorView | null;
|
|
95
|
+
/** 获取全部 Tab 文件快照 */
|
|
96
|
+
declare function getFiles(): EditorFile[];
|
|
97
|
+
/** 获取当前 Tab 文件快照 */
|
|
98
|
+
declare function getActiveFile(): EditorFile;
|
|
99
|
+
declare const _default: import('vue').DefineComponent<Props, {
|
|
100
|
+
run: typeof run;
|
|
101
|
+
stop: typeof stop;
|
|
102
|
+
clearOutput: typeof clearOutput;
|
|
103
|
+
clearCode: typeof clearCode;
|
|
104
|
+
newFile: typeof newFile;
|
|
105
|
+
switchFile: typeof switchFile;
|
|
106
|
+
closeFile: typeof closeFile;
|
|
107
|
+
copyCode: typeof copyCode;
|
|
108
|
+
download: typeof download;
|
|
109
|
+
openFile: typeof openFile;
|
|
110
|
+
focus: typeof focus;
|
|
111
|
+
install: typeof install;
|
|
112
|
+
checkSyntax: typeof checkSyntax;
|
|
113
|
+
getEditorView: typeof getEditorView;
|
|
114
|
+
getCode: typeof getCode;
|
|
115
|
+
setCode: typeof setCode;
|
|
116
|
+
getFiles: typeof getFiles;
|
|
117
|
+
getActiveFile: typeof getActiveFile;
|
|
118
|
+
writeFile: typeof writeFile;
|
|
119
|
+
readFile: typeof readFile;
|
|
120
|
+
listFiles: typeof listFiles;
|
|
121
|
+
downloadFile: typeof downloadFile;
|
|
122
|
+
clearPersistedState: typeof clearPersistedState;
|
|
123
|
+
}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
|
|
124
|
+
[x: string]: any;
|
|
125
|
+
} & {
|
|
126
|
+
[x: string]: any;
|
|
127
|
+
}, string, import('vue').PublicProps, Readonly<Props> & Readonly<{
|
|
128
|
+
[x: `on${Capitalize<any>}`]: ((...args: any) => any) | undefined;
|
|
129
|
+
}>, {
|
|
130
|
+
height: number | string;
|
|
131
|
+
stdin: string;
|
|
132
|
+
pyodideUrl: string;
|
|
133
|
+
modelValue: string;
|
|
134
|
+
theme: "light" | "dark";
|
|
135
|
+
outputHeight: number | string;
|
|
136
|
+
placeholder: string;
|
|
137
|
+
readOnly: boolean;
|
|
138
|
+
autofocus: boolean;
|
|
139
|
+
showToolbar: boolean;
|
|
140
|
+
showTabs: boolean;
|
|
141
|
+
showOutput: boolean;
|
|
142
|
+
clearOutputOnRun: boolean;
|
|
143
|
+
lintDelay: number;
|
|
144
|
+
disableLint: boolean;
|
|
145
|
+
preload: boolean;
|
|
146
|
+
fileName: string;
|
|
147
|
+
language: EditorLanguage;
|
|
148
|
+
syncFilesOnRun: boolean;
|
|
149
|
+
storageKey: string;
|
|
150
|
+
preloadPackages: string[];
|
|
151
|
+
}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
|
|
152
|
+
tabsEl: HTMLDivElement;
|
|
153
|
+
fileInputEl: HTMLInputElement;
|
|
154
|
+
editorEl: HTMLDivElement;
|
|
155
|
+
outputEl: HTMLPreElement;
|
|
156
|
+
}, HTMLDivElement>;
|
|
157
|
+
export default _default;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { Extension } from '@codemirror/state';
|
|
2
|
+
import { EditorView } from '@codemirror/view';
|
|
3
|
+
export declare const MONO_FONT_STACK = "'JetBrains Mono', 'Fira Code', 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace";
|
|
4
|
+
/** 效果:设置错误行(1 起的行号数组),传空数组清除 */
|
|
5
|
+
export declare const setErrorLines: import('@codemirror/state').StateEffectType<number[]>;
|
|
6
|
+
export interface CreateEditorOptions {
|
|
7
|
+
value: string;
|
|
8
|
+
dark: boolean;
|
|
9
|
+
placeholderText: string;
|
|
10
|
+
/** 语言扩展,默认 Python */
|
|
11
|
+
language?: Extension;
|
|
12
|
+
/** 由组件注入的扩展(主题 / 只读 Compartment、linter 等) */
|
|
13
|
+
extensions: Extension[];
|
|
14
|
+
onDocChange: (code: string) => void;
|
|
15
|
+
/** Ctrl/Cmd + Enter 快捷运行回调 */
|
|
16
|
+
onRunShortcut: () => void;
|
|
17
|
+
}
|
|
18
|
+
export declare function createEditor(host: HTMLElement, opts: CreateEditorOptions): EditorView;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { Extension } from '@codemirror/state';
|
|
2
|
+
import { PyodideRunner } from '../runtime/PyodideRunner';
|
|
3
|
+
/**
|
|
4
|
+
* 基于运行器 ast.parse 的实时语法 linter。
|
|
5
|
+
* 运行器未就绪时静默跳过(不触发 Pyodide 下载),
|
|
6
|
+
* 就绪后由组件调用 forceLinting 主动刷新一次。
|
|
7
|
+
*/
|
|
8
|
+
export declare function makePythonLinter(runner: PyodideRunner, delay?: number): Extension;
|
package/dist/icons.d.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { FunctionalComponent } from 'vue';
|
|
2
|
+
/** 运行(实心三角) */
|
|
3
|
+
export declare const IconPlay: FunctionalComponent<{}, {}, any, {}>;
|
|
4
|
+
/** 停止(实心方块) */
|
|
5
|
+
export declare const IconStop: FunctionalComponent<{}, {}, any, {}>;
|
|
6
|
+
/** 清空(垃圾桶) */
|
|
7
|
+
export declare const IconClear: FunctionalComponent<{}, {}, any, {}>;
|
|
8
|
+
/** 新建文件(文件 + 加号) */
|
|
9
|
+
export declare const IconNew: FunctionalComponent<{}, {}, any, {}>;
|
|
10
|
+
/** 打开文件(文件夹) */
|
|
11
|
+
export declare const IconFolder: FunctionalComponent<{}, {}, any, {}>;
|
|
12
|
+
/** 文件 */
|
|
13
|
+
export declare const IconFile: FunctionalComponent<{}, {}, any, {}>;
|
|
14
|
+
/** 下载(向下箭头 + 托盘) */
|
|
15
|
+
export declare const IconDownload: FunctionalComponent<{}, {}, any, {}>;
|
|
16
|
+
/** 复制(双层纸张) */
|
|
17
|
+
export declare const IconCopy: FunctionalComponent<{}, {}, any, {}>;
|
|
18
|
+
/** 对勾(复制成功反馈) */
|
|
19
|
+
export declare const IconCheck: FunctionalComponent<{}, {}, any, {}>;
|
|
20
|
+
/** 关闭(叉号) */
|
|
21
|
+
export declare const IconClose: FunctionalComponent<{}, {}, any, {}>;
|
|
22
|
+
/** 加号(新建 Tab) */
|
|
23
|
+
export declare const IconPlus: FunctionalComponent<{}, {}, any, {}>;
|