Files
template/docs/advanced/ii/ui/builtin-basic.md
T

14 KiB
Raw Blame History

内置组件:基础

@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>