14 KiB
内置组件:基础
@user/client-base 里已经有一批常用的基础组件。它们和普通组件一样,在 TSX 里按名字使用,属性名写成 camelCase。下面每个组件都先说它解决什么问题,再给最小写法,常用参数跟着讲,最后接一个 live。
Input
要接收用户文字输入,用 Input。
第一步:用 v-model:value 绑定一个字符串拿到输入内容,loc 给位置与大小,宽度决定输入区的宽度。
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:
<Input
loc={[40, 56, 240, 32]}
v-model:value={name.value}
placeholder="输入名字"
/>
需要多行编辑就加 multiline,这时输入框允许换行,高度由 loc 的第四项决定:
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 |
确认输入时触发,收到当前字符串 | 无 |
单行占位、填入内容与多行输入三种状态。
Icons
要显示现成的图标,直接导入图标组件,按名字用,不用自己画。
每个图标只接受 loc:前两项是位置,后两项是宽高。
| 属性 | 作用 | 默认或常用值 |
|---|---|---|
loc |
图标的位置与大小 | 必填 |
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 列表里的参数查找。
渲染示例需要浏览器环境。九个图标按 loc 排在网格里,名字写在图标下方。
Arrow
要画一条带箭头的线,用 Arrow。
arrow 依次是起点 x1、y1 和终点 x2、y2;不用写 loc,位置由两端决定。
import { Arrow } from '@user/client-base';
// 组件内容
<Arrow arrow={[40, 40, 400, 120]} />;
箭头头部想大一点,改 head,默认 8:
<Arrow arrow={[40, 40, 400, 120]} head={18} />
想改线条和箭头的颜色,加 color:
<Arrow arrow={[40, 40, 400, 120]} head={18} color="#f2b84b" />
| 属性 | 作用 | 默认或常用值 |
|---|---|---|
arrow |
起点与终点,依次是 x1、y1、x2、y2 |
必填 |
head |
箭头头部的大小 | 8 |
color |
线条与箭头的颜色 | 描边默认色 |
三条箭头分别把 head 改成 8、18、30,颜色也各不相同。
Selection
要画一个选中框,用 Selection。
Selection 只负责画框,不处理点击;点击和选中状态放在外层容器上自己维护。
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]。
<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] |
两组 color 与 border 画出的选中框,第二组用 alphaRange 调大了闪烁深浅,最后一行没有选中框。
Progress
要显示进度,用 Progress。
loc 前两项是位置,第三项是进度条长度;progress 是完成比例,0 是空、1 是满。
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 给未完成部分:
<Progress
loc={[40, 40, 300, 10]}
progress={progress.value}
success="#7ee787"
background="#26364d"
/>
| 属性 | 作用 | 默认或常用值 |
|---|---|---|
loc |
进度条的位置与宽度 | 必填 |
progress |
完成比例,0 是空,1 是满 |
必填 |
success |
已完成部分的颜色 | green |
background |
未完成部分的颜色 | gray |
lineWidth |
线条宽度 | 2 |
progress 分别取 0.3、0.6 与 1。
Background
要画一块背景框,用 Background。
loc 给位置与大小,color 是填充色,border 是边框颜色。
import { Background } from '@user/client-base';
// 组件内容
<Background loc={[24, 24, 432, 272]} color="#1d2b45" border="#3a5a8c" />;
想用现成的背景素材,就只写 winskin,不再写 color / border:给了 winskin 就画素材,否则按颜色画圆角矩形。
<Background loc={[24, 24, 432, 272]} winskin="winskin.png" />
| 属性 | 作用 | 默认或常用值 |
|---|---|---|
loc |
背景的位置与大小 | 必填 |
color |
填充色 | 无 |
border |
边框颜色 | 无 |
winskin |
换成现成的背景素材 | 无 |
同一块背景换两组 color 与 border。
Slider
要让用户拖拽调数值,用 Slider。
loc 给位置与大小,value 是当前值;拖动时用 v-model:value 双向绑定。
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 给每次变化的最小差值:
<Slider
loc={[40, 80, 240, 24]}
v-model:value={volume.value}
min={0}
max={100}
step={5}
/>
右侧默认显示当前值;不想显示就写 showValue={false}:
<Slider
loc={[40, 80, 240, 24]}
v-model:value={volume.value}
min={0}
max={100}
step={5}
showValue={false}
/>
移动端拖动滑动条不方便,建议在它旁边再放两个按钮,分别增减数值:
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 |
拖动滑动条或点两侧按钮,右侧数值会跟着变。
<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>