Files
template/docs/render-guide/index.md

91 lines
17 KiB
Markdown
Raw Permalink 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.
# 渲染指南
本指南只讲画屏幕 / 写 UI:怎样用 TSX 画出界面、摆好位置、处理交互、拆成组件,以及 UI 系统与性能的取舍。数据端、存档与录像、插件系统、编辑器等与绘制屏幕关系不紧密的系统不在这里讲,仍见中级 / 高级教程;普通教程只保留主要的渲染逻辑,具体写法集中到本指南。
本指南只收现有 32 篇自定义 UI 文档,内容分为渲染基础、渲染进阶与渲染底层三层;不新增系统文档,也不增设系统页面。
## 三级结构
| 分区 | 定位 | 页面数 |
| -------- | ---------------------------------------------- | ------ |
| 渲染基础 | 模板、元素、坐标、图形、文字与元素属性 | 10 |
| 渲染进阶 | 响应式、事件、动画、组件化、UI 系统/性能与示例 | 18 |
| 渲染底层 | 动画曲线、动画激励、执行器与渐变的内部实现 | 4 |
分层是深度标签,不是领域分类:同一层里可能既有元素,也有组件或示例;读到哪一层取决于你要解决的问题,不必按层读完全部页面。
## 适合谁
- **完全没写过 UI**:从 [UI 通用模板(TSX)](./basics/ui-template.md) 起步,先拿模板跑起来,再用 [UI 入门](./basics/ui-basics.md) 认识标签、组件与渲染树。
- **写过基础界面,想加交互与组件**:从[响应式](./advanced/reactivity.md)接手,把状态、事件与条件渲染接进已有界面。
- **想了解 UI 系统与性能**:从 [UI 系统](./advanced/ui-system.md)读起,再看 [UI 性能](./advanced/ui-performance.md)的日常优化习惯。
- **想让界面元素平滑变化**:从[动画](./advanced/animation.md)入手,用 `transitioned`、`transitionedColor` 与 `cycledTransition` 做数值、颜色和循环渐变。
- **想弄清动画曲线与底层怎么推进**:先读[动画曲线](./internals/animation-curves.md),再看[动画激励](./internals/animation-excitation.md)、[动画执行器](./internals/animation-runner.md)与[渐变执行器](./internals/animation-transition.md)。
## 阅读路径
- **从基础顺读**:[UI 通用模板(TSX)](./basics/ui-template.md) → [UI 入门](./basics/ui-basics.md) → [第一个静态界面](./basics/first-static-ui.md) → [容器与坐标](./basics/container-and-coordinates.md) → [基础图形](./basics/basic-shapes.md) → [文字](./basics/text.md) → [图片与纹理](./basics/image-and-texture.md) → [通用参数](./basics/common-props.md) → [层级、变换与性能](./basics/layer-transform-performance.md)。适合第一次写界面,先把静态部分画稳。
- **从静态到交互**:[响应式](./advanced/reactivity.md) → [事件与交互](./advanced/events.md) → [条件渲染与循环渲染](./advanced/conditional-and-list-rendering.md) → [按键与快捷键](./advanced/hotkey-in-ui.md) → [什么是组件](./advanced/what-is-component.md) → [自定义组件](./advanced/custom-components.md)。适合界面已经画出来、要接数据和操作的时候。
- **做一个完整面板**:[示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md) → [示例(二)道具网格](./advanced/inventory-example-2-grid.md) → [示例(三)详情区](./advanced/inventory-example-3-detail.md) → [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md) → [示例(五)交互与状态](./advanced/inventory-example-5-state.md) → [示例(六)动画、拆分与注册](./advanced/inventory-example-6-animation-and-register.md)。适合把零件装成背包 / 装备面板。
- **改内置 UI 或做性能取舍**:[什么是组件](./advanced/what-is-component.md) → [内置组件:基础](./advanced/builtin-basic.md) → [内置组件:布局](./advanced/builtin-layout.md) → [内置组件:文本](./advanced/builtin-text.md) → [自定义组件](./advanced/custom-components.md) → [UI 系统](./advanced/ui-system.md) → [UI 性能](./advanced/ui-performance.md)。适合替换现成控件或处理缓存与列表开销。
- **让数值与颜色动起来**:[响应式](./advanced/reactivity.md) → [动画](./advanced/animation.md) → 需要更深时读[动画曲线](./internals/animation-curves.md) → [动画激励](./internals/animation-excitation.md) → [动画执行器](./internals/animation-runner.md) / [渐变执行器](./internals/animation-transition.md)。适合给界面加过渡、循环闪烁或颜色变化。
五条路径都建议先读 [UI 通用模板(TSX)](./basics/ui-template.md);模板是后面所有页面的起点。
## 页面目录
### 渲染基础
| 篇目 | 一句话说明 | 前置 |
| --------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [UI 通用模板(TSX)](./basics/ui-template.md) | 写 UI 时从这段模板开始:复制、改名、在 `container` 里写内容 | 无 |
| [UI 入门](./basics/ui-basics.md) | 怎样打开 UI、TSX 的标签与组件怎么写、渲染树是什么样 | 无 |
| [第一个静态界面](./basics/first-static-ui.md) | 从头拼一个静态界面:深色底、标题、图标、图形、分隔线与层级 | [UI 入门](./basics/ui-basics.md) |
| [容器与坐标](./basics/container-and-coordinates.md) | 坐标从哪里算起、`loc` 与锚点怎么配合、嵌套后子元素怎么算 | [第一个静态界面](./basics/first-static-ui.md) |
| [基础图形](./basics/basic-shapes.md) | 八种图形元素的几何参数,以及共用的填充、描边与颜色规则 | [容器与坐标](./basics/container-and-coordinates.md) |
| [文字](./basics/text.md) | `Font` 与文字元素:单行绘制、尺寸测量与锚点对齐 | [容器与坐标](./basics/container-and-coordinates.md)、[基础图形](./basics/basic-shapes.md) |
| [图片与纹理](./basics/image-and-texture.md) | 从贴图管理器按别名或索引取纹理,按 `loc` 显示并处理比例 | [容器与坐标](./basics/container-and-coordinates.md) |
| [自绘元素与自定义容器](./basics/custom-and-container-custom.md) | 用 Canvas 2D 自绘内容,或接管子元素的绘制与事件传递 | [容器与坐标](./basics/container-and-coordinates.md)、[基础图形](./basics/basic-shapes.md) |
| [通用参数](./basics/common-props.md) | 大多数元素都能写的一组属性,以及它们在什么条件下有意义 | [容器与坐标](./basics/container-and-coordinates.md)、[基础图形](./basics/basic-shapes.md) |
| [层级、变换与性能](./basics/layer-transform-performance.md) | 渲染树的层级与绘制顺序、缩放旋转,以及缓存的取舍 | [容器与坐标](./basics/container-and-coordinates.md)、[通用参数](./basics/common-props.md) |
### 渲染进阶
| 篇目 | 一句话说明 | 前置 |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [响应式](./advanced/reactivity.md) | 数据变化如何自动推到画布元素,以及渲染函数读到什么才算依赖 | [UI 入门](./basics/ui-basics.md)、[第一个静态界面](./basics/first-static-ui.md) |
| [事件与交互](./advanced/events.md) | 点击、按下、抬起、移动、悬停与滚轮的捕获与冒泡 | [容器与坐标](./basics/container-and-coordinates.md)、[响应式](./advanced/reactivity.md) |
| [条件渲染与循环渲染](./advanced/conditional-and-list-rendering.md) | 用 `hidden` 或三元做条件、用 `.map()` 做循环 | [响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) |
| [按键与快捷键](./advanced/hotkey-in-ui.md) | 按键指令、分组、作用域,以及组件里怎么接 | [响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) |
| [什么是组件](./advanced/what-is-component.md) | 组件最基本的形态、props 的传法,以及组件与 `GameUI` 的关系 | [UI 入门](./basics/ui-basics.md) |
| [内置组件:基础](./advanced/builtin-basic.md) | `Input`、`Icons`、`Arrow`、`Selection`、`Progress`、`Background` 与 `Slider` | [什么是组件](./advanced/what-is-component.md) |
| [内置组件:布局](./advanced/builtin-layout.md) | `Scroll`、`Page`、`List` 与 `ListPage` 的区域与列表用法 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) |
| [内置组件:文本](./advanced/builtin-text.md) | `TextContent` 的折行与打字机、`ScrollText` 的自动滚动 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) |
| [自定义组件](./advanced/custom-components.md) | 怎么接收参数、发事件、留出内容位置与透传属性 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) |
| [动画](./advanced/animation.md) | 用曲线驱动 `transitioned`、`transitionedColor` 与 `cycledTransition`,让数值、颜色平滑变化或循环 | [响应式](./advanced/reactivity.md)、[UI 入门](./basics/ui-basics.md) |
| [UI 系统](./advanced/ui-system.md) | 控制器、实例与栈:打开关闭、隐藏显示与显示策略 | [事件与交互](./advanced/events.md) |
| [UI 性能](./advanced/ui-performance.md) | 一组日常习惯,用来减少不必要的绘制与内存占用 | [层级、变换与性能](./basics/layer-transform-performance.md)、[UI 系统](./advanced/ui-system.md) |
| [示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md) | 定下背包 / 装备面板的目标、组件拆分与骨架 | [第一个静态界面](./basics/first-static-ui.md)、[容器与坐标](./basics/container-and-coordinates.md) |
| [示例(二)道具网格](./advanced/inventory-example-2-grid.md) | 把道具数据、`ItemCell` 与 `ItemGrid` 填进左侧,让网格能显示与选中 | [示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md)、[基础图形](./basics/basic-shapes.md) |
| [示例(三)详情区](./advanced/inventory-example-3-detail.md) | 用 `ItemDetail` 填右侧:名称、数量、描述与空选中提示 | [示例(二)道具网格](./advanced/inventory-example-2-grid.md)、[文字](./basics/text.md)、[通用参数](./basics/common-props.md) |
| [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md) | 把普通网格换成 `Scroll`,并说明渲染树、事件与数据流的变化 | [示例(三)详情区](./advanced/inventory-example-3-detail.md)、[内置组件:布局](./advanced/builtin-layout.md) |
| [示例(五)交互与状态](./advanced/inventory-example-5-state.md) | 加 `ActionBar`:装备、使用、关闭,并把状态收口到面板 | [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md)、[响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) |
| [示例(六)动画、拆分与注册](./advanced/inventory-example-6-animation-and-register.md) | 让选中态与提示动起来,把代码落回文件并注册成 `GameUI` | [示例(五)交互与状态](./advanced/inventory-example-5-state.md)、[自定义组件](./advanced/custom-components.md)、[UI 系统](./advanced/ui-system.md) |
### 渲染底层
| 篇目 | 一句话说明 | 前置 |
| ------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [动画曲线](./internals/animation-curves.md) | `ExcitationCurve`、`CurveMode`、内置曲线与曲线计算函数 | [动画](./advanced/animation.md)、[响应式](./advanced/reactivity.md) |
| [动画激励](./internals/animation-excitation.md) | 激励源怎样驱动受激励对象,以及变速器与分频器如何接入 | [动画](./advanced/animation.md)、[响应式](./advanced/reactivity.md) |
| [动画执行器](./internals/animation-runner.md) | `Animater` 把多个对象的多个步骤组织成计划组并按时执行 | [动画激励](./internals/animation-excitation.md)、[动画](./advanced/animation.md)、[响应式](./advanced/reactivity.md) |
| [渐变执行器](./internals/animation-transition.md) | `Transition` 让单个数值平滑靠近目标值,处理曲线与结尾参考 | [动画激励](./internals/animation-excitation.md)、[动画](./advanced/animation.md)、[响应式](./advanced/reactivity.md) |
## 边界与注意
- 本指南只讲绘制屏幕与编写 UI;数据端、存档与录像、插件系统、编辑器等内容见中级 / 高级教程,这里不重复。
- 元素坐标相对父容器,不是屏幕绝对坐标;需要跨元素比较位置时,用事件里的画布坐标。
- 示例里的预览是文档站内固定尺寸的演示,与真实画布的尺寸、缩放和素材都不同;实际效果以接入后的画布为准。
- 文字元素只画一行,不自动换行;长文本用内置的文本组件。
- 缓存的默认值与开关只是当前实现的取舍,超出容器的绘制不要依赖缓存行为。