mcpField
O
opendesign-components

opendesign-components

github.com/finch-poiDesign & UI176 installsUpdated 9w ago
Repository

About opendesign-components

opendesign-components is a usage-guide skill for the Vue 3 component library serving the openEuler ecosystem, covering 59 reusable UI components. It also documents theme selection, responsive styling, and customization rules, plus a workflow for identifying components from Pixso MCP design data.

Key features

  1. 01Covers 59 Vue 3 UI components
  2. 02Supports six community themes and light/dark modes
  3. 03Provides visual, usage, and styling references
  4. 04Defines responsive styling and customization conventions
  5. 05Maps Pixso layers to components

Use cases

  1. 01Use components consistently in Vue 3 projects
  2. 02Choose a theme for an openEuler ecosystem project
  3. 03Map design mockups to existing components
  4. 04Look up component APIs and responsive styling

MCP support

The guide describes using Pixso MCP to read design nodes and map layers to OpenDesign components. It does not describe an MCP server capability provided by the skill.

Install

Copy the command and run it in a terminal.

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

After installing, type/opendesign-componentsin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with 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

Details

From the project 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="加载中..." />

Comments

Markdown supported