mcpField
O
opendesign-components

opendesign-components

github.com/finch-poi设计与 UI176 次安装9 周前更新
代码仓库

关于 opendesign-components

opendesign-components 是面向 openEuler 生态的 Vue 3 组件库使用指南 Skill,涵盖 59 个可复用 UI 组件。它还规定主题选择、响应式样式和组件定制方式,并提供 Pixso MCP 设计稿识别流程。

主要功能

  1. 01涵盖 59 个 Vue 3 UI 组件
  2. 02支持六套社区主题及深浅模式
  3. 03提供组件视觉、用法和样式参考
  4. 04规定响应式样式与组件定制规范
  5. 05包含 Pixso 图层到组件的识别流程

适用场景

  1. 01在 Vue 3 项目中按规范使用组件
  2. 02为 openEuler 生态项目选择主题
  3. 03将设计稿界面映射到已有组件
  4. 04查询组件 API 并定制响应式样式

MCP 相关

指南说明可通过 Pixso MCP 读取设计稿节点,并据此将图层映射到 OpenDesign 组件;没有描述该 Skill 提供 MCP 服务端能力。

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/finch-poi/opendesign-skills --skill opendesign-components

安装后在 Claude Code 中输入/opendesign-components确认已加载。

包含的文件

除 SKILL.md 外,安装时一起下载的参考资料和脚本。

CHANGELOG.md
references/
anchor.style.md
anchor.usage.md
anchor.visual.md
avatar.style.md
avatar.usage.md
avatar.visual.md
badge.style.md
badge.usage.md
badge.visual.md
breadcrumb.style.md
breadcrumb.usage.md
breadcrumb.visual.md
button.style.md
button.usage.md
button.visual.md
card.style.md
card.usage.md
card.visual.md
carousel.style.md
carousel.usage.md
carousel.visual.md
cascader-v2.style.md
cascader-v2.usage.md
cascader-v2.visual.md
cascader.style.md
cascader.usage.md
cascader.visual.md
checkbox.style.md
checkbox.usage.md

详细介绍

来自项目 README

OpenDesign 组件库使用指南

本 Skill 对应 @opensig/opendesign v1.2.6(2026-07 生成),最低依赖版本 ≥1.2.6。具体组件 API 在哪个版本引入/变更/废弃,查 ReleaseNote。

OpenDesign 是一个面向 openEuler 生态的 Vue 3 组件库,提供 59 个可复用 UI 组件。组件库有六套独立主题,每个社区项目在初始化时选定一套,运行时只切换 dark/light 模式。

安装

1. 安装依赖包
pnpm add @opensig/opendesign @opensig/opendesign-token
# 或
npm install @opensig/opendesign @opensig/opendesign-token
  • @opensig/opendesign — 组件库(最低版本见各组件 Skill 头部标注)
  • @opensig/opendesign-token — 设计 token(必需),最低版本见 Token Skill 头部标注(当前为 ≥0.1.1)
2. 选择主题并引入样式

首先引入样式

// main.ts
import '@opensig/opendesign/es/index.css' // 引入组件样式文件

六套主题对应不同社区,项目初始化时选定其中一套,引入对应的 token 文件:

openEuler 社区项目:

// main.ts
import '@opensig/opendesign-token/themes/e.dark.token.css'  // openEuler 主题 token
import '@opensig/opendesign-token/themes/e.light.token.css'  // openEuler 主题 token

Ascend 社区项目:

// main.ts
import '@opensig/opendesign-token/themes/a.dark.token.css'  // Ascend 主题 token
import '@opensig/opendesign-token/themes/a.light.token.css'  // Ascend 主题 token

Kunpeng 社区项目:

// main.ts
import '@opensig/opendesign-token/themes/k.dark.token.css'  // Kunpeng 主题 token
import '@opensig/opendesign-token/themes/k.light.token.css'  // Kunpeng 主题 token

MindSpore 社区项目:

// main.ts
import '@opensig/opendesign-token/themes/m.dark.token.css'  // MindSpore 主题 token
import '@opensig/opendesign-token/themes/m.light.token.css'  // MindSpore 主题 token

Gauss 社区项目:

// main.ts
import '@opensig/opendesign-token/themes/g.dark.token.css'  // Gauss 主题 token
import '@opensig/opendesign-token/themes/g.light.token.css'  // Gauss 主题 token

UBMC 社区项目:

// main.ts
import '@opensig/opendesign-token/themes/u.dark.token.css'  // UBMC 主题 token
import '@opensig/opendesign-token/themes/u.light.token.css'  // UBMC 主题 token
3. 切换 dark/light 模式

引入 token 文件后,通过 data-o-theme 属性(设置在 <html> 或 <body> 上)在浅色/深色间切换:

社区浅色模式深色模式
openEulerdata-o-theme="e.light"data-o-theme="e.dark"
Ascenddata-o-theme="a.light"data-o-theme="a.dark"
Kunpengdata-o-theme="k.light"data-o-theme="k.dark"
MindSporedata-o-theme="m.light"data-o-theme="m.dark"
Gaussdata-o-theme="g.light"data-o-theme="g.dark"
UBMCdata-o-theme="u.light"data-o-theme="u.dark"
// 切换深色模式(以 openEuler 项目为例)
document.documentElement.setAttribute('data-o-theme', 'e.dark')
// 切换回浅色模式
document.documentElement.setAttribute('data-o-theme', 'e.light')
4. 设置组件默认圆角

引入组件后,可以通过 initRound 来全局设置大部分组件的圆角

import {initRound} from '@opensig/opendesign'

initRound('pill') // 'pill'代表全圆角,通常在Ascend社区使用
5. 引入鸿蒙字体
// main.ts
import '@opensig/opendesign-token/fonts/css' // 鸿蒙字体

快速开始

所有组件都从 @opensig/opendesign 导入:

<script setup>
import { OButton, OInput, OCard } from '@opensig/opendesign';
</script>

全局编码原则

⚠️ 以下原则适用于 所有 OpenDesign 组件,不可违反。

优先使用 OpenDesign 生态

在编写任何 UI 代码之前,第一步是识别需求是否已由 OpenDesign 覆盖。

拿到需求或设计稿时,按以下顺序决策:

  1. 识别视觉结构 → 将设计稿中的每个视觉区域/交互元素与 OpenDesign 组件列表对比
  2. 优先使用现有组件 → 凡是 OpenDesign 已提供的能力,必须通过组件 props / slots / events 实现,不允许绕过自行实现同类功能
  3. 扩展而非重写 → 若现有组件不能完全满足需求,优先通过 slot 插入自定义内容,或通过 CSS 变量覆盖样式,而不是重新实现整个组件
  4. 最后才考虑自定义 → 只有在 OpenDesign 确实没有对应能力时,才编写完全自定义的代码,并在注释中说明原因
需求/设计稿
  ↓
① 能否用 OpenDesign 组件覆盖?
  ├─ 是 → 使用组件 props/slots/events ✅
  ├─ 部分 → slot 插入 + CSS 变量覆盖 ✅
  └─ 否 → 自定义实现(注明理由)⚠️

核心精神:不要在已有轮子的情况下重新造轮子。OpenDesign 组件经过响应式、无障碍、多主题的完整打磨,自行实现同等功能的成本远高于学习组件 API 的成本。


禁止使用 :deep 修改组件内部样式

在 Vue scoped 样式(<style scoped>)中,严禁使用 :deep() 修改任何 OpenDesign 组件的内部 CSS,包括但不限于:

  • 组件内部 class(如 .o-select-inner、.o-form-item)
  • 组件内部 CSS 变量覆盖(放在 :deep 块中的情况)
  • 任何以 :deep(.o-*) 开头的规则

允许的替代方案:

  1. 全局 CSS 文件(如 src/styles/xxx.css):针对组件渲染类(如 .o-input、.o-select)的全局设计系统规则,在 main.ts 中统一导入
  2. CSS 变量覆盖:在父元素上覆盖组件暴露的公开 CSS 变量(如 --form-item-gap),无需 :deep
  3. 组件 Props:优先通过 props 控制外观(如 color、size、variant)
/* ✅ 正确:全局 CSS 文件中设置渲染类 */
.o-form .o-input { width: var(--o-r-grid-6); }

/* ✅ 正确:在父元素覆盖组件暴露的 CSS 变量 */
.my-form { --form-item-gap: 32px; }

/* ❌ 错误:在 scoped 样式中使用 :deep */
.my-form :deep(.o-form-item) { margin-bottom: 0; }
响应式样式:使用 respond mixin

在生成任何包含响应式样式的代码前,按以下顺序检查并初始化:

  1. 检查 mixin 文件是否存在:在项目 src/ 目录下搜索包含 @mixin respond 的 .scss 文件
  2. 若不存在:在 src/styles/mixin.scss(或项目约定的公共样式目录)创建下方的初始化文件
  3. 检查构建工具配置,注册为全局自动注入(见「构建工具全局注入」章节)——注册后组件内无需手动 @use,可直接使用所有 mixin

初始化文件内容(src/styles/mixin.scss):

@use 'sass:map';
@use 'sass:list';
@use 'sass:meta';

// OpenDesign V2 断点定义
// 关键断点:840px(手机/平板竖屏)、1200px(移动/桌面)、1680px(笔记本/大屏)
$o-breakpoints: (
  // phone:≤600px
  'phone': (0, 600px),
  '>phone': 601px,
  // pad:601–1200px(平板竖屏 + 横屏)
  'pad': (601px, 1200px),
  '<=pad': (0, 1200px),
  '>pad': 1201px,
  // pad-v:601–840px(平板竖屏)
  'pad_v': (601px, 840px),
  '<=pad_v': (0, 840px),
  '>pad_v': 841px,
  // pad-h:841–1200px(平板横屏)
  'pad_h': (841px, 1200px),
  // laptop:1201–1680px(笔记本/桌面)
  'laptop': (1201px, 1680px),
  '<=laptop': (0, 1680px),
  '>laptop': 1681px,
  'pad-laptop': (601px, 1680px),
  'pad_v-laptop': (841px, 1680px),
  'laptop_s': (1201px, 1440px),
  '<=laptop_s': (0, 1440px),
  '>laptop_l': 1441px,
  // pc:>1680px(大屏)
  'pc': (1680px, 1920px),
  '>pc': 1921px,
);

/// 响应式媒体查询 mixin(V2)
/// 用法:@include respond('<=pad') { ... }
@mixin respond($breakname) {
  $bp: map.get($o-breakpoints, $breakname);
  @if meta.type-of($bp) == 'list' {
    $min: list.nth($bp, 1);
    $max: list.nth($bp, 2);
    @if $min == 0 {
      @media (max-width: $max) {
        @content;
      }
    } @else {
      @media (min-width: $min) and (max-width: $max) {
        @content;
      }
    }
  } @else {
    @media (min-width: $bp) {
      @content;
    }
  }
}

/// 设备悬停能力查询——筛选设备类型,不附加 :hover 伪类
/// 与 hover() 的区别:hoverable 只做设备筛选,@content 原样输出;
///   hover() 会自动包裹 &:hover,只在指针设备的 hover 瞬态生效。
/// 用法:@include hoverable { ... }(仅在支持 hover 的设备生效,常驻样式)
///      @include hoverable(none) { ... }(仅在触控等不支持 hover 的设备生效)
@mixin hoverable($hover: hover) {
  @media (hover: $hover) {
    @content;
  }
}

/// 安全 hover 样式——仅在支持 hover 的指针设备上追加 :hover
/// 与 hoverable() 的区别:hover() 自动包裹 &:hover,只在 hover 瞬态生效;
///   hoverable() 只做设备筛选,@content 原样输出,不附加 :hover。
/// 触控设备不会产生粘连残留状态
/// 用法:@include hover { color: red; }
@mixin hover() {
  @media (hover: hover) {
    &:hover {
      @content;
    }
  }
}

/// 展开/收起箭头旋转动效(hover 时旋转 180°,带过渡动画)
/// 用法:.arrow { @include x-hover; }
@mixin x-hover() {
  transition: all var(--o-duration-m1) var(--o-easing-standard-in);
  @include hover {
    transform: rotate(180deg);
  }
}

/// SVG 图标旋转动效(overflow:hidden + 内部 svg 旋转 180°)
/// 用法:.icon-wrap { @include x-svg-hover; }
@mixin x-svg-hover() {
  & {
    overflow: hidden;
  }
  svg {
    transition: all var(--o-duration-m1) var(--o-easing-standard-in);
  }
  @include hover {
    svg {
      transform: rotate(180deg);
    }
  }
}

在组件样式中使用(全局注入后无需 @use,直接调用):

// SomeComponent.vue <style lang="scss">
// ✅ 全局注入后不需要 @use,直接使用

.my-component {
  display: grid;
  grid-template-columns: repeat(4, 1fr);

  @include respond('pad_h') {        // 841–1200px:3列
    grid-template-columns: repeat(3, 1fr);
  }

  @include respond('<=pad_v') {      // ≤840px:1列
    grid-template-columns: 1fr;
  }
}

// 安全 hover(触控设备不残留)
.my-btn {
  opacity: 0.8;
  @include hover {
    opacity: 1;
  }
}

// 仅 hover 设备生效的常驻样式
.action-area {
  @include hoverable {
    background-color: var(--o-color-fill3);
  }
}

// 仅触控设备生效的样式
.mobile-only {
  @include hoverable(none) {
    display: block;
  }
}

// 展开/收起箭头旋转
.expand-icon {
  @include x-hover;
}

构建工具全局注入(必须配置,避免每个文件手动 @use):

首先分析项目的构建工具:检查根目录下是否有 vite.config.ts(或 .js)、nuxt.config.ts,再决定采用哪种方式注入。

Vite 项目(vite.config.ts):

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        // 路径为 mixin 文件相对于 vite.config.ts 的路径(或 alias 路径)
        additionalData: '@use "@/styles/mixin" as *;\n',
      },
    },
  },
});

Nuxt 项目(nuxt.config.ts):

export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: '@use "@/styles/mixin" as *;\n',
        },
      },
    },
  },
});

⚠️ 注意:additionalData 中路径的 @ 别名需与 resolve.alias 的配置一致。若项目用绝对路径,改为 '@use "/abs/path/to/mixin" as *;\n'。配置后 所有 .scss 文件自动注入,组件里不再需要 @use。

断点速查(最常用):

断点名范围典型场景
'<=pad_v'≤840px手机 + 平板竖屏
'pad_h'841–1200px平板横屏
'<=pad'≤1200px所有移动端(isPhonePad)
'>pad'≥1201px桌面端
'laptop'1201–1680px笔记本
'>laptop'≥1681px大屏

Hover mixin 选用速查:

场景用哪个
鼠标悬停改变样式(触控设备跳过)@include hover { ... }
某段样式仅限支持 hover 的设备(常驻,非瞬态)@include hoverable { ... }
某段样式仅限触控设备@include hoverable(none) { ... }
展开/收起箭头旋转动效@include x-hover
带 overflow 裁切的 SVG 旋转动效@include x-svg-hover

⚠️ 不要直接写裸 @media (hover: hover) 或 @media 断点查询,统一通过对应 mixin 保持与组件库行为一致。

组件索引

每个组件的参考文档按用途拆分为三个文件:

  • {name}.visual.md — 视觉识别(视觉特征指纹、Token→Prop 映射、易混淆组件区分)
  • {name}.usage.md — 代码使用(API 表、代码模板、prop 组合速查、变更记录)
  • {name}.style.md — 样式定制(CSS 变量、布局结构 YAML、响应式行为表)
  • OAnchor — 锚点 · references/anchor.{visual|usage|style}.md
  • OAvatar / OAvatarGroup — 头像 · references/avatar.{visual|usage|style}.md
  • OBadge — 徽标 · references/badge.{visual|usage|style}.md
  • OBreadcrumb — 面包屑 · references/breadcrumb.{visual|usage|style}.md
  • OButton — 按钮 · references/button.{visual|usage|style}.md
  • OCard — 卡片 · references/card.{visual|usage|style}.md
  • OCarousel — 幻灯片 · references/carousel.{visual|usage|style}.md
  • OCascader — 级联选择 · references/cascader.{visual|usage|style}.md
  • OCascaderV2 — 级联选择(PC重构版) · references/cascader-v2.{visual|usage|style}.md
  • OCheckbox / OCheckboxGroup — 多选框 · references/checkbox.{visual|usage|style}.md
  • OCollapse — 折叠面板 · references/collapse.{visual|usage|style}.md
  • OConfigProvider — 全局配置 · references/config-provider.{visual|usage|style}.md
  • ODataTable — 数据表格(高级) · references/data-table.{visual|usage|style}.md
  • ODatePicker 系列 — 日期选择器 · references/date-picker.{visual|usage|style}.md
  • ODialog — 对话框 · references/dialog.{visual|usage|style}.md
  • ODivider — 分割线 · references/divider.{visual|usage|style}.md
  • ODropdown — 下拉菜单 · references/dropdown.{visual|usage|style}.md
  • OFigure — 图片 · references/figure.{visual|usage|style}.md
  • OForm / OFormItem — 表单 · references/form.{visual|usage|style}.md
  • ORow / OCol — 栅格布局 · references/grid.{visual|usage|style}.md
  • OIcon — 图标 · references/icon.{visual|usage|style}.md
  • OInput — 输入框 · references/input.{visual|usage|style}.md
  • OInputNumber — 数字输入框 · references/input-number.{visual|usage|style}.md
  • OIpInput — IP 地址输入框 · references/ip-input.{visual|usage|style}.md
  • OLayer — 浮层 · references/layer.{visual|usage|style}.md
  • OLink — 链接 · references/link.{visual|usage|style}.md
  • OLoading — 加载中 · references/loading.{visual|usage|style}.md
  • OMenu — 菜单 · references/menu.{visual|usage|style}.md
  • OMessage — 消息提示 · references/message.{visual|usage|style}.md
  • OPagination — 分页 · references/pagination.{visual|usage|style}.md
  • OPopover — 气泡卡片 · references/popover.{visual|usage|style}.md
  • OPopup — 弹出层 · references/popup.{visual|usage|style}.md
  • OProgress — 进度条 · references/progress.{visual|usage|style}.md
  • ORadio / ORadioGroup — 单选框 · references/radio.{visual|usage|style}.md
  • ORate — 评分 · references/rate.{visual|usage|style}.md
  • OResult — 结果 · references/result.{visual|usage|style}.md
  • OScrollbar / OScroller — 滚动条 · references/scrollbar.{visual|usage|style}.md
  • OSelect — 选择器 · references/select.{visual|usage|style}.md
  • OSkeleton — 骨架屏 · references/skeleton.{visual|usage|style}.md
  • OSlider — 滑块 · references/slider.{visual|usage|style}.md
  • OStep / OStepItem — 步骤条 · references/step.{visual|usage|style}.md
  • OSwitch — 开关 · references/switch.{visual|usage|style}.md
  • OTab / OTabPane — 标签页 · references/tab.{visual|usage|style}.md
  • OTag — 标签 · references/tag.{visual|usage|style}.md
  • OTextarea — 文本域 · references/textarea.{visual|usage|style}.md
  • OTimePicker 系列 — 时间选择器 · references/time-picker.{visual|usage|style}.md
  • OToast — 轻提示 · references/toast.{visual|usage|style}.md
  • OToggle — 选择块 · references/toggle.{visual|usage|style}.md
  • OUpload — 上传 · references/upload.{visual|usage|style}.md
  • OVirtualList — 虚拟列表 · references/virtual-list.{visual|usage|style}.md

Pixso MCP 设计稿识别指南

通过 Pixso MCP 读取设计稿节点时,使用本节将图层数据映射到 OpenDesign 组件,再调用该组件的 references/{name}.visual.md 获取视觉识别信息、references/{name}.usage.md 获取完整 API。

匹配流程
Pixso 图层信息(节点类型 / 图层名称 / 视觉属性 / 布局结构)
  ↓
① 检查图层/组件名称 → 「名称关键词表」
  ↓ 未命中
② 分析视觉结构特征 → 「视觉特征速查表」
  ↓ 有多个候选
③ 使用「歧义辨别规则」确定唯一组件
  ↓
④ 提取 Pixso 视觉属性 → 「属性映射表」转为 Props
  ↓
⑤ 调用 references/{name}.visual.md 获取完整代码模板

① 图层名称关键词识别

Pixso 图层或组件实例名通常含有以下关键词,可直接映射:

名称含有(不区分大小写)优先匹配组件Reference
button / btn / 按钮OButtonreferences/button.visual.md
input / 输入框 / text-fieldOInputreferences/input.visual.md
textarea / 文本域 / 多行输入OTextareareferences/textarea.visual.md
input-number / 数字输入OInputNumberreferences/input-number.visual.md
ip-input / ip输入OIpInputreferences/ip-input.visual.md
select / 下拉 / dropdown-selectOSelectreferences/select.visual.md
cascader / 级联OCascaderreferences/cascader.visual.md
checkbox / 多选框 / 复选框OCheckboxreferences/checkbox.visual.md
radio / 单选框ORadioreferences/radio.visual.md
switch / 开关OSwitchreferences/switch.visual.md
slider / 滑块OSliderreferences/slider.visual.md
toggle / 选择块OTogglereferences/toggle.visual.md
tag / 标签OTagreferences/tag.visual.md
badge / 徽标 / 角标OBadgereferences/badge.visual.md
progress / 进度条 / 进度环OProgressreferences/progress.visual.md
rate / 评分 / 星级ORatereferences/rate.visual.md
result / 结果页OResultreferences/result.visual.md
skeleton / 骨架屏 / 占位OSkeletonreferences/skeleton.visual.md
loading / 加载OLoadingreferences/loading.visual.md
message / 消息 / 提示条OMessagereferences/message.visual.md
toast / 轻提示 / 浮动提示OToastreferences/toast.visual.md
dialog / 弹窗 / modalODialogreferences/dialog.visual.md
popover / 气泡OPopoverreferences/popover.visual.md
popup / 弹出层OPopupreferences/popup.visual.md
dropdown / 下拉菜单ODropdownreferences/dropdown.visual.md
layer / 浮层OLayerreferences/layer.visual.md
card / 卡片OCardreferences/card.visual.md
carousel / 幻灯片 / 轮播OCarouselreferences/carousel.visual.md
collapse / 折叠OCollapsereferences/collapse.visual.md
menu / 菜单 / sidebar-navOMenureferences/menu.visual.md
tab / 标签页OTabreferences/tab.visual.md
step / 步骤条OStepreferences/step.visual.md
breadcrumb / 面包屑OBreadcrumbreferences/breadcrumb.visual.md
anchor / 锚点OAnchorreferences/anchor.visual.md
pagination / 分页OPaginationreferences/pagination.visual.md
figure / 图片 / imageOFigurereferences/figure.visual.md
icon / 图标OIconreferences/icon.visual.md
link / 链接OLinkreferences/link.visual.md
divider / 分割线ODividerreferences/divider.visual.md
upload / 上传OUploadreferences/upload.visual.md
scrollbar / scroller / 滚动OScrollbarreferences/scrollbar.visual.md
virtual-list / 虚拟列表OVirtualListreferences/virtual-list.visual.md
data-table / 表格 / tableODataTablereferences/data-table.visual.md
row / col / grid / 栅格ORow/OColreferences/grid.visual.md
form / 表单OFormreferences/form.visual.md

② 视觉结构特征速查

名称无法匹配时,根据图层的几何形状 + 内部内容 + 布局方向判断:

交互控件
视觉特征组件Reference
圆角矩形 + 文本,有填充背景或描边,可点击触发操作OButtonreferences/button.visual.md
横向矩形描边框 + 内部文本/占位符,可自由输入字符OInputreferences/input.visual.md
横向矩形描边框 + 内部文本 + 右侧固定 chevron 下箭头OSelectreferences/select.visual.md
多行可输入区域,有描边,支持垂直拉伸(或固定高度多行)OTextareareferences/textarea.visual.md
数字输入框 + 左右(或上下)加减控制按钮OInputNumberreferences/input-number.visual.md
四段横向输入框,各段接受 0-255,段间有圆点 . 分隔OIpInputreferences/ip-input.visual.md
小方形框(或勾选图标)+ 右侧标签文本OCheckboxreferences/checkbox.visual.md
小圆形框(有内圆点状态)+ 右侧标签文本ORadioreferences/radio.visual.md
横向胶囊形轨道 + 圆形滑块(开/关两态,无数值)OSwitchreferences/switch.visual.md
横向长条轨道 + 可拖动圆形滑块(有数值刻度)OSliderreferences/slider.visual.md
矩形/胶囊形区域 + 文本,可切换选中/未选中两态OTogglereferences/toggle.visual.md
多层逐级展开的下拉面板(选择时触发下一级)OCascaderreferences/cascader.visual.md
状态 / 反馈类
视觉特征组件Reference
小圆角矩形或胶囊 + 短文本,内嵌在内容流中OTagreferences/tag.visual.md
悬浮在其他元素右上角/角落的小圆点或数字气泡OBadgereferences/badge.visual.md
横向细线进度条(有背景轨道,只读展示百分比)OProgress(line)references/progress.visual.md
圆形进度环(只读展示百分比)OProgress(circle)references/progress.visual.md
一排 ★ 星形图标(部分填充或半填充)ORatereferences/rate.visual.md
页面居中大图标 + 粗标题 + 描述文字(成功/警告/错误状态页)OResultreferences/result.visual.md
多个灰色矩形占位块,模拟文字/图片加载中OSkeletonreferences/skeleton.visual.md
旋转动画图标或全屏蒙层 + "加载中" 文字OLoadingreferences/loading.visual.md
嵌入页面内容流的横向条形,含图标 + 文字(不自动消失)OMessagereferences/message.visual.md
浮于页面上层底部或顶部出现的短提示条,带消失动画OToastreferences/toast.visual.md
导航 / 结构类
视觉特征组件Reference
横向 文本 > 文本 > 文本 链式结构(箭头/斜线分隔)OBreadcrumbreferences/breadcrumb.visual.md
垂直侧边导航,层级缩进,有折叠子项和选中高亮OMenureferences/menu.visual.md
顶部横向标签行 + 下方可切换内容区OTabreferences/tab.visual.md
横向数字/图标序列 + 连接线(流程步骤)OStepreferences/step.visual.md
垂直排列的锚点链接列表,通常悬浮在页面侧边OAnchorreferences/anchor.visual.md
横向数字页码按钮组(含上下页、跳转输入)OPaginationreferences/pagination.visual.md
容器 / 叠加层类
视觉特征组件Reference
圆角矩形卡片,内部有封面图/图标 + 标题 + 描述 + 操作结构OCardreferences/card.visual.md
居中弹窗 + 半透明全屏蒙层 + 标题栏 + 关闭按钮ODialogreferences/dialog.visual.md
附着触发元素的小弹框,有指向箭头OPopoverreferences/popover.visual.md
贴合触发元素展开的菜单面板,无指向箭头ODropdownreferences/dropdown.visual.md
通用弹出层容器(自身无样式,定位在触发元素附近)OPopupreferences/popup.visual.md
通用蒙层/全屏浮层容器(无固定内部结构)OLayerreferences/layer.visual.md
可展开/收起的内容面板,标题区可点击切换OCollapsereferences/collapse.visual.md
横向或垂直弹性列布局容器(flex 排列子元素)ORow/OColreferences/grid.visual.md
表单容器,内部为标签 + 控件成对排列OFormreferences/form.visual.md
媒体 / 其他
视觉特征组件Reference
图片容器(固定宽高比矩形,hover 可预览/放大)OFigurereferences/figure.visual.md
多张图片/内容轮播,有指示点和左右切换箭头OCarouselreferences/carousel.visual.md
虚线边框区域 + 上传图标 + 提示文字OUploadreferences/upload.visual.md
长列表容器,有自定义滚动条样式OScrollbar/OScrollerreferences/scrollbar.visual.md
多行多列表格(有表头,支持排序/筛选/多选)ODataTablereferences/data-table.visual.md
纯文字 + 下划线,点击跳转,无背景无边框OLinkreferences/link.visual.md
单个 SVG 图标元素OIconreferences/icon.visual.md
水平或垂直细线分割线ODividerreferences/divider.visual.md
超长列表,可见区域之外的列表项不渲染OVirtualListreferences/virtual-list.visual.md

③ 常见歧义辨别规则
歧义场景判断依据
OButton vs OLinkButton 有背景色或描边矩形框;Link 是纯文字(可选下划线),无任何背景/边框
OButton vs OTagButton 高度通常 ≥32px,触发主要操作;Tag 高度通常 ≤24px,标注状态或分类,不触发主操作
OTag vs OBadgeTag 独立出现在文本流/列表中;Badge 叠加覆盖在其他元素的角落(有绝对定位偏移)
OSelect vs OInputSelect 右侧有固定的 chevron 下箭头,点击展开选项列表;Input 无箭头,可自由键入
OSelect vs ODropdownSelect 的触发器固定为输入框样式;Dropdown 的触发器可以是任意内容(按钮、图标等)
ODropdown vs OPopoverDropdown 内容是菜单选项列表,无指向箭头;Popover 内容自由,有指向触发元素的小三角箭头
OMessage vs OToastMessage 嵌入页面内容流(inline),不自动消失;Toast 浮于页面上层,有自动消失计时
ODialog vs OLayerDialog 有固定的标题栏 + 关闭按钮 + 底部操作区三段结构;Layer 是无预设结构的通用浮层
OCollapse vs OTabCollapse 展开时内容在标题下方纵向展开,多项可同时展开;Tab 横向切换,同时只显示一个面板
OProgress vs OSliderProgress 只展示进度(只读,无交互手柄);Slider 有可拖动的圆形滑块(可交互)
OSwitch vs OCheckboxSwitch 是胶囊形开关,表达开/关整体状态;Checkbox 是方形,用于列表多选场景
OCard vs 普通容器OCard 有封面图/图标、标题、内容区的固定内部结构;普通 div 容器无内部分区约定

④ Pixso 视觉属性 → Props 映射
颜色 / 主题 (color + variant)
Pixso 视觉表现prop值
蓝色实心填充背景,白色文字color + variantcolor="primary" variant="solid"
蓝色描边,内部透明,蓝色文字color + variantcolor="primary" variant="outline"
无填充无描边,纯文字蓝色color + variantcolor="primary" variant="text"
渐变填充背景(品牌专属渐变色)color + variantcolor="brand" variant="solid"
灰色/中性色填充或描边colorcolor="normal"
绿色系colorcolor="success"
橙色/黄色系colorcolor="warning"
红色系colorcolor="danger"

⚠️ color="brand" 仅用于渐变 solid 按钮(--o-color-main2 渐变背景),普通蓝色按钮(solid/outline/text)一律用 color="primary"。

尺寸 (size)
Pixso 元素高度(参考值)size 值
≈24px"small"
≈32px"medium"(默认,可不传)
≈40px"large"
圆角 (round)
Pixso 圆角特征round 值
圆角 = 高度的一半(完全圆角胶囊)round="pill"
具体数值(如 8px、12px)round="8px" / round="12px"
标准小圆角(4px 以内)通常为默认值,无需传
状态
Pixso 视觉表现prop
降低透明度(opacity ≈ 0.4),不可交互disabled
含旋转动画图标loading

⑤ 完整匹配示例

Pixso 图层信息:圆角矩形(border-radius: 20px,高度: 40px),品牌蓝填充背景,白色文字"提交",右侧有一个 SVG 图标图层。

匹配过程:

  1. 图层名含 "button" → OButton
  2. 视觉特征:圆角矩形 + 文字 + 填充 → 确认 OButton
  3. 视觉属性映射:品牌蓝填充 → color="brand" variant="solid";高度 40px → size="large";圆角 20px = 高度一半 → round="pill";右侧图标 → #suffix 插槽
  4. 调用 references/button.visual.md

生成代码:

<OButton color="brand" variant="solid" size="large" round="pill">
  提交
  <template #suffix><OIconXxx /></template>
</OButton>

INSTANCE节点的样式盲区与补救方法
问题背景

当 Pixso 节点的 type 为 INSTANCE(组件库实例)时,getNodeDSL 只返回该实例外层容器的覆盖属性(overrides),不展开组件内部的子节点。 具体表现:

  • pixDslNodes 中该节点无任何子节点(查询 parentGuid === instanceGuid 结果为空)
  • 节点上的 cornerRadius / fillPaints 等属性属于外层容器,不代表内部元素(如按钮、图标)的真实样式
  • 内部元素(如胶囊按钮、图标)的样式由组件 master 定义,DSL 中完全不可见
识别方法

在解析 DSL 时,如果发现以下情况,说明遇到了样式盲区:

  1. 节点 type === "INSTANCE"
  2. 在 pixDslNodes 中查不到任何以该节点 guid 为 parentGuid 的子节点
  3. DSL 中的 cornerRadius 与设计图视觉不符(例如 DSL 写 4,但设计图看起来是胶囊形)
补救方法

方法一(首选):getImage 视觉确认

对该 INSTANCE 节点调用 getImage(itemId),直接获取组件渲染图像,从图像中读取所有可见的视觉属性,再用「属性映射表」推断完整 Props。

mcp__pixso__getImage({ itemId: "节点的guid" })
→ 返回图片,从图片中直接读取视觉信息

⚠️ 使用 getImage 时必须同时确认以下所有维度,不可只看圆角:

需确认的维度从图像中观察对应 Prop
圆角形状直角 / 小圆角 / 胶囊形round
背景色品牌色填充 / 透明+描边 / 无背景纯文字variant(solid / outline / text)
前景色蓝色品牌色→color="primary" / 渐变品牌色→color="brand"(仅 solid) / 灰色→color="normal"color
尺寸目测高度:≈24px→small / ≈32px→medium / ≈40px→largesize

方法二:在 Pixso 中进入组件内部选取子节点

在 Pixso 设计工具中双击进入该 INSTANCE 组件内部,选中目标子元素(如内部按钮),获取其 item-id 后再调用 getNodeDSL,即可拿到内部元素的真实样式数据。

getNodeDSL({ itemId: "内部子元素的guid" })
→ 返回真实的 cornerRadius / fillPaints 等样式
典型案例

上传按钮(上传 Upload/按钮,type: INSTANCE) DSL 中 cornerRadius: 4(外层容器),fillPaints: [](无填充信息)。 getImage 图像显示:胶囊形、蓝色描边、蓝色文字"+ 上传文件",高度约 32px。 ✅ 正确做法:<OButton color="primary" variant="outline" size="medium" round="pill"> ❌ 错误做法:<OButton color="brand" variant="outline" round="pill">(color="brand" 仅用于渐变 solid 按钮,outline 场景下蓝色应用 color="primary")


OAnchor

size 属性

  • 说明:指定锚点的尺寸风格(默认值:medium)

container 属性

  • 说明:指定锚点监听的滚动容器(默认值:window)
  • 示例:container="#wrap" 表示监听 id 为 wrap 的容器滚动事件

targetOffset 属性

  • 说明:目标元素跳转或激活时距离容器顶部的偏移量(默认值:0)

bounds 属性

  • 说明:设置锚点激活的判定边界(默认值:5)

changeHash 属性

  • 说明:是否在点击锚点时改变浏览器地址栏的 hash 值(默认值:true)

锚点嵌套:OAnchorItem 可以嵌套使用,形成多级锚点结构

示例代码
<OAnchor container="#wrap" :target-offset="10">
  <OAnchorItem href="#section1" title="第一节">
    <OAnchorItem href="#section1-1" title="第一节第一小节" />
  </OAnchorItem>
  <OAnchorItem href="#section2" title="第二节" />
</OAnchor>

详细使用说明和完整属性列表,请查看 references/anchor.usage.md


OBadge

徽标包含 primary、success、warning、danger 四种主题色。

徽标 value 参数支持数字和文本两种类型的值,当为数字时 max 参数会影响值的显示。

徽标支持小红点样式,小红点中不会显示徽标内容。

徽标可以通过 offset 设置偏移位置。

详细使用说明和完整属性列表,请查看 references/badge.usage.md


OBreadcrumb

通过 href 属性设置链接跳转地址,或者使用 to 属性配合 Vue Router 实现路由跳转。当 href 和 to 属性都未设置时,OBreadcrumbItem 组件会使用 span 标签渲染为普通文本(有利于 SEO)。

href 属性和 target 属性组合使用,to 属性和 replace 属性组合使用,当同时传递 href 属性和 to 属性时,会优先使用 to 形式的跳转。

示例代码
<OBreadcrumb>
  <OBreadcrumbItem>Home</OBreadcrumbItem>
  <OBreadcrumbItem>Category</OBreadcrumbItem>
  <OBreadcrumbItem>Current Page</OBreadcrumbItem>
</OBreadcrumb>

详细使用说明和完整属性列表,请查看 references/breadcrumb.usage.md


OButton

主题色 color:normal(默认)、brand

尺寸 size:small、medium(默认)、large

形状 variant:solid、outline(默认)、text

禁用:disabled

加载状态:loading

圆角 round:

  • round="pill" 设置为半圆角
  • round="16px" 设置具体圆角值(带单位)
  • 支持 border-radius 的任意值

其他属性:

  • href — 设置后以 <a> 标签渲染
  • icon — 按钮图标(Component)
  • tag — 根标签类型(默认 button)

插槽:default(内容)、icon(图标)、suffix(后缀)

事件:@click="(evt: MouseEvent) => void"

示例代码
<OButton color="brand" variant="solid" size="medium" round="pill">
  点击按钮
</OButton>

<OButton variant="outline" :loading="isLoading" @click="handleClick">
  <template #suffix>
    <OIconChevronDown />
  </template>
  下拉
</OButton>

详细使用说明和完整属性列表,请查看 references/button.usage.md


OCard

OCard 分为图文卡片和图标卡片。

图文卡片:给 cover 设置图片链接,通过 coverRatio 设置图片长宽比,通过 coverFit 设置图片填充方式

图标卡片:给 icon 设置值(图片链接或组件)

通过 layout 设置卡片布局方式(垂直/水平/水平反向)

设置卡片标题:

  • title — 标题内容
  • titleRow — 标题高度(行数)
  • titleMaxRow — 标题最大行数(超出显示省略号)
  • titleIcon — 标题开头图标

设置卡片内容:

  • detail — 卡片内容
  • detailRow — 内容高度(行数)
  • detailMaxRow — 内容最大行数
  • textOverflow — 文本溢出处理方式(ellipsis 或渐隐)

其他:

  • hoverable — 鼠标悬停阴影
  • href — 跳转链接(设置后以 <a> 标签渲染)
  • cursor — 鼠标悬停样式
  • noResponsive — 禁用响应式尺寸

详细使用说明和完整属性列表,请查看 references/card.usage.md


OCarousel

幻灯片有两种播放效果:

  • effect="gallery"(默认)— 滚动效果
  • effect="toggle" — 切换效果

自动播放:autoPlay、interval(默认 5000ms)、pauseOnHover

指示器:hideIndicator、indicatorClick

箭头:arrow(hover/always/never)

其他:clickToSwitch、manualInit、activeIndex(可双向绑定)

详细使用说明和完整属性列表,请查看 references/carousel.usage.md


OCascader

选中值:通过 v-model 双向绑定,类型为 CascaderValueT

type CascaderNodeValueT = string | number;
type CascaderNodePathT = Array<CascaderNodeValueT>;
type CascaderValueT = CascaderNodeValueT | CascaderNodePathT;

type CascaderOptionT = {
  value: CascaderNodeValueT;
  label?: string;
  children?: CascaderOptionT[];
};

属性:

  • options — 选项数据(CascaderOptionT[])
  • round — 圆角
  • variant — 按钮样式:solid/outline/text
  • optionPosition — 选项框位置(top/bottom/left/right/tl/tr/bl/br/lt/lb/rt/rb)
示例代码
<OCascader v-model="selectedValue" :options="options" />

详细使用说明和完整属性列表,请查看 references/cascader.usage.md


OCheckbox / OCheckboxGroup

多选框传值:

  • value — 设置选中后 modelValue 中包含的值
  • modelValue 类型是 Array<string | number>

半选:indeterminate="true" 时处于半选状态。

多选框组:可以单独使用 OCheckbox,也可以嵌套在 OCheckboxGroup 中统一管理 v-model。

示例代码
<OCheckboxGroup v-model="checkedList">
  <OCheckbox value="apple">Apple</OCheckbox>
  <OCheckbox value="banana">Banana</OCheckbox>
</OCheckboxGroup>

详细使用说明和完整属性列表,请查看 references/checkbox.usage.md


OCollapse

通过 accordion 属性开启手风琴模式(同时只展开一项)。

<OCollapse accordion v-model="activeKey">
  <OCollapseItem title="标题1" name="1">内容1</OCollapseItem>
  <OCollapseItem title="标题2" name="2">内容2</OCollapseItem>
</OCollapse>

详细使用说明和完整属性列表,请查看 references/collapse.usage.md


OConfigProvider

全局配置组件,本身不渲染任何可见内容,通过 Vue provide/inject 向后代组件注入统一配置。

属性:

  • locale — 语言词条对象({ locale: string; [key: string]: string }),优先级高于全局 useLocale() 设置。词条中支持 {0} 占位符进行变量替换
  • link — OLink 全局点击配置({ click: (e, params, attrs) => void }),仅在 OLink 的 global 属性为 true(默认)时触发

插槽:default(子组件内容)

示例代码
<script setup>
import { ref } from 'vue';
import { OConfigProvider } from '@opensig/opendesign';

const locale = ref({
  locale: 'en-US',
  'pagination.goto': 'go to',
  'pagination.total': 'Total: {0}',
});
const linkConfig = {
  click: (e, params, attrs) => {
    console.log('Link clicked:', params.href);
  },
};
</script>

<template>
  <OConfigProvider :locale="locale" :link="linkConfig">
    <RouterView />
  </OConfigProvider>
</template>

详细使用说明和完整属性列表,请查看 references/config-provider.usage.md


ODataTable

高级数据表格,支持排序、筛选、多选、列宽调整等复杂功能。

主要属性:

属性类型说明
dataTableRowT[]表格数据(必需)
columnsDataTableColumnT[]列配置(必需)
size'medium' | 'small'尺寸(默认 medium)
heightnumber | string表格高度
maxHeightnumber | string最大高度(默认 fit-content)
rowKeystring行唯一键(默认 'id')
borderTableBorderT边框样式(默认 'row')
stripeboolean斑马纹
loadingboolean加载状态
highlightCurrentRowboolean高亮当前行
columnResizableboolean列宽可调整
spanMethodFunction单元格合并方法

双向绑定(v-model):

  • v-model:conditions — 筛选条件
  • v-model:selection-keys — 已选行 key 列表

插槽:

  • #th_{key} — 自定义列头
  • #td_{key} — 自定义单元格,props: { column, row, cellValue, index }
  • #header — 自定义整个表头
  • #loading / #empty — 加载/空状态

事件:

  • @condition-update — 筛选条件更新
  • @sort-update — 排序更新
  • @selection / @selection-change / @selection-all — 选择相关
示例代码
<ODataTable
  :data="tableData"
  :columns="columns"
  v-model:selection-keys="selectedKeys"
  :loading="loading"
>
  <template #td_name="{ row }">
    <router-link :to="`/detail/${row.id}`">{{ row.name }}</router-link>
  </template>
</ODataTable>

详细使用说明和完整属性列表,请查看 references/data-table.usage.md


ODialog

尺寸 size:exlarge、large、medium(默认)、small、auto

  • auto — 根据内容自动调整大小
  • 固定尺寸 — 具有固定宽度,高度随内容变化

响应式:默认根据视口大小调整,noResponsive="true" 禁用

移动端半屏:phoneHalfFull="true" 在小屏幕(<600px)上全宽显示在底部

详细使用说明和完整属性列表,请查看 references/dialog.usage.md


ODivider

variant:solid(实线)、dashed(虚线)、dotted(点线)

direction:h(水平,默认占满容器)、v(垂直,默认高度 1em)

darker:true(深色)/ false(浅色)

标签(仅水平分割线):

  • labelPosition:left、center、right
  • 标签内容放在 default 插槽中
<ODivider direction="h" variant="dashed" label-position="center">
  分隔文字
</ODivider>

详细使用说明和完整属性列表,请查看 references/divider.usage.md


ODropdown

触发方式:none、click、click-outclick、hover、hover-outclick、focus、contextmenu

位置:top、tl、tr、bottom、bl、br、left、lt、lb、right、rt、rb

示例代码
<ODropdown trigger="hover">
  <OButton color="brand" round="pill">
    Dropdown
    <template #suffix>
      <OIconChevronDown />
    </template>
  </OButton>
  <template #dropdown>
    <OOption label="选项1" value="1" />
    <OOption label="选项2" value="2" />
  </template>
</ODropdown>

详细使用说明和完整属性列表,请查看 references/dropdown.usage.md


OFigure

ratio — 图片宽高比(通过 padding-top 百分比实现)

fit(默认 contain):

  • background=false(<img> 标签):cover/contain/fill/none/scale-down
  • background=true(背景图):cover/contain/auto/百分比

hoverable — 悬停放大效果(设置 href/preview/videoPoster 时自动生效)

preview — 点击预览(启用后接管点击事件)

previewClose — 预览关闭方式:'none'/'mask'/'button'/'body',支持数组组合

href — 链接(渲染为 <a> 标签)

注意:preview 和 href 不能同时使用

详细使用说明和完整属性列表,请查看 references/figure.usage.md


OForm / OFormItem

OForm 属性:

  • layout:h(水平)、v(垂直)、inline(行内)
  • labelAlign:top/center/bottom
  • labelJustify:left/center/right
  • labelWidth:标签宽度(PC 水平布局推荐 96px)
  • hasRequired:显示必填星号

支持的表单项:OInput、OInputNumber、OTextarea、OSelect、OCheckboxGroup、ORadioGroup、OUpload

多列表单栅格布局规则

多列表单中,每个 OFormItem 的宽度须对齐到栅格列(参见 opendesign-tokens skill 第 3 节「表单组件栅格规则」)。

断点每行项数每项宽度layoutlabelWidth
>1200px(桌面/笔记本)4 项/行var(--o-r-grid-6)h96px
841–1200px(平板横屏)3 项/行var(--o-r-grid-4)h96px
≤840px(手机)1 项/行全宽v—

行间距:32px(>840px 水平布局)/ 12px(≤840px 堆叠布局);水平模式下 Hint 在输入框右侧留 24px。

示例代码
<!-- 桌面端 4 列表单(每项 grid-6,水平标签) -->
<OForm layout="h" label-width="96px" has-required>
  <div style="display:flex; flex-wrap:wrap; gap:32px var(--o-r-grid-column-gutter);">
    <OFormItem label="用户名" required style="width:var(--o-r-grid-6);">
      <OInput v-model="form.name" />
    </OFormItem>
    <OFormItem label="类型" style="width:var(--o-r-grid-6);">
      <OSelect v-model="form.type">
        <OOption v-for="item in options" :key="item.value" :label="item.label" :value="item.value" />
      </OSelect>
    </OFormItem>
    <OFormItem label="描述" style="width:var(--o-r-grid-6);">
      <OInput v-model="form.desc" />
    </OFormItem>
    <!-- 宽项(文本域)独占一行 -->
    <OFormItem label="备注" style="width:100%;">
      <OTextarea v-model="form.remark" />
    </OFormItem>
  </div>
</OForm>

详细使用说明和完整属性列表,请查看 references/form.usage.md


ORow / OCol

ORow 属性:

  • align — 辅轴对齐方式
  • justify — 主轴对齐方式
  • wrap — flex-wrap 值
  • direction — flex-direction 值
  • gap / gapX / gapY — 子元素间距
  • inline — 使用 inline-flex
  • 响应式属性:pcS、laptop、pad、padV、phone(控制不同断点下的 gap)

OCol 属性:

  • flex — flex 样式值
  • align — 辅轴对齐方式
  • 响应式属性:pcS、laptop、pad、padV、phone(控制不同断点下的 flex)

详细使用说明和完整属性列表,请查看 references/grid.usage.md


OIcon

通用图标容器,展示 SVG 图标,也可作为图标按钮使用。图标大小继承上下文 font-size(默认 1em)。

属性:

  • icon — 图标组件(如 OIconAdd、OIconEdit)
  • button — 图标按钮模式(悬停/激活样式,自动 pointer 光标和 tabindex)
  • disabled — 禁用(配合 button 使用)
  • loading — 加载状态(显示旋转动画替换原图标)

插槽:default(自定义图标内容,使用后 icon 属性和 loading 内置图标不渲染)

示例代码
<script setup>
import { OIcon, OIconAdd, OIconDelete } from '@opensig/opendesign';
</script>

<template>
  <!-- 纯展示 -->
  <OIcon :icon="OIconAdd" />

  <!-- 图标按钮 -->
  <OIcon :icon="OIconDelete" button @click="handleDelete" />

  <!-- 自定义大小 -->
  <OIcon :icon="OIconAdd" style="font-size: 32px" />
</template>

详细使用说明和完整图标清单,请查看 references/icon.usage.md


OInput

主题色 color:normal(默认)、success、warning、danger

尺寸 size:small、medium(默认)、large

形状 variant:solid、outline(默认)、text

输入类型 type:text(默认)、password

其他属性:disabled、readonly、clearable、maxLength、placeholder、autoWidth、inputId

字符计数 showLength:'always'(始终显示)、'auto'(默认,有 maxLength 时显示)、'never'(不显示)

超限输入 inputOnOutlimit:超过 maxLength 时是否仍允许输入。默认 true

格式化与校验:format(格式化函数)、validate(校验函数)、valueOnInvalidChange(校验不通过时是否更新 modelValue)

密码框:showPasswordEvent(切换明文的触发方式 'click'/'mousedown')、passwordPlaceholder(密码占位符)

round:圆角值(pill 或 CSS border-radius 值)

插槽:prepend、append、prefix、suffix、extra

事件:@update:modelValue、@change、@input、@blur、@focus、@clear、@pressEnter

暴露方法:focus()、blur()、clear()、inputEl()、togglePassword()

示例代码
<OInput v-model="inputVal" placeholder="请输入" clearable show-length="always" :max-length="100" />

详细使用说明和完整属性列表,请查看 references/input.usage.md


OInputNumber

数字输入框,支持步进控制。

属性:

属性类型说明
modelValuenumber绑定值(v-model)
stepnumber步长(默认 1)
minnumber最小值
maxnumber最大值
controls'both' | 'right' | 'left' | 'none'控制按钮位置(默认 'both')
clearableboolean可清空
disabledboolean禁用
readonlyboolean只读
sizeSizeT尺寸
variantVariantT形状
colorColor2T主题色
placeholderstring占位文本
formatFunction格式化函数

插槽:prefix、suffix、plus(加号按钮)、minus(减号按钮)

事件:@change、@input、@blur、@focus、@clear、@pressEnter、@plus、@minus

示例代码
<OInputNumber v-model="count" :min="0" :max="100" :step="5" controls="right" />

详细使用说明和完整属性列表,请查看 references/input-number.usage.md


OIpInput

IP 地址输入框,自动分段处理 IPv4 地址。

属性:

属性类型说明
modelValuestring绑定值(v-model),格式如 "192.168.1.1"
disabledboolean禁用
readonlyboolean只读
segmentsLennumber分段数量(默认 4,即 IPv4)
sizeSizeT尺寸
roundRoundT圆角
colorstring主题色(默认 'normal')
variantstring形状(默认 'outline')

事件:

  • @update:modelValue — (value: string) => void
  • @change — (valid: boolean, ip: string) => void(valid 表示是否为合法 IP)
示例代码
<OIpInput v-model="ipAddress" @change="(valid, ip) => console.log(valid, ip)" />

详细使用说明和完整属性列表,请查看 references/ip-input.usage.md


OLayer

transitionOrigin:内容盒子缩放动画的原点:

  • 'mouse'(默认)— 鼠标点击位置
  • 'css' — 通过 CSS 变量 --layer-origin 设置

wrapper:浮层渲染的父节点:

  • 'body'(默认)— 渲染到 body,position: fixed
  • string-selector — 通过 querySelector 查询的元素
  • HTMLElement — 直接指定元素
  • null — 渲染到当前元素下,position: absolute

mask:是否渲染遮罩层

maskClose:点击遮罩层时是否关闭浮层

buttonClose:是否渲染关闭按钮

详细使用说明和完整属性列表,请查看 references/layer.usage.md


OLink

主题色 color:normal、primary、success、warning、danger

尺寸 size:auto、small、medium、large

跳转方式 target:_blank、_parent、_self、_top

状态:disabled、loading

<OLink href="https://openeuler.org" color="primary" target="_blank">
  访问 openEuler
</OLink>

详细使用说明和完整属性列表,请查看 references/link.usage.md


OLoading

通过 label 属性控制 loading 时显示的文本;

通过 icon 属性自定义 loading 时的图标;

通过 iconRotating 属性控制自定义的 loading 图标是否旋转;

其它属性的使用与 OLayer 一致。

<OLoading :visible="isLoading" label="加载中..." />

详细使用说明和完整属性列表,请查看 references/loading.usage.md


OMenu

尺寸 size:small、medium(默认)

通过 accordion 属性开启手风琴模式;

通过 expanded 属性控制展开的节点值;

通过 subMenu 的 icon 控制菜单图标(small 尺寸不支持自定义图标);

通过 selectable 控制 subMenu 本身是否可以被选中;

通过 CSS 变量 --menu-item-base-indent、--sub-menu-base-indent 控制层级缩进距离。

<OMenu v-model="activeKey" accordion>
  <OMenuItem value="home">首页</OMenuItem>
  <OSubMenu value="products" title="产品">
    <OMenuItem value="product-a">产品 A</OMenuItem>
    <OMenuItem value="product-b">产品 B</OMenuItem>
  </OSubMenu>
</OMenu>

详细使用说明和完整属性列表,请查看 references/menu.usage.md


OMessage

内联使用:

<OMessage type="success">操作成功!</OMessage>
<OMessage type="warning">警告信息</OMessage>
<OMessage type="danger">错误信息</OMessage>
<OMessage type="info">提示信息</OMessage>

详细使用说明和完整属性列表,请查看 references/message.usage.md


OPagination

layout:设置显示的控件(数组组合):

  • total — 总数据量标签
  • pagesize — 每页数据条数选择器
  • pager — 页码按钮
  • jumper — 页码跳转输入框

variant:outline(默认)/ solid

showPageCount:最多显示多少个页码按钮

showMore:鼠标悬停省略按钮时是否弹出省略的页码

simple:是否使用简单布局(启用后 layout 和 showPageCount 失效)

<OPagination
  v-model:current-page="page"
  v-model:page-size="pageSize"
  :total="total"
  :layout="['total', 'pagesize', 'pager', 'jumper']"
/>

详细使用说明和完整属性列表,请查看 references/pagination.usage.md


OPopover

OPopover 是基于 OPopup 封装的气泡卡片组件,调整了触发方式、偏移和锚点的默认值。

  1. 弹出窗位置:position 属性
  2. 触发方式:trigger 属性
  3. 距离触发对象的距离:offset 属性
  4. 宽度设置:adjustMinWidth、adjustWidth
  5. 挂载容器类名:wrapClass
示例代码
<OPopover>
  <div>气泡内容文本</div>
  <template #target>
    <OButton round="pill">触发按钮</OButton>
  </template>
</OPopover>

详细使用说明和完整属性列表,请查看 references/popover.usage.md


OPopup

通用弹出层组件,OPopover、ODropdown、OSelect 等组件的底层实现。

  1. visible — 显示状态(双向绑定)
  2. position — 弹出位置
  3. trigger — 触发方式
  4. offset — 距触发对象的距离
  5. anchor — 弹出窗锚点
  6. adjustMinWidth、adjustWidth — 宽度设置
  7. wrapClass — 挂载容器类名
  8. bodyClass — 内容体类名

插槽:default(弹出内容)、target(触发目标)、anchor(锚点内容,anchor 属性为 true 时渲染)

事件:@update:visible、@change

详细使用说明和完整属性列表,请查看 references/popup.usage.md


OProgress

类型 type:line(默认)、circle

尺寸 size:medium(默认)、small

颜色 color:primary、success、warning、danger

其他属性:

  • percentage — 进度百分比(0-100)
  • strokeWidth — 进度条线宽
  • trackWidth — 进度条轨道宽度
<OProgress type="line" :percentage="60" color="primary" />
<OProgress type="circle" :percentage="75" color="success" :stroke-width="8" />

详细使用说明和完整属性列表,请查看 references/progress.usage.md


ORadio / ORadioGroup

单选框传值:

  • value — 设置选中后 modelValue 的值
  • modelValue 类型是 string | number | boolean

单选框组:使用 ORadioGroup 包裹多个 ORadio,统一管理 v-model。

示例代码
<ORadioGroup v-model="selected">
  <ORadio value="apple">Apple</ORadio>
  <ORadio value="banana">Banana</ORadio>
</ORadioGroup>

详细使用说明和完整属性列表,请查看 references/radio.usage.md


ORate

评分组件,支持半星、清除和自定义图标。

属性:

属性类型默认说明
modelValuenumber—绑定值(v-model)
defaultValuenumber0非受控模式默认值
countnumber5星星总数
size'large' | 'medium'—尺寸
colorColorT'normal'主题色
readonlybooleanfalse只读
allowHalfbooleanfalse允许半星
clearablebooleanfalse可清除(再次点击同一值时清除)
labelsstring[]—各星级的描述文本

插槽:

  • #icon — 自定义星标图标,props: { index: number, status: RateItemStatusT }

事件:

  • @update:modelValue — (val: number) => void
  • @change — (val: number) => void
示例代码
<ORate v-model="score" :count="5" allow-half clearable />
<ORate v-model="score" readonly :labels="['很差', '较差', '一般', '较好', '很好']" />

详细使用说明和完整属性列表,请查看 references/rate.usage.md


OResult

  1. status — 展示状态:info、success、warning、danger
  2. title — 结果标题
  3. description — 补充描述
示例代码
<OResult status="success" title="提交成功" description="您的申请已成功提交,请等待审核" />

详细使用说明和完整属性列表,请查看 references/result.usage.md


OScrollbar / OScroller

尺寸 size:medium(默认)、small

显示方式 visibility:auto(默认)、always、hover、never

auto 模式下,通过 duration 控制停止滚动后持续显示的时间。

示例代码
<OScroller class="wrapper" style="height: 200px;">
  <div>内容区域</div>
</OScroller>

详细使用说明和完整属性列表,请查看 references/scrollbar.usage.md


OSelect

主题色 color:normal(默认)、success、warning、danger

尺寸 size:small、medium(默认)、large

形状 variant:solid、outline(默认)、text

属性:disabled、multiple、clearable、placeholder、loading

maxTagCount:多选时最多显示的标签数

showFoldTags:折叠标签的展示方式(true/false/'hover'/'click')

optionPosition:选项框位置(同 OCascader)

optionWidthMode:'auto'/'min-width'/'width'

子组件:

  • OOption — 单个选项(label、value、disabled)
  • OOptionGroup — 选项分组(name 属性设置分组名)

插槽:default(选项)、empty(空状态)、arrow(下拉箭头,slot props: { active })、suffix(后缀,slot props: { active })、tag-fold(折叠标签)、action(底部操作区)

事件:@change、@clear、@options-visible-change

示例代码
<OSelect v-model="selected" multiple :max-tag-count="3">
  <OOption v-for="item in options" :key="item.value" :label="item.label" :value="item.value" />
</OSelect>

详细使用说明和完整属性列表,请查看 references/select.usage.md


OSlider

滑动条组件,通过拖拽选择数值。支持单值和范围选择,可选配输入框、气泡提示和自定义标记。

属性:

属性类型默认说明
modelValuenumber | number[]0绑定值(v-model),范围模式传数组
minnumber0最小值
maxnumber100最大值
stepnumber1步长
rangebooleanfalse范围选择模式
showStopsbooleanfalse显示间隔刻度点
showInputbooleanfalse显示输入框(非 range 模式)
showPopoverbooleantrue显示数值气泡
marksRecord<number, string | { style, label }>—自定义标记
unitstring—输入框单位文字
disabledbooleanfalse禁用

插槽:unit(替换输入框单位文字)

事件:@input(滑动过程中实时触发)、@change(滑动结束后触发)

示例代码
<OSlider v-model="value" :min="0" :max="100" :step="5" show-input unit="kg" />
<OSlider v-model="rangeVal" range />
<OSlider v-model="level" show-stops :step="10" :marks="{ 0: '低', 50: '中', 100: '高' }" />

详细使用说明和完整属性列表,请查看 references/slider.usage.md


OSkeleton

  1. loading — 控制骨架屏显示/隐藏(false 时显示真实内容)
  2. animation — 动画效果(wave/none等)
  3. rows — 显示的文本行数
示例代码
<OSkeleton :loading="isLoading" :rows="3">
  <div>真实内容</div>
</OSkeleton>

详细使用说明和完整属性列表,请查看 references/skeleton.usage.md


OStep / OStepItem

步骤条组件,用于展示任务流程进度。

OStep 属性:

  • direction:'h'(水平,默认)/ 'v'(垂直)

OStepItem 属性:

属性类型默认说明
titlestring—步骤标题
descriptionstring—步骤描述
status'finished' | 'processing' | 'waiting' | 'failed''finished'状态
stepIndexnumber—步骤序号(必需)
iconboolean | Component—自定义图标
示例代码
<OStep direction="h">
  <OStepItem :step-index="1" title="第一步" status="finished" description="已完成" />
  <OStepItem :step-index="2" title="第二步" status="processing" description="进行中" />
  <OStepItem :step-index="3" title="第三步" status="waiting" description="待处理" />
</OStep>

详细使用说明和完整属性列表,请查看 references/step.usage.md


OSwitch

尺寸 size:small、medium(默认)

状态:disabled、loading

round:圆角值

自定义值:通过 checkedValue、uncheckedValue 自定义选中/未选中时对应的值

<OSwitch v-model="enabled" checked-value="on" unchecked-value="off" />

详细使用说明和完整属性列表,请查看 references/switch.usage.md


OTab / OTabPane

OTab 属性:

属性类型默认说明
modelValuestring | number—当前激活的 tab(v-model)
variant'solid' | 'text' | 'button''text'标签页样式
sizeSizeT—尺寸
roundRoundT—圆角
lazyboolean—懒加载(首次展示时才渲染)
addableboolean—是否可以新增标签
maxShownumber—最多显示的标签数(超出折叠)
linebooleantrue是否显示底部线
headerClassstring | Array | Object—头部自定义类名

OTabPane 属性:

属性类型默认说明
valuestring | number—标识值
labelstring—标签文本
disabledbooleanfalse禁用
closablebooleanfalse是否可关闭
lazybooleanfalse懒加载
unmountOnHidebooleanfalse隐藏时卸载

OTab 插槽:prefix(头部前缀)、suffix(头部后缀)

OTab 事件:

  • @change — (value, oldValue) => void
  • @delete — (value) => void(关闭标签时触发)
  • @add — (evt: MouseEvent) => void(点击添加按钮时触发)
示例代码
<OTab v-model="activeTab" variant="text">
  <OTabPane value="tab1" label="标签1">
    <div>标签1内容</div>
  </OTabPane>
  <OTabPane value="tab2" label="标签2">
    <div>标签2内容</div>
  </OTabPane>
</OTab>

详细使用说明和完整属性列表,请查看 references/tab.usage.md


OTag

主题色 color:normal(默认)、info、primary、success、warning、danger、pending(蓝色待处理态)、disabled(灰色禁用态)、main2(品牌渐变色)

形状 variant:solid(默认)、outline

尺寸 size:large(默认)、medium、small

round:圆角值

交互态:interactive(v1.2.6 新增,设为 true 后 hover 时有背景/边框变化;closable 为 true 时自动开启)

可关闭:closable、v-model:visible(控制显示/隐藏)、beforeClose(关闭前钩子)

插槽:default(文本内容)、icon(图标)

事件:@close、@update:visible

示例代码
<OTag color="primary" variant="outline" closable @close="handleClose">
  标签文本
</OTag>

<!-- 受控显示 -->
<OTag v-model:visible="tagVisible" closable>可关闭标签</OTag>

<!-- v1.2.6 新增:待处理态 + 品牌渐变色 -->
<OTag color="pending">待审核</OTag>
<OTag color="main2" variant="outline">品牌标签</OTag>

详细使用说明和完整属性列表,请查看 references/tag.usage.md


OTextarea

主题色 color:normal(默认)、success、warning、danger

尺寸 size:small、medium(默认)、large

形状 variant:solid、outline(默认)、text

属性:disabled、readonly、clearable、maxLength、showLength、placeholder

autoSize:自动调整高度(true 或 { minRows, maxRows })

resize:调整方式(none/vertical/horizontal/both)

scrollbar:是否显示滚动条

插槽:prepend、append、suffix

事件:@update:modelValue、@change、@input、@blur、@focus、@clear

暴露方法:focus()、blur()、clear()、inputEl()

示例代码
<OTextarea v-model="content" :auto-size="{ minRows: 3, maxRows: 8 }" :max-length="500" show-length />

详细使用说明和完整属性列表,请查看 references/textarea.usage.md


OToast

轻提示组件,用于操作后的即时反馈。支持内联使用和命令式调用(useToast)。

内联属性:

  • visible(v-model)— 是否可见
  • message — 提示文字
  • duration — 自动消失时间(ms),不传或 ≤0 不自动消失
  • position — 定位方向:'top'、'center'、'bottom'(默认)
  • long — 长提示模式(命令式默认 3500ms)
  • beforeClose — 关闭前钩子

命令式调用:

const toast = useToast(target?);
toast.show('操作成功');           // 字符串
toast.show({ content: '...', long: true }); // 对象配置
toast.close();                   // 关闭本实例提示
toast.closeAll();                // 关闭全部提示

命令式默认 duration: 2000ms(long 模式 3500ms),position: 'bottom'。支持 targetAlign/targetOffset 指定目标元素附近定位。

插槽:default(替换提示内容,使用后 message 失效)

事件:@duration-end、@close

示例代码
<!-- 命令式调用 -->
<script setup>
import { useToast, OButton } from '@opensig/opendesign';
const { show: showToast } = useToast();
const handleClick = () => showToast('操作成功');
</script>
<template>
  <OButton @click="handleClick">操作</OButton>
</template>

详细使用说明和完整属性列表,请查看 references/toast.usage.md


OToggle

选择块,指示当前状态并提供切换操作的表单控件。

属性:

  • checked (v-model:checked) — 双向绑定选中状态
  • defaultChecked — 非受控模式下是否默认选中
  • round — 圆角值
  • icon — 前缀图标
  • disabled — 禁用

可配合 ORadio、ORadioGroup 实现唯一选择。

<ORadioGroup v-model="selected">
  <OToggle :value="'option1'">选项1</OToggle>
  <OToggle :value="'option2'">选项2</OToggle>
</ORadioGroup>

详细使用说明和完整属性列表,请查看 references/toggle.usage.md


OUpload

属性:

属性类型说明
modelValueFileItem[]文件列表(v-model)
acceptstringMIME 类型限制
disabledboolean禁用
multipleboolean多选
draggableboolean拖拽上传
listTypestring文件列表类型
lazyUploadboolean延迟上传时机
btnLabelstring按钮文本
onAfterSelectFunction选择后的回调
uploadRequestFunction自定义上传请求
示例代码
<OUpload
  v-model="fileList"
  accept=".jpg,.png"
  multiple
  draggable
  :upload-request="handleUpload"
/>

详细使用说明和完整属性列表,请查看 references/upload.usage.md


OVirtualList

虚拟滚动列表,高性能渲染大量数据。

属性:

属性类型默认说明
listunknown[][]数据列表(必需,需含 id)
itemSizenumber | ((item, index) => number)—项高度。数字=定高;函数=按项定高;不传=不定高(运行时测量)
defaultItemSizenumber80不定高时每项的预估默认高度
buffernumber1缓冲区倍数(相对可视区域的上下额外渲染量)
defaultStartIndexnumber0初始滚动到的索引
scrollbarboolean | Objecttrue滚动条配置
layout'vertical' | 'horizontal''vertical'布局方向(v1.2.6 新增)
thresholdnumber | nullnull数据量阈值,低于此值不启用虚拟化(v1.2.6 新增)

插槽:

  • #default — 列表项模板,props: { item: any, index: number }

事件:

  • @renderChange — 渲染范围变化,props: { start, end, visible, count }

暴露方法:

  • scrollToView(index, align?, behavior?) — 滚动到指定索引项。align 支持 'start'/'end'/'center'/'nearest'/数字偏移量
  • scrollToOffset(px) — 滚动到指定像素偏移量(v1.2.6 新增)
示例代码
<OVirtualList :list="bigDataList" :item-size="60" style="height: 400px;">
  <template #default="{ item, index }">
    <div class="list-item">
      {{ index }}: {{ item.name }}
    </div>
  </template>
</OVirtualList>

详细使用说明和完整属性列表,请查看 references/virtual-list.usage.md


常用组合模式

表单页面
<OForm layout="h" has-required>
  <OFormItem label="名称" required>
    <OInput v-model="form.name" />
  </OFormItem>
  <OFormItem label="类型">
    <OSelect v-model="form.type">
      <OOption v-for="opt in options" :key="opt.value" :value="opt.value" :label="opt.label" />
    </OSelect>
  </OFormItem>
  <OFormItem label="描述">
    <OTextarea v-model="form.desc" :auto-size="{ minRows: 3 }" />
  </OFormItem>
</OForm>
数据展示
<ODataTable :columns="columns" :data="tableData" border="row">
  <template #td_status="{ row }">
    <OTag :color="row.status === 'active' ? 'success' : 'normal'">
      {{ row.status }}
    </OTag>
  </template>
</ODataTable>
<OPagination v-model:current-page="page" :total="total" />
交互反馈
<!-- 对话框 -->
<ODialog v-model:visible="dialogVisible" title="确认操作" size="small">
  <p>确认要执行此操作吗?</p>
  <template #footer>
    <OButton @click="dialogVisible = false">取消</OButton>
    <OButton color="brand" variant="solid" @click="handleConfirm">确认</OButton>
  </template>
</ODialog>

<!-- 消息提示 -->
<OMessage type="success">操作成功</OMessage>

<!-- 加载状态 -->
<OLoading :visible="loading" label="加载中..." />

评论

支持 Markdown