Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Grid 栅格
把一行分成 24 列,用 NsRow 包一行、NsCol 占其中几列,快速搭出按比例分栏、随屏幕宽度变化的布局。
引入
import { NsRow, NsCol } from '@ns/ui'
基础用法
NsCol 的 span 是这一列占的列数,一行一共 24 列。一行里各列的 span 加起来超过 24 时,多出来的列换到下一行。
<script setup lang="ts">
import { NsRow, NsCol, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill>
<NsRow>
<NsCol :span="24"><div class="cell">24</div></NsCol>
</NsRow>
<NsRow>
<NsCol :span="12"><div class="cell">12</div></NsCol>
<NsCol :span="12"><div class="cell cell--light">12</div></NsCol>
</NsRow>
<NsRow>
<NsCol :span="8"><div class="cell">8</div></NsCol>
<NsCol :span="8"><div class="cell cell--light">8</div></NsCol>
<NsCol :span="8"><div class="cell">8</div></NsCol>
</NsRow>
</NsSpace>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
.cell--light {
background: var(--ns-fill-color-light);
}
</style>
.cell 只是给格子加底色、方便看出每一列的位置,和栅格本身无关,后面每个示例都带着同样的样式。
span 可以是 0~24 之间的任意整数,同一行里的列可以宽窄不一:
<template>
<NsSpace direction="vertical" fill>
<NsRow>
<NsCol v-for="i in 4" :key="i" :span="6">
<div :class="['cell', { 'cell--light': i % 2 === 0 }]">6</div>
</NsCol>
</NsRow>
<NsRow>
<NsCol v-for="i in 6" :key="i" :span="4">
<div :class="['cell', { 'cell--light': i % 2 === 0 }]">4</div>
</NsCol>
</NsRow>
<NsRow>
<NsCol v-for="i in 8" :key="i" :span="3">
<div :class="['cell', { 'cell--light': i % 2 === 0 }]">3</div>
</NsCol>
</NsRow>
<NsRow>
<NsCol :span="16"><div class="cell">16</div></NsCol>
<NsCol :span="8"><div class="cell cell--light">8</div></NsCol>
</NsRow>
<NsRow>
<NsCol :span="4"><div class="cell">4</div></NsCol>
<NsCol :span="16"><div class="cell cell--light">16</div></NsCol>
<NsCol :span="4"><div class="cell">4</div></NsCol>
</NsRow>
<NsRow>
<NsCol :span="16"><div class="cell">16</div></NsCol>
<NsCol :span="16"><div class="cell cell--light">16(加起来超过 24,换到下一行)</div></NsCol>
</NsRow>
</NsSpace>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
.cell--light {
background: var(--ns-fill-color-light);
}
</style>
列间距
NsRow 的 gutter 设置列与列之间的间距,单位 px。传数组 [水平, 垂直] 时还会加上行与行之间的间距,适合一行放不下、换行显示的场景。
<template>
<NsSpace direction="vertical" fill>
<NsRow :gutter="16">
<NsCol :span="6"><div class="cell">6</div></NsCol>
<NsCol :span="6"><div class="cell">6</div></NsCol>
<NsCol :span="6"><div class="cell">6</div></NsCol>
<NsCol :span="6"><div class="cell">6</div></NsCol>
</NsRow>
<NsRow :gutter="[16, 16]">
<NsCol v-for="i in 8" :key="i" :span="6"
><div class="cell">{{ i }}</div></NsCol
>
</NsRow>
</NsSpace>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
</style>
间距是这样实现的:每个 NsCol 左右各加 gutter / 2 的内边距,NsRow 左右各用 -gutter / 2 的外边距抵消掉,所以第一列和最后一列的内容仍然和行的边缘对齐。列的背景要画在 NsCol 里面的元素上,画在 NsCol 上会把间距也涂上颜色。
不同的间距放在一起对比:
<template>
<NsSpace direction="vertical" fill>
<div v-for="gutter in [0, 8, 16, 32]" :key="gutter">
<div class="label">gutter {{ gutter }}px</div>
<NsRow :gutter="gutter">
<NsCol v-for="i in 4" :key="i" :span="6"><div class="cell">6</div></NsCol>
</NsRow>
</div>
</NsSpace>
</template>
<style scoped>
.label {
margin-bottom: 4px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
</style>
运行中修改 gutter,各列的间距跟着变。拖动滑块分别调整水平和垂直间距:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCol, NsRow, NsSlider, NsSpace } from '@ns/ui'
const horizontal = ref(16)
const vertical = ref(16)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap size="large">
<span>水平 {{ horizontal }}px</span>
<NsSlider v-model="horizontal" :min="0" :max="48" :step="8" show-stops style="width: 200px" />
<span>垂直 {{ vertical }}px</span>
<NsSlider v-model="vertical" :min="0" :max="48" :step="8" show-stops style="width: 200px" />
</NsSpace>
<NsRow :gutter="[horizontal, vertical]">
<NsCol v-for="i in 8" :key="i" :span="6">
<div class="cell">{{ i }}</div>
</NsCol>
</NsRow>
</NsSpace>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
</style>
列偏移
offset 让列向右空出指定的列数,偏移的列数和 span 一样是 0~24。
<template>
<NsSpace direction="vertical" fill>
<NsRow>
<NsCol :span="6"><div class="cell">6</div></NsCol>
<NsCol :span="6" :offset="6"><div class="cell">6,偏移 6</div></NsCol>
</NsRow>
<NsRow>
<NsCol :span="12" :offset="6"><div class="cell">12,偏移 6(居中)</div></NsCol>
</NsRow>
<NsRow v-for="offset in [0, 4, 8, 12, 16, 20]" :key="offset">
<NsCol :span="4" :offset="offset">
<div class="cell cell--light">偏移 {{ offset }}</div>
</NsCol>
</NsRow>
<NsRow>
<NsCol :span="6" :offset="2"><div class="cell">6,偏移 2</div></NsCol>
<NsCol :span="6" :offset="2"><div class="cell">6,偏移 2</div></NsCol>
<NsCol :span="6" :offset="2"><div class="cell">6,偏移 2</div></NsCol>
</NsRow>
</NsSpace>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
.cell--light {
background: var(--ns-fill-color-light);
}
</style>
调换顺序
push 把列向右推、pull 把列向左拉,单位是列数。只移动显示位置,不影响其他列的位置,常用来在不改模板顺序的前提下调换两列。
<template>
<NsRow>
<NsCol :span="18" :push="6"><div class="cell">在模板里排第一,显示在右边</div></NsCol>
<NsCol :span="6" :pull="18"
><div class="cell cell--light">在模板里排第二,显示在左边</div></NsCol
>
</NsRow>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
.cell--light {
background: var(--ns-fill-color-light);
}
</style>
水平排列
NsRow 的 justify 控制一行里各列的水平分布,可选 start(默认)、end、center、space-around、space-between、space-evenly。只有各列加起来不满 24 列、一行还有空余时才看得出区别。
<script setup lang="ts">
import { NsCol, NsRow, NsSpace } from '@ns/ui'
import type { RowJustify } from '@ns/ui'
const justifies: RowJustify[] = [
'start',
'end',
'center',
'space-around',
'space-between',
'space-evenly'
]
</script>
<template>
<NsSpace direction="vertical" fill>
<div v-for="item in justifies" :key="item">
<div class="label">{{ item }}</div>
<NsRow :justify="item" class="row">
<NsCol :span="4"><div class="cell">4</div></NsCol>
<NsCol :span="4"><div class="cell cell--light">4</div></NsCol>
<NsCol :span="4"><div class="cell">4</div></NsCol>
</NsRow>
</div>
</NsSpace>
</template>
<style scoped>
.label {
margin-bottom: 4px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.row {
outline: 1px dashed var(--ns-border-color);
}
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
.cell--light {
background: var(--ns-fill-color-dark);
}
</style>
垂直对齐
NsRow 的 align 控制各列在垂直方向上的对齐,可选 top(默认)、middle、bottom、stretch。stretch 让每一列都拉到这一行最高的那一列的高度。
<template>
<NsRow align="middle" :gutter="16">
<NsCol :span="8"><div class="cell" style="height: 80px">高 80px</div></NsCol>
<NsCol :span="8"><div class="cell">垂直居中</div></NsCol>
<NsCol :span="8"><div class="cell" style="height: 50px">高 50px</div></NsCol>
</NsRow>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
</style>
四个值放在一起对比。每行左边一列高 80px,中间一列没设高度(拉伸时高度跟着列变),右边一列高 50px:
<script setup lang="ts">
import { NsCol, NsRow, NsSpace } from '@ns/ui'
import type { RowAlign } from '@ns/ui'
const aligns: RowAlign[] = ['top', 'middle', 'bottom', 'stretch']
</script>
<template>
<NsSpace direction="vertical" fill>
<div v-for="item in aligns" :key="item">
<div class="label">{{ item }}</div>
<NsRow :align="item" :gutter="16">
<NsCol :span="8"><div class="cell" style="height: 80px">高 80px</div></NsCol>
<NsCol :span="8"><div class="cell cell--fit">不设高度</div></NsCol>
<NsCol :span="8"><div class="cell" style="height: 50px">高 50px</div></NsCol>
</NsRow>
</div>
</NsSpace>
</template>
<style scoped>
.label {
margin-bottom: 4px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.cell {
display: flex;
align-items: center;
justify-content: center;
min-height: 36px;
box-sizing: border-box;
background: var(--ns-fill-color);
}
/* 列被拉伸时,高度 100% 才能跟着列变高 */
.cell--fit {
height: 100%;
background: var(--ns-fill-color-dark);
}
</style>
不换行
NsRow 默认允许换行。wrap 为 false 时所有列排在同一行,列不会被压窄,span 加起来超过 24 时会超出这一行。
<template>
<NsRow :wrap="false">
<NsCol :span="12"><div class="cell">12</div></NsCol>
<NsCol :span="12"><div class="cell cell--light">12</div></NsCol>
<NsCol :span="12"><div class="cell">12</div></NsCol>
</NsRow>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
.cell--light {
background: var(--ns-fill-color-light);
}
</style>
同样三列 12,默认换行和不换行对比(下面给行外面套了横向滚动的容器,看得到超出的部分):
<template>
<NsSpace direction="vertical" fill>
<div>
<div class="label">wrap(默认):第三列换到下一行</div>
<NsRow>
<NsCol v-for="i in 3" :key="i" :span="12">
<div :class="['cell', { 'cell--light': i % 2 === 0 }]">12</div>
</NsCol>
</NsRow>
</div>
<div>
<div class="label">:wrap="false":第三列超出这一行</div>
<div style="overflow-x: auto">
<NsRow :wrap="false">
<NsCol v-for="i in 3" :key="i" :span="12">
<div :class="['cell', { 'cell--light': i % 2 === 0 }]">12</div>
</NsCol>
</NsRow>
</div>
</div>
</NsSpace>
</template>
<style scoped>
.label {
margin-bottom: 4px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
.cell--light {
background: var(--ns-fill-color-light);
}
</style>
宽度随内容和隐藏列
span 不填时,列的宽度等于里面内容的宽度。span 为 0 时这一列不显示。
<template>
<NsRow :gutter="8">
<NsCol><div class="cell" style="padding: 0 12px">宽度随内容</div></NsCol>
<NsCol :span="0"><div class="cell">不显示</div></NsCol>
<NsCol :span="8"><div class="cell cell--light">8</div></NsCol>
</NsRow>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
.cell--light {
background: var(--ns-fill-color-light);
}
</style>
响应式布局
xs、sm、md、lg、xl 按屏幕宽度设置列宽,值可以是数字(等同于 span),也可以是对象 { span, offset, push, pull }。各断点的生效范围:
| 断点 | 生效范围 |
|---|---|
| xs | <576px,只在这个范围内 |
| sm | ≥576px 起生效,向上继承 |
| md | ≥640px 起生效,向上继承 |
| lg | ≥768px 起生效,向上继承 |
| xl | ≥1024px 起生效,向上继承 |
“向上继承”的意思是:断点设置的值在比它更宽的屏幕上一直有效,直到被更大的断点覆盖。span、offset 等不带断点的属性在所有宽度下都有效,被断点的值覆盖。
下面这个例子:小于 640px 时每列占满一行;640px 起两列一行;1024px 起四列一行。
<template>
<NsRow :gutter="[16, 16]">
<NsCol v-for="i in 4" :key="i" :span="24" :md="12" :xl="6">
<div class="cell">{{ i }}</div>
</NsCol>
</NsRow>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
</style>
五个断点都写上时,每个宽度范围各有自己的列宽。下面显示当前窗口宽度和生效的断点,拖动浏览器窗口改变宽度看效果:
<script setup lang="ts">
import { computed, onBeforeUnmount, onMounted, ref } from 'vue'
import { NsCol, NsRow, NsSpace } from '@ns/ui'
const width = ref(0)
const updateWidth = () => {
width.value = window.innerWidth
}
onMounted(() => {
updateWidth()
window.addEventListener('resize', updateWidth)
})
onBeforeUnmount(() => window.removeEventListener('resize', updateWidth))
const current = computed(() => {
if (width.value < 576) return 'xs(每列 24,一行 1 列)'
if (width.value < 640) return 'sm(每列 12,一行 2 列)'
if (width.value < 768) return 'md(每列 8,一行 3 列)'
if (width.value < 1024) return 'lg(每列 6,一行 4 列)'
return 'xl(每列 4,一行 6 列)'
})
</script>
<template>
<NsSpace direction="vertical" fill>
<span>窗口宽度 {{ width }}px,生效的断点是 {{ current }}</span>
<NsRow :gutter="[16, 16]">
<NsCol v-for="i in 6" :key="i" :xs="24" :sm="12" :md="8" :lg="6" :xl="4">
<div :class="['cell', { 'cell--light': i % 2 === 0 }]">{{ i }}</div>
</NsCol>
</NsRow>
</NsSpace>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
.cell--light {
background: var(--ns-fill-color-light);
}
</style>
用对象形式时可以在某个断点同时改偏移。下面这一列在 768px 以下占满一行,768px 起占 12 列并居中:
<template>
<NsRow>
<NsCol :span="24" :lg="{ span: 12, offset: 6 }">
<div class="cell">响应式偏移</div>
</NsCol>
</NsRow>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
</style>
对象里的 push、pull 可以只在宽屏上调换顺序。下面在 768px 以下主内容在上、侧栏在下;768px 起侧栏挪到左边:
<template>
<NsRow :gutter="[16, 16]">
<NsCol :span="24" :lg="{ span: 16, push: 8 }">
<div class="cell">主内容(模板里排第一)</div>
</NsCol>
<NsCol :span="24" :lg="{ span: 8, pull: 16 }">
<div class="cell cell--light">侧栏(模板里排第二)</div>
</NsCol>
</NsRow>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
.cell--light {
background: var(--ns-fill-color-light);
}
</style>
某个断点设成 0 可以在这个宽度及以上隐藏这一列,更大的断点设成非零值又会显示出来:
<template>
<NsRow :gutter="16">
<NsCol :span="6" :md="0" :xl="6"><div class="cell">640~1023px 隐藏</div></NsCol>
<NsCol :span="18" :md="24" :xl="18"><div class="cell cell--light">主内容</div></NsCol>
</NsRow>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
.cell--light {
background: var(--ns-fill-color-light);
}
</style>
自定义标签
NsRow、NsCol 默认渲染成 div,tag 可以换成别的元素,例如列表结构用 ul 和 li。
<template>
<NsRow tag="ul" :gutter="16" style="padding: 0; list-style: none">
<NsCol v-for="i in 3" :key="i" tag="li" :span="8"
><div class="cell">{{ i }}</div></NsCol
>
</NsRow>
</template>
<style scoped>
.cell {
height: 36px;
line-height: 36px;
text-align: center;
background: var(--ns-fill-color);
}
</style>
NsRow Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| gutter | number | [number, number] | 0 | 列间距,单位 px。数组是 [水平, 垂直],垂直间距是行与行之间的距离 |
| justify | 'start' | 'end' | 'center' | 'space-around' | 'space-between' | 'space-evenly' | 'start' | 各列的水平分布 |
| align | 'top' | 'middle' | 'bottom' | 'stretch' | 'top' | 各列的垂直对齐 |
| wrap | boolean | true | 放不下时是否换行 |
| tag | string | 'div' | 渲染成的元素 |
NsCol Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| span | number | - | 占的列数,0~24。不填时宽度等于内容宽度;为 0 时隐藏 |
| offset | number | - | 左侧空出的列数 |
| push | number | - | 向右移动的列数,不影响其他列的位置 |
| pull | number | - | 向左移动的列数,不影响其他列的位置 |
| xs | number | ColResponsiveProps | - | 屏幕宽度 <576px 时的设置,只在这个范围内生效。数字等同于 span |
| sm | number | ColResponsiveProps | - | ≥576px 起生效,向上继承。数字等同于 span |
| md | number | ColResponsiveProps | - | ≥640px 起生效,向上继承。数字等同于 span |
| lg | number | ColResponsiveProps | - | ≥768px 起生效,向上继承。数字等同于 span |
| xl | number | ColResponsiveProps | - | ≥1024px 起生效,向上继承。数字等同于 span |
| tag | string | 'div' | 渲染成的元素 |
NsRow Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsCol |
NsCol Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 列的内容 |
类型
import type { RowProps, ColProps, ColResponsiveProps, RowJustify, RowAlign } from '@ns/ui'
type RowJustify = 'start' | 'end' | 'center' | 'space-around' | 'space-between' | 'space-evenly'
type RowAlign = 'top' | 'middle' | 'bottom' | 'stretch'
interface RowProps {
gutter?: number | [number, number]
justify?: RowJustify
align?: RowAlign
wrap?: boolean
tag?: string
}
/** 断点属性写成对象时的格式 */
interface ColResponsiveProps {
span?: number
offset?: number
push?: number
pull?: number
}
interface ColProps extends ColResponsiveProps {
xs?: number | ColResponsiveProps
sm?: number | ColResponsiveProps
md?: number | ColResponsiveProps
lg?: number | ColResponsiveProps
xl?: number | ColResponsiveProps
tag?: string
}
另外还导出了 RowContext 和注入用的 ROW_INJECTION_KEY,NsCol 通过它拿到所在行的 gutter,一般用不到。
注意事项
- 断点阈值是 576、640、768、1024px,和主题变量
--ns-breakpoint-sm/md/lg/xl(640、768、1024、1280px)不是同一套,按这里写的阈值为准。 xs只在 576px 以下生效,不会向上继承。要在所有宽度下都有效的值写在span上,例如:span="24" :md="12",不要写成:xs="24" :md="12"(这样 576~639px 之间没有设置,列宽会变成内容宽度)。- 只写了断点、没写
span时,在最小的那个断点以下列宽等于内容宽度。 - 不带断点的
push、pull同时写在了元素的行内样式上,断点里的push、pull覆盖不了它。推拉要随屏幕宽度变化时,不要写不带断点的push、pull,改成在各断点里分别写(例如xs和sm各写一份,覆盖所有宽度)。 gutter由NsRow传给它下面的NsCol,运行中修改gutter,各列的间距会跟着变。NsCol不放在NsRow里时没有间距。NsRow两侧各有-gutter / 2的外边距,会比父元素宽出一个gutter。父元素是滚动容器或者页面最外层时可能出现横向滚动条,可以给父元素加上gutter / 2的左右内边距。wrap为false时各列仍是span / 24的宽度,不会被压缩,放不下的部分超出这一行。