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.html DELETED
@@ -1,1013 +0,0 @@
1
- <!doctype html>
2
- <html lang="zh-CN">
3
- <head>
4
- <meta charset="utf-8" />
5
- <meta name="viewport" content="width=device-width, initial-scale=1" />
6
- <meta name="color-scheme" content="light dark" />
7
- <title>princess-python-editor · README</title>
8
- <style>
9
- :root {
10
- color-scheme: light dark;
11
- --page-bg: #f2f4f7;
12
- --card-bg: #ffffff;
13
- --subtle-bg: #f6f8fa;
14
- --text: #1f2328;
15
- --muted: #59636e;
16
- --border: #d1d9e0;
17
- --link: #0969da;
18
- --inline-code-bg: rgba(129, 139, 152, 0.14);
19
- --stripe: #f6f8fa;
20
- --shadow: 0 1px 2px rgba(31, 35, 40, 0.04), 0 16px 40px rgba(31, 35, 40, 0.08);
21
- --brand-1: #165dff;
22
- --brand-2: #61afef;
23
- --brand-3: #98c379;
24
- }
25
-
26
- @media (prefers-color-scheme: dark) {
27
- :root {
28
- --page-bg: #010409;
29
- --card-bg: #0d1117;
30
- --subtle-bg: #151b23;
31
- --text: #e6edf3;
32
- --muted: #9198a1;
33
- --border: #3d444d;
34
- --link: #4493f8;
35
- --inline-code-bg: rgba(101, 108, 118, 0.22);
36
- --stripe: #151b23;
37
- --shadow: 0 1px 2px rgba(1, 4, 9, 0.4), 0 16px 40px rgba(1, 4, 9, 0.55);
38
- }
39
- }
40
-
41
- *,
42
- *::before,
43
- *::after {
44
- box-sizing: border-box;
45
- }
46
-
47
- html {
48
- -webkit-text-size-adjust: 100%;
49
- }
50
-
51
- body {
52
- margin: 0;
53
- background: var(--page-bg);
54
- color: var(--text);
55
- font-family:
56
- -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', 'PingFang SC',
57
- 'Hiragino Sans GB', 'Microsoft YaHei', sans-serif;
58
- font-size: 16px;
59
- line-height: 1.75;
60
- -webkit-font-smoothing: antialiased;
61
- text-rendering: optimizeLegibility;
62
- }
63
-
64
- ::selection {
65
- background: rgba(22, 93, 255, 0.18);
66
- }
67
-
68
- .page {
69
- width: 100%;
70
- max-width: 1060px;
71
- margin: 0 auto;
72
- padding: 48px 24px 72px;
73
- }
74
-
75
- .card {
76
- position: relative;
77
- overflow: hidden;
78
- padding: 52px 56px 60px;
79
- border: 1px solid var(--border);
80
- border-radius: 14px;
81
- background: var(--card-bg);
82
- box-shadow: var(--shadow);
83
- }
84
-
85
- .card::before {
86
- content: '';
87
- position: absolute;
88
- inset: 0 0 auto;
89
- height: 3px;
90
- background: linear-gradient(90deg, var(--brand-1), var(--brand-2), var(--brand-3));
91
- }
92
-
93
- .markdown-body h1,
94
- .markdown-body h2,
95
- .markdown-body h3,
96
- .markdown-body h4,
97
- .markdown-body h5,
98
- .markdown-body h6 {
99
- margin: 32px 0 16px;
100
- font-weight: 600;
101
- line-height: 1.35;
102
- letter-spacing: -0.01em;
103
- }
104
-
105
- .markdown-body h1 {
106
- margin-top: 0;
107
- padding-bottom: 0.35em;
108
- border-bottom: 1px solid var(--border);
109
- font-size: 2.1em;
110
- letter-spacing: -0.02em;
111
- }
112
-
113
- .markdown-body h2 {
114
- padding-bottom: 0.3em;
115
- border-bottom: 1px solid var(--border);
116
- font-size: 1.5em;
117
- }
118
-
119
- .markdown-body h3 {
120
- font-size: 1.22em;
121
- }
122
-
123
- .markdown-body h4 {
124
- font-size: 1.05em;
125
- }
126
-
127
- .markdown-body p,
128
- .markdown-body ul,
129
- .markdown-body ol,
130
- .markdown-body table,
131
- .markdown-body pre,
132
- .markdown-body blockquote,
133
- .markdown-body dl {
134
- margin: 0 0 16px;
135
- }
136
-
137
- .markdown-body h2 + p,
138
- .markdown-body h2 + ul,
139
- .markdown-body h2 + ol,
140
- .markdown-body h2 + table,
141
- .markdown-body h2 + pre,
142
- .markdown-body h3 + p,
143
- .markdown-body h3 + ul,
144
- .markdown-body h3 + ol,
145
- .markdown-body h3 + table,
146
- .markdown-body h3 + pre {
147
- margin-top: 0;
148
- }
149
-
150
- .markdown-body h1 + p {
151
- margin-bottom: 10px;
152
- color: var(--muted);
153
- font-size: 1.08em;
154
- }
155
-
156
- .markdown-body h1 + p + p {
157
- margin-bottom: 28px;
158
- }
159
-
160
- .markdown-body ul,
161
- .markdown-body ol {
162
- padding-left: 2em;
163
- }
164
-
165
- .markdown-body li + li {
166
- margin-top: 0.3em;
167
- }
168
-
169
- .markdown-body li > ul,
170
- .markdown-body li > ol {
171
- margin: 0.3em 0 0.4em;
172
- }
173
-
174
- .markdown-body li::marker {
175
- color: var(--muted);
176
- }
177
-
178
- .markdown-body a {
179
- color: var(--link);
180
- text-decoration: none;
181
- }
182
-
183
- .markdown-body a:hover {
184
- text-decoration: underline;
185
- text-underline-offset: 2px;
186
- }
187
-
188
- .markdown-body strong {
189
- font-weight: 600;
190
- }
191
-
192
- .markdown-body img {
193
- max-width: 100%;
194
- vertical-align: middle;
195
- }
196
-
197
- .markdown-body img[src*='img.shields.io'] {
198
- height: 20px;
199
- width: auto;
200
- }
201
-
202
- .markdown-body hr {
203
- height: 1px;
204
- margin: 36px 0;
205
- border: 0;
206
- background: var(--border);
207
- }
208
-
209
- .markdown-body blockquote {
210
- margin-right: 0;
211
- margin-left: 0;
212
- padding: 0 1em;
213
- border-left: 0.25em solid var(--border);
214
- color: var(--muted);
215
- }
216
-
217
- .markdown-body blockquote > :last-child {
218
- margin-bottom: 0;
219
- }
220
-
221
- .markdown-body code,
222
- .markdown-body kbd,
223
- .markdown-body pre {
224
- font-family:
225
- 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, 'JetBrains Mono', monospace;
226
- }
227
-
228
- .markdown-body code {
229
- padding: 0.18em 0.4em;
230
- border-radius: 6px;
231
- background: var(--inline-code-bg);
232
- font-size: 85%;
233
- white-space: break-spaces;
234
- }
235
-
236
- .markdown-body pre {
237
- padding: 16px 18px;
238
- overflow: auto;
239
- border: 1px solid var(--border);
240
- border-radius: 8px;
241
- background: var(--subtle-bg);
242
- line-height: 1.6;
243
- }
244
-
245
- .markdown-body pre code {
246
- display: block;
247
- padding: 0;
248
- border-radius: 0;
249
- background: transparent;
250
- font-size: 13px;
251
- white-space: pre;
252
- overflow-wrap: normal;
253
- }
254
-
255
- .markdown-body table {
256
- display: block;
257
- width: max-content;
258
- max-width: 100%;
259
- overflow: auto;
260
- border-collapse: collapse;
261
- border-spacing: 0;
262
- font-size: 95%;
263
- }
264
-
265
- .markdown-body th,
266
- .markdown-body td {
267
- padding: 7px 14px;
268
- border: 1px solid var(--border);
269
- }
270
-
271
- .markdown-body th {
272
- background: var(--subtle-bg);
273
- font-weight: 600;
274
- text-align: left;
275
- white-space: nowrap;
276
- }
277
-
278
- .markdown-body tbody tr:nth-child(2n) {
279
- background: var(--stripe);
280
- }
281
-
282
- .markdown-body td code {
283
- white-space: nowrap;
284
- }
285
-
286
- @media (max-width: 760px) {
287
- .page {
288
- padding: 0;
289
- }
290
-
291
- .card {
292
- padding: 32px 20px 44px;
293
- border: 0;
294
- border-radius: 0;
295
- box-shadow: none;
296
- }
297
-
298
- .markdown-body h1 {
299
- font-size: 1.75em;
300
- }
301
-
302
- .markdown-body h2 {
303
- font-size: 1.32em;
304
- }
305
-
306
- .markdown-body pre {
307
- padding: 12px 14px;
308
- }
309
- }
310
-
311
- @media print {
312
- body {
313
- background: #fff;
314
- }
315
-
316
- .page {
317
- max-width: none;
318
- padding: 0;
319
- }
320
-
321
- .card {
322
- padding: 0;
323
- border: 0;
324
- box-shadow: none;
325
- }
326
-
327
- .card::before {
328
- display: none;
329
- }
330
-
331
- .markdown-body pre,
332
- .markdown-body table,
333
- .markdown-body blockquote {
334
- break-inside: avoid;
335
- }
336
- }
337
- </style>
338
- </head>
339
- <body>
340
- <main class="page">
341
- <article class="card markdown-body">
342
- <h1>princess-python-editor</h1>
343
- <p>
344
- Vue 3 + TypeScript 的 Python 代码编辑器组件:基于 CodeMirror 6 的编辑体验,通过 Pyodide
345
- 在浏览器端执行 Python,并支持实时语法检查。
346
- </p>
347
- <p>
348
- <a href="https://www.npmjs.com/package/princess-python-editor"
349
- ><img src="https://img.shields.io/npm/v/princess-python-editor.svg" alt="npm version"
350
- /></a>
351
- <a href="LICENSE"
352
- ><img src="https://img.shields.io/npm/l/princess-python-editor.svg" alt="license"
353
- /></a>
354
- </p>
355
- <h2>特性</h2>
356
- <ul>
357
- <li>
358
- <strong>CodeMirror 6 编辑</strong>:语法高亮、自动补全、括号匹配、撤销重做、错误行高亮
359
- </li>
360
- <li>
361
- <strong>浏览器端执行 Python</strong>:基于 Pyodide(CPython WASM),无需后端,支持顶层
362
- <code>await</code>
363
- </li>
364
- <li>
365
- <strong>实时语法检查</strong>:停止输入后自动检查 Python 语法,可配置防抖时间或关闭
366
- </li>
367
- <li>
368
- <strong>多文件 Tab</strong
369
- >:新建、打开本地文件、下载、复制、清空、切换、关闭,文件名可编辑
370
- </li>
371
- <li><strong>多语言编辑</strong>:Python、SQL、JavaScript、JSON 的语法高亮与补全</li>
372
- <li><strong>输出面板</strong>:stdout / stderr 分色展示,自动滚动,可清空</li>
373
- <li>
374
- <strong>主题与只读</strong>:浅色 / 深色主题,只读模式,工具栏与输出面板均可按需显示
375
- </li>
376
- <li><strong>第三方包安装</strong>:优先使用 Pyodide 内置 wheel,缺失时回退 micropip</li>
377
- <li><strong>可中断执行</strong>:运行长时间计算时可停止,Worker 自动重建</li>
378
- <li>
379
- <strong>Headless 能力</strong>:额外导出 <code>usePyodide</code>、<code
380
- >PyodideRunner</code
381
- >
382
- 等 API,可在无编辑器场景下执行 Python
383
- </li>
384
- </ul>
385
- <h2>环境要求</h2>
386
- <ul>
387
- <li>Vue <code>&gt;= 3.3.0</code></li>
388
- <li>支持 WebAssembly 与 Web Worker 的现代浏览器</li>
389
- <li>首次加载 Pyodide 需要访问 CDN(默认 jsDelivr),也可以自托管</li>
390
- </ul>
391
- <blockquote>
392
- <p>组件执行代码时运行在 Web Worker 中,无法直接访问页面 DOM。</p>
393
- </blockquote>
394
- <h2>安装</h2>
395
- <pre><code class="language-bash">pnpm add princess-python-editor
396
- # 或
397
- npm install princess-python-editor
398
- # 或
399
- yarn add princess-python-editor
400
- </code></pre>
401
- <h2>快速开始</h2>
402
- <p>在应用入口引入组件样式:</p>
403
- <pre><code class="language-ts">// main.ts
404
- import &#39;princess-python-editor/style.css&#39;
405
- </code></pre>
406
- <p>在页面中使用:</p>
407
- <pre><code class="language-vue">&lt;script setup lang=&quot;ts&quot;&gt;
408
- import { ref } from &#39;vue&#39;
409
- import { PythonEditor } from &#39;princess-python-editor&#39;
410
- import type { EditorLanguage, PyError, RunResult } from &#39;princess-python-editor&#39;
411
-
412
- const code = ref(`# 点击工具栏“运行”或按 Ctrl+Enter
413
- def greet(name):
414
- return f&quot;Hello, {name}!&quot;
415
-
416
- print(greet(&quot;Pyodide&quot;))
417
- `)
418
- const fileName = ref(&#39;main.py&#39;)
419
- const language = ref&lt;EditorLanguage&gt;(&#39;python&#39;)
420
-
421
- function onRunFinish(result: RunResult) {
422
- console.log(result.ok ? `执行完成,耗时 ${result.durationMs}ms` : &#39;执行失败&#39;)
423
- }
424
-
425
- function onRunError(error: PyError) {
426
- console.error(error.type, error.message)
427
- }
428
- &lt;/script&gt;
429
-
430
- &lt;template&gt;
431
- &lt;PythonEditor
432
- v-model=&quot;code&quot;
433
- v-model:file-name=&quot;fileName&quot;
434
- v-model:language=&quot;language&quot;
435
- height=&quot;100%&quot;
436
- :output-height=&quot;220&quot;
437
- placeholder=&quot;# 在这里编写 Python 代码&quot;
438
- @run-finish=&quot;onRunFinish&quot;
439
- @run-error=&quot;onRunError&quot;
440
- /&gt;
441
- &lt;/template&gt;
442
- </code></pre>
443
- <blockquote>
444
- <p>
445
- <code>height=&quot;100%&quot;</code> 需要父容器具有明确高度;也可以直接传入数字(按 px
446
- 处理)。
447
- </p>
448
- </blockquote>
449
- <h3>双向绑定</h3>
450
- <table>
451
- <thead>
452
- <tr>
453
- <th>绑定</th>
454
- <th>类型</th>
455
- <th>说明</th>
456
- </tr>
457
- </thead>
458
- <tbody>
459
- <tr>
460
- <td><code>v-model</code></td>
461
- <td><code>string</code></td>
462
- <td>当前 Tab 的代码内容</td>
463
- </tr>
464
- <tr>
465
- <td><code>v-model:file-name</code></td>
466
- <td><code>string</code></td>
467
- <td>当前 Tab 的文件名,切换 Tab 时同步</td>
468
- </tr>
469
- <tr>
470
- <td><code>v-model:language</code></td>
471
- <td><code>EditorLanguage</code></td>
472
- <td>当前 Tab 的语法类型,切换 Tab 时同步</td>
473
- </tr>
474
- </tbody>
475
- </table>
476
- <h2>Props</h2>
477
- <table>
478
- <thead>
479
- <tr>
480
- <th>属性</th>
481
- <th>类型</th>
482
- <th>默认值</th>
483
- <th>说明</th>
484
- </tr>
485
- </thead>
486
- <tbody>
487
- <tr>
488
- <td><code>modelValue</code></td>
489
- <td><code>string</code></td>
490
- <td><code>&#39;&#39;</code></td>
491
- <td>当前 Tab 的代码内容,支持 <code>v-model</code></td>
492
- </tr>
493
- <tr>
494
- <td><code>theme</code></td>
495
- <td><code>&#39;light&#39; | &#39;dark&#39;</code></td>
496
- <td><code>&#39;light&#39;</code></td>
497
- <td>编辑器主题</td>
498
- </tr>
499
- <tr>
500
- <td><code>height</code></td>
501
- <td><code>number | string</code></td>
502
- <td><code>520</code></td>
503
- <td>组件整体高度(含工具栏、Tab 与输出面板),数字按 px 处理</td>
504
- </tr>
505
- <tr>
506
- <td><code>outputHeight</code></td>
507
- <td><code>number | string</code></td>
508
- <td><code>180</code></td>
509
- <td>输出面板高度</td>
510
- </tr>
511
- <tr>
512
- <td><code>placeholder</code></td>
513
- <td><code>string</code></td>
514
- <td><code>&#39;&#39;</code></td>
515
- <td>内容为空时的占位提示</td>
516
- </tr>
517
- <tr>
518
- <td><code>readOnly</code></td>
519
- <td><code>boolean</code></td>
520
- <td><code>false</code></td>
521
- <td>只读模式,同时禁用文件操作与语言切换</td>
522
- </tr>
523
- <tr>
524
- <td><code>autofocus</code></td>
525
- <td><code>boolean</code></td>
526
- <td><code>false</code></td>
527
- <td>挂载后自动聚焦编辑器</td>
528
- </tr>
529
- <tr>
530
- <td><code>showToolbar</code></td>
531
- <td><code>boolean</code></td>
532
- <td><code>true</code></td>
533
- <td>是否显示工具栏</td>
534
- </tr>
535
- <tr>
536
- <td><code>showTabs</code></td>
537
- <td><code>boolean</code></td>
538
- <td><code>true</code></td>
539
- <td>是否显示文件 Tab 栏</td>
540
- </tr>
541
- <tr>
542
- <td><code>showOutput</code></td>
543
- <td><code>boolean</code></td>
544
- <td><code>true</code></td>
545
- <td>是否显示输出面板</td>
546
- </tr>
547
- <tr>
548
- <td><code>clearOutputOnRun</code></td>
549
- <td><code>boolean</code></td>
550
- <td><code>true</code></td>
551
- <td>运行前是否清空输出</td>
552
- </tr>
553
- <tr>
554
- <td><code>lintDelay</code></td>
555
- <td><code>number</code></td>
556
- <td><code>600</code></td>
557
- <td>语法检查防抖毫秒数</td>
558
- </tr>
559
- <tr>
560
- <td><code>disableLint</code></td>
561
- <td><code>boolean</code></td>
562
- <td><code>false</code></td>
563
- <td>关闭实时语法检查</td>
564
- </tr>
565
- <tr>
566
- <td><code>preload</code></td>
567
- <td><code>boolean</code></td>
568
- <td><code>false</code></td>
569
- <td>挂载后立即预加载 Pyodide</td>
570
- </tr>
571
- <tr>
572
- <td><code>pyodideUrl</code></td>
573
- <td><code>string</code></td>
574
- <td>见下文</td>
575
- <td>自定义 Pyodide <code>indexURL</code>,必须以 <code>/</code> 结尾</td>
576
- </tr>
577
- <tr>
578
- <td><code>fileName</code></td>
579
- <td><code>string</code></td>
580
- <td><code>&#39;main.py&#39;</code></td>
581
- <td>初始文件名,支持 <code>v-model:file-name</code></td>
582
- </tr>
583
- <tr>
584
- <td><code>language</code></td>
585
- <td><code>EditorLanguage</code></td>
586
- <td><code>&#39;python&#39;</code></td>
587
- <td>初始语法类型,支持 <code>v-model:language</code></td>
588
- </tr>
589
- </tbody>
590
- </table>
591
- <h2>事件</h2>
592
- <table>
593
- <thead>
594
- <tr>
595
- <th>事件</th>
596
- <th>参数</th>
597
- <th>说明</th>
598
- </tr>
599
- </thead>
600
- <tbody>
601
- <tr>
602
- <td><code>ready</code></td>
603
- <td>—</td>
604
- <td>Pyodide 加载完成</td>
605
- </tr>
606
- <tr>
607
- <td><code>status-change</code></td>
608
- <td><code>PyodideStatus</code></td>
609
- <td>
610
- 运行器状态变化:<code>idle</code> / <code>loading</code> / <code>ready</code> /
611
- <code>running</code>
612
- </td>
613
- </tr>
614
- <tr>
615
- <td><code>run-start</code></td>
616
- <td>—</td>
617
- <td>开始执行</td>
618
- </tr>
619
- <tr>
620
- <td><code>run-output</code></td>
621
- <td><code>{ stream: &#39;stdout&#39; | &#39;stderr&#39;; text: string }</code></td>
622
- <td>执行期间的实时输出</td>
623
- </tr>
624
- <tr>
625
- <td><code>run-error</code></td>
626
- <td><code>PyError</code></td>
627
- <td>执行过程中抛出 Python 异常</td>
628
- </tr>
629
- <tr>
630
- <td><code>run-finish</code></td>
631
- <td><code>RunResult</code></td>
632
- <td>本次执行结束(成功、失败或中断)</td>
633
- </tr>
634
- <tr>
635
- <td><code>load-error</code></td>
636
- <td><code>string</code></td>
637
- <td>Pyodide 加载失败</td>
638
- </tr>
639
- <tr>
640
- <td><code>new-file</code></td>
641
- <td><code>EditorFile</code></td>
642
- <td>新建文件</td>
643
- </tr>
644
- <tr>
645
- <td><code>file-switch</code></td>
646
- <td><code>EditorFile</code></td>
647
- <td>切换文件</td>
648
- </tr>
649
- <tr>
650
- <td><code>file-close</code></td>
651
- <td><code>EditorFile</code></td>
652
- <td>关闭文件</td>
653
- </tr>
654
- <tr>
655
- <td><code>copy</code></td>
656
- <td><code>string</code></td>
657
- <td>复制代码成功</td>
658
- </tr>
659
- <tr>
660
- <td><code>download</code></td>
661
- <td><code>string</code></td>
662
- <td>下载文件,参数为最终文件名</td>
663
- </tr>
664
- <tr>
665
- <td><code>file-open</code></td>
666
- <td><code>FileOpenEvent</code></td>
667
- <td>打开本地文件</td>
668
- </tr>
669
- <tr>
670
- <td><code>update:modelValue</code></td>
671
- <td><code>string</code></td>
672
- <td>代码内容变化</td>
673
- </tr>
674
- <tr>
675
- <td><code>update:fileName</code></td>
676
- <td><code>string</code></td>
677
- <td>文件名变化</td>
678
- </tr>
679
- <tr>
680
- <td><code>update:language</code></td>
681
- <td><code>EditorLanguage</code></td>
682
- <td>语法类型变化</td>
683
- </tr>
684
- </tbody>
685
- </table>
686
- <h2>实例方法</h2>
687
- <p>通过模板 <code>ref</code> 调用:</p>
688
- <pre><code class="language-vue">&lt;script setup lang=&quot;ts&quot;&gt;
689
- import { ref } from &#39;vue&#39;
690
- import { PythonEditor } from &#39;princess-python-editor&#39;
691
-
692
- const editorRef = ref&lt;InstanceType&lt;typeof PythonEditor&gt; | null&gt;(null)
693
-
694
- async function runAndInstall() {
695
- editorRef.value?.run()
696
- editorRef.value?.setCode(&#39;print(&quot;hello&quot;)&#39;)
697
- const result = await editorRef.value?.install([&#39;numpy&#39;])
698
- console.log(result?.ok)
699
- }
700
- &lt;/script&gt;
701
-
702
- &lt;template&gt;
703
- &lt;PythonEditor ref=&quot;editorRef&quot; v-model=&quot;code&quot; /&gt;
704
- &lt;/template&gt;
705
- </code></pre>
706
- <table>
707
- <thead>
708
- <tr>
709
- <th>方法</th>
710
- <th>返回值</th>
711
- <th>说明</th>
712
- </tr>
713
- </thead>
714
- <tbody>
715
- <tr>
716
- <td><code>run()</code></td>
717
- <td><code>void</code></td>
718
- <td>运行当前 Python 文件</td>
719
- </tr>
720
- <tr>
721
- <td><code>stop()</code></td>
722
- <td><code>void</code></td>
723
- <td>中断执行(终止并重建 Worker,Python 运行时状态会丢失)</td>
724
- </tr>
725
- <tr>
726
- <td><code>clearOutput()</code></td>
727
- <td><code>void</code></td>
728
- <td>清空输出面板</td>
729
- </tr>
730
- <tr>
731
- <td><code>clearCode()</code></td>
732
- <td><code>void</code></td>
733
- <td>清空当前文件内容(保留输出)</td>
734
- </tr>
735
- <tr>
736
- <td><code>newFile()</code></td>
737
- <td><code>void</code></td>
738
- <td>新建文件并切换过去</td>
739
- </tr>
740
- <tr>
741
- <td><code>switchFile(id)</code></td>
742
- <td><code>void</code></td>
743
- <td>切换到指定文件</td>
744
- </tr>
745
- <tr>
746
- <td><code>closeFile(id)</code></td>
747
- <td><code>void</code></td>
748
- <td>关闭指定文件(至少保留一个)</td>
749
- </tr>
750
- <tr>
751
- <td><code>copyCode()</code></td>
752
- <td><code>Promise&lt;boolean&gt;</code></td>
753
- <td>复制当前代码到剪贴板</td>
754
- </tr>
755
- <tr>
756
- <td><code>download()</code></td>
757
- <td><code>string</code></td>
758
- <td>下载当前文件,返回最终文件名</td>
759
- </tr>
760
- <tr>
761
- <td><code>openFile()</code></td>
762
- <td><code>void</code></td>
763
- <td>打开本地文件选择框</td>
764
- </tr>
765
- <tr>
766
- <td><code>focus()</code></td>
767
- <td><code>void</code></td>
768
- <td>聚焦编辑器</td>
769
- </tr>
770
- <tr>
771
- <td><code>install(packages)</code></td>
772
- <td><code>Promise&lt;InstallResult&gt;</code></td>
773
- <td>安装第三方包</td>
774
- </tr>
775
- <tr>
776
- <td><code>checkSyntax()</code></td>
777
- <td><code>Promise&lt;SyntaxIssue | null&gt;</code></td>
778
- <td>检查当前内容语法,未就绪时返回 <code>null</code></td>
779
- </tr>
780
- <tr>
781
- <td><code>getEditorView()</code></td>
782
- <td><code>EditorView | null</code></td>
783
- <td>获取 CodeMirror <code>EditorView</code> 实例</td>
784
- </tr>
785
- <tr>
786
- <td><code>getCode()</code></td>
787
- <td><code>string</code></td>
788
- <td>获取当前代码</td>
789
- </tr>
790
- <tr>
791
- <td><code>setCode(code)</code></td>
792
- <td><code>void</code></td>
793
- <td>替换当前代码(保留撤销历史)</td>
794
- </tr>
795
- <tr>
796
- <td><code>getFiles()</code></td>
797
- <td><code>EditorFile[]</code></td>
798
- <td>获取全部文件快照</td>
799
- </tr>
800
- <tr>
801
- <td><code>getActiveFile()</code></td>
802
- <td><code>EditorFile</code></td>
803
- <td>获取当前文件快照</td>
804
- </tr>
805
- </tbody>
806
- </table>
807
- <h2>语言与执行说明</h2>
808
- <p>
809
- <code>language</code> 可选值为
810
- <code>&#39;python&#39; | &#39;sql&#39; | &#39;javascript&#39; | &#39;json&#39;</code
811
- >,用于语法高亮、补全与文件扩展名推断。
812
- </p>
813
- <p>
814
- <strong>只有 Python 文件可以执行。</strong> 切换到 SQL / JavaScript / JSON
815
- 后,运行按钮会被禁用,<code>Ctrl+Enter</code> 也只会在输出面板提示“仅支持执行 Python
816
- 代码”。这些语言目前是纯编辑模式,不具备运行时。
817
- </p>
818
- <h2>Pyodide 配置</h2>
819
- <h3>默认 CDN</h3>
820
- <p>默认从 jsDelivr 加载 Pyodide <code>v0.27.2</code>:</p>
821
- <pre><code class="language-ts">import { DEFAULT_PYODIDE_URL } from &#39;princess-python-editor&#39;
822
- // https://cdn.jsdelivr.net/pyodide/v0.27.2/full/
823
- </code></pre>
824
- <h3>自托管</h3>
825
- <p>将 Pyodide 发行包放到静态资源目录,然后传入以 <code>/</code> 结尾的 URL:</p>
826
- <pre><code class="language-vue">&lt;PythonEditor v-model=&quot;code&quot; pyodide-url=&quot;/pyodide/v0.27.2/full/&quot; /&gt;
827
- </code></pre>
828
- <blockquote>
829
- <p>
830
- 底层运行器是模块级单例,<code>pyodideUrl</code>
831
- 只在页面中第一次初始化前生效;之后再传入会被忽略并输出警告。
832
- </p>
833
- </blockquote>
834
- <h3>安装第三方包</h3>
835
- <pre><code class="language-ts">const result = await editorRef.value?.install([&#39;numpy&#39;, &#39;pandas&#39;])
836
- </code></pre>
837
- <p>优先使用 Pyodide 内置 wheel,未内置的包会回退到 micropip 从 PyPI 下载。</p>
838
- <h3>CSP 提示</h3>
839
- <p>组件通过 Blob URL 创建 Worker,并在 Worker 中加载 Pyodide。使用严格 CSP 时需要允许:</p>
840
- <ul>
841
- <li><code>worker-src blob:</code></li>
842
- <li>Pyodide 资源地址对应的 <code>script-src</code> / <code>connect-src</code></li>
843
- </ul>
844
- <h2>无编辑器使用 Python</h2>
845
- <p><code>usePyodide</code> 与编辑器共享同一个 Pyodide 实例:</p>
846
- <pre><code class="language-ts">import { usePyodide } from &#39;princess-python-editor&#39;
847
-
848
- const { status, version, outputs, runPython, install, checkSyntax, interrupt, clearOutputs } =
849
- usePyodide({ preload: true })
850
-
851
- const result = await runPython(&#39;print(1 + 1)&#39;)
852
- console.log(result.ok, result.value, result.durationMs)
853
- </code></pre>
854
- <p>返回内容包括:</p>
855
- <table>
856
- <thead>
857
- <tr>
858
- <th>字段</th>
859
- <th>类型</th>
860
- <th>说明</th>
861
- </tr>
862
- </thead>
863
- <tbody>
864
- <tr>
865
- <td><code>status</code></td>
866
- <td><code>Ref&lt;PyodideStatus&gt;</code></td>
867
- <td>运行器状态</td>
868
- </tr>
869
- <tr>
870
- <td><code>version</code></td>
871
- <td><code>Ref&lt;string&gt;</code></td>
872
- <td>Pyodide 版本</td>
873
- </tr>
874
- <tr>
875
- <td><code>outputs</code></td>
876
- <td><code>Ref&lt;OutputLine[]&gt;</code></td>
877
- <td>输出行</td>
878
- </tr>
879
- <tr>
880
- <td><code>runPython(code)</code></td>
881
- <td><code>Promise&lt;RunResult&gt;</code></td>
882
- <td>执行代码</td>
883
- </tr>
884
- <tr>
885
- <td><code>install(packages)</code></td>
886
- <td><code>Promise&lt;InstallResult&gt;</code></td>
887
- <td>安装包</td>
888
- </tr>
889
- <tr>
890
- <td><code>checkSyntax(code)</code></td>
891
- <td><code>Promise&lt;SyntaxIssue | null&gt;</code></td>
892
- <td>语法检查</td>
893
- </tr>
894
- <tr>
895
- <td><code>interrupt()</code></td>
896
- <td><code>void</code></td>
897
- <td>中断执行</td>
898
- </tr>
899
- <tr>
900
- <td><code>clearOutputs()</code></td>
901
- <td><code>void</code></td>
902
- <td>清空输出</td>
903
- </tr>
904
- <tr>
905
- <td><code>ready()</code></td>
906
- <td><code>Promise&lt;void&gt;</code></td>
907
- <td>等待就绪</td>
908
- </tr>
909
- </tbody>
910
- </table>
911
- <h2>主题定制</h2>
912
- <p>组件样式通过 CSS 变量控制,可在 <code>.vpe-root</code> 上覆盖:</p>
913
- <pre><code class="language-css">.vpe-root {
914
- --vpe-accent: #165dff;
915
- --vpe-bg: #ffffff;
916
- --vpe-text: #1d2129;
917
- --vpe-border: #e5e6eb;
918
- --vpe-output-bg: #f7f8fa;
919
- --vpe-stderr: #f53f3f;
920
- }
921
- </code></pre>
922
- <p>深色主题使用 <code>.vpe-root.vpe-dark</code> 下的变量,覆盖时注意同时处理两种主题。</p>
923
- <h2>类型导出</h2>
924
- <pre><code class="language-ts">import type {
925
- EditorLanguage,
926
- EditorFile,
927
- PyodideStatus,
928
- OutputStream,
929
- OutputLine,
930
- PyError,
931
- SyntaxIssue,
932
- RunResult,
933
- InstallResult,
934
- RunOutputEvent,
935
- FileOpenEvent,
936
- PythonEditorProps,
937
- } from &#39;princess-python-editor&#39;
938
- </code></pre>
939
- <h2>本地开发</h2>
940
- <pre><code class="language-bash">pnpm install
941
- pnpm dev # 启动 playground(含 Vue DevTools)
942
- pnpm build # 构建组件库到 dist
943
- pnpm lint
944
- pnpm format
945
- pnpm typecheck
946
- </code></pre>
947
- <h2>发布到 npm</h2>
948
- <p>发布前确认:</p>
949
- <ol>
950
- <li>包名 <code>princess-python-editor</code> 在 npm 上可用。</li>
951
- <li>
952
- 已在 npm 官方源登录:<code>npm whoami --registry=https://registry.npmjs.org/</code>。
953
- </li>
954
- <li>代码已提交,工作区没有未提交改动(推荐)。</li>
955
- </ol>
956
- <pre><code class="language-bash"># 1. 登录官方 npm(如果本机 registry 配置的是镜像,需要显式指定)
957
- npm login --registry=https://registry.npmjs.org/
958
-
959
- # 2. 更新版本号(会创建 commit 与 tag,也可手动修改 package.json)
960
- npm version patch # 或 minor / major
961
-
962
- # 3. 构建并检查将要发布的文件
963
- pnpm build
964
- npm pack --dry-run
965
-
966
- # 4. 发布(package.json 的 publishConfig 已指定官方 registry)
967
- npm publish --registry=https://registry.npmjs.org/
968
-
969
- # 5. 验证
970
- npm view princess-python-editor version --registry=https://registry.npmjs.org/
971
- </code></pre>
972
- <p>如果账号开启了 2FA,发布时需要提供动态验证码:</p>
973
- <pre><code class="language-bash">npm publish --registry=https://registry.npmjs.org/ --otp=123456
974
- </code></pre>
975
- <p>如果希望发布时免验证码,可以创建 Granular Access Token,创建时必须:</p>
976
- <ul>
977
- <li>
978
- 权限选择 <code>Read and write</code>,不能选 <code>Read and write (stage only)</code>
979
- </li>
980
- <li>勾选 <code>Bypass 2FA</code></li>
981
- </ul>
982
- <p>然后替换用户级 <code>~/.npmrc</code> 中的 Token:</p>
983
- <pre><code class="language-bash">npm config set //registry.npmjs.org/:_authToken &quot;npm_你的token&quot;
984
- </code></pre>
985
- <p>说明:</p>
986
- <ul>
987
- <li><code>prepublishOnly</code> 会自动执行 <code>pnpm build</code>,无需手动构建。</li>
988
- <li>
989
- npm 正在收紧 Bypass 2FA Token 的直接发布权限;CI 发布建议使用 Trusted Publishing
990
- (OIDC),或使用 stage-only Token 配合 <code>npm stage publish</code> 人工审批。
991
- </li>
992
- <li>
993
- 如果包名被占用,可以改为作用域包,例如
994
- <code>@your-scope/princess-python-editor</code>,并执行
995
- <code>npm publish --access public</code>。
996
- </li>
997
- <li>
998
- 发布后建议在空目录中执行 <code>npm i princess-python-editor</code> 做一次安装冒烟测试。
999
- </li>
1000
- </ul>
1001
- <h2>License</h2>
1002
- <p><a href="LICENSE">MIT</a></p>
1003
- </article>
1004
- </main>
1005
- <script>
1006
- // 文档内的外链在新标签页打开,站内相对链接(如 LICENSE)保持当前页
1007
- document.querySelectorAll('.markdown-body a[href^="http"]').forEach(function (link) {
1008
- link.target = '_blank'
1009
- link.rel = 'noopener noreferrer'
1010
- })
1011
- </script>
1012
- </body>
1013
- </html>