@deot/docs-playground 1.0.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/README.md +112 -0
- package/dist/index.cjs +2025 -0
- package/dist/index.d.ts +202 -0
- package/dist/index.js +1972 -0
- package/dist/index.style.css +1 -0
- package/package.json +43 -0
package/README.md
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# @deot/docs-playground
|
|
2
|
+
|
|
3
|
+
`@deot/docs-playground` 是基于 Vue REPL 的浏览器代码预览组件，支持单文件或多文件运行、文件浏览与编辑、响应式视口、代码高亮和父页面导航事件。
|
|
4
|
+
|
|
5
|
+
## 安装
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pnpm add @deot/docs-playground @deot/docs-locale @deot/vc vue
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## 快速开始
|
|
12
|
+
|
|
13
|
+
```vue
|
|
14
|
+
<template>
|
|
15
|
+
<Playground
|
|
16
|
+
v-model:files="files"
|
|
17
|
+
v-model:entry="entry"
|
|
18
|
+
v-model:viewport="viewport"
|
|
19
|
+
:views="['runtime', 'files']"
|
|
20
|
+
:viewport-options="['auto', 375, [375, 667]]"
|
|
21
|
+
:locale="zhCN"
|
|
22
|
+
/>
|
|
23
|
+
</template>
|
|
24
|
+
|
|
25
|
+
<script setup lang="ts">
|
|
26
|
+
import { ref } from 'vue';
|
|
27
|
+
import { Playground } from '@deot/docs-playground';
|
|
28
|
+
import { zhCN } from '@deot/docs-locale';
|
|
29
|
+
import '@deot/docs-playground/dist/index.style.css';
|
|
30
|
+
|
|
31
|
+
const entry = ref('App.vue');
|
|
32
|
+
const viewport = ref<'auto' | number | [number, number]>('auto');
|
|
33
|
+
const files = ref({
|
|
34
|
+
'App.vue': `<template><h1>Hello Playground</h1></template>`
|
|
35
|
+
});
|
|
36
|
+
</script>
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
宿主应用还需要加载 `@deot/vc-components` 的组件样式。本仓库示例使用 `/node_modules/@deot/vc-components/dist/index.style.css`。
|
|
40
|
+
|
|
41
|
+
## Playground 属性
|
|
42
|
+
|
|
43
|
+
| 属性 | 类型 | 默认值 | 说明 |
|
|
44
|
+
| --- | --- | --- | --- |
|
|
45
|
+
| `modelValue` | `string` | `''` | 单文件模式的入口 SFC 内容。 |
|
|
46
|
+
| `files` | `Record<string, string>` | `{}` | 多文件源码映射。非空时优先于 `modelValue`。 |
|
|
47
|
+
| `entry` | `string` | `''` | 入口文件；未设置时使用文件映射的第一项。 |
|
|
48
|
+
| `views` | `('runtime' \| 'files')[]` | `['runtime']` | 可用视图及初始视图顺序。 |
|
|
49
|
+
| `viewport` | `'auto' \| number \| [number, number]` | `'auto'` | 运行时宽度，或固定宽高。 |
|
|
50
|
+
| `viewportOptions` | `PlaygroundViewport[]` | `['auto', 375]` | 可切换的视口列表。 |
|
|
51
|
+
| `styleless` | `boolean` | `false` | 只渲染无工具栏的运行时预览。 |
|
|
52
|
+
| `options` | `PlaygroundOptions` | `{}` | 传给 Vue REPL store 的实例级选项；`cdnURL` 会同时作用于预览样式和默认 import map。 |
|
|
53
|
+
| `previewOptions` | `SandboxProps['previewOptions']` | `undefined` | 传给当前 iframe 的 preview 选项。 |
|
|
54
|
+
| `locale` | `Language` | `en-US` | 界面语言；未传入时使用上层 Locale Provider。 |
|
|
55
|
+
|
|
56
|
+
## 事件与双向绑定
|
|
57
|
+
|
|
58
|
+
| 事件 | 说明 |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| `update:modelValue` | 入口文件内容更新。 |
|
|
61
|
+
| `update:files` | 文件映射更新。 |
|
|
62
|
+
| `update:entry` | 入口文件更新。 |
|
|
63
|
+
| `update:viewport` | 视口更新。 |
|
|
64
|
+
| `change` | 当前入口内容被编辑。 |
|
|
65
|
+
| `navigate` | iframe 内的 `<DocsLink to="...">` 请求父页面导航。 |
|
|
66
|
+
|
|
67
|
+
Playground 只接受来自自身 iframe 的导航消息。宿主应用应监听 `navigate` 并交给自己的 Router 处理。
|
|
68
|
+
|
|
69
|
+
## 其他公共导出
|
|
70
|
+
|
|
71
|
+
| 导出 | 说明 |
|
|
72
|
+
| --- | --- |
|
|
73
|
+
| `CodePreview` | 带语言标识、复制按钮和高亮的只读代码预览。 |
|
|
74
|
+
| `Editor` | 基于 `@deot/vc` Portal 的共享文件编辑器入口。 |
|
|
75
|
+
| `highlightCode(code, filename)` | 按文件名识别语言并返回高亮 HTML。 |
|
|
76
|
+
| `highlightCodeByLanguage(code, language)` | 按显式语言高亮。 |
|
|
77
|
+
| `resolveHighlightLanguage(filename)` | 将常见扩展名映射为 highlight.js 语言。 |
|
|
78
|
+
| `registerVueHighlight(api?)` | 向 highlight.js 注册 Vue SFC 语法。 |
|
|
79
|
+
| `vueHighlight` | Vue SFC 的 highlight.js 语言定义。 |
|
|
80
|
+
| `DEFAULT_CDN_URL` | 默认 CDN 根地址（jsDelivr）。 |
|
|
81
|
+
| `createBuiltinImports(cdnURL?)` / `createBuiltinStyles(cdnURL?)` | 按 CDN 生成内置 import map 与预览样式表 URL。 |
|
|
82
|
+
| `normalizeCdnURL(value?)` | 规范化 CDN 根地址。 |
|
|
83
|
+
|
|
84
|
+
同时导出 `PlaygroundFiles`、`PlaygroundView`、`PlaygroundViewport`、`PlaygroundOptions`、`PlaygroundPreviewOptions`、`EditorFilesChange` 和 `EditorFilesChangeAction` 类型。
|
|
85
|
+
|
|
86
|
+
站点级 Playground 模块与预览 CSS 默认由 Client 的 `$docs.modules` 与 `$docs.styles` 管理（见 [`@deot/docs-client`](../client/README.md)）。独立嵌入 Playground 时，可通过 `options.builtinImportMap` 与 `options.cdnURL` 覆盖实例级配置。
|
|
87
|
+
|
|
88
|
+
## 运行环境
|
|
89
|
+
|
|
90
|
+
- Playground 运行时通过公共 CDN 加载 Vue 和默认 import map 中的依赖，手工预览需要网络访问。
|
|
91
|
+
- 默认 CDN 为 `https://cdn.jsdelivr.net/npm`，可通过 `options.cdnURL` 换成 unpkg 等兼容 `/{package}/{file}` 路径的镜像；该地址用于预览样式和内置 import map。
|
|
92
|
+
- `lodash-es` 和在线 Sass 编译器使用 jsDelivr 的 `/+esm` 入口；unpkg 等 CDN 不支持该路径。
|
|
93
|
+
- Vue SFC 的 `<style lang="scss">` / `lang="sass"` 以及独立 `.scss` / `.sass` 文件会在浏览器里编译；`_partial.scss` 只作为 `@use` 依赖。
|
|
94
|
+
- `options.builtinImportMap.imports` 可以覆盖默认模块 URL。Vue 运行时仍从 `play.vuejs.org` 加载。
|
|
95
|
+
- 每个 Playground 实例都使用自己的 preview 配置和 iframe 消息来源校验。
|
|
96
|
+
|
|
97
|
+
## 仓库内 examples
|
|
98
|
+
|
|
99
|
+
在 monorepo 根目录执行 `npm run dev` 可预览 [`packages/playground/examples`](examples/) 下的单文件与多文件 Playground 示例。
|
|
100
|
+
|
|
101
|
+
## 仓库内验证
|
|
102
|
+
|
|
103
|
+
在仓库根目录执行：
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
npm run test -- --package-name playground
|
|
107
|
+
npm run build -- --package-name playground
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## 许可证
|
|
111
|
+
|
|
112
|
+
MIT
|