# 内置组件:布局 这一篇讲四个负责区域与列表的组件:`Scroll`、`Page`、`List`、`ListPage`。它们都先说要解决什么,再给最小写法,常用参数跟着讲,最后接一个 live。 ## 前置知识 阅读本篇前,建议先读完: - [什么是组件](./what-is-component.md) - [内置组件:基础](./builtin-basic.md) ## Scroll 内容超过视口时,用 `Scroll` 给一块区域加滚动。 `loc` 是视口的位置与大小。总长度按**直接子元素**的包围盒计算,所以每一行都要直接挂在 `Scroll` 下面,不要先用一个大容器把所有内容包起来。 ```tsx import { Scroll } from '@user/client-base'; // setup const rows = Array.from({ length: 12 }, (_, index) => `第 ${index + 1} 行`); // 组件内容 {rows.map((row, index) => ( ))} ; ``` 每一行的高度与顺序由子元素自己的 `loc` 决定。 想横向滚动,加 `hor`,子元素改为从左往右排: ```tsx {rows.map((row, index) => ( ))} ``` 滚动条默认可以手动滚;不想显示滚动条时,加 `noscroll`,滚轮与拖拽滚动仍然可用。 滚到末尾想多留一点空白,用 `padEnd` 给额外长度,默认 `0`。 参数汇总: | 属性 | 作用 | 默认或常用值 | | ---------- | ------------------------ | ------------ | | `loc` | 视口的位置与大小 | 必填 | | `hor` | 改为横向滚动 | `false` | | `noscroll` | 隐藏滚动条 | `false` | | `padEnd` | 滚到末尾时额外填充的长度 | `0` | 直接子元素从上往下排,右侧是滚动条。 ## Page 内容分页用 `Page`。 `pages` 是总页数,`loc` 决定内容与页码条的位置和大小;当前页用 `v-model:page` 绑定。默认 slot 收到当前页索引,从 `0` 开始,按索引渲染对应内容。 ```tsx import { ref } from 'vue'; import { Page } from '@user/client-base'; // setup const page = ref(0); const pages = ['第一页内容', '第二页内容', '第三页内容']; // 组件内容 {(index: number) => ( )} ; ``` 页码条占 `loc` 的底部,内容只能放在剩下的高度里。 只有一页时页码条没有意义,加 `hideIfSingle` 隐藏它: ```tsx {() => } ``` 参数汇总: | 属性 | 作用 | 默认或常用值 | | -------------- | ------------------------ | ------------ | | `pages` | 总页数 | 必填 | | `loc` | 内容与页码条的位置和大小 | 必填 | | `page` | 当前页索引,从 `0` 开始 | `0` | | `font` | 页码字体 | 默认字体 | | `hideIfSingle` | 只有一页时隐藏页码条 | `false` | 页码变化时触发 `pageChange`,同时用 `update:page` 同步 `v-model:page`。 点底部的页码或两侧箭头切换三页内容。 ## List 要显示一列可选择项,用 `List`。 `list` 是 `[id, 文本]` 数组,每项第一项是 id、第二项是列表里显示的文字。`loc` 是列表视口的位置与大小,内容超出时由内部的 `Scroll` 滚动。`selected` / `v-model:selected` 是当前选中项的 id,初值取列表第一项。`List` 自身没有默认 slot,行文字完全来自 `list`。 `lineHeight` 是每行的固定高度,默认 `24`,**不会随字体自动调整**;改了 `font` 的字号后必须同时设置合适的 `lineHeight`,否则行与文字可能重叠。 `font` 控制行文字;`winskin`、`color`、`border`、`alphaRange` 控制选中光标,分别指定光标图片、填充色、边框色与闪烁的不透明度范围。 ```tsx import { ref } from 'vue'; import { List } from '@user/client-base'; // setup const items: [string, string][] = [ ['basic', '基础设置'], ['sound', '声音'], ['key', '按键'] ]; const selected = ref(items[0][0]); // 组件内容 ; ``` 选中某一行时触发 `update` 与 `update:selected`,参数都是该行的 id。 参数汇总: | 属性 | 作用 | 默认或常用值 | | ------------ | ----------------------------------------- | -------------- | | `list` | `[id, 文本][]`,id 用于选中,文本用于显示 | 必填 | | `loc` | 列表视口的位置与大小 | 必填 | | `selected` | 当前选中项的 id,支持 `v-model:selected` | 第一项 id | | `lineHeight` | 每行固定高度,不随字号自动调整 | `24` | | `font` | 行文字字体 | 默认字体 | | `winskin` | 用作选中光标的图片 | 无 | | `color` | 选中光标的填充色 | 默认填充 | | `border` | 选中光标的边框色 | 默认描边 | | `alphaRange` | 选中光标闪烁的不透明度范围 | `[0.25, 0.55]` | 四项列表,选中项高亮,点击任意一行切换。 ## ListPage 左边列表、右边详情,用 `ListPage`。 `list` 是 `[id, 文本]` 数组,每项第一项是 id、第二项是列表里显示的文字;`loc` 是整个组件的位置与大小。当前选中项用 `v-model:selected` 绑定,默认 slot 收到选中的 id,按 id 渲染右侧内容。 ```tsx import { ref } from 'vue'; import { ListPage } from '@user/client-base'; // setup const items: [string, string][] = [ ['basic', '基础设置'], ['sound', '声音'], ['key', '按键'] ]; const detail: Record = { basic: '这里放基础设置的说明。', sound: '这里放音量与音效的说明。', key: '这里放按键改绑的说明。' }; const selected = ref(items[0][0]); // 组件内容 {(key: string) => ( )} ; ``` `selected` 的初值取列表第一项的 id,左侧高亮和右侧内容才会从同一项开始。 左侧列表默认占整宽的 `0.3`;想改比例用 `basis`: ```tsx {(key: string) => ( )} ``` 想把列表放到右侧,加 `right`。需要关闭按钮时加 `close`,按钮位置用 `closeLoc` 给,相对于 `loc`: ```tsx {(key: string) => ( )} ``` `ListPage` 复用 `List` 的全部参数,并额外提供列表比例、排列方向与关闭按钮: | 属性 | 作用 | 默认或常用值 | | ------------ | --------------------------------------------- | -------------- | | `list` | `[id, 文本][]`,id 用于选中,文本用于列表显示 | 必填 | | `loc` | 整个组件的位置与大小 | 必填 | | `selected` | 当前选中项的 id,支持 `v-model:selected` | 第一项 id | | `lineHeight` | 每行固定高度,不随字号自动调整 | `24` | | `font` | 列表与关闭按钮的字体 | 默认字体 | | `winskin` | 用作选中光标的图片 | 无 | | `color` | 选中光标的填充色 | 默认填充 | | `border` | 选中光标的边框色 | 默认描边 | | `alphaRange` | 选中光标闪烁的不透明度范围 | `[0.25, 0.55]` | | `basis` | 列表占整宽的比例 | `0.3` | | `right` | 列表排在右侧 | `false` | | `close` | 显示关闭按钮 | `false` | | `closeLoc` | 关闭按钮位置,相对于 `loc` | 无 | 列表项点击同样触发 `update` 与 `update:selected`;点关闭按钮触发 `close`。默认 slot 收到选中项 id,也可以按 id 写具名 slot,选中哪项就优先用哪项的 slot。 左侧是三项列表,选中项高亮,右侧显示对应说明。