mirror of
https://github.com/motajs/template.git
synced 2026-11-20 19:54:36 +08:00
docs: add render guide and migrate UI documentation
This commit is contained in:
1 parent
2a4b3220ed
commit
c4096f4bfb
40 files changed
+1815
-563
No files matched your search
@@ -0,0 +1,402 @@
|
||||
# 内置组件:基础
|
||||
|
||||
`@user/client-base` 里已经有一批常用的基础组件。它们和普通组件一样,在 TSX 里按名字使用,属性名写成 camelCase。下面每个组件都先说它解决什么问题,再给最小写法,常用参数跟着讲,最后接一个 live。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [什么是组件](./what-is-component.md)
|
||||
|
||||
## Input
|
||||
|
||||
要接收用户文字输入,用 `Input`。
|
||||
|
||||
第一步:用 `v-model:value` 绑定一个字符串拿到输入内容,`loc` 给位置与大小,宽度决定输入区的宽度。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
import { Input } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const name = ref('');
|
||||
|
||||
// 组件内容
|
||||
<Input loc={[40, 56, 240, 32]} v-model:value={name.value} />;
|
||||
```
|
||||
|
||||
输入框还没有内容时,想给一句提示,加 `placeholder`:
|
||||
|
||||
```tsx
|
||||
<Input
|
||||
loc={[40, 56, 240, 32]}
|
||||
v-model:value={name.value}
|
||||
placeholder="输入名字"
|
||||
/>
|
||||
```
|
||||
|
||||
需要多行编辑就加 `multiline`,这时输入框允许换行,高度由 `loc` 的第四项决定:
|
||||
|
||||
```tsx
|
||||
const note = ref('');
|
||||
|
||||
<Input
|
||||
loc={[40, 104, 320, 80]}
|
||||
v-model:value={note.value}
|
||||
multiline
|
||||
placeholder="多行备注"
|
||||
/>;
|
||||
```
|
||||
|
||||
常用参数都在 `loc` 与外观上:`loc` 给位置和大小,宽度决定输入区宽度;`placeholder` 是空内容时的提示;`border` 是边框颜色,默认 `'#ddd'`;`borderWidth` 是边框宽度,默认 `1`;`circle` 是边框圆角,写法与 `g-rectr` 一致,例如 `[4]`;`pad` 是文字与边框之间的内边距,默认 `4`。
|
||||
|
||||
`value` 就是 `v-model:value` 绑定的那个值。想知道每次输入的内容加 `onInput`,想只在确认时取值加 `onChange`,两者都收到当前字符串。
|
||||
|
||||
全部参数:
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ------------- | ---------------------------------------- | ------------ |
|
||||
| `loc` | 位置与大小,宽度决定输入区宽度 | 必填 |
|
||||
| `value` | 输入内容,配合 `v-model:value` 双向绑定 | `''` |
|
||||
| `placeholder` | 空内容时的提示文字 | 无 |
|
||||
| `multiline` | 多行输入,高度由 `loc` 的第四项决定 | `false` |
|
||||
| `border` | 边框颜色 | `'#ddd'` |
|
||||
| `borderWidth` | 边框宽度 | `1` |
|
||||
| `circle` | 边框圆角,写法同 `g-rectr` | 无 |
|
||||
| `pad` | 文字与边框之间的内边距 | `4` |
|
||||
| `font` | 输入文字的字体,排版参数同 `TextContent` | 默认字体 |
|
||||
| `fillStyle` | 文字颜色 | 白色 |
|
||||
| `onInput` | 每次输入都触发,收到当前字符串 | 无 |
|
||||
| `onChange` | 确认输入时触发,收到当前字符串 | 无 |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="inputLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
单行占位、填入内容与多行输入三种状态。
|
||||
|
||||
## Icons
|
||||
|
||||
要显示现成的图标,直接导入图标组件,按名字用,不用自己画。
|
||||
|
||||
每个图标只接受 `loc`:前两项是位置,后两项是宽高。
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ----- | ---------------- | ------------ |
|
||||
| `loc` | 图标的位置与大小 | 必填 |
|
||||
|
||||
```tsx
|
||||
import { PlayIcon, PauseIcon, RollbackIcon } from '@user/client-base';
|
||||
|
||||
// 组件内容
|
||||
<container loc={FULL_LOC}>
|
||||
<PlayIcon loc={[40, 40, 32, 32]} />
|
||||
<PauseIcon loc={[88, 40, 32, 32]} />
|
||||
<RollbackIcon loc={[136, 40, 32, 32]} />
|
||||
</container>;
|
||||
```
|
||||
|
||||
内置图标共 17 个,都从 `@user/client-base` 导入:
|
||||
|
||||
`RollbackIcon`、`RetweetIcon`、`ViewMapIcon`、`DanmakuIcon`、`ReplayIcon`、
|
||||
`NumpadIcon`、`PlayIcon`、`PauseIcon`、`DoubleArrow`、`StepForward`、
|
||||
`SoundVolume`、`Fullscreen`、`ExitFullscreen`、`ArrowLeftTailless`、
|
||||
`ArrowRightTailless`、`ArrowUpTailless`、`ArrowDownTailless`。
|
||||
|
||||
图标内部的线条样式不在组件参数里展开,需要改的时候按 API 列表里的参数查找。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="iconsLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
九个图标按 `loc` 排在网格里,名字写在图标下方。
|
||||
|
||||
## Arrow
|
||||
|
||||
要画一条带箭头的线,用 `Arrow`。
|
||||
|
||||
`arrow` 依次是起点 `x1`、`y1` 和终点 `x2`、`y2`;不用写 `loc`,位置由两端决定。
|
||||
|
||||
```tsx
|
||||
import { Arrow } from '@user/client-base';
|
||||
|
||||
// 组件内容
|
||||
<Arrow arrow={[40, 40, 400, 120]} />;
|
||||
```
|
||||
|
||||
箭头头部想大一点,改 `head`,默认 `8`:
|
||||
|
||||
```tsx
|
||||
<Arrow arrow={[40, 40, 400, 120]} head={18} />
|
||||
```
|
||||
|
||||
想改线条和箭头的颜色,加 `color`:
|
||||
|
||||
```tsx
|
||||
<Arrow arrow={[40, 40, 400, 120]} head={18} color="#f2b84b" />
|
||||
```
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ------- | ----------------------------------------- | ------------ |
|
||||
| `arrow` | 起点与终点,依次是 `x1`、`y1`、`x2`、`y2` | 必填 |
|
||||
| `head` | 箭头头部的大小 | `8` |
|
||||
| `color` | 线条与箭头的颜色 | 描边默认色 |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="arrowLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
三条箭头分别把 `head` 改成 `8`、`18`、`30`,颜色也各不相同。
|
||||
|
||||
## Selection
|
||||
|
||||
要画一个选中框,用 `Selection`。
|
||||
|
||||
`Selection` 只负责画框,不处理点击;点击和选中状态放在外层容器上自己维护。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
import { Selection } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const selected = ref(0);
|
||||
|
||||
// 组件内容
|
||||
<container loc={[40, 40, 220, 32]} onClick={() => (selected.value = 1)}>
|
||||
<Selection loc={[0, 0, 220, 32]} color="#2f6fed" border="#7aa2ff" />
|
||||
<text loc={[12, 8]} text="被选中的项" fillStyle="#ffffff" />
|
||||
</container>;
|
||||
```
|
||||
|
||||
`loc` 是框的位置与大小,通常和外层容器一样大;`color` 是框内填充色,`border` 是边框颜色。框会自己闪烁,想改闪烁的深浅用 `alphaRange`,先低后高,默认 `[0.25, 0.55]`。
|
||||
|
||||
```tsx
|
||||
<Selection
|
||||
loc={[0, 0, 220, 32]}
|
||||
color="#2f6fed"
|
||||
border="#7aa2ff"
|
||||
alphaRange={[0.4, 0.8]}
|
||||
/>
|
||||
```
|
||||
|
||||
需要现成的选中素材时,改用 `winskin`,不再写颜色。
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ------------ | ---------------------------- | -------------- |
|
||||
| `loc` | 框的位置与大小 | 必填 |
|
||||
| `color` | 框内填充色 | 无 |
|
||||
| `border` | 边框颜色 | 无 |
|
||||
| `winskin` | 换成现成的选中素材 | 无 |
|
||||
| `alphaRange` | 闪烁的不透明度范围,先低后高 | `[0.25, 0.55]` |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="selectionLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
两组 `color` 与 `border` 画出的选中框,第二组用 `alphaRange` 调大了闪烁深浅,最后一行没有选中框。
|
||||
|
||||
## Progress
|
||||
|
||||
要显示进度,用 `Progress`。
|
||||
|
||||
`loc` 前两项是位置,第三项是进度条长度;`progress` 是完成比例,`0` 是空、`1` 是满。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
import { Progress } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const progress = ref(0.6);
|
||||
|
||||
// 组件内容
|
||||
<Progress loc={[40, 40, 300, 10]} progress={progress.value} />;
|
||||
```
|
||||
|
||||
默认已完成部分是绿色、未完成部分是灰色;想换颜色,用 `success` 给已完成部分、`background` 给未完成部分:
|
||||
|
||||
```tsx
|
||||
<Progress
|
||||
loc={[40, 40, 300, 10]}
|
||||
progress={progress.value}
|
||||
success="#7ee787"
|
||||
background="#26364d"
|
||||
/>
|
||||
```
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ------------ | ---------------------------- | ------------ |
|
||||
| `loc` | 进度条的位置与宽度 | 必填 |
|
||||
| `progress` | 完成比例,`0` 是空,`1` 是满 | 必填 |
|
||||
| `success` | 已完成部分的颜色 | `green` |
|
||||
| `background` | 未完成部分的颜色 | `gray` |
|
||||
| `lineWidth` | 线条宽度 | `2` |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="progressLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
`progress` 分别取 `0.3`、`0.6` 与 `1`。
|
||||
|
||||
## Background
|
||||
|
||||
要画一块背景框,用 `Background`。
|
||||
|
||||
`loc` 给位置与大小,`color` 是填充色,`border` 是边框颜色。
|
||||
|
||||
```tsx
|
||||
import { Background } from '@user/client-base';
|
||||
|
||||
// 组件内容
|
||||
<Background loc={[24, 24, 432, 272]} color="#1d2b45" border="#3a5a8c" />;
|
||||
```
|
||||
|
||||
想用现成的背景素材,就只写 `winskin`,不再写 `color` / `border`:给了 `winskin` 就画素材,否则按颜色画圆角矩形。
|
||||
|
||||
```tsx
|
||||
<Background loc={[24, 24, 432, 272]} winskin="winskin.png" />
|
||||
```
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| --------- | ------------------ | ------------ |
|
||||
| `loc` | 背景的位置与大小 | 必填 |
|
||||
| `color` | 填充色 | 无 |
|
||||
| `border` | 边框颜色 | 无 |
|
||||
| `winskin` | 换成现成的背景素材 | 无 |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="backgroundLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
同一块背景换两组 `color` 与 `border`。
|
||||
|
||||
## Slider
|
||||
|
||||
要让用户拖拽调数值,用 `Slider`。
|
||||
|
||||
`loc` 给位置与大小,`value` 是当前值;拖动时用 `v-model:value` 双向绑定。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
import { Slider } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const volume = ref(40);
|
||||
|
||||
// 组件内容
|
||||
<Slider loc={[40, 80, 240, 24]} v-model:value={volume.value} />;
|
||||
```
|
||||
|
||||
`min` / `max` 给范围,`step` 给每次变化的最小差值:
|
||||
|
||||
```tsx
|
||||
<Slider
|
||||
loc={[40, 80, 240, 24]}
|
||||
v-model:value={volume.value}
|
||||
min={0}
|
||||
max={100}
|
||||
step={5}
|
||||
/>
|
||||
```
|
||||
|
||||
右侧默认显示当前值;不想显示就写 `showValue={false}`:
|
||||
|
||||
```tsx
|
||||
<Slider
|
||||
loc={[40, 80, 240, 24]}
|
||||
v-model:value={volume.value}
|
||||
min={0}
|
||||
max={100}
|
||||
step={5}
|
||||
showValue={false}
|
||||
/>
|
||||
```
|
||||
|
||||
移动端拖动滑动条不方便,建议在它旁边再放两个按钮,分别增减数值:
|
||||
|
||||
```tsx
|
||||
const decrease = () => (volume.value = Math.max(0, volume.value - 5));
|
||||
const increase = () => (volume.value = Math.min(100, volume.value + 5));
|
||||
|
||||
// 组件内容
|
||||
<container loc={FULL_LOC}>
|
||||
<Slider
|
||||
loc={[40, 80, 240, 24]}
|
||||
v-model:value={volume.value}
|
||||
min={0}
|
||||
max={100}
|
||||
step={5}
|
||||
/>
|
||||
<container loc={[40, 120, 64, 28]} onClick={decrease}>
|
||||
<g-rectr loc={[0, 0, 64, 28]} circle={[4]} fillStyle="#2f6fed" />
|
||||
<text loc={[32, 14]} anc={[0.5, 0.5]} text="-" fillStyle="#ffffff" />
|
||||
</container>
|
||||
<container loc={[116, 120, 64, 28]} onClick={increase}>
|
||||
<g-rectr loc={[0, 0, 64, 28]} circle={[4]} fillStyle="#3a2f5f" />
|
||||
<text loc={[32, 14]} anc={[0.5, 0.5]} text="+" fillStyle="#ffffff" />
|
||||
</container>
|
||||
</container>;
|
||||
```
|
||||
|
||||
全部参数:
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ------------- | ------------------------------------- | --------------- |
|
||||
| `loc` | 位置与大小 | 必填 |
|
||||
| `value` | 当前值,配合 `v-model:value` 双向绑定 | `min` |
|
||||
| `min` | 最小值 | `0` |
|
||||
| `max` | 最大值 | `0` |
|
||||
| `step` | 每次变化的最小差值 | `1` |
|
||||
| `showValue` | 右侧是否显示当前值 | `true` |
|
||||
| `valueWidth` | 右侧数值区域的宽度 | `40` |
|
||||
| `font` | 右侧数值的字体 | `12` 号默认字体 |
|
||||
| `lineWidth` | 滑动条的线宽 | `2` |
|
||||
| `padding` | 线两端距容器边缘的距离 | `4` |
|
||||
| `filledStyle` | 控制点左侧(已选部分)的颜色 | `'#0ff'` |
|
||||
| `emptyStyle` | 控制点右侧(未选部分)与描边的颜色 | `'#888'` |
|
||||
| `radius` | 控制点的半径 | `4` |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="sliderLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
拖动滑动条或点两侧按钮,右侧数值会跟着变。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const inputLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-input-demo.tsx');
|
||||
const iconsLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-icons-demo.tsx');
|
||||
const arrowLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-arrow-demo.tsx');
|
||||
const selectionLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-selection-demo.tsx');
|
||||
const progressLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-progress-demo.tsx');
|
||||
const backgroundLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-background-demo.tsx');
|
||||
const sliderLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-slider-demo.tsx');
|
||||
</script>
|
||||
Reference in new issue
Block a user