# 内置组件:基础
`@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('');
// 组件内容
;
```
输入框还没有内容时,想给一句提示,加 `placeholder`:
```tsx
```
需要多行编辑就加 `multiline`,这时输入框允许换行,高度由 `loc` 的第四项决定:
```tsx
const note = ref('');
;
```
常用参数都在 `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` | 图标的位置与大小 | 必填 |
```tsx
import { PlayIcon, PauseIcon, RollbackIcon } from '@user/client-base';
// 组件内容
;
```
内置图标共 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`,位置由两端决定。
```tsx
import { Arrow } from '@user/client-base';
// 组件内容
;
```
箭头头部想大一点,改 `head`,默认 `8`:
```tsx
```
想改线条和箭头的颜色,加 `color`:
```tsx
```
| 属性 | 作用 | 默认或常用值 |
| ------- | ----------------------------------------- | ------------ |
| `arrow` | 起点与终点,依次是 `x1`、`y1`、`x2`、`y2` | 必填 |
| `head` | 箭头头部的大小 | `8` |
| `color` | 线条与箭头的颜色 | 描边默认色 |
渲染示例需要浏览器环境。
三条箭头分别把 `head` 改成 `8`、`18`、`30`,颜色也各不相同。
## Selection
要画一个选中框,用 `Selection`。
`Selection` 只负责画框,不处理点击;点击和选中状态放在外层容器上自己维护。
```tsx
import { ref } from 'vue';
import { Selection } from '@user/client-base';
// setup
const selected = ref(0);
// 组件内容
(selected.value = 1)}>
;
```
`loc` 是框的位置与大小,通常和外层容器一样大;`color` 是框内填充色,`border` 是边框颜色。框会自己闪烁,想改闪烁的深浅用 `alphaRange`,先低后高,默认 `[0.25, 0.55]`。
```tsx
```
需要现成的选中素材时,改用 `winskin`,不再写颜色。
| 属性 | 作用 | 默认或常用值 |
| ------------ | ---------------------------- | -------------- |
| `loc` | 框的位置与大小 | 必填 |
| `color` | 框内填充色 | 无 |
| `border` | 边框颜色 | 无 |
| `winskin` | 换成现成的选中素材 | 无 |
| `alphaRange` | 闪烁的不透明度范围,先低后高 | `[0.25, 0.55]` |
渲染示例需要浏览器环境。
两组 `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);
// 组件内容
;
```
默认已完成部分是绿色、未完成部分是灰色;想换颜色,用 `success` 给已完成部分、`background` 给未完成部分:
```tsx
```
| 属性 | 作用 | 默认或常用值 |
| ------------ | ---------------------------- | ------------ |
| `loc` | 进度条的位置与宽度 | 必填 |
| `progress` | 完成比例,`0` 是空,`1` 是满 | 必填 |
| `success` | 已完成部分的颜色 | `green` |
| `background` | 未完成部分的颜色 | `gray` |
| `lineWidth` | 线条宽度 | `2` |
渲染示例需要浏览器环境。
`progress` 分别取 `0.3`、`0.6` 与 `1`。
## Background
要画一块背景框,用 `Background`。
`loc` 给位置与大小,`color` 是填充色,`border` 是边框颜色。
```tsx
import { Background } from '@user/client-base';
// 组件内容
;
```
想用现成的背景素材,就只写 `winskin`,不再写 `color` / `border`:给了 `winskin` 就画素材,否则按颜色画圆角矩形。
```tsx
```
| 属性 | 作用 | 默认或常用值 |
| --------- | ------------------ | ------------ |
| `loc` | 背景的位置与大小 | 必填 |
| `color` | 填充色 | 无 |
| `border` | 边框颜色 | 无 |
| `winskin` | 换成现成的背景素材 | 无 |
渲染示例需要浏览器环境。
同一块背景换两组 `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);
// 组件内容
;
```
`min` / `max` 给范围,`step` 给每次变化的最小差值:
```tsx
```
右侧默认显示当前值;不想显示就写 `showValue={false}`:
```tsx
```
移动端拖动滑动条不方便,建议在它旁边再放两个按钮,分别增减数值:
```tsx
const decrease = () => (volume.value = Math.max(0, volume.value - 5));
const increase = () => (volume.value = Math.min(100, volume.value + 5));
// 组件内容
;
```
全部参数:
| 属性 | 作用 | 默认或常用值 |
| ------------- | ------------------------------------- | --------------- |
| `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` |
渲染示例需要浏览器环境。
拖动滑动条或点两侧按钮,右侧数值会跟着变。