@rinova/playground 0.1.0 → 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/README.md +174 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# @rinova/playground
|
|
2
|
+
|
|
3
|
+
Vue3 的「文件即场景」组件演示框架。往 `src/scenes/` 里放 `.vue` 文件，侧栏、预览、源码面板、入参/出参面板自己就长出来了 —— 没有注册 API，没有配置要改。
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
pnpm add @rinova/playground
|
|
7
|
+
pnpm add -D @rinova/playground-vite
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
需要 Vue `^3.5`（peer）。场景扫描由 `@rinova/playground-vite` 完成，Vite 项目请一起装。
|
|
11
|
+
|
|
12
|
+
## 30 秒接入
|
|
13
|
+
|
|
14
|
+
`index.html`
|
|
15
|
+
|
|
16
|
+
```html
|
|
17
|
+
<div id="app"></div>
|
|
18
|
+
<script type="module" src="/src/main.ts"></script>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
`src/main.ts`
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import '@rinova/playground/style.css'
|
|
25
|
+
import { createPlayground } from '@rinova/playground'
|
|
26
|
+
|
|
27
|
+
createPlayground()
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`vite.config.ts`
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
import vue from '@vitejs/plugin-vue'
|
|
34
|
+
import { defineConfig } from 'vite'
|
|
35
|
+
import { playground } from '@rinova/playground-vite'
|
|
36
|
+
|
|
37
|
+
export default defineConfig({
|
|
38
|
+
plugins: [vue(), playground()],
|
|
39
|
+
})
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`playground.config.ts`（可选，不写也能跑）
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
import { defineConfig } from '@rinova/playground'
|
|
46
|
+
|
|
47
|
+
export default defineConfig({
|
|
48
|
+
title: 'My Lib',
|
|
49
|
+
scenes: 'src/scenes',
|
|
50
|
+
components: ['src/components/**/*.vue'], // 配了才产出契约清单
|
|
51
|
+
})
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`src/scenes/button/size.vue` —— 存盘，侧栏立刻出现「Button / Size」：
|
|
55
|
+
|
|
56
|
+
```vue
|
|
57
|
+
<script lang="ts">
|
|
58
|
+
import { defineSceneMeta } from '@rinova/playground'
|
|
59
|
+
|
|
60
|
+
export const sceneMeta = defineSceneMeta({ title: '尺寸', order: 1 })
|
|
61
|
+
</script>
|
|
62
|
+
|
|
63
|
+
<script setup lang="ts">
|
|
64
|
+
import { ref } from 'vue'
|
|
65
|
+
import { MyButton } from '../../components'
|
|
66
|
+
|
|
67
|
+
const size = ref<'sm' | 'md' | 'lg'>('lg')
|
|
68
|
+
</script>
|
|
69
|
+
|
|
70
|
+
<template>
|
|
71
|
+
<MyButton :size="size">Button</MyButton>
|
|
72
|
+
</template>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`sceneMeta` 必须写在**普通 `<script>`** 里并以 `export const sceneMeta` 导出（构建期由 Vite 插件执行，拿不到组件状态）。不写 meta 时标题由文件名推导：`size.vue` → `Size`。
|
|
76
|
+
|
|
77
|
+
## 配置项
|
|
78
|
+
|
|
79
|
+
| 字段 | 默认 | 说明 |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| `title` | `'Playground'` | 侧栏品牌标题，同时写进 `document.title` |
|
|
82
|
+
| `scenes` | `'src/scenes'` | 场景扫描根目录（相对项目根） |
|
|
83
|
+
| `sources` | `true` | 是否显示源码面板 |
|
|
84
|
+
| `codeViewer` | `'monaco'` | `'monaco'` 只读编辑器 / `'shiki'` 静态高亮块（更轻，不加载编辑器 worker） |
|
|
85
|
+
| `theme.ui` | `'auto'` | `'light' \| 'dark' \| 'auto'` |
|
|
86
|
+
| `theme.code` | 随明暗用 `vitesse-light` / `vitesse-dark` | **v0.1 尚未接线，改这个值暂时无效** |
|
|
87
|
+
| `exclude` | — | 排除的 glob（相对 `scenes` 根） |
|
|
88
|
+
| `base` | Vite 默认 | 部署子路径 |
|
|
89
|
+
| `port` | Vite 默认（5173） | dev server 端口 |
|
|
90
|
+
| `components` | — | 契约清单要扫的组件 glob；不配则不生成 `.playground/manifest.json` |
|
|
91
|
+
| `tsconfig` | 项目根 `tsconfig.json` | 组件契约提取用的 tsconfig |
|
|
92
|
+
|
|
93
|
+
## 场景内 API
|
|
94
|
+
|
|
95
|
+
### defineSceneMeta
|
|
96
|
+
|
|
97
|
+
| 字段 | 说明 |
|
|
98
|
+
|---|---|
|
|
99
|
+
| `title` | 覆盖由文件名推导的标题 |
|
|
100
|
+
| `order` | 同层排序，数值小的在前 |
|
|
101
|
+
| `tags` | 搜索/筛选标签 |
|
|
102
|
+
| `description` | 说明文字，显示在预览区上方 |
|
|
103
|
+
| `files` | 额外展示的源码文件（相对项目根） |
|
|
104
|
+
| `hideInNav` | 不在侧栏出现，但可通过链接直达 |
|
|
105
|
+
|
|
106
|
+
`SceneMeta` 类型里还有 `payload` 字段，但构建期拿不到组件状态，**请改用下面的 `useSceneArgs` / `useSceneOutput`**。
|
|
107
|
+
|
|
108
|
+
### useSceneArgs —— 入参面板
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
const args = useSceneArgs(
|
|
112
|
+
{ size: 'md' as 'sm' | 'md' | 'lg', disabled: false },
|
|
113
|
+
{
|
|
114
|
+
labels: { size: '尺寸', disabled: '禁用' },
|
|
115
|
+
options: { size: ['sm', 'md', 'lg'] },
|
|
116
|
+
}
|
|
117
|
+
)
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
返回响应式对象：面板改表单 → 这里同步变 → 组件重渲染。按值类型自动选控件（`boolean` → 开关，`number` → 数字框，`string` → 输入框，带 `options` → 下拉）。
|
|
121
|
+
|
|
122
|
+
纯前端响应式，**生产静态站同样可用**，不依赖 dev server。
|
|
123
|
+
|
|
124
|
+
> 字面量会被拓宽成 `string`，直接传给只接受联合类型的 prop 会报 TS2322，所以写 `'md' as 'sm' | 'md' | 'lg'`。
|
|
125
|
+
|
|
126
|
+
### useSceneOutput —— 出参快照
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
useSceneOutput(() => ({ size: args.size, clicked: count.value }))
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
面板以 400ms 轮询这个 getter，把返回值显示在出参区。
|
|
133
|
+
|
|
134
|
+
### toast
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
import { toast } from '@rinova/playground'
|
|
138
|
+
|
|
139
|
+
toast('已复制')
|
|
140
|
+
toast('保存失败', 'error') // 'info' | 'success' | 'warning' | 'error'
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## 样式约定
|
|
144
|
+
|
|
145
|
+
- 场景写 `<style scoped lang="less">`（使用方需要装 `less`）。**v0.1 没有 DOM 隔离**，非 scoped 样式会污染外壳。
|
|
146
|
+
- 不要硬编码颜色，用外壳暴露的 12 个变量，明暗主题自动切换：
|
|
147
|
+
|
|
148
|
+
```
|
|
149
|
+
--rp-color-bg --rp-color-surface --rp-color-border --rp-color-text
|
|
150
|
+
--rp-color-text-muted --rp-color-primary --rp-color-primary-contrast
|
|
151
|
+
--rp-color-success --rp-color-warning --rp-color-danger
|
|
152
|
+
--rp-radius --rp-font-mono
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## 已知限制（v0.1）
|
|
156
|
+
|
|
157
|
+
- 场景与外壳无 DOM 隔离，必须写 scoped
|
|
158
|
+
- 源码面板只读，不支持编辑（实时预览也已明确不做：只在 dev 可用，价值不足）
|
|
159
|
+
- `theme.code` 未接线
|
|
160
|
+
- 只支持 Vue3，不支持 React / Svelte
|
|
161
|
+
|
|
162
|
+
## 相关包
|
|
163
|
+
|
|
164
|
+
| 包 | 作用 |
|
|
165
|
+
|---|---|
|
|
166
|
+
| `@rinova/playground-vite` | 场景扫描 + 契约清单，Vite 项目必需 |
|
|
167
|
+
| `@rinova/playground-mcp` | 把契约清单挂给 Claude Code / Cursor 等 AI 工具（可选） |
|
|
168
|
+
| `create-rinova-playground` | `pnpm create rinova-playground my-lib` 开新项目 |
|
|
169
|
+
|
|
170
|
+
仓库与文档：<https://github.com/jove-rina/rinova-playground>
|
|
171
|
+
|
|
172
|
+
## License
|
|
173
|
+
|
|
174
|
+
MIT
|
package/package.json
CHANGED