ylb-design

v0.1.3

Published

a month ago

Vue 3 layout component library

0High
0Medium
0Low

ylb-design

一个基于 Vue 3 的轻量布局组件库，除页面容器 YContainer、水平/垂直布局 YHLayout / YHItem、YVLayout / YVItem 以外，还提供模块面板 YPanel 全家桶、查询面板 YQueryPanel 与 YQueryItem。

安装

npm install ylb-design

全量注册

import {createApp} from 'vue'
import App from './App.vue'
import YlbDesign from 'ylb-design'

createApp(App).use(YlbDesign).mount('#app')

按需引入

import {
    YContainer,
    YContainerHeader,
    YContainerBody,
    YContainerFooter,
    YHLayout,
    YHItem,
    YVLayout,
    YVItem,
    YPanel,
    YPanelHeader,
    YPanelToolbar,
    YPanelBody,
    YPanelFooter,
    YPanelItem,
    YPanelItemLeft,
    YPanelItemCenter,
    YPanelItemRight,
    YQueryPanel,
    YQueryItem,
} from 'ylb-design'

也可以按子路径单独引入：

import {YContainer} from 'ylb-design/y-container'
import {YContainerHeader} from 'ylb-design/y-container-header'
import {YContainerBody} from 'ylb-design/y-container-body'
import {YContainerFooter} from 'ylb-design/y-container-footer'
import {YHLayout} from 'ylb-design/yh-layout'
import {YHItem} from 'ylb-design/yh-item'
import {YVLayout} from 'ylb-design/yv-layout'
import {YVItem} from 'ylb-design/yv-item'
import {YPanel} from 'ylb-design/y-panel'
import {YPanelHeader} from 'ylb-design/y-panel-header'
import {YPanelToolbar} from 'ylb-design/y-panel-toolbar'
import {YPanelBody} from 'ylb-design/y-panel-body'
import {YPanelFooter} from 'ylb-design/y-panel-footer'
import {YPanelItem} from 'ylb-design/y-panel-item'
import {YPanelItemLeft} from 'ylb-design/y-panel-item-left'
import {YPanelItemCenter} from 'ylb-design/y-panel-item-center'
import {YPanelItemRight} from 'ylb-design/y-panel-item-right'
import {YQueryPanel} from 'ylb-design/y-query-panel'
import {YQueryItem} from 'ylb-design/y-query-item'

示例

页面容器

YContainer 适合作为模块页面的根容器使用。YContainerHeader 和 YContainerFooter 是可选子组件。已使用 YContainerHeader 时，不再渲染由 title / showTitle / subTitle / showBack 生成的内置标题条（标题内容由 YContainerHeader 自行负责）。

组件内部的默认内容安全区使用 CSS 变量 --ylb-spacing，默认值为 16px。你可以在外层容器上覆盖它来自定义 YContainer、 YHLayout、YVLayout 的内边距。组件样式使用 ylb-* 命名空间类名，并以内置 CSS 文件驱动，内部结构节点做了更强的局部 reset，降低与其他 UI 库混用时的样式冲突概率。


<template>
  <YContainer height="300">
    <YContainerHeader>头部(固定于页面顶部)</YContainerHeader>
    <YContainerBody>
      <div class="body">主内容区</div>
    </YContainerBody>
    <YContainerFooter>尾部(固定于页面底部)</YContainerFooter>
  </YContainer>
</template>

<style scoped>
  .ylb-container {
    border: 1px solid #ebebeb;
  }

  .body {
    height: 300px;
    background: #ffffff;
  }
</style>

当未显式使用 YContainerBody 时，YContainer 会把除 YContainerHeader 和 YContainerFooter 外的元素自动视为主内容区内容并包裹到 YContainerBody 中：


<template>
  <YContainer title="页面标题" height="200">
    <div>内容1</div>
    <div>内容2</div>
    <YContainerFooter>尾部(固定于页面底部)</YContainerFooter>
  </YContainer>
</template>

当显式使用 YContainerBody 时，只有 YContainerHeader、YContainerBody 和 YContainerFooter 会被渲染，这三个标签外的其他元素会被忽略：


<template>
  <YContainer height="200">
    <div>不会渲染...</div>
    <YContainerHeader>头部(固定于页面顶部)</YContainerHeader>
    <YContainerBody>主内容区</YContainerBody>
    <YContainerFooter>尾部(固定于页面底部)</YContainerFooter>
  </YContainer>
</template>

水平布局


<template>
  <div class="layout-box">
    <YHLayout :auto="false">
      <div>不会渲染</div>
      <YHItem width="200px">
        <div class="block block-a">内容一</div>
      </YHItem>
      <YHItem flex="1">
        <div class="block block-b">内容二</div>
      </YHItem>
      <YHItem flex="2">
        <div class="block block-c">内容三</div>
      </YHItem>
    </YHLayout>
  </div>
</template>

<style scoped>
  .layout-box {
    height: 220px;
  }

  .block {
    height: 100%;
  }

  .block-a {
    background: #409eff;
  }

  .block-b {
    background: #7dbcea;
  }

  .block-c {
    background: #3ba0e9;
  }
</style>

垂直布局


<template>
  <div class="layout-box">
    <YVLayout :auto="false">
      <div>不会渲染</div>
      <YVItem height="100px">
        <div class="block block-a">内容一</div>
      </YVItem>
      <YVItem flex="1">
        <div class="block block-b">内容二</div>
      </YVItem>
      <YVItem flex="2">
        <div class="block block-c">内容三</div>
      </YVItem>
    </YVLayout>
  </div>
</template>

<style scoped>
  .layout-box {
    height: 320px;
  }

  .block {
    height: 100%;
  }

  .block-a {
    background: #409eff;
  }

  .block-b {
    background: #7dbcea;
  }

  .block-c {
    background: #3ba0e9;
  }
</style>

YPanel

YPanel 仅渲染 YPanelHeader / YPanelToolbar / YPanelBody / YPanelFooter / YPanelItem 子元素。

当未显式使用 YPanelHeader 且设置了 title 或 colorCode 时，会自动生成标题栏；此时可通过 #action 插槽在标题栏右侧放置操作按钮。

<template>
  <YPanel color-code="003" title="订单信息">
    <template #action>
      <button>新增</button>
      <button>导出</button>
    </template>
    <YPanelBody>主内容区</YPanelBody>
  </YPanel>
</template>

当显式使用 YPanelHeader 时，#action 插槽不会渲染，头部内容请在 YPanelHeader 内自行布局。

API

YContainer

| 参数 | 说明 | 类型 | 默认值 | |--------------|----------------------------------------|--------------------|----------| | title | 页面标题 | string | - | | showTitle | 是否显示标题区 | boolean | false | | noPadding | 自动生成的主内容区是否去除内边距 | boolean | false | | height | 容器高度，支持 px / % / vh，纯数字按 px 处理 | string \| number | '100%' | | icon | 标题图标类名 | string | - | | colorCode | 标题图标颜色 | string | - | | subTitle | 副标题 | string | - | | fixed | 固定头尾，支持 top、bottom、top bottom | string | - | | showBack | 是否显示返回按钮 | boolean | false | | backHandle | 返回按钮回调 | () => void | - |

默认 height 为 '100%' 时，根节点在样式表中还带有 flex: 1 1 0%：父级是列向 flex 时会参与分配剩余高度（常见后台主内容区）；父级是普通块级时 flex 不生效，仍靠 height: 100%。传入非 100% 的高度（如 300 / 50%）时会自动加上 flex: 0 0 auto，避免在 flex 父级下被拉高。

YContainerHeader

顶栏与 YContainer 内置 title 区共用同一套样式（flex 顶栏、12px 纵向与 --ylb-container-padding 横向、底部分割线）。

| 参数 | 说明 | 类型 | 默认值 | |-------------|---------|-----------|---------| | noPadding | 是否去除内边距 | boolean | false |

YContainerBody

| 参数 | 说明 | 类型 | 默认值 | |-------------|---------|-----------|---------| | noPadding | 是否去除内边距 | boolean | false |

YContainerFooter

| 参数 | 说明 | 类型 | 默认值 | |-------------|---------|-----------|---------| | noPadding | 是否去除内边距 | boolean | false |

YHLayout

默认会在布局容器内保留 var(--ylb-spacing, 16px) 内边距，设置 noSpace 为 true 后移除内边距。

| 参数 | 说明 | 类型 | 默认值 | |-----------|------------------------------------|-----------|---------| | auto | 是否自动高度。true 为内容高度，false 为父元素 100% 高度 | boolean | true | | noSpace | 是否去除布局间距 | boolean | false |

YHItem

| 参数 | 说明 | 类型 | 默认值 | |----------|----------------------------------------|--------------------|-----| | width | 宽度，支持 px / % / auto，纯数字按 px 处理 | string \| number | - | | height | 高度，支持 px / % / auto，纯数字按 px 处理 | string \| number | - | | flex | 占据剩余空间比例 | string \| number | 1 |

YVLayout

默认会在布局容器内保留 var(--ylb-spacing, 16px) 内边距，设置 noSpace 为 true 后移除内边距。

| 参数 | 说明 | 类型 | 默认值 | |-----------|------------|-----------|---------| | auto | 是否使用自动流式高度 | boolean | true | | noSpace | 是否去除布局间距 | boolean | false |

YVItem

| 参数 | 说明 | 类型 | 默认值 | |----------|----------------------------------------|--------------------|-----| | height | 高度，支持 px / % / auto，纯数字按 px 处理 | string \| number | - | | flex | 占据剩余空间比例 | string \| number | 1 |

YPanel

面板容器，默认占父元素 100% 宽高。仅渲染 YPanelHeader / YPanelToolbar / YPanelBody / YPanelFooter / YPanelItem 子元素；其他子节点会被忽略并在控制台警告。

当未显式使用 YPanelHeader，但设置了 title 或 colorCode 时，会自动生成带色块的标题栏（等价于嵌入 YPanelHeader + YPanelItemLeft）。

| 参数 | 说明 | 类型 | 默认值 | |--------------------|----------------------------------------------|------------------------------|----------| | title | 面板标题 | string | - | | colorCode | 标题色块编码，支持 001-012 内置色值，亦可直接传入 CSS 颜色 | string | - | | auto | 是否使用自动布局（流式布局） | boolean | false | | noPadding | 各子区域是否默认无内边距（子组件可覆盖） | boolean | false | | noSpace | 各布局单元格之间是否无间距（子组件可覆盖） | boolean | false | | headBorderBottom | YPanelHeader 是否显示下边框 | boolean | true | | showFold | 是否显示展开/收起按钮 | boolean | false | | foldDirection | 折叠方向，可选 left / right / top | string | left |

事件：

| 事件 | 说明 | 回调参数 | |--------|------------|-------------------| | fold | 折叠状态切换时触发 | folded: boolean |

插槽：

| 名称 | 说明 | |----------|--------------------------------------------------------------------| | default | 仅识别 YPanelHeader / YPanelToolbar / YPanelBody / YPanelFooter / YPanelItem | | action | 默认标题栏右侧操作区（仅在未显式使用 YPanelHeader 且自动标题栏生效时显示） |

YPanelHeader / YPanelToolbar / YPanelFooter / YPanelItem

YPanelHeader 默认带下边框，YPanelFooter 默认带上边框；四者均支持 YPanelItemLeft / YPanelItemCenter / YPanelItemRight 三槽布局。

| 参数 | 说明 | 类型 | 默认值 | |--------------------|-------------|-----------|-------------------------| | noPadding | 是否无内边距 | boolean | 取父 YPanel 值 | | noSpace | 是否无单元格间距 | boolean | 取父 YPanel 值 | | headBorderBottom | 仅 Header 可用 | boolean | 取父 YPanel 值 |

YPanelBody

主内容区，默认撑满 YPanel 剩余空间；YPanel 的 auto 为 true 时高度由子元素决定。

| 参数 | 说明 | 类型 | 默认值 | |-------------|---------------------------|-----------|-------| | center | 子元素是否水平且垂直居中 | boolean | false | | noPadding | 是否无内边距 | boolean | 取父值 |

YPanelItemLeft / YPanelItemCenter / YPanelItemRight

行内单元格，分别向左 / 居中 / 向右分布，无 props。

YQueryPanel

查询面板，内部请仅嵌套使用 YQueryItem、#inner 插槽和 #action 插槽。

| 参数 | 说明 | 类型 | 默认值 | |----------------|------------------------------------------------------------|-------------------|--------------| | type | 展示类型，可选 dropdown / drawer。drawer 时 layout 无效 | string | dropdown | | showLabel | 是否展示文本域 | boolean | true | | colCount | 栅格列数（建议 ≤ 4） | number | 3 | | layout | 布局：horizontal / vertical / inline | string | vertical | | labelWidth | 统一设置文本域宽度，支持 px / % | string \| number | 33.33% | | labelAlign | 统一设置文本域对齐：left / center / right | string | 由 layout 决定 | | controlWidth | 统一设置控件宽度（仅 layout='inline' 生效） | string \| number | - | | showFold | dropdown 时显示展开/收起按钮；drawer 时显示高级筛选按钮 | boolean | true | | defaultFold | 查询区是否默认收起（inline 时始终为 false） | boolean | false | | showAction | 是否显示操作按钮（重置 + 查询） | boolean | true | | showReset | 是否显示重置按钮 | boolean | true | | resetText | 重置按钮文案 | string | 重置 | | queryText | 查询按钮文案 | string | 查询 | | reverseBtn | 是否调换重置/查询按钮顺序 | boolean | false | | drawerTitle | 抽屉标题 | string | 高级筛选 | | advancedText | 抽屉触发按钮文案 | string | 高级筛选 |

事件：

| 事件 | 说明 | 回调参数 | |----------|-------------------|-------------------| | query | 点击查询按钮触发 | - | | reset | 点击重置按钮触发 | - | | expand | 点击展开/收起按钮触发 | isFold: boolean |

插槽：

| 名称 | 说明 | |-----------|------------------------------------| | default | 主查询项，始终可见 | | inner | 可隐藏查询项（dropdown 由展开/收起控制；drawer 在抽屉中展示） | | action | 自定义操作按钮，排在默认按钮左侧 |

YQueryItem

查询项，需内嵌表单组件使用。单独使用时（非 YQueryPanel 子元素），col / labelWidth 等与栅格相关的 prop 无效。

| 参数 | 说明 | 类型 | 默认值 | |----------------|----------------------------------------|-------------------|---------| | label | 文本域内容，为空时不渲染标签 | string | - | | col | 本项占据的列数 | string \| number | 1 | | labelWidth | 覆盖父组件 labelWidth（horizontal 布局生效） | string \| number | 33.33%| | labelAlign | 覆盖父组件 labelAlign（inline 布局无效） | string | - | | controlWidth | 控件宽度（inline 布局生效） | string \| number | - |

Development

npm run build
npm run build:demo

Release

Update package.json version and append release notes to CHANGELOG.md.
Push a tag like v0.1.0.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ylb-design

安装

全量注册

按需引入

示例

页面容器

水平布局

垂直布局

YPanel

API

YContainer

YContainerHeader

YContainerBody

YContainerFooter

YHLayout

YHItem

YVLayout

YVItem

YPanel

YPanelHeader / YPanelToolbar / YPanelFooter / YPanelItem

YPanelBody

YPanelItemLeft / YPanelItemCenter / YPanelItemRight

YQueryPanel

YQueryItem

Development

Release