mirror of
https://github.com/motajs/template.git
synced 2026-11-22 04:54:30 +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,524 @@
|
||||
# 基础图形
|
||||
|
||||
上一篇[《容器与坐标》](./container-and-coordinates.md)讲的是怎么把元素摆到位置上:坐标从哪里来、`loc` 与锚点怎么配合、容器嵌套后子元素怎么算。位置有了,这一篇开始画东西。界面里的图形元素一共八种:矩形 `g-rect`、圆 `g-circle`、椭圆 `g-ellipse`、直线 `g-line`、三次贝塞尔 `g-bezier`、二次贝塞尔 `g-quad`、路径 `g-path` 和圆角矩形 `g-rectr`。
|
||||
|
||||
在逐个看图形之前,先弄清所有图形共用的填充、描边与颜色规则,后面每种图形的用法都建立在这套规则上。每种图形都有一个用数组传参的简写,日常写 UI 用简写最省事;逐个属性写的普通写法只在需要拆分或复用单个值时再用,下面每节只提一句。每种图形配一个 live,最后再把八种放在一起。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [容器与坐标](./container-and-coordinates.md)
|
||||
|
||||
## 通用规则:填充、描边与颜色
|
||||
|
||||
图形有两种绘制模式:填充和描边。`fill`、`stroke`、`strokeAndFill` 是模式开关,值都是布尔值,不是颜色;颜色分别写在 `fillStyle` 与 `strokeStyle` 里。写 `fill="#f00"` 不会把图形变成红色,要写 `fill fillStyle="#f00"`;默认填充的图形本来就不用写 `fill`。
|
||||
|
||||
每种图形有自己的默认模式:
|
||||
|
||||
| 图形 | 默认模式 |
|
||||
| ---------------------------------------------------------- | -------- |
|
||||
| `g-rect` / `g-circle` / `g-ellipse` / `g-rectr` / `g-path` | 填充 |
|
||||
| `g-line` / `g-bezier` / `g-quad` | 描边 |
|
||||
|
||||
默认填充的图形只写 `fillStyle`;默认描边的图形只写 `strokeStyle`。需要同时填充和描边时,写 `fill` 与 `stroke`:渲染时先填充、后描边,所以**描边会覆盖 fill**,边框完整地画在填充之上。`strokeAndFill` 是另一套顺序——先描边、后填充,**fill 会覆盖描边**,描边的内半边被填充盖住,边框看起来更细;`strokeAndFill` 优先级最高,写它会忽略 `fill` 与 `stroke`。
|
||||
|
||||
这里有个容易踩的地方:默认填充的图形只要写了 `stroke`、又没写过 `fill`,模式就会切换成只描边,原来的填充不再生效。也就是说,默认填充只在「没写 `stroke`、也没写 `strokeAndFill`」时成立。想同时填充和描边,必须显式写 `fill` + `stroke`,或者直接用 `strokeAndFill`。
|
||||
|
||||
```tsx
|
||||
// 默认填充的矩形只写 stroke:只画边框,不填充
|
||||
<g-rect loc={[40, 40, 160, 100]} stroke strokeStyle="#58c4dd" lineWidth={4} />
|
||||
|
||||
// 想同时填充和描边:必须显式写 fill + stroke
|
||||
<g-rect
|
||||
loc={[240, 40, 160, 100]}
|
||||
fill
|
||||
stroke
|
||||
fillStyle="#2f6fed"
|
||||
strokeStyle="#e8f0ff"
|
||||
lineWidth={4}
|
||||
/>
|
||||
```
|
||||
|
||||
这四种模式放在一起对照:
|
||||
|
||||
```tsx
|
||||
// 默认填充:颜色用 fillStyle
|
||||
<g-rect loc={[40, 40, 120, 80]} fillStyle="#2f6fed" />
|
||||
|
||||
// 默认描边:颜色用 strokeStyle
|
||||
<g-line line={[40, 160, 200, 160]} strokeStyle="#7ee787" />
|
||||
|
||||
// 同时填充与描边:先填充后描边,描边盖住 fill
|
||||
<g-circle
|
||||
circle={[300, 100, 50]}
|
||||
fill
|
||||
stroke
|
||||
fillStyle="#58c4dd"
|
||||
strokeStyle="#e8f0ff"
|
||||
lineWidth={4}
|
||||
/>
|
||||
|
||||
// 先描边后填充:fill 盖住描边,strokeAndFill 优先级最高
|
||||
<g-rect
|
||||
loc={[260, 180, 120, 80]}
|
||||
strokeAndFill
|
||||
fillStyle="#f2b84b"
|
||||
strokeStyle="#141a22"
|
||||
lineWidth={6}
|
||||
/>
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="modesLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
同一个矩形分别用四种模式,对照看边框和填充;重点对照 `fill` + `stroke` 与 `strokeAndFill` 的覆盖关系。
|
||||
|
||||
`fillRule` 只在填充路径时起作用,可选 `nonzero` 与 `evenodd`,具体在后面的路径一节展开。所有图形的默认颜色都是浅灰 `#ddd`;示例里通常显式写 `fillStyle` 或 `strokeStyle`。
|
||||
|
||||
### 描边细节
|
||||
|
||||
默认描边的图形,以及任何写了 `stroke` 的图形,都可以用下面这些属性控制描边:
|
||||
|
||||
| 属性 | 作用 | 常见值 |
|
||||
| ---------------- | ------------------------------------------ | --------------------------- |
|
||||
| `lineWidth` | 线宽,默认 `2` | `2` / `6` / `12` |
|
||||
| `lineDash` | 虚线样式,数组按「实线长度、空白长度」交替 | `[18, 10]` |
|
||||
| `lineDashOffset` | 虚线起始偏移,改变虚线从哪里开始 | `0` / `12` |
|
||||
| `lineCap` | 端点样式,只影响线段两端 | `butt` / `round` / `square` |
|
||||
| `lineJoin` | 拐角样式,只影响线段连接处 | `miter` / `round` / `bevel` |
|
||||
| `miterLimit` | 尖角限制,`miter` 拐角过长时会被截断 | 默认 `10` |
|
||||
|
||||
`lineDash` 的数组会按「画一段、空一段」交替;写 `[18, 10]` 就是画 18、空 10。超过两项时继续交替,例如 `[16, 6, 2, 6]` 是长线、空白、短线、空白,常用来画点划线。`lineDashOffset` 把整个虚线图案向后平移,可以做流动的虚线。
|
||||
|
||||
`lineCap` 只改变两个端点,`lineJoin` 只改变拐角,两者互不影响。`miterLimit` 只在 `lineJoin="miter"` 时有意义,尖角被拉得太长时会被切成斜角。
|
||||
|
||||
```tsx
|
||||
<g-line
|
||||
line={[80, 80, 400, 80]}
|
||||
strokeStyle="#7ee787"
|
||||
lineWidth={6}
|
||||
lineDash={[18, 10]}
|
||||
lineDashOffset={4}
|
||||
lineCap="round"
|
||||
/>
|
||||
|
||||
<g-path
|
||||
path={arrow}
|
||||
stroke
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={6}
|
||||
lineJoin="miter"
|
||||
miterLimit={8}
|
||||
/>
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="strokeLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 分四组对比:线宽、虚线、端点与拐角。
|
||||
|
||||
这些属性对所有描边图形通用:默认描边的直线、贝塞尔曲线能直接用,矩形、圆、椭圆、路径写了 `stroke` 之后也能用。例如给矩形加虚线描边:
|
||||
|
||||
```tsx
|
||||
<g-rect
|
||||
loc={[40, 40, 180, 100]}
|
||||
stroke
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={6}
|
||||
lineDash={[12, 8]}
|
||||
/>
|
||||
```
|
||||
|
||||
## 矩形 g-rect
|
||||
|
||||
矩形用 `loc` 简写,四个值依次是左上角 `x`、左上角 `y`、宽度、高度。矩形默认填充,颜色用 `fillStyle`。也可以把四个值拆成 `x`、`y`、`width`、`height` 分别写,效果一样。
|
||||
|
||||
```tsx
|
||||
<g-rect loc={[80, 80, 240, 140]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="rectLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 里放了四组参数,分别对比 `loc` 不同时的位置与宽高。
|
||||
|
||||
矩形默认锚点在左上角,所以前两个值是左上角的位置。想改锚点时,可以把 `loc` 写成六个值,最后两项是 `anchorX`、`anchorY`;也可以单独写 `anchorX` / `anchorY`。例如把锚点改成 `0.5` 后,前两个值就变成矩形中心。
|
||||
|
||||
```tsx
|
||||
// 锚点在中心:前两个值是矩形中心坐标
|
||||
<g-rect loc={[240, 160, 120, 80, 0.5, 0.5]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
`g-rect` 本身没有圆角参数,需要圆角时用后面的 `g-rectr`。
|
||||
|
||||
## 圆 g-circle
|
||||
|
||||
圆用 `circle` 简写,三个值依次是圆心 `x`、圆心 `y`、半径。圆默认填充,颜色用 `fillStyle`。也可以写 `x`、`y`、`radius`,效果一样。
|
||||
|
||||
```tsx
|
||||
<g-circle circle={[240, 170, 80]} fillStyle="#58c4dd" />
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="circleLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 上排放三个整圆对比半径,下排三个圆弧分别用 fill、stroke、fill+stroke 三种模式,`start` / `end` 只控制角度;标签上写的是度数,代码里按弧度写。
|
||||
|
||||
`circle` 还能写五个值:`[圆心 x, 圆心 y, 半径, 起始角度, 终止角度]`,这时画的是从起始角到终止角的圆弧。`start` / `end` 的单位是**弧度**,不是度数;`0` 指向右侧,角度增大沿顺时针方向。live 标签用度数只是为了好读,代码里仍要换算成弧度:
|
||||
|
||||
| 度数 | 弧度 |
|
||||
| ------ | ------- |
|
||||
| `0°` | `0` |
|
||||
| `90°` | `π / 2` |
|
||||
| `180°` | `π` |
|
||||
| `270°` | `1.5π` |
|
||||
| `360°` | `2π` |
|
||||
|
||||
圆弧也按填充 / 描边两种模式画:默认填充,`start` 与 `end` 之间的圆弧和两端连线围成的区域会被填满,颜色用 `fillStyle`;只想看弧线时写 `stroke`,颜色改用 `strokeStyle`;两者都要就同时写 `fill` 和 `stroke`,`fillStyle` 与 `strokeStyle` 分别给色。
|
||||
|
||||
```tsx
|
||||
// 完整圆
|
||||
<g-circle circle={[120, 100, 60]} fillStyle="#58c4dd" />
|
||||
|
||||
// 圆弧 0° → 180°:默认填充,弧与两端连线围成的区域被填满
|
||||
<g-circle circle={[320, 100, 60, 0, Math.PI]} fillStyle="#58c4dd" />
|
||||
|
||||
// 同一个圆弧只描边:写 stroke,颜色改用 strokeStyle
|
||||
<g-circle
|
||||
circle={[320, 100, 60, 0, Math.PI]}
|
||||
stroke
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={4}
|
||||
/>
|
||||
|
||||
// 填充与描边都要:同时写 fill 和 stroke,两种颜色分别给
|
||||
<g-circle
|
||||
circle={[320, 100, 60, 0, Math.PI]}
|
||||
fill
|
||||
stroke
|
||||
fillStyle="#58c4dd"
|
||||
strokeStyle="#e8f0ff"
|
||||
lineWidth={3}
|
||||
/>
|
||||
```
|
||||
|
||||
## 椭圆 g-ellipse
|
||||
|
||||
椭圆用 `ellipse` 简写,四个值依次是圆心 `x`、圆心 `y`、横向半径 `rx`、纵向半径 `ry`。椭圆默认填充。也可以写 `x`、`y`、`radiusX`、`radiusY`。
|
||||
|
||||
```tsx
|
||||
<g-ellipse ellipse={[240, 170, 130, 70]} fillStyle="#c58af9" />
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="ellipseLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 上排放三个整椭圆对比 `rx` / `ry`,下排三个部分椭圆分别用 fill、stroke、fill+stroke 三种模式,`start` / `end` 只控制角度;标签上写的是度数,代码里按弧度写。
|
||||
|
||||
`ellipse` 还能写六个值:`[圆心 x, 圆心 y, 横向半径, 纵向半径, 起始角度, 终止角度]`,用来画部分椭圆。角度规则与圆相同:`start` / `end` 用弧度,不是度数,`0` 指向右侧,角度增大沿顺时针方向;换算见上面的度数对照表。部分椭圆也按填充 / 描边两种模式画:默认填充,圆弧与两端连线围成的区域会被填满,颜色用 `fillStyle`;只想看弧线时写 `stroke`,颜色改用 `strokeStyle`;两者都要就同时写 `fill` 和 `stroke`,`fillStyle` 与 `strokeStyle` 分别给色。
|
||||
|
||||
```tsx
|
||||
// 完整椭圆
|
||||
<g-ellipse ellipse={[120, 100, 70, 40]} fillStyle="#c58af9" />
|
||||
|
||||
// 部分椭圆 180° → 360°:默认填充
|
||||
<g-ellipse
|
||||
ellipse={[330, 100, 80, 45, Math.PI, Math.PI * 2]}
|
||||
fillStyle="#c58af9"
|
||||
/>
|
||||
|
||||
// 同一个部分椭圆只描边:写 stroke,颜色改用 strokeStyle
|
||||
<g-ellipse
|
||||
ellipse={[330, 100, 80, 45, Math.PI, Math.PI * 2]}
|
||||
stroke
|
||||
strokeStyle="#c58af9"
|
||||
lineWidth={4}
|
||||
/>
|
||||
|
||||
// 填充与描边都要:同时写 fill 和 stroke,两种颜色分别给
|
||||
<g-ellipse
|
||||
ellipse={[330, 100, 80, 45, Math.PI, Math.PI * 2]}
|
||||
fill
|
||||
stroke
|
||||
fillStyle="#c58af9"
|
||||
strokeStyle="#e8f0ff"
|
||||
lineWidth={3}
|
||||
/>
|
||||
```
|
||||
|
||||
## 直线 g-line
|
||||
|
||||
直线用 `line` 简写,四个值依次是两个端点 `x1`、`y1`、`x2`、`y2`。直线默认描边,`strokeStyle` 给颜色,`lineWidth` 给线宽。也可以逐个写 `x1`、`y1`、`x2`、`y2`。
|
||||
|
||||
```tsx
|
||||
<g-line line={[80, 240, 400, 100]} strokeStyle="#7ee787" lineWidth={6} />
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="lineLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 里放了四组参数,分别对比端点、`lineWidth`、`lineDash` 与颜色。
|
||||
|
||||
直线是最简单的描边图形,描边细节一节讲的 `lineDash`、`lineDashOffset`、`lineCap` 都能直接写在 `g-line` 上。`lineCap` 只改变两个端点,虚线则从起点开始按 `lineDash` 交替。
|
||||
|
||||
```tsx
|
||||
<g-line
|
||||
line={[80, 200, 400, 200]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={10}
|
||||
lineDash={[18, 10]}
|
||||
lineCap="round"
|
||||
/>
|
||||
```
|
||||
|
||||
## 三次贝塞尔 g-bezier
|
||||
|
||||
三次贝塞尔用 `curve` 简写,八个值依次是起点 `sx`、`sy`,第一个控制点 `cp1x`、`cp1y`,第二个控制点 `cp2x`、`cp2y`,终点 `ex`、`ey`。曲线默认描边,`strokeStyle` 与 `lineWidth` 控制颜色和粗细。也可以逐个写这八个属性。
|
||||
|
||||
```tsx
|
||||
<g-bezier
|
||||
curve={[80, 240, 140, 70, 340, 250, 400, 100]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={4}
|
||||
/>
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="bezierLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 里放了四组曲线,分别对比控制点靠近、拉远、交叉与 S 形;白点是控制点,虚线是起点 → `cp1` → `cp2` → 终点的控制多边形。
|
||||
|
||||
起点与终点决定曲线两端,两个控制点决定中间的弯曲:第一个控制点主要拉住起点附近的走向,第二个控制点主要拉住终点附近的走向。控制点离端点越远,曲线被拉得越开;两个控制点分居曲线两侧时会出现 S 形。
|
||||
|
||||
## 二次贝塞尔 g-quad
|
||||
|
||||
二次贝塞尔用 `curve` 简写,六个值依次是起点 `sx`、`sy`,控制点 `cpx`、`cpy`,终点 `ex`、`ey`。曲线默认描边。也可以逐个写这六个属性。
|
||||
|
||||
```tsx
|
||||
<g-quad
|
||||
curve={[90, 230, 240, 80, 390, 230]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={4}
|
||||
/>
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="quadLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 里放了四组曲线,分别对比控制点在上、下、左、右;白点是控制点,虚线是起点 → 控制点 → 终点的控制多边形。
|
||||
|
||||
二次曲线只有一个控制点,它同时影响起点与终点两侧的走向,曲线在控制点方向达到最大弯曲。控制点离两个端点越远,弧线越鼓;做简单的弧线或装饰够用。
|
||||
|
||||
## 路径 g-path
|
||||
|
||||
路径用 `path` 属性,值是一个 `Path2D`。`Path2D` 是浏览器自带的全局构造器,直接 `new Path2D()` 即可,不需要 import。路径默认填充;只想画线时写 `stroke`。路径坐标相对元素自身,元素默认在父容器的原点,所以不写 `x` / `y` 时,坐标看起来就是从父容器原点开始。
|
||||
|
||||
```tsx
|
||||
// Path2D 是浏览器全局对象,直接 new
|
||||
const badge = new Path2D();
|
||||
badge.moveTo(240, 80);
|
||||
badge.lineTo(340, 140);
|
||||
badge.lineTo(315, 255);
|
||||
badge.lineTo(165, 255);
|
||||
badge.lineTo(140, 140);
|
||||
badge.closePath();
|
||||
|
||||
// 默认填充:给颜色即可
|
||||
<g-path path={badge} fillStyle="#7ee787" />;
|
||||
|
||||
// 只想画轮廓:写 stroke
|
||||
<g-path path={badge} stroke strokeStyle="#7ee787" lineWidth={3} />;
|
||||
|
||||
// 自交或多段重叠时,用 fillRule 指定填充规则
|
||||
<g-path path={badge} fillStyle="#7ee787" fillRule="evenodd" />;
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="pathLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 里放了三个路径,分别对比折线、闭合填充与圆弧。
|
||||
|
||||
`moveTo` 决定从哪里开始,`lineTo` 连到下一个点,`closePath` 把最后一点连回起点。路径可以有多段;`arc` 画圆弧,`bezierCurveTo` 画三次贝塞尔。开放路径通常写 `stroke`,闭合路径适合填充;有自交或多段重叠时,用 `fillRule` 决定哪些区域算内部:`nonzero` 按环绕方向,`evenodd` 按奇偶,默认是 `nonzero`。
|
||||
|
||||
同一个 `Path2D` 可以交给多个 `g-path` 复用;但 `Path2D` 不能序列化,不能直接放进存档。需要保存路径时,保存构造它用到的点或参数,读档后重新构造。
|
||||
|
||||
## 圆角矩形 g-rectr
|
||||
|
||||
圆角矩形用 `g-rectr`。`g-rect` 没有圆角参数,需要圆角时换用 `g-rectr`。圆角用 `circle` 或 `ellipse` 简写:`circle` 给圆形圆角,`ellipse` 给椭圆圆角。
|
||||
|
||||
`circle` 可以写 1 到 4 项,按项数决定每个角用哪个半径:
|
||||
|
||||
- 1 项 `[r1]`:四个角都用 `r1`。
|
||||
- 2 项 `[r1, r2]`:左上、右下用 `r1`,右上、左下用 `r2`。
|
||||
- 3 项 `[r1, r2, r3]`:左上用 `r1`,右上和左下用 `r2`,右下用 `r3`。
|
||||
- 4 项 `[r1, r2, r3, r4]`:依次对应左上、右上、右下、左下。
|
||||
|
||||
`ellipse` 每两个值为一组(横向半径、纵向半径),按组数决定每个角用哪一组:
|
||||
|
||||
- 2 项 `[rx1, ry1]`:四个角都用这一组。
|
||||
- 4 项 `[rx1, ry1, rx2, ry2]`:左上、右下用第 1 组,右上、左下用第 2 组。
|
||||
- 6 项 `[rx1, ry1, rx2, ry2, rx3, ry3]`:左上用第 1 组,右上和左下用第 2 组,右下用第 3 组。
|
||||
- 8 项 `[rx1, ry1, rx2, ry2, rx3, ry3, rx4, ry4]`:依次对应左上、右上、右下、左下,每组两个值。
|
||||
|
||||
只想让某几个角是圆角时,把不需要的角写成 0。
|
||||
|
||||
```tsx
|
||||
// 四个角同样圆
|
||||
<g-rectr loc={[30, 70, 120, 90]} circle={[24]} fillStyle="#2f6fed" />
|
||||
|
||||
// 依次左上、右上、右下、左下
|
||||
<g-rectr
|
||||
loc={[180, 70, 120, 90]}
|
||||
circle={[36, 0, 36, 0]}
|
||||
fillStyle="#58c4dd"
|
||||
/>
|
||||
|
||||
// 椭圆圆角:横向与纵向半径不同
|
||||
<g-rectr
|
||||
loc={[330, 70, 120, 90]}
|
||||
ellipse={[48, 24]}
|
||||
fillStyle="#c58af9"
|
||||
/>
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="rectrLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 里放了四组圆角参数,分别对比一项半径、四项半径、椭圆圆角与大半径。
|
||||
|
||||
圆角矩形默认填充;圆角半径超过宽高一半时会被限制在宽高的一半以内,不会画到矩形外面。
|
||||
|
||||
## 所有图形的组合
|
||||
|
||||
把八种图形放进同一个标准 `container`,用 `FULL_LOC` 铺满整块 UI。下面是一段完整 TSX;路径先构造一次 `Path2D`,再交给 `g-path`。
|
||||
|
||||
```tsx
|
||||
const badge = new Path2D();
|
||||
badge.moveTo(300, 205);
|
||||
badge.lineTo(345, 230);
|
||||
badge.lineTo(333, 280);
|
||||
badge.lineTo(267, 280);
|
||||
badge.lineTo(255, 230);
|
||||
badge.closePath();
|
||||
|
||||
<container loc={FULL_LOC}>
|
||||
<g-rect loc={FULL_LOC} fillStyle="#141a22" />
|
||||
<text loc={[24, 14]} text="八种图形" fillStyle="#e8f0ff" />
|
||||
|
||||
{/* 上排:矩形、圆、椭圆、直线 */}
|
||||
<g-rect loc={[20, 72, 80, 62]} fillStyle="#2f6fed" />
|
||||
<g-circle circle={[180, 103, 34]} fillStyle="#58c4dd" />
|
||||
<g-ellipse ellipse={[300, 103, 50, 32]} fillStyle="#c58af9" />
|
||||
<g-line line={[370, 133, 460, 75]} strokeStyle="#7ee787" lineWidth={4} />
|
||||
|
||||
{/* 下排:三次贝塞尔、二次贝塞尔、路径、圆角矩形 */}
|
||||
<g-bezier
|
||||
curve={[20, 275, 45, 205, 80, 280, 105, 212]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-quad
|
||||
curve={[140, 270, 180, 205, 220, 270]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-path path={badge} fillStyle="#7ee787" />
|
||||
<g-rectr loc={[370, 215, 80, 62]} circle={[24]} fillStyle="#f2b84b" />
|
||||
|
||||
{/* 每个图形的短标签 */}
|
||||
<text loc={[44, 146]} text="矩形" fillStyle="#cfe0ff" />
|
||||
<text loc={[170, 146]} text="圆" fillStyle="#cfe0ff" />
|
||||
<text loc={[285, 146]} text="椭圆" fillStyle="#cfe0ff" />
|
||||
<text loc={[405, 146]} text="直线" fillStyle="#cfe0ff" />
|
||||
<text loc={[20, 292]} text="三次贝塞尔" fillStyle="#cfe0ff" />
|
||||
<text loc={[140, 292]} text="二次贝塞尔" fillStyle="#cfe0ff" />
|
||||
<text loc={[290, 292]} text="路径" fillStyle="#cfe0ff" />
|
||||
<text loc={[380, 292]} text="圆角矩形" fillStyle="#cfe0ff" />
|
||||
</container>;
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="allLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这段代码里每种图形只出现一次,位置按 4×2 排开;换成自己的布局时,改各自的 `loc`、圆心或端点即可。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const modesLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/shapes-modes.tsx');
|
||||
const strokeLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/shapes-stroke.tsx');
|
||||
const rectLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/shapes-rect.tsx');
|
||||
const circleLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/shapes-circle.tsx');
|
||||
const ellipseLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/shapes-ellipse.tsx');
|
||||
const lineLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/shapes-line.tsx');
|
||||
const bezierLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/shapes-bezier.tsx');
|
||||
const quadLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/shapes-quad.tsx');
|
||||
const pathLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/shapes-path.tsx');
|
||||
const rectrLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/shapes-rectr.tsx');
|
||||
const allLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/shapes-all.tsx');
|
||||
</script>
|
||||
|
||||
## 默认值与注意
|
||||
|
||||
- 圆与椭圆的默认锚点是 `0.5`,`x` / `y` 指圆心;矩形与容器的默认锚点是 `0`,`x` / `y` 指左上角。
|
||||
- `curve` 数组长度写错不会报错,只会画出错误形状:三次贝塞尔要 8 个值,二次贝塞尔要 6 个值。
|
||||
- `lineDash` 建议写偶数项;写奇数项时浏览器会自动复制一份再交替,容易看不出规律。
|
||||
- 默认填充只在没写 `stroke` 时生效:给默认填充的图形加 `stroke` 会变成只描边,要同时填充和描边就显式写 `fill` + `stroke`。
|
||||
|
||||
下一篇[《文字》](./text.md)讲怎么在图形旁边写字:内容、字体、颜色与简单排版。
|
||||
@@ -0,0 +1,157 @@
|
||||
# 通用参数
|
||||
|
||||
这些属性大多数元素都能写。它们有的只在特定条件下有意义:`hd` 只对开启缓存的元素有效;`anti` / `noanti` 影响绘制内容在缩放时的插值;`cursor`、`hidden` 要鼠标经过或隐藏时才能看出差别。下面会说明每个参数在什么条件下有意义;场景只是由属性语义推出的适用条件,不是限定用途。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [容器与坐标](./container-and-coordinates.md)
|
||||
- [基础图形](./basic-shapes.md)
|
||||
|
||||
## hd
|
||||
|
||||
`hd` 默认 `true`。它控制元素的缓存画布是否按设备像素比(DPR)使用高清分辨率:为 `true` 时缓存画布按 DPR 放大,为 `false` 时按 1x 绘制。它只对开启缓存的元素有效;没有缓存的元素写 `hd` 看不到可见变化。
|
||||
|
||||
是否要高清缓存由缓存内容决定。缓存的是文字、矢量图形这类需要清晰边缘的内容时,在高 DPR 屏幕上按 DPR 绘制,放大后边缘才不会糊,默认的 `true` 适合这类内容。反过来,如果缓存内容本身就是 1x 的像素数据,按 DPR 放大并不会多出信息;或者更在意缓存的显存与内存开销而不是 DPR 下的清晰度,就可以写 `hd={false}`。
|
||||
|
||||
```tsx
|
||||
// hd 只对开启缓存的元素有效;container 默认开启缓存,这里让它按 1x 绘制缓存
|
||||
<container loc={[40, 40, 240, 160]} hd={false}>
|
||||
<text loc={[8, 8]} text="缓存内容" fillStyle="#ffffff" />
|
||||
</container>
|
||||
```
|
||||
|
||||
## anti / noanti
|
||||
|
||||
`anti` 默认 `true`,`noanti` 默认 `false`。两者控制同一个抗锯齿开关:`anti` 为 `false` 关闭抗锯齿,`noanti` 为 `true` 也关闭抗锯齿。`noanti` 的优先级更高,`noanti` 为 `true` 等价于关闭 `anti`;不要同时依赖两个开关。
|
||||
|
||||
抗锯齿影响的是图片等绘制内容在缩放时的插值方式。连续色调的图片与渐变在缩放时,平滑插值能减少锯齿和色块,默认的 `anti` 适合这类内容。像素图相反:它的边缘本来就是硬边,抗锯齿会把硬边插值成半透明过渡,放大后像素边缘会发虚。因此像素图放大时应写 `noanti`,并尽量按整数倍放大,减少额外的重采样。这个结论是从「像素图需要硬边」推出来的适用条件,不是对 `noanti` 用途的限定。
|
||||
|
||||
```tsx
|
||||
// noanti 关闭图片缩放时的插值,让像素边缘保持硬边
|
||||
<image image={texture} noanti loc={[40, 40, 160, 160]} />
|
||||
```
|
||||
|
||||
下面把同一张 16×16 纹理放大到 160×160:左边用默认绘制,右边写了 `noanti`,对照边缘是平滑还是方块。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="propsAntiLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## hidden
|
||||
|
||||
`hidden` 默认 `false`。为 `true` 时元素不绘制,也不参与交互。它不改变元素的尺寸与坐标,改回 `false` 后原样恢复。需要保留元素实例、只是临时不绘制或不交互时用它;改回 `false` 就能恢复,不需要反复创建和销毁元素。
|
||||
|
||||
```tsx
|
||||
// hidden 为 true 时不绘制,也不参与交互
|
||||
<g-rect loc={[40, 40, 120, 80]} hidden fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
## id
|
||||
|
||||
`id` 默认空字符串,一般情况下不会用到。只有需要从渲染器按 id 直接查找元素时才写,例如调试、测试或命令式访问;日常写 UI 不需要给元素命名。
|
||||
|
||||
空 id 不会被登记;同一个渲染器内 id 应当唯一,重复会告警。给元素写 `id` 后,可以用渲染器的 `getElementById(id)` 查找它。它不是 DOM id,不影响显示与布局。
|
||||
|
||||
```tsx
|
||||
// 需要按 id 查找时才写,之后可以用渲染器的 getElementById 取回
|
||||
<g-rect id="target" loc={FULL_LOC} fillStyle="#141a22" />
|
||||
```
|
||||
|
||||
## alpha
|
||||
|
||||
`alpha` 默认 `1`,范围 `0`–`1`。它不是继承属性,不会自动写到每个子元素各自的绘制上。子元素是否一起变透明,取决于当前元素有没有开启缓存:开启缓存的父级会把子元素先画进缓存图,再对整张缓存结果应用 `alpha`,子元素会一起变透明;未开启缓存时,`alpha` 只影响当前元素自身的绘制,子元素按自己的 `alpha` 绘制。单个元素需要淡入淡出时,改自己的 `alpha` 即可。
|
||||
|
||||
```tsx
|
||||
// 只影响这个矩形自身的透明度
|
||||
<g-rect loc={[40, 40, 120, 80]} fillStyle="#4f8cff" alpha={0.5} />
|
||||
```
|
||||
|
||||
下面三个同尺寸矩形分别使用 `alpha` 为 `1`、`0.6` 与 `0.25`。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="propsAlphaLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## cursor
|
||||
|
||||
`cursor` 默认 `inherit`。值是一个 CSS cursor 字符串,例如 `pointer`、`text`、`default`,按 CSS 中这些值的语义选择需要的形状。它只改变鼠标悬停时的光标,不负责点击:点击由元素的事件处理,光标只是提示。鼠标悬停在元素上时才生效,所以元素本身要参与交互;不参与交互的元素不会改变光标。
|
||||
|
||||
```tsx
|
||||
// 悬停在这个矩形上时,光标变成手型
|
||||
<g-rect loc={[40, 40, 200, 80]} fillStyle="#2f6fed" cursor="pointer" />
|
||||
```
|
||||
|
||||
下面这块区域写了 `cursor="pointer"`,鼠标移上去后光标会变成手型。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="propsCursorLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## filter
|
||||
|
||||
`filter` 默认 `none`。值可以是任何合法的 CSS filter 字符串,例如 `blur(3px)`、`grayscale(1) brightness(0.7)`、`drop-shadow(0 4px 6px #000)`;完整的函数列表见 [MDN 的 filter 文档](https://developer.mozilla.org/zh-CN/docs/Web/CSS/filter)。可以组合多个函数,用空格分隔,按书写顺序依次应用。
|
||||
|
||||
`filter` 不是继承属性,不会自动套到每个子元素各自的绘制上。子元素是否被过滤,取决于当前元素有没有开启缓存:开启缓存时,子元素先画进当前元素的缓存图,`filter` 作用在整张缓存结果上,子元素会一起被过滤;未开启缓存时,子元素按自己的 `filter` 绘制,当前元素的 `filter` 只影响自身绘制。如果当前元素没有自己的绘制(例如未开启缓存的容器),`filter` 就不会作用到子元素。它也不影响布局。
|
||||
|
||||
```tsx
|
||||
// 多个 filter 函数按书写顺序依次应用
|
||||
<g-rect
|
||||
loc={[40, 40, 160, 100]}
|
||||
fillStyle="#4f8cff"
|
||||
filter="blur(3px) brightness(0.8)"
|
||||
/>
|
||||
```
|
||||
|
||||
下面三张相同的图分别是正常、模糊与灰度加亮度。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="propsFilterLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## zIndex
|
||||
|
||||
`zIndex` 默认 `0`。它只在同一父元素下的兄弟之间比较:值越大越后画、越靠上。不同父级的元素不直接比较,它们跟随各自父级在树中的叠放关系绘制。`zIndex` 可以是负数,值越小越先画、越靠下。相同值不要依赖先后顺序。
|
||||
|
||||
```tsx
|
||||
// 只影响同一父元素下的兄弟:zIndex 较大的后画,盖住默认的 0
|
||||
<g-rect loc={[40, 40, 160, 110]} fillStyle="#f0b428" zIndex={1} />
|
||||
<g-rect loc={[100, 80, 160, 110]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
需要强制决定同一父级下兄弟的叠放顺序时,用 `zIndex`。下面两个矩形互相重叠,蓝色写了更高的 `zIndex`,即使先写也盖在黄色上面。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="propsZIndexLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const propsAntiLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/props-anti.tsx');
|
||||
const propsAlphaLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/props-alpha.tsx');
|
||||
const propsCursorLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/props-cursor.tsx');
|
||||
const propsFilterLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/props-filter.tsx');
|
||||
const propsZIndexLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/props-zindex.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,113 @@
|
||||
# 容器与坐标
|
||||
|
||||
上一篇[《第一个静态界面》](./first-static-ui.md)已经用容器、文字和几个简单图形拼出了一块静态界面:`container` 圈出范围,文字和图形按 `loc` 摆进去。这一篇只讲怎么把元素放到想要的位置:坐标从哪里算起、`loc` 与锚点怎么配合、容器嵌套后子元素的坐标怎么变。事件、变换、缓存和层级都留到后面的篇章。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [第一个静态界面](./first-static-ui.md)
|
||||
|
||||
## 坐标来源
|
||||
|
||||
根容器的左上角是原点,向右是正 `x`,向下是正 `y`。子元素的坐标相对父容器的左上角,不是相对整块画布;容器嵌套时,每一层都把坐标系重新平移一次。
|
||||
|
||||
```tsx
|
||||
<container loc={FULL_LOC}>
|
||||
<text loc={[24, 24]} text="左上角是原点" fillStyle="#e8f0ff" />
|
||||
<g-rect loc={[24, 64, 120, 60]} fillStyle="#2f6fed" />
|
||||
</container>
|
||||
```
|
||||
|
||||
这段代码里,文字和矩形的 `x` / `y` 都从根容器的左上角量起。
|
||||
|
||||
## loc 与锚点
|
||||
|
||||
`loc` 是一个六元组,顺序固定:`x`、`y`、`width`、`height`、`anchorX`、`anchorY`。
|
||||
|
||||
```tsx
|
||||
// x、y、width、height、anchorX、anchorY
|
||||
<g-rect loc={[40, 40, 120, 80, 0, 0]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
六个值也可以拆成同名属性分别写:
|
||||
|
||||
```tsx
|
||||
<g-rect
|
||||
x={40}
|
||||
y={40}
|
||||
width={120}
|
||||
height={80}
|
||||
anchorX={0}
|
||||
anchorY={0}
|
||||
fillStyle="#2f6fed"
|
||||
/>
|
||||
```
|
||||
|
||||
`anchorX` 与 `anchorY` 还可以合并成 `anc`:
|
||||
|
||||
```tsx
|
||||
<container loc={[240, 160, 160, 120]} anc={[0.5, 0.5]} />
|
||||
```
|
||||
|
||||
`loc` 里每一对(`x` / `y`、`width` / `height`、`anchorX` / `anchorY`)要么都写,要么整对省略。只写 `[x, y]` 是合法的;宽高省略时沿用默认的 200×200。
|
||||
|
||||
锚点回答的是「元素自己的哪一个点落在 `x` / `y` 上」。矩形与容器的默认锚点是 `0`,也就是左上角;圆与椭圆的默认锚点是 `0.5`,也就是中心。锚点不是把元素整体平移,而是换一个点去对齐坐标:同一个 `x` / `y` 配不同锚点,元素落下的位置会明显不同。
|
||||
|
||||
矩形代表容器,圆点标出 `(x, y)` 所在的位置。下面四个例子用的是同一个局部坐标 `(110, 70)`,只是锚点和尺寸不同:
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="anchorLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
四个例子的坐标点相同:锚点为 `0, 0` 时矩形从圆点向右下展开,锚点为 `0.5, 0.5` 时圆点是矩形中心,锚点为 `1, 1` 时矩形从圆点向左上展开。最后一个仍是中心锚点,只是宽高更大,所以向四周展开得更多。
|
||||
|
||||
## 嵌套:局部坐标系
|
||||
|
||||
把一组元素放进子容器后,子元素的坐标就相对这个子容器,而不是相对根容器。移动父容器时,里面的子容器和元素跟着移动,子元素自己的 `x` / `y` 不需要改。
|
||||
|
||||
```tsx
|
||||
<container loc={FULL_LOC}>
|
||||
{/* 父容器:在根容器里的 (80, 60),尺寸 240×160 */}
|
||||
<container loc={[80, 60, 240, 160]}>
|
||||
{/* 子容器:在父容器里的 (20, 20),尺寸 160×100 */}
|
||||
<container loc={[20, 20, 160, 100]}>
|
||||
{/* 圆点在子容器的 (0, 0),也就是子容器的左上角 */}
|
||||
<g-circle circle={[0, 0, 6]} fillStyle="#58c4dd" />
|
||||
</container>
|
||||
</container>
|
||||
</container>
|
||||
```
|
||||
|
||||
子容器不需要知道自己在屏幕上的绝对位置,只需要知道自己在父容器里的位置。下面的 live 用两种颜色区分父容器和子容器,两个圆点分别是它们的左上角:
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="containerLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
子容器的 `(0, 0)` 是它在父容器内的位置,不是画布原点;父容器移动时,子容器和里面的元素一起移动。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const anchorLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/anchor-demo.tsx');
|
||||
const containerLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/container-demo.tsx');
|
||||
</script>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- 不写宽高时,元素的默认尺寸是 200×200。
|
||||
- 锚点改变的是「元素自己的哪一个点」落在 `x` / `y` 上,不是把元素整体平移。
|
||||
- 子元素的坐标相对父容器,不是相对画布;移动父容器时,子元素跟着移动。
|
||||
- 容器外的内容默认不可见;需要显示的内容要放在容器矩形内。
|
||||
- `nocache` 可能让超出容器的内容显示,但这是渲染实现的特性,后续可能变动,不要依赖。
|
||||
|
||||
下一篇[《基础图形》](./basic-shapes.md)开始讲矩形、圆、线这些元素本身:它们的几何参数、填充与描边怎么用。
|
||||
@@ -0,0 +1,147 @@
|
||||
# 自绘元素与自定义容器
|
||||
|
||||
`<custom>` 与 `<container-custom>` 用来处理现成元素无法直接表达的绘制与子元素控制:前者在元素内部直接用 Canvas 2D 画内容,后者接管子元素的绘制与事件传递。普通布局仍然优先用 `<container>` 与现成元素;只有确实需要直接操作画布或控制子元素时才用这两个标签。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [容器与坐标](./container-and-coordinates.md)
|
||||
- [基础图形](./basic-shapes.md)
|
||||
|
||||
## custom
|
||||
|
||||
`<custom>` 是叶子元素,没有子元素。它的尺寸与位置由 `loc` 决定,`loc` 之外不参与布局。
|
||||
|
||||
`render` 接收 `MotaOffscreenCanvas2D`,在元素局部坐标里直接用 `canvas.ctx` 绘制。局部坐标的原点在元素左上角,宽高就是 `loc` 的宽高。
|
||||
|
||||
系统在调用 `render` 前后已经保存并恢复了画布状态,函数里不需要在开头和结尾习惯性地写 `save` / `restore`。只有在函数内部临时改变状态、之后还要恢复并继续绘制时,才需要自己保存和恢复。
|
||||
|
||||
`bindings` 接收依赖值数组。把 `render` 读取的响应式值放进数组,例如 `bindings={[angle.value]}`,不需要传 `ref` 对象。读取 `.value` 发生在父组件 render 中,和 `loc={[x.value, ...]}` 一样会被 Vue 追踪;值变化后父组件重渲染,`bindings` prop 更新,`<custom>` 重绘。`render` 函数本身不需要认识 Vue、`Ref` 或 `watch`,它只读取普通值。`Ref` 等响应式基础见[《响应式》](../advanced/reactivity.md)。
|
||||
|
||||
::: warning
|
||||
不要在 `render` 里修改用于 `bindings` 的响应式值(例如渲染时递增 `angle.value`),这会让渲染与状态更新互相触发。一般不会遇到这种情况,确实需要时会在高级 III 中进一步讲解。
|
||||
:::
|
||||
|
||||
`<custom>` 默认开启缓存。内容频繁变化、缓存没有收益时,可以加 `nocache`。
|
||||
|
||||
需要直接使用 Canvas 2D 的路径、渐变、裁剪等能力,而现成元素组合不出来时,用 `<custom>` 自绘。能用 `g-*` 图形、`image` 与 `text` 拼出来的内容,继续用现成元素。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
|
||||
// 把 angle.value 放进 bindings;角度变化时 <custom> 会重绘
|
||||
const angle = ref(0);
|
||||
const ringColors = ['#2f6fed', '#7aa7ff', '#f2b84b'];
|
||||
|
||||
// render 在元素局部坐标里绘制内容
|
||||
const render = canvas => {
|
||||
const ctx = canvas.ctx;
|
||||
const cx = 100;
|
||||
const cy = 100;
|
||||
|
||||
// 径向渐变与同心圆环直接走 Canvas 2D
|
||||
const gradient = ctx.createRadialGradient(cx, cy, 12, cx, cy, 88);
|
||||
gradient.addColorStop(0, '#2f6fed');
|
||||
gradient.addColorStop(1, '#141a22');
|
||||
ctx.beginPath();
|
||||
ctx.arc(cx, cy, 88, 0, Math.PI * 2);
|
||||
ctx.fillStyle = gradient;
|
||||
ctx.fill();
|
||||
|
||||
ringColors.forEach((color, index) => {
|
||||
ctx.beginPath();
|
||||
ctx.arc(cx, cy, 70 - index * 16, 0, Math.PI * 2);
|
||||
ctx.strokeStyle = color;
|
||||
ctx.lineWidth = 3;
|
||||
ctx.stroke();
|
||||
});
|
||||
|
||||
// 指针从圆心出发,按 angle 旋转;坐标都相对元素左上角
|
||||
ctx.translate(cx, cy);
|
||||
ctx.rotate(angle.value);
|
||||
ctx.beginPath();
|
||||
ctx.moveTo(0, 0);
|
||||
ctx.lineTo(0, -64);
|
||||
ctx.strokeStyle = '#e8f0ff';
|
||||
ctx.lineWidth = 4;
|
||||
ctx.stroke();
|
||||
};
|
||||
|
||||
<custom loc={[40, 40, 200, 200]} bindings={[angle.value]} render={render} />;
|
||||
```
|
||||
|
||||
下面的 live 用 `<custom>` 绘制同心圆环、径向渐变与旋转指针,角度值通过 `bindings` 触发重绘。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="customDemoLoader" :width="480" :height="320" />
|
||||
</ClientOnly>
|
||||
|
||||
## container-custom
|
||||
|
||||
`<container-custom>` 是带子元素的容器,区别只在绘制方式:`render` 接管子元素的绘制。
|
||||
|
||||
`render(canvas, children, transform)` 拿到画布、排好序的子元素列表与当前变换。子元素不会自动出现,必须自己遍历 `children`,对每个子元素调用 `renderContent`;不调用就不会绘制。`children` 已经按 `zIndex` 排好序,遍历顺序就是绘制顺序;`hidden` 的子元素应当跳过。
|
||||
|
||||
因为绘制的是子元素本身,`render` 里可以先逐个修改子元素的属性,再调用 `renderContent`。下面的例子给每个子元素设置依次递增的模糊:
|
||||
|
||||
```tsx
|
||||
// render 接管子元素绘制:按顺序给每个子元素设置递增的模糊,再逐个绘制
|
||||
const render = (canvas, children, transform) => {
|
||||
children.forEach((child, index) => {
|
||||
if (child.hidden) return;
|
||||
child.setFilter(`blur(${index * 2}px)`);
|
||||
child.renderContent(canvas, transform);
|
||||
});
|
||||
};
|
||||
|
||||
<container-custom loc={[40, 40, 240, 160]} render={render}>
|
||||
<g-rect loc={[16, 16, 208, 40]} fillStyle="#2f6fed" />
|
||||
<g-rect loc={[16, 64, 208, 40]} fillStyle="#2f6fed" />
|
||||
<g-rect loc={[16, 112, 208, 40]} fillStyle="#2f6fed" />
|
||||
</container-custom>;
|
||||
```
|
||||
|
||||
和 `custom` 一样,系统在调用 `render` 前后已经保存并恢复了画布状态,这个例子不需要写 `save` / `restore`。
|
||||
|
||||
`propagate` 接管事件传递,参数依次是事件类型、当前进度、事件对象、当前容器和「按默认规则继续传递」的回调。不写 `propagate` 就沿用默认。只有需要修改事件坐标或改变传递路径时才写,日常自定义绘制不需要它。
|
||||
|
||||
`<container-custom>` 常用于内置组件内部;需要自己控制子元素绘制或事件传递时也可以使用。普通布局继续用 `<container>`。
|
||||
|
||||
它默认开启缓存。内容频繁变化、缓存没有收益时,可以加 `nocache`。
|
||||
|
||||
普通 `<container>` 默认也会开启缓存:子元素先画到容器的缓存画布上,超出缓存画布的内容会被裁掉。给容器加 `nocache` 后子元素直接画到上层画布,超出容器的内容才不再被裁。不过这是缓存实现带来的特性,后续可能变化,不要依赖它来做布局或裁剪。
|
||||
|
||||
下面的 live 用同一组子元素对比:左侧普通 `<container>` 原样绘制,右侧 `<container-custom>` 在 `render` 里给子元素依次设置递增的模糊。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="containerCustomDemoLoader" :width="480" :height="320" />
|
||||
</ClientOnly>
|
||||
|
||||
## 选择方式
|
||||
|
||||
| 需求 | 用法 |
|
||||
| -------------------- | ----------------------------------- |
|
||||
| 只画内容、没有子元素 | `<custom>` |
|
||||
| 要控制子元素怎么画 | `<container-custom>` 的 `render` |
|
||||
| 要控制事件怎么传递 | `<container-custom>` 的 `propagate` |
|
||||
| 普通布局 | `<container>` 与现成元素 |
|
||||
|
||||
能用现成元素组合出来的内容,优先用现成元素;`<custom>` 与 `<container-custom>` 留给 Canvas 2D 直接绘制或子元素控制。
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- `<custom>` 没有子元素,尺寸与位置由 `loc` 决定。
|
||||
- `<container-custom>` 的 `render` 必须遍历并调用子元素的 `renderContent`,否则子元素不会绘制。
|
||||
- `propagate` 不写就沿用默认;不需要改变事件传递时不要写。
|
||||
- `<custom>` 与 `<container-custom>` 默认缓存;内容频繁变化时再加 `nocache`。
|
||||
- 普通布局与能用现成元素表达的内容,继续用 `<container>` 与现成元素。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const customDemoLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/custom-demo.tsx');
|
||||
const containerCustomDemoLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/container-custom-demo.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,175 @@
|
||||
# 第一个静态界面
|
||||
|
||||
这一篇从头拼一个静态界面:深色底、标题、一个图标、一个矩形、一个圆、一条分隔线,最后用两块重叠的矩形看层级。整屏 UI 用引擎给出的 `FULL_LOC`。每一步只加一种东西,最后得到一份可以直接运行的静态界面。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [UI 入门](./ui-basics.md)
|
||||
|
||||
## 容器
|
||||
|
||||
界面从容器开始。容器决定这块 UI 占多大,也决定子元素的坐标从哪里算:
|
||||
|
||||
```tsx
|
||||
<container loc={FULL_LOC}>
|
||||
<g-rect loc={FULL_LOC} fillStyle="#141a22" />
|
||||
</container>
|
||||
```
|
||||
|
||||
- `FULL_LOC` 是引擎给出的整屏位置;
|
||||
- 子元素的坐标相对这个容器的左上角,而不是相对整块画布;
|
||||
- `container` 本身不画颜色,深色底用一块和它一样大的 `g-rect` 铺出来;
|
||||
- 图形默认填充,`fillStyle` 是填充颜色。
|
||||
|
||||
现在得到一块铺满整屏的深色区域,后面的元素都放进这个 `container`。
|
||||
|
||||
## 文字
|
||||
|
||||
在容器里加标题:
|
||||
|
||||
```tsx
|
||||
<text loc={[24, 24]} text="背包" fillStyle="#e8f0ff" />
|
||||
```
|
||||
|
||||
- `text` 是文字内容,写在属性里,不要写成标签之间的裸文字;
|
||||
- `loc` 只写两个数:文字左上角相对容器左上角的位置;
|
||||
- `fillStyle` 是文字颜色。
|
||||
|
||||
## 矩形与圆
|
||||
|
||||
矩形用 `g-rect`,位置和大小都由 `loc` 给出:
|
||||
|
||||
```tsx
|
||||
<g-rect loc={[24, 64, 160, 64]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
前两个数是左上角,后两个数是宽和高。
|
||||
|
||||
圆用 `g-circle`,写成 `circle={[圆心x, 圆心y, 半径]}`:
|
||||
|
||||
```tsx
|
||||
<g-circle circle={[280, 96, 32]} fillStyle="#58c4dd" />
|
||||
```
|
||||
|
||||
圆默认填充,`fillStyle` 给颜色。
|
||||
|
||||
## 直线
|
||||
|
||||
分隔线用 `g-line`,给出两个端点即可:
|
||||
|
||||
```tsx
|
||||
<g-line line={[24, 168, 456, 168]} strokeStyle="#7aa7ff" />
|
||||
```
|
||||
|
||||
- `line` 的四个数是起点 `x` / `y` 和终点 `x` / `y`;
|
||||
- 线默认描边,`strokeStyle` 是颜色。
|
||||
|
||||
这条线从 `(24, 168)` 画到 `(456, 168)`,横在面板中间。
|
||||
|
||||
## 素材管理器中的图片
|
||||
|
||||
图片从素材管理器按别名取:
|
||||
|
||||
```tsx
|
||||
const icon = props.state.materials.getImageByAlias('bg.jpg');
|
||||
|
||||
<image image={icon} loc={[24, 184, 64, 64]} />;
|
||||
```
|
||||
|
||||
- `props.state.materials` 是 ClientCore 提供的素材管理器,素材和别名由它统一维护;
|
||||
- `getImageByAlias('bg.jpg')` 按别名取一张已经登记好的图,返回纹理或 `null`;
|
||||
- 取到的纹理直接交给 `image` 的 `image` 属性,`loc` 决定画在哪里、画多大。
|
||||
|
||||
## 相对坐标与层级
|
||||
|
||||
前面所有元素的坐标都相对根容器。把一组元素放进子容器时,坐标改成相对这个子容器:
|
||||
|
||||
```tsx
|
||||
<container loc={[240, 200, 216, 88]}>
|
||||
<g-rect loc={[0, 0, 216, 88]} fillStyle="#1d2733" />
|
||||
<text loc={[12, 12]} text="状态" fillStyle="#9fb6d1" />
|
||||
</container>
|
||||
```
|
||||
|
||||
子容器的 `loc` 是它在根容器里的位置;里面 `g-rect` 的 `[0, 0]` 是子容器的左上角,不是面板的左上角。移动子容器时,里面的元素整体跟着走。
|
||||
|
||||
同一父级里的兄弟按 `zIndex` 决定谁在上面:值大的画在上面。第二个矩形后写,但给第一个写 `zIndex={2}`,重叠处就是第一个在上面:
|
||||
|
||||
```tsx
|
||||
<g-rect loc={[320, 120, 120, 72]} fillStyle="#f2b84b" zIndex={2} />
|
||||
<g-rect loc={[368, 152, 120, 72]} fillStyle="#58c4dd" />
|
||||
```
|
||||
|
||||
`zIndex` 只在同一个父级的兄弟之间比较;不写时按书写顺序叠放。缓存与命中的细节不在本篇展开。
|
||||
|
||||
## 完整模板
|
||||
|
||||
把上面的内容按顺序放进标准模板:
|
||||
|
||||
```tsx
|
||||
import { defineComponent } from 'vue';
|
||||
import { GameUI, SetupComponentOptions } from '@motajs/system';
|
||||
import { DefaultProps } from '@motajs/render-vue';
|
||||
import { IGameUIPropsBase } from '@user/client-base';
|
||||
import { FULL_LOC } from '@/client';
|
||||
|
||||
// 这里填写自定义的 UI 参数
|
||||
interface MyPanelProps extends IGameUIPropsBase, DefaultProps {}
|
||||
|
||||
const myPanelProps = {
|
||||
props: ['controller', 'instance', 'state']
|
||||
} satisfies SetupComponentOptions<MyPanelProps>;
|
||||
|
||||
const MyPanel = defineComponent<MyPanelProps>(props => {
|
||||
// 图片从素材管理器按别名取
|
||||
const icon = props.state.materials.getImageByAlias('bg.jpg');
|
||||
|
||||
return () => (
|
||||
<container loc={FULL_LOC}>
|
||||
<g-rect loc={FULL_LOC} fillStyle="#141a22" />
|
||||
<text loc={[24, 24]} text="背包" fillStyle="#e8f0ff" />
|
||||
<g-rect loc={[24, 64, 160, 64]} fillStyle="#2f6fed" />
|
||||
<g-circle circle={[280, 96, 32]} fillStyle="#58c4dd" />
|
||||
<g-line line={[24, 168, 456, 168]} strokeStyle="#7aa7ff" />
|
||||
<image image={icon} loc={[24, 184, 64, 64]} />
|
||||
<container loc={[240, 200, 216, 88]}>
|
||||
<g-rect loc={[0, 0, 216, 88]} fillStyle="#1d2733" />
|
||||
<text loc={[12, 12]} text="状态" fillStyle="#9fb6d1" />
|
||||
</container>
|
||||
<g-rect loc={[320, 120, 120, 72]} fillStyle="#f2b84b" zIndex={2} />
|
||||
<g-rect loc={[368, 152, 120, 72]} fillStyle="#58c4dd" />
|
||||
</container>
|
||||
);
|
||||
}, myPanelProps);
|
||||
|
||||
export const MyPanelUI = new GameUI('my-panel', MyPanel);
|
||||
```
|
||||
|
||||
`FULL_LOC` 是整块画布的位置;在已有 UI 中使用 `props.controller.open(MyPanelUI, {})` 打开后,看到的就是这块面板。
|
||||
|
||||
## 运行效果
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="staticUiLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const staticUiLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/static-ui-demo.tsx');
|
||||
</script>
|
||||
|
||||
## 后续
|
||||
|
||||
- 坐标、锚点与嵌套:[容器与坐标](./container-and-coordinates.md)
|
||||
- 更多图形:[基础图形](./basic-shapes.md)
|
||||
- 文字样式:[文字](./text.md)
|
||||
- 纹理与素材:[图片与纹理](./image-and-texture.md)
|
||||
- 层级、变换与缓存:[层级、变换与性能](./layer-transform-performance.md)
|
||||
- 让界面响应点击:[事件与交互](../advanced/events.md)
|
||||
@@ -0,0 +1,70 @@
|
||||
# 图片与纹理
|
||||
|
||||
`<image>` 用来显示一张纹理。它只负责把纹理按元素矩形铺开,本身不产生像素,也不负责加载。界面里用到的纹理都已经由客户端登记在贴图管理器里,写 UI 时从那里取,不在页面里现场生成。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [容器与坐标](./container-and-coordinates.md)
|
||||
|
||||
## 贴图管理器中的纹理
|
||||
|
||||
`props.state.materials` 是 `ITextureManager`,客户端启动时把素材登记进去。取图片有两种方法:
|
||||
|
||||
- `getImageByAlias(alias)`:按别名取图片,返回 `ITexture | null`。别名来自素材配置,可能带后缀(如 `bg.jpg`),不是文件路径。
|
||||
- `getImage(index)`:按数字索引取图片,同样返回 `ITexture | null`。索引也来自素材配置。
|
||||
|
||||
```tsx
|
||||
// 按别名取一张已经登记好的图片
|
||||
const texture = props.state.materials.getImageByAlias('bg.jpg');
|
||||
|
||||
<image image={texture} loc={[40, 48, 96, 96]} />;
|
||||
```
|
||||
|
||||
取到后直接交给 `<image>` 的 `image` 属性,不需要额外判断或占位。
|
||||
|
||||
下面是 `<image>` 按 `loc` 显示纹理的效果。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="imageBasicLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## 图片尺寸
|
||||
|
||||
`<image>` 的显示矩形由 `loc` 决定:`[x, y, 宽, 高]`。纹理会被拉伸铺满这个矩形,所以同一张纹理放到不同大小会显示成不同尺寸。宽高比和纹理不一致时会变形,按纹理的原始宽高比给尺寸:
|
||||
|
||||
```tsx
|
||||
// 同一张纹理,显示成 64×64
|
||||
<image image={texture} loc={[40, 40, 64, 64]} />
|
||||
```
|
||||
|
||||
不写 `loc` 时元素默认 200×200。
|
||||
|
||||
下面把同一张纹理放进 64×64、96×96 与 128×128 三个矩形,对照显示尺寸的变化。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="imageSizesLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- 别名来自素材配置,可能带后缀(如 `bg.jpg`),不是文件路径;数字索引也来自同一份配置。
|
||||
- 同一张纹理取一次就够,不要把取图放进频繁执行的渲染逻辑里重复取。
|
||||
- 不要在 UI 里现场造纹理;界面只使用贴图管理器里已经登记的素材。
|
||||
- `<image>` 会把纹理拉伸到 `loc` 的宽高,比例不一致会变形;按原图比例给尺寸。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const imageBasicLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/image-basic.tsx');
|
||||
const imageSizesLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/image-sizes.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,140 @@
|
||||
# 层级、变换与性能
|
||||
|
||||
元素摆好位置之后,还会遇到三类问题:层级怎么沿树生效、怎么缩放旋转与混合、什么时候该缓存。这三件事都写在元素属性上,不需要额外的图层对象。理解它们的前提是渲染树:层级、变换与缓存都沿着父子关系生效,不是全局开关。
|
||||
|
||||
<div id="渲染树层级与绘制顺序"></div>
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [容器与坐标](./container-and-coordinates.md)
|
||||
- [通用参数](./common-props.md)
|
||||
|
||||
## 渲染树、层级与绘制顺序
|
||||
|
||||
元素组成一棵渲染树:子元素相对父元素定位,绘制顺序、变换与缓存都沿父子关系生效。同一父级下的兄弟按 `zIndex` 从小到大绘制,命中顺序相反;`zIndex` 只在兄弟之间比较,父级的 `zIndex` 带着整棵子树参与父级兄弟的排序。`zIndex` 与 `hidden` 的完整语义见[通用参数页](./common-props.md#zindex)。
|
||||
|
||||
UI 栈也遵循同一套规则。控制器把每个打开的面板当作 UI 容器下的兄弟,按栈顺序分配递增的 `zIndex`;面板之间的遮挡由打开顺序与显示策略决定,面板内部的 `zIndex` 只影响这棵子树内部。先看面板在哪个栈、哪个位置,再看面板内部的兄弟顺序。
|
||||
|
||||
## 变换:scale、rotate 与 transform
|
||||
|
||||
`scale` 是 `[x, y]` 数组,分别表示横向与纵向缩放比例;`rotate` 的单位是弧度,不是角度。两者都作用在元素自己的坐标系里,锚点就是变换中心:缩放与旋转都绕锚点进行。默认锚点在左上角;改成 `[0.5, 0.5]` 后,同一个缩放或旋转会绕中心进行,元素的视觉位置与扩展方向都会跟着改变。
|
||||
|
||||
`scale` 与 `rotate` 是底层 `transform` 的简写:`transform` 属性可以直接接收一个 `Transform` 对象,用来表达更一般的矩阵与平移。日常写界面用 `scale` / `rotate` 就够了;需要直接替换整个变换矩阵时再传 `transform`,本篇不展开构造方式。
|
||||
|
||||
```tsx
|
||||
// scale 写 [x, y];rotate 写弧度。两者都是 transform 的简写属性
|
||||
<g-rect loc={[40, 40, 120, 80]} fillStyle="#2f6fed" scale={[1.2, 0.8]} />
|
||||
<g-rect loc={[220, 40, 120, 80]} fillStyle="#f2b84b" rotate={Math.PI / 12} />
|
||||
|
||||
// 同一个变换换锚点:anc 决定绕哪个点缩放 / 旋转
|
||||
<g-rect
|
||||
loc={[40, 180, 120, 80]}
|
||||
fillStyle="#2f6fed"
|
||||
scale={[1.2, 0.8]}
|
||||
anc={[0.5, 0.5]}
|
||||
/>
|
||||
<g-rect
|
||||
loc={[220, 180, 120, 80]}
|
||||
fillStyle="#f2b84b"
|
||||
rotate={Math.PI / 12}
|
||||
anc={[0.5, 0.5]}
|
||||
/>
|
||||
```
|
||||
|
||||
`scale` 只写一个数字不会生效。需要等比缩放时写 `scale={[1.2, 1.2]}`,需要压扁时分别给两个值。`rotate` 想转 30 度要写 `Math.PI / 6`;写成 `30` 会转很多圈。
|
||||
|
||||
`container` 默认开启缓存。对默认缓存的容器做 `scale` 或 `rotate` 时,引擎会先画出缓存图,再对这张图做变换;缓存图被缩放或旋转后会重新采样,边缘可能发糊。需要清晰变换时,给做变换的容器加 `nocache`,让子元素按变换直接绘制。
|
||||
|
||||
下面四组对比同一个 `scale` 或 `rotate` 在 `anc={[0, 0]}` 与 `anc={[0.5, 0.5]}` 下的差异。每组锚点位置的白点就是变换中心:`anc={[0, 0]}` 以左上角为基准,缩放向右下方展开、旋转绕左上角扫过;`anc={[0.5, 0.5]}` 以中心为基准,缩放向四周展开、旋转绕中心转动,两者的视觉位置也不同。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="layerTransformLoader" :width="480" :height="320" />
|
||||
</ClientOnly>
|
||||
|
||||
## 变换沿树传递
|
||||
|
||||
父级的平移、缩放、旋转会复合到子级。父级移动,子级跟着移动;父级放大,子级的坐标与尺寸都按放大后的比例理解;父级旋转,子级的局部坐标轴也跟着旋转。子元素不需要知道父级做了哪些变换,它只按自己的局部坐标描述内容。
|
||||
|
||||
```tsx
|
||||
// 父容器放大 1.5 倍;加 nocache 让子元素按变换直接绘制,避免缓存图被重采样
|
||||
<container loc={[80, 40, 140, 100]} scale={[1.5, 1.5]} nocache>
|
||||
<g-rect loc={[0, 0, 140, 100]} fill fillStyle="#2f6fed" />
|
||||
<text loc={[12, 12]} text="局部坐标 140×100" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
```
|
||||
|
||||
子矩形的 `loc` 仍是 `[0, 0, 140, 100]`,但父级放大后,它在画布上占 210×150。文字也一起放大,包括字形。要反过来「让子元素不跟着放大」,不能靠给子元素写一个 0.667 的 `scale` 去抵消——父级变换已经作用在整棵子树上;正确做法是把需要独立缩放的内容移出这个父级,放到另一个不被缩放的容器里。
|
||||
|
||||
嵌套变换不要用「把每层坐标累加成屏幕坐标」的心算。按树逐层理解:先看元素在父容器里的局部坐标,再看父容器在它自己父级里的位置与变换。需要跨元素比较位置时,用事件里的 `absoluteX` / `absoluteY`(画布坐标),不要自己把若干层的 `x` / `y` 相加。
|
||||
|
||||
下面左侧的父容器放大了 1.5 倍,子元素仍按局部坐标写;右侧是同一棵子树未缩放的参考。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="layerTransformTreeLoader" :width="480" :height="320" />
|
||||
</ClientOnly>
|
||||
|
||||
## 缓存:cache 与 nocache {#缓存与脏更新}
|
||||
|
||||
默认值只作判断起点:`container` 默认缓存;`text`、`image` 与全部 `g-*` 图形默认不缓存。
|
||||
|
||||
- 什么时候开:结构复杂、内容稳定、重复绘制成本高的子树。
|
||||
- 什么时候不开:内容频繁变化、子树很小,或者缓存的维护成本超过收益。
|
||||
|
||||
`cache` 用于打开缓存,`nocache` 用于关闭缓存。两者都在元素创建时决定,`nocache` 优先级更高;不要把它当成运行时反复切换的开关,需要改变缓存策略时应当重新创建元素。
|
||||
|
||||
```tsx
|
||||
// 静态复杂子树:内容不变、绘制成本高,开缓存
|
||||
<container loc={[40, 40, 240, 160]} cache>
|
||||
<g-rect loc={[0, 0, 240, 160]} fillStyle="#1b2433" />
|
||||
<g-rect loc={[16, 16, 208, 40]} fillStyle="#2f6fed" />
|
||||
<g-circle circle={[48, 96, 24]} fillStyle="#f2b84b" />
|
||||
<text loc={[96, 84]} text="静态标题" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
|
||||
// 频繁变化的子树:文字随时会被改写,不开缓存
|
||||
<container loc={[40, 40, 240, 160]} nocache>
|
||||
<text loc={[0, 0]} text={String(clock.value)} fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
```
|
||||
|
||||
## composite
|
||||
|
||||
`composite` 默认 `source-over`。值取 `GlobalCompositeOperation`(见 [MDN 的 composite 文档](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation)),例如 `multiply`、`screen`、`overlay`、`lighter`。它影响当前绘制结果与已绘制内容的混合方式,不改变布局与命中区域。
|
||||
|
||||
```tsx
|
||||
// composite 默认 source-over;这里用 multiply 让上层与已绘制内容混合
|
||||
<g-rect loc={[40, 40, 120, 120]} fillStyle="#2f6fed" />
|
||||
<g-rect loc={[100, 80, 120, 120]} fillStyle="#f2b84b" composite="multiply" />
|
||||
```
|
||||
|
||||
下面三组是相同的重叠图形,分别使用 `source-over`、`multiply` 与 `screen`。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="layerCompositeLoader" :width="480" :height="320" />
|
||||
</ClientOnly>
|
||||
|
||||
## 性能:缓存的代价
|
||||
|
||||
缓存用离屏画布换绘制次数:每帧少画一遍子树,代价是多占一份画布内存,内容变化时还要重画整块缓存。嵌套缓存会叠加内存占用,只在绘制成本确实高的地方开。没有确认有性能问题之前,先不开缓存。
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- `scale` 必须是 `[x, y]` 数组。写成数字不会生效,也不会报错。
|
||||
- `rotate` 的单位是弧度。想转 30 度要写 `Math.PI / 6`,不是 `30`。
|
||||
- 锚点是变换中心:缩放与旋转都绕锚点进行,改锚点会连同变换一起改变视觉位置。
|
||||
- 父级变换会作用在整棵子树上;子元素不能用自己的 `scale` 抵消父级缩放,需要独立缩放时把内容移出该父级。
|
||||
- `cache` / `nocache` 在元素创建时决定,`nocache` 优先级更高;不要把它当成运行时反复切换的开关。
|
||||
- `composite` 影响绘制结果的混合方式,不改变布局与命中区域。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const layerTransformLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/layer-transform.tsx');
|
||||
const layerTransformTreeLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/layer-transform-tree.tsx');
|
||||
const layerCompositeLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/layer-composite.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,169 @@
|
||||
# 文字
|
||||
|
||||
文字元素只画一行。它的宽高由字体测量结果决定,不能自动换行,也没有行高与对齐属性;字号、字重、斜体这些信息由 `Font` 描述,`<text>` 负责把内容画出来。这一篇先讲 `Font`,再讲文字元素怎么用、尺寸与锚点怎么定。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [容器与坐标](./container-and-coordinates.md)
|
||||
- [基础图形](./basic-shapes.md)
|
||||
|
||||
## 字体:Font
|
||||
|
||||
`Font` 是描述字体的值对象,不负责绘制。它只有五项配置:
|
||||
|
||||
| 属性 | 默认值 | 说明 |
|
||||
| ---------- | ----------- | ---------------------------------------------- |
|
||||
| `family` | `'Verdana'` | 字体族名称 |
|
||||
| `size` | `16` | 字号数值 |
|
||||
| `sizeUnit` | `'px'` | 字号单位,通常用 `px` |
|
||||
| `weight` | `400` | 字重,`0`–`1000`,可写数字或 `FontWeight` 枚举 |
|
||||
| `italic` | `false` | 是否斜体 |
|
||||
|
||||
`weight` 除了直接写数字,也可以用 `FontWeight` 枚举。`FontWeight` 从 `@motajs/render` 导入,提供三个常用档位:`FontWeight.Light = 300`、`FontWeight.Normal = 400`、`FontWeight.Bold = 700`。枚举值本身就是数字,两种写法等价。
|
||||
|
||||
构造函数按位置传参:`Font(family, size, sizeUnit, weight, italic)`。省略的项用上面的默认值。例如在 TSX 里直接内联:
|
||||
|
||||
```tsx
|
||||
// 24px 粗体:字重可以用 FontWeight 枚举,也可以直接写数字
|
||||
<text
|
||||
text="标题"
|
||||
font={new Font('Verdana', 24, 'px', FontWeight.Bold)}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
```
|
||||
|
||||
`Font` 与 `FontWeight` 都从 `@motajs/render` 导入。`font` 只接受 `Font` 实例,不接收 CSS 字符串;不写 `font` 时使用默认 `Font`,也就是 Verdana、16px、400、非斜体。
|
||||
|
||||
五项配置在构造后是只读的:要换字号或字重,就再构造一个 `Font`。修改 `Font.defaultFamily` 这类默认值只影响之后创建的实例,已经创建的 `Font` 保留构造时的值。
|
||||
|
||||
需要基于默认值或已有字体做局部修改时,用静态方法:
|
||||
|
||||
- `Font.defaults()` 返回一个默认 `Font`;也可以传配置对象,例如 `Font.defaults({ size: 20 })`,没传的项仍用默认值。
|
||||
- `Font.clone(base, patch)` 复制一份字体,用 `patch` 覆盖部分字段,例如 `Font.clone(font, { weight: FontWeight.Bold })`。
|
||||
- `Font.setDefaults(font)` 一次性写入五项默认值;之后的 `new Font()` 都从它开始。
|
||||
- `addFallback(...fonts)` 给字体加后备字体;主字体不可用时按添加顺序尝试。后备字体也可以再加后备,但不要形成循环。
|
||||
|
||||
`Font` 没有行高、字距、下划线、对齐这些属性;它们不属于字体,文字元素也不提供行高或对齐属性。斜体只有 `italic` 一个开关。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="fontTextLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
同一个字符串换成不同字号、字重与斜体后的效果。
|
||||
|
||||
## 文字元素用法
|
||||
|
||||
`container` 里不能直接写裸文字:空白文字会变成注释节点,非空白文字会创建文字元素并告警。文字内容一律放在 `text` 属性里:
|
||||
|
||||
```tsx
|
||||
// 一行文字:内容只写在 text 属性
|
||||
<text loc={[40, 40]} text="一行文字" fillStyle="#ffffff" />
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="basicTextLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
最基本的一行文字:内容写在 `text`,位置由 `loc` 决定。
|
||||
|
||||
`text` 只支持单行;字符串里的换行符不会产生第二行。需要多行、折行或输入时,用内置的文本组件。
|
||||
|
||||
### 文字属性
|
||||
|
||||
文字元素自己的属性不多,全部列在下面:
|
||||
|
||||
| 属性 | 默认值 | 作用 |
|
||||
| ------------- | ----------- | ------------------------ |
|
||||
| `text` | `''` | 要显示的内容,只支持单行 |
|
||||
| `font` | 默认 `Font` | 字体,必须是 `Font` 实例 |
|
||||
| `fillStyle` | `'#fff'` | 填充颜色 |
|
||||
| `strokeStyle` | 无 | 描边颜色,设置后才描边 |
|
||||
| `strokeWidth` | `1` | 描边宽度,参与尺寸测量 |
|
||||
|
||||
- `fillStyle` 默认白色,且不从父容器继承:父容器设了 `fillStyle`,文字也不会跟着变色。需要统一颜色时,在每个文字上显式写,或把同一个颜色变量传给每个文字。
|
||||
- `strokeStyle` 没有默认值。不写就不描边;写了之后才按这个颜色描边。
|
||||
- `strokeWidth` 默认 `1`,只在有描边时看得出效果。描边宽度会参与尺寸测量,改大之后文字占用的矩形也会变大。
|
||||
- 绘制时先画描边、再画填充,填充会盖住描边靠内的一半,所以描边看起来是沿字形外沿的一条边。
|
||||
- `text` 只支持单行,换行符不会生效。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="styleTextLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
填充、描边颜色与描边宽度的对照。
|
||||
|
||||
### 尺寸、锚点与对齐
|
||||
|
||||
文字没有固定宽度。宽高由字体测量结果决定:内容、字号、字重、斜体、描边宽度一变,尺寸就重新计算。给 `<text>` 写 `width` / `height` 不会裁剪文字,只会暂时改变元素的定位框;下一次测量会把它覆盖回去。需要固定占位或裁剪时,在外面包一个容器。
|
||||
|
||||
默认锚点是 `anc={[0, 0]}`,`loc` 的 x / y 是测量矩形的左上角。锚点用 `anc={[ax, ay]}` 表示,两个值分别是横向、纵向的锚点比例:`anc={[0.5, 0.5]}` 同时把横纵锚点设成中心,`anc={[1, 0]}` 让 x 落在右边缘、y 仍落在顶边,`anc={[1, 1]}` 则是右下角。
|
||||
|
||||
```tsx
|
||||
// 锚点居中:loc 的 x / y 落在文字中心
|
||||
<text loc={[240, 160]} anc={[0.5, 0.5]} text="居中文字" fillStyle="#ffffff" />
|
||||
```
|
||||
|
||||
本篇统一用 `loc` + `anc` 写位置和锚点。`loc` 只写 `[x, y]`,锚点统一用 `anc`。`loc` 的完整形式还能在坐标后写宽高与锚点(`[x, y, width, height, ax, ay]`),但文字尺寸由测量决定,宽高会被覆盖,所以文字页不采用;锚点也不塞进 `loc`。`anchorX` / `anchorY` 是 `anc` 的等价独立属性写法,例如 `anc={[0.5, 0.5]}` 等价于 `anchorX={0.5} anchorY={0.5}`;同一处只选一种写法,不要混用。
|
||||
|
||||
右对齐数值时用 `anc={[1, 0]}`,让文字的右边缘落在 x 上,y 仍是顶边:
|
||||
|
||||
```tsx
|
||||
// 锚点 [1, 0]:x 是文字右边缘,适合数量、金币这类右对齐数字
|
||||
<text loc={[440, 24]} anc={[1, 0]} text="128" fillStyle="#f2b84b" />
|
||||
```
|
||||
|
||||
这段文字无论内容多长,右边缘都固定在 `(440, 24)`,左侧按测量宽度向左延伸。做数值列时,把这一列都设成同一个 x 与 `anc={[1, 0]}`,数字就会沿右边缘对齐。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="anchorTextLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
三行文字分别用不同的锚点,白点标出 `loc` 的位置。
|
||||
|
||||
文字没有 `textAlign`、`textBaseline`、`lineHeight` 这些属性。对齐只能靠锚点;单行文字基线固定,垂直居中按实际字形的上下沿算,不按行高;也不会自动换行。
|
||||
|
||||
## 文字在界面里的常见用法
|
||||
|
||||
- 标题:用较大字号与较粗字重,与正文拉开层级。
|
||||
- 标签:小字号、浅色,做说明,不抢主内容的视觉重心。
|
||||
- 按钮文字:放在按钮底容器里,点击由按钮底统一处理。
|
||||
- 数值显示:用 `anc={[1, 0]}` 右对齐;不要用 `width` 裁剪,长度变化靠锚点对齐。
|
||||
|
||||
## 换行、打字机与输入
|
||||
|
||||
文字元素只画一行,`text` 里的换行符不会生效,长文本也不会按宽度折行。多行说明、按宽度折行与打字机效果不要用多个 `<text>` 硬拼;用[内置组件:文本](../advanced/builtin-text.md)里的 `TextContent`。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const basicTextLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/text-basic.tsx');
|
||||
const fontTextLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/text-font.tsx');
|
||||
const styleTextLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/text-style.tsx');
|
||||
const anchorTextLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/text-anchor.tsx');
|
||||
</script>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- `fillStyle` 默认是白色。浅色背景上直接写字要显式改色。
|
||||
- `strokeWidth` 默认是 `1`,描边会计入尺寸;给 `strokeStyle` 时记得一起考虑宽度,靠边摆放要留出空间。
|
||||
- 给文字设 `width` / `height` 不会截断内容,下一次测量还会覆盖它们。需要固定占位或裁剪时,用外层容器。
|
||||
- 长文本不要用文字元素硬排。它只适合标题、标签、数值这类单行内容。
|
||||
- 本篇统一用 `loc` + `anc`;`anchorX` / `anchorY` 是等价写法,同一处只写一种。
|
||||
@@ -0,0 +1,183 @@
|
||||
# UI 入门
|
||||
|
||||
这篇讲三件事:怎样打开一个 UI、TSX 里的标签和组件怎么写、渲染树是什么样。看完你能在模板里写出文字和矩形。
|
||||
|
||||
## 前置知识
|
||||
|
||||
无——只要掌握基础 TS/JS,并按本指南的阅读路径阅读即可。
|
||||
|
||||
## UI 的打开
|
||||
|
||||
每个 UI 是一个 `GameUI` 对象。在已有 UI 里,可以用 `props.controller` 打开另一个 UI,返回值是这次打开的实例:
|
||||
|
||||
```tsx
|
||||
// 打开 MyPanelUI,空对象是传给它的参数
|
||||
const instance = props.controller.open(MyPanelUI, {});
|
||||
|
||||
// 关闭这次打开的实例
|
||||
props.controller.close(instance);
|
||||
```
|
||||
|
||||
每次 `open` 都会得到独立实例,同一个 `GameUI` 也可以被打开多次。参数、栈顺序与 `alwaysShow` 的细节见 [UI 系统](../advanced/ui-system.md)。
|
||||
|
||||
## TSX 里的标签和组件
|
||||
|
||||
这里的 TSX 不是 DOM 的 JSX。它看起来像 HTML,但会被渲染系统解释成画布元素。记住下面几条就能开始写。
|
||||
|
||||
### 标签
|
||||
|
||||
`container`、`g-rect`、`text` 都是渲染元素,不是 HTML 标签。元素名一律小写,没有子元素时用自闭合写法:
|
||||
|
||||
```tsx
|
||||
<g-rect loc={[0, 0, 120, 80]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
有子元素时成对写,例如 `<container>...</container>`。
|
||||
|
||||
### 属性
|
||||
|
||||
属性写在标签上,名字用 camelCase:
|
||||
|
||||
```tsx
|
||||
<text loc={[24, 24]} text="你好,UI" fillStyle="#e8f0ff" />
|
||||
```
|
||||
|
||||
`loc` 的值是数组,所以写成 `loc={[...]}`;`text` 的值是字符串,直接写引号即可。
|
||||
|
||||
### 表达式与注释
|
||||
|
||||
`{}` 里可以写 JavaScript 表达式,表达式的结果会作为属性值,例如:
|
||||
|
||||
```tsx
|
||||
<text text={'分数:' + score} />
|
||||
```
|
||||
|
||||
`{/* ... */}` 是 TSX 注释,不会显示出来。
|
||||
|
||||
### 嵌套
|
||||
|
||||
标签里可以放子标签,子标签就是它的内容。下面容器里有一个文字和一个矩形:
|
||||
|
||||
```tsx
|
||||
<container loc={[0, 0, 240, 120]}>
|
||||
<text loc={[12, 12]} text="标题" fillStyle="#ffffff" />
|
||||
<g-rect loc={[12, 44, 120, 48]} fillStyle="#2f6fed" />
|
||||
</container>
|
||||
```
|
||||
|
||||
### 组件
|
||||
|
||||
大写开头的名字(如 `MyPanel`)是组件,可以像标签一样使用:
|
||||
|
||||
```tsx
|
||||
<container loc={FULL_LOC}>
|
||||
<MyPanel />
|
||||
</container>
|
||||
```
|
||||
|
||||
`FULL_LOC` 来自标准模板的 import。
|
||||
|
||||
组件本身不额外产生节点,它的根元素挂在使用位置。组件内部写什么,由组件自己决定。
|
||||
|
||||
条件与循环这里先不展开,用到时再看[条件渲染与循环渲染](../advanced/conditional-and-list-rendering.md)。
|
||||
|
||||
## 渲染树的基本模型
|
||||
|
||||
模板里的 UI 都是这样一个容器:
|
||||
|
||||
```tsx
|
||||
<container loc={FULL_LOC}>{/* UI 内容 */}</container>
|
||||
```
|
||||
|
||||
- `container` 是整块 UI 的容器,负责位置和大小;
|
||||
- 里面的 `text`、`g-rect` 等元素负责具体内容;
|
||||
- 元素放在哪个容器里,就跟着哪个容器移动;子元素的位置相对它所在的容器;
|
||||
- `MyPanel` 组件本身不额外产生节点,它的根 `container` 就是整块 UI 的根。
|
||||
|
||||
所以写 UI 时,先把模板里的 `container` 当成画布,再往里面按顺序放元素。
|
||||
|
||||
## 一行文字
|
||||
|
||||
在模板的 `container` 里加一行:
|
||||
|
||||
```tsx
|
||||
<text loc={[24, 24]} text="你好,UI" fillStyle="#e8f0ff" />
|
||||
```
|
||||
|
||||
- `text` 是元素名,表示一行文字;
|
||||
- `loc` 的前两个数 `24, 24` 是文字左上角相对容器的位置;
|
||||
- `text="你好,UI"` 是要显示的文字;
|
||||
- `fillStyle="#e8f0ff"` 是文字颜色。
|
||||
|
||||
坐标以容器左上角为原点:第一个数是向右的距离,第二个数是向下的距离。文字的大小由字号决定,所以 `loc` 只写两个数就够了。
|
||||
|
||||
## 一个矩形
|
||||
|
||||
再加一个矩形:
|
||||
|
||||
```tsx
|
||||
<g-rect loc={[24, 64, 160, 80]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
- `g-rect` 是绘制矩形用的标签;
|
||||
- `loc` 的前两个数 `24, 64` 是矩形左上角的位置,后两个数 `160, 80` 是宽和高;
|
||||
- 矩形默认填充,`fillStyle="#2f6fed"` 是填充颜色。
|
||||
|
||||
和文字不同,矩形必须给出宽高,所以 `loc` 写了四个数。
|
||||
|
||||
## 组合
|
||||
|
||||
两段放进同一个 `container`,就是完整的 UI:
|
||||
|
||||
```tsx
|
||||
import { defineComponent } from 'vue';
|
||||
import { GameUI, SetupComponentOptions } from '@motajs/system';
|
||||
import { DefaultProps } from '@motajs/render-vue';
|
||||
import { IGameUIPropsBase } from '@user/client-base';
|
||||
import { FULL_LOC } from '@/client';
|
||||
|
||||
// 这里填写自定义的 UI 参数
|
||||
interface MyPanelProps extends IGameUIPropsBase, DefaultProps {}
|
||||
|
||||
const myPanelProps = {
|
||||
props: ['controller', 'instance', 'state']
|
||||
} satisfies SetupComponentOptions<MyPanelProps>;
|
||||
|
||||
const MyPanel = defineComponent<MyPanelProps>(props => {
|
||||
return () => (
|
||||
<container loc={FULL_LOC}>
|
||||
<text loc={[24, 24]} text="你好,UI" fillStyle="#e8f0ff" />
|
||||
<g-rect loc={[24, 64, 160, 80]} fillStyle="#2f6fed" />
|
||||
</container>
|
||||
);
|
||||
}, myPanelProps);
|
||||
|
||||
export const MyPanelUI = new GameUI('my-panel', MyPanel);
|
||||
```
|
||||
|
||||
在已有 UI 中使用 `props.controller.open(MyPanelUI, {})` 打开后,效果就是下面这样。同一个容器里的元素按书写先后顺序叠放,后写的画在上面。
|
||||
|
||||
## 运行效果
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="basicsLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const basicsLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/basics-demo.tsx');
|
||||
</script>
|
||||
|
||||
## 后续
|
||||
|
||||
- 摆位置:[容器与坐标](./container-and-coordinates.md)
|
||||
- 画更多图形:[基础图形](./basic-shapes.md)
|
||||
- 写字:[文字](./text.md)
|
||||
- 处理交互:[事件与交互](../advanced/events.md)
|
||||
- 拆组件:[自定义组件](../advanced/custom-components.md)
|
||||
- 接 UI 系统:[UI 系统](../advanced/ui-system.md)
|
||||
@@ -0,0 +1,48 @@
|
||||
# UI 通用模板
|
||||
|
||||
写 UI 时从这段模板开始。
|
||||
|
||||
```tsx
|
||||
import { defineComponent } from 'vue';
|
||||
import { GameUI, SetupComponentOptions } from '@motajs/system';
|
||||
import { DefaultProps } from '@motajs/render-vue';
|
||||
import { IGameUIPropsBase } from '@user/client-base';
|
||||
import { FULL_LOC } from '@/client';
|
||||
|
||||
// 这里填写自定义的 UI 参数
|
||||
interface MyPanelProps extends IGameUIPropsBase, DefaultProps {}
|
||||
|
||||
const myPanelProps = {
|
||||
props: ['controller', 'instance', 'state']
|
||||
} satisfies SetupComponentOptions<MyPanelProps>;
|
||||
|
||||
const MyPanel = defineComponent<MyPanelProps>(props => {
|
||||
return () => (
|
||||
<container loc={FULL_LOC}>{/* 在这里编写自己的 UI 内容 */}</container>
|
||||
);
|
||||
}, myPanelProps);
|
||||
|
||||
export const MyPanelUI = new GameUI('my-panel', MyPanel);
|
||||
```
|
||||
|
||||
## 前置知识
|
||||
|
||||
无——只要掌握基础 TS/JS,并按本指南的阅读路径阅读即可。
|
||||
|
||||
## 模板用法
|
||||
|
||||
1. 复制到 `src/client/ui/` 下新建的 `.tsx` 文件(例如 `my-panel.tsx`)。
|
||||
2. 把 `MyPanel`、`myPanelProps`、`MyPanelUI` 换成自己的名字。
|
||||
3. 在 `<container>` 里写 UI 内容。
|
||||
4. 在 `src/client/ui/index.ts` 中导出 `MyPanelUI`。
|
||||
|
||||
## 后续阅读
|
||||
|
||||
- 先读 [UI 入门](./ui-basics.md)
|
||||
- 摆放元素:[容器与坐标](./container-and-coordinates.md)
|
||||
- 画图形:[基础图形](./basic-shapes.md)
|
||||
- 写字与图片:[文字](./text.md)、[图片与纹理](./image-and-texture.md)
|
||||
- 让 UI 动起来:[响应式](../advanced/reactivity.md)、[事件与交互](../advanced/events.md)
|
||||
- 拆组件:[自定义组件](../advanced/custom-components.md)
|
||||
- 接 UI 系统:[UI 系统](../advanced/ui-system.md)
|
||||
- 完整示例:[示例(一)目标与骨架](../advanced/inventory-example-1-skeleton.md)
|
||||
Reference in new issue
Block a user