Files
template/docs/render-guide/advanced/builtin-basic.md
T

403 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 内置组件:基础
`@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>