princess-python-editor 0.3.0 → 0.3.2

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
@@ -44,7 +44,13 @@ npm install princess-python-editor
44
44
  yarn add princess-python-editor
45
45
  ```
46
46
 
47
- ## 快速开始
47
+ ## 使用方式
48
+
49
+ 提供两种接入方式:安装 npm 包,或直接复制组件源码。两者使用相同的 Props、事件和实例方法,无需调用 `app.use`。
50
+
51
+ ### npm 包方式
52
+
53
+ 按上面的命令安装 `princess-python-editor` 后,在需要的页面中导入组件即可。CodeMirror 等运行依赖会自动安装。
48
54
 
49
55
  在应用入口引入组件样式:
50
56
 
@@ -95,6 +101,104 @@ function onRunError(error: PyError) {
95
101
 
96
102
  > `height="100%"` 需要父容器具有明确高度;也可以直接传入数字(按 px 处理)。
97
103
 
104
+ ### 源码组件方式(直接复制 PythonEditor 目录)
105
+
106
+ 适用于不安装 `princess-python-editor`、直接在其他 Vue 3 + TypeScript 项目中维护组件源码的场景。
107
+
108
+ #### 1. 复制完整目录
109
+
110
+ 将本项目的 `src/components/PythonEditor/` 整个复制到目标项目的 `src/components/PythonEditor/`,保留目录结构:
111
+
112
+ ```text
113
+ src/components/PythonEditor/
114
+ ├── PythonEditor.vue
115
+ ├── index.ts
116
+ ├── types.ts
117
+ ├── icons.ts
118
+ ├── languages.ts
119
+ ├── themes.ts
120
+ ├── editor/
121
+ │ ├── createEditor.ts
122
+ │ ├── pythonLint.ts
123
+ │ └── theme.ts
124
+ ├── runtime/
125
+ │ ├── PyodideRunner.ts
126
+ │ ├── files.ts
127
+ │ ├── python.ts
128
+ │ ├── sql.ts
129
+ │ ├── usePyodide.ts
130
+ │ └── workerSource.ts
131
+ └── styles/
132
+ └── editor.css
133
+ ```
134
+
135
+ 不能只复制 `PythonEditor.vue`:编辑器配置、运行器、图标和样式均通过相对路径引用同目录下的文件。无需复制本项目根目录的 `src/index.ts`、`playground` 或构建配置。
136
+
137
+ #### 2. 安装运行依赖
138
+
139
+ 在目标项目根目录执行以下命令,版本范围与本项目一致(可逐行执行):
140
+
141
+ ```bash
142
+ pnpm add "@codemirror/autocomplete@^6.18.6" "@codemirror/commands@^6.8.0"
143
+ pnpm add "@codemirror/lang-javascript@^6.2.5" "@codemirror/lang-json@^6.0.2" "@codemirror/lang-python@^6.1.7" "@codemirror/lang-sql@^6.10.0"
144
+ pnpm add "@codemirror/language@^6.10.8" "@codemirror/lint@^6.8.4"
145
+ pnpm add "@codemirror/state@^6.5.2" "@codemirror/view@^6.36.2" "@lezer/highlight@^1.2.5"
146
+ ```
147
+
148
+ - 宿主项目需使用 Vue `>= 3.3.0`,并支持编译 Vue 单文件组件和 TypeScript;已有 Vue 3 + TypeScript 的 Vite 项目通常无需调整构建配置。
149
+ - 上面的 CodeMirror 包和 `@lezer/highlight` 是源码直接引用的依赖。即使只编辑 Python,也应全部安装,因为 JavaScript、JSON、SQL 语言支持使用静态导入。
150
+ - **无需安装 Arco Design 或图标库**:Arco Design 只用于本仓库的演示页面,组件内部使用自带图标和样式。
151
+ - **无需安装 `pyodide` npm 包或本机 Python**:浏览器运行模式会从 CDN 加载 Pyodide;内网或离线部署需按下文“Pyodide 配置”自托管资源。
152
+ - **无需安装 `vite-plugin-dts` 或 `vite-plugin-vue-devtools`**:它们只用于本仓库的库构建和演示开发。已有 Vue 项目也无需额外配置专用 Vite 插件。
153
+
154
+ #### 3. 在页面中使用
155
+
156
+ 以下示例假设页面文件为 `src/views/PythonPlayground.vue`,通过相对路径导入,不依赖 `@` 别名:
157
+
158
+ ```vue
159
+ <script setup lang="ts">
160
+ import { ref } from 'vue'
161
+ import { PythonEditor } from '../components/PythonEditor'
162
+ import type { EditorLanguage, PyError, RunResult } from '../components/PythonEditor'
163
+
164
+ const code = ref('print("Hello, Python!")')
165
+ const fileName = ref('main.py')
166
+ const language = ref<EditorLanguage>('python')
167
+
168
+ function onRunFinish(result: RunResult) {
169
+ console.log(result.ok ? `执行完成,耗时 ${result.durationMs}ms` : '执行失败')
170
+ }
171
+
172
+ function onRunError(error: PyError) {
173
+ console.error(error.type, error.message)
174
+ }
175
+ </script>
176
+
177
+ <template>
178
+ <PythonEditor
179
+ v-model="code"
180
+ v-model:file-name="fileName"
181
+ v-model:language="language"
182
+ :height="520"
183
+ :output-height="180"
184
+ @run-finish="onRunFinish"
185
+ @run-error="onRunError"
186
+ />
187
+ </template>
188
+ ```
189
+
190
+ `PythonEditor.vue` 已通过 `<style src="./styles/editor.css">` 自动引入组件样式,源码方式**不需要**再导入 `princess-python-editor/style.css`,也不需要安装 `princess-python-editor`。
191
+
192
+ 如需调用实例方法或导入类型、主题、`usePyodide` 等能力,同样从复制后的本地目录导入。下文示例中的 `'princess-python-editor'` 应替换为目标项目中该目录的实际导入路径。
193
+
194
+ #### 4. 按需接入后端
195
+
196
+ 默认即可在浏览器内编辑和执行 Python,无需后端。服务端 Python、服务端文件管理和远程 SQL 查询属于可选功能,复制组件目录不会自动部署这些服务:
197
+
198
+ - 服务端 Python:配置 `python-endpoint`,后端需实现下文的会话接口。
199
+ - 服务端文件:配置 `files-endpoint`,后端需实现文件读写接口。
200
+ - 远程数据库:配置 `sql-config` 的 HTTP 网关,或传入 `sql-executor`;浏览器内 SQLite 无需后端。
201
+
98
202
  ### 双向绑定
99
203
 
100
204
  | 绑定 | 类型 | 说明 |
@@ -785,57 +889,3 @@ pnpm lint
785
889
  pnpm format
786
890
  pnpm typecheck
787
891
  ```
788
-
789
- ## 发布到 npm
790
-
791
- 发布前确认:
792
-
793
- 1. 包名 `princess-python-editor` 在 npm 上可用。
794
- 2. 已在 npm 官方源登录:`npm whoami --registry=https://registry.npmjs.org/`。
795
- 3. 代码已提交,工作区没有未提交改动(推荐)。
796
-
797
- ```bash
798
- # 1. 登录官方 npm(如果本机 registry 配置的是镜像,需要显式指定)
799
- npm login --registry=https://registry.npmjs.org/
800
-
801
- # 2. 更新版本号(会创建 commit 与 tag,也可手动修改 package.json)
802
- npm version patch # 或 minor / major
803
-
804
- # 3. 构建并检查将要发布的文件
805
- pnpm build
806
- npm pack --dry-run
807
-
808
- # 4. 发布(package.json 的 publishConfig 已指定官方 registry)
809
- npm publish --registry=https://registry.npmjs.org/
810
-
811
- # 5. 验证
812
- npm view princess-python-editor version --registry=https://registry.npmjs.org/
813
- ```
814
-
815
- 如果账号开启了 2FA,发布时需要提供动态验证码:
816
-
817
- ```bash
818
- npm publish --registry=https://registry.npmjs.org/ --otp=123456
819
- ```
820
-
821
- 如果希望发布时免验证码,可以创建 Granular Access Token,创建时必须:
822
-
823
- - 权限选择 `Read and write`,不能选 `Read and write (stage only)`
824
- - 勾选 `Bypass 2FA`
825
-
826
- 然后替换用户级 `~/.npmrc` 中的 Token:
827
-
828
- ```bash
829
- npm config set //registry.npmjs.org/:_authToken "npm_你的token"
830
- ```
831
-
832
- 说明:
833
-
834
- - `prepublishOnly` 会自动执行 `pnpm build`,无需手动构建。
835
- - npm 正在收紧 Bypass 2FA Token 的直接发布权限;CI 发布建议使用 Trusted Publishing (OIDC),或使用 stage-only Token 配合 `npm stage publish` 人工审批。
836
- - 如果包名被占用,可以改为作用域包,例如 `@your-scope/princess-python-editor`,并执行 `npm publish --access public`。
837
- - 发布后建议在空目录中执行 `npm i princess-python-editor` 做一次安装冒烟测试。
838
-
839
- ## License
840
-
841
- [MIT](LICENSE)
@@ -17,6 +17,16 @@ export interface Props {
17
17
  autofocus?: boolean;
18
18
  /** 是否显示工具栏 */
19
19
  showToolbar?: boolean;
20
+ /** 是否显示底部提交按钮,默认隐藏;点击后触发 submit 事件 */
21
+ showSubmit?: boolean;
22
+ /** 是否显示工具栏新建按钮及 Tab 栏新建入口 */
23
+ showNewFile?: boolean;
24
+ /** 是否显示工具栏打开本地文件按钮 */
25
+ showOpenFile?: boolean;
26
+ /** 是否显示工具栏下载当前文件按钮 */
27
+ showDownload?: boolean;
28
+ /** 是否显示工具栏虚拟文件入口 */
29
+ showVirtualFiles?: boolean;
20
30
  /** 是否显示文件 Tab 栏 */
21
31
  showTabs?: boolean;
22
32
  /** 是否显示输出面板 */
@@ -72,6 +82,8 @@ declare function openSqlConfig(): void;
72
82
  declare function closeSqlConfig(): void;
73
83
  /** 执行指定 SQL;不传参数时执行当前文件内容(会切换当前文件为 SQL) */
74
84
  declare function executeSql(sql?: string): Promise<SqlQueryResult | null>;
85
+ /** 提交当前代码,由宿主处理保存或业务请求 */
86
+ declare function submit(): void;
75
87
  /** 运行当前编辑器中的代码 */
76
88
  declare function run(): void;
77
89
  /** 中断当前文件的执行 */
@@ -125,6 +137,7 @@ declare function getFiles(): EditorFile[];
125
137
  /** 获取当前 Tab 文件快照 */
126
138
  declare function getActiveFile(): EditorFile;
127
139
  declare const _default: import('vue').DefineComponent<Props, {
140
+ submit: typeof submit;
128
141
  run: typeof run;
129
142
  stop: typeof stop;
130
143
  clearOutput: typeof clearOutput;
@@ -171,6 +184,11 @@ declare const _default: import('vue').DefineComponent<Props, {
171
184
  readOnly: boolean;
172
185
  autofocus: boolean;
173
186
  showToolbar: boolean;
187
+ showSubmit: boolean;
188
+ showNewFile: boolean;
189
+ showOpenFile: boolean;
190
+ showDownload: boolean;
191
+ showVirtualFiles: boolean;
174
192
  showTabs: boolean;
175
193
  showOutput: boolean;
176
194
  clearOutputOnRun: boolean;
package/dist/icons.d.ts CHANGED
@@ -15,6 +15,8 @@ export declare const IconFile: FunctionalComponent<{}, {}, any, {}>;
15
15
  export declare const IconDownload: FunctionalComponent<{}, {}, any, {}>;
16
16
  /** 复制(双层纸张) */
17
17
  export declare const IconCopy: FunctionalComponent<{}, {}, any, {}>;
18
+ /** 发送(纸飞机) */
19
+ export declare const IconSend: FunctionalComponent<{}, {}, any, {}>;
18
20
  /** 对勾(复制成功反馈) */
19
21
  export declare const IconCheck: FunctionalComponent<{}, {}, any, {}>;
20
22
  /** 关闭(叉号) */