SuperAPI AI Directory

opendesign-components

Frontend & websites

View repository

Updated 10-15 23:46

About this skill

OpenDesign Component Library Usage Guide

This Skill corresponds to @opensig/opendesign v1.2.6(generated 2026-07), minimum dependency version ≥1.2.6. To find out in which version a specific component API was introduced/changed/deprecated, check ReleaseNote。

OpenDesign is a Vue 3 component library for the openEuler ecosystem, providing 59 reusable UI components. The component library has six independent themes,each community project selects one during initialization, and at runtime only switches between dark/light mode。

Installation

1. Install dependency packages

pnpm add @opensig/opendesign @opensig/opendesign-token
# 或
npm install @opensig/opendesign @opensig/opendesign-token
  • @opensig/opendesign — component library (minimum version is noted in the header of each component Skill)
  • @opensig/opendesign-token — design tokens (required), minimum version is noted in the header of the Token Skill (currently ≥0.1.1)

2. Choose a theme and import styles

First import the styles

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

The six themes correspond to different communities,select one of them during project initialization, and import the corresponding token file:

openEuler community project:

// 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 community project:

// 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 community project:

// 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 community project:

// 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 community project:

// 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 community project:

// 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. Switch dark/light mode

After importing the token file, switch between light/dark via the data-o-theme attribute (set on <html> or <body> ):

Community Light mode Dark mode
openEuler data-o-theme="e.light" data-o-theme="e.dark"
Ascend data-o-theme="a.light" data-o-theme="a.dark"
Kunpeng data-o-theme="k.light" data-o-theme="k.dark"
MindSpore data-o-theme="m.light" data-o-theme="m.dark"
Gauss data-o-theme="g.light" data-o-theme="g.dark"
UBMC data-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. Set the default component border radius

After importing the components, you can use initRound to globally set the border radius of most components

import {initRound} from '@opensig/opendesign'

initRound('pill') // 'pill'代表全圆角,通常在Ascend社区使用

5. Import HarmonyOS fonts

// main.ts
import '@opensig/opendesign-token/fonts/css' // 鸿蒙字体

Quick Start

All components are imported from @opensig/opendesign :

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

Global Coding Principles

⚠️ The following principles apply to all OpenDesign components and must not be violated.

Prioritize the OpenDesign ecosystem

Before writing any UI code, the first step is to identify whether the requirement is already covered by OpenDesign.

When receiving a requirement or design mockup, make decisions in the following order:

  1. Identify the visual structure → Compare each visual area/interactive element in the design mockup against the OpenDesign component list
  2. Prefer existing components → For any capability already provided by OpenDesign,mustbe implemented through component props / slots / events; bypassing them and implementing similar functionality yourself is not allowed
  3. Extend rather than rewrite → If existing components cannot fully satisfy the requirement, prefer inserting custom content through slots, or overriding styles through CSS variables, rather than reimplementing the entire component
  4. Only consider customization as a last resort → Only when OpenDesign truly has no corresponding capability should you write fully custom code, and explain the reason in comments
需求/设计稿
  ↓
① 能否用 OpenDesign 组件覆盖?
  ├─ 是 → 使用组件 props/slots/events ✅
  ├─ 部分 → slot 插入 + CSS 变量覆盖 ✅
  └─ 否 → 自定义实现(注明理由)⚠️

Core Spirit: Do not reinvent the wheel when one already exists. OpenDesign components are fully polished for responsiveness, accessibility, and multiple themes; the cost of implementing equivalent functionality yourself far exceeds the cost of learning the component API.


Prohibited: using :deep to modify a component's internal styles

In Vue scoped styles (<style scoped>),it is strictly forbiddento use :deep() to modify the internal CSS of any OpenDesign component, including but not limited to:

  • Component internal classes (such as .o-select-inner、.o-form-item)
  • Component internal CSS variable overrides (placed in :deep cases in blocks)
  • Any rule starting with :deep(.o-*) Rules at the beginning

Allowed alternatives:

  1. Global CSS files(such as src/styles/xxx.css): global design system rules for component render classes (such as .o-input、.o-select), uniformly imported in main.ts unified import in
  2. CSS variable overrides: override the public CSS variables exposed by the component on a parent element (such as --form-item-gap), no need for :deep
  3. Component Props: control appearance primarily through props (such as 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; }

Responsive styles: use respond mixin

before generating any code that contains responsive styles, check and initialize in the following order:

  1. Check whether the mixin file exists: in the project src/ search the directory for files containing @mixin respond of the .scss files
  2. If it does not exist: in src/styles/mixin.scss(or the project's agreed-upon common styles directory), create the initialization file below
  3. Check the build tool configuration and register it as a global automatic injection(see the "Build Tool Global Injection" section) — after registration, no manual @useis needed inside components, and all mixins can be used directly

Initialization file contents (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 in component styles (after global injection, no @useis needed; call directly):

// 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;
}

Build tool global injection (must be configured to avoid manual @use):

in every file. First analyze the project's build tool: check whether the root directory contains vite.config.ts(or .js)、nuxt.config.ts, then decide which injection method to use.

Vite project (vite.config.ts):

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

Nuxt project (nuxt.config.ts):

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

⚠️ Note:additionalData in the path @ alias must match the resolve.alias configuration. If the project uses an absolute path, change it to '@use "/abs/path/to/mixin" as *;\n'. After configuration, all .scss files are automatically injected, and components no longer need @use。

Breakpoint quick reference (most commonly used):

Breakpoint name Range Typical scenario
'<=pad_v' ≤840px Phone + tablet portrait
'pad_h' 841–1200px Tablet landscape
'<=pad' ≤1200px All mobile devices (isPhonePad)
'>pad' ≥1201px Desktop
'laptop' 1201–1680px Laptop
'>laptop' ≥1681px Large screen

Hover mixin quick reference:

Scenario Which to use
Change styles on mouse hover (skip on touch devices) @include hover { ... }
A segment of styles only for devices that support hover (persistent, not transient) @include hoverable { ... }
A segment of styles only for touch devices @include hoverable(none) { ... }
expand/collapse arrow rotation animation @include x-hover
SVG rotation animation with overflow clipping @include x-svg-hover

⚠️ Do not write bare @media (hover: hover) or @media breakpoint queries, and always use the corresponding mixin to stay consistent with the component library behavior.

Component Index

Each component's reference documentation is split into three files by purpose:

  • {name}.visual.md — Visual identification (visual feature fingerprints, Token→Prop mapping, distinguishing easily confused components)
  • {name}.usage.md — Code usage (API tables, code templates, prop combination quick reference, changelog)
  • {name}.style.md — Style customization (CSS variables, layout structure YAML, responsive behavior tables)
  • OAnchor — Anchor · references/anchor.{visual|usage|style}.md
  • OAvatar / OAvatarGroup — Avatar · references/avatar.{visual|usage|style}.md
  • OBadge — Badge · references/badge.{visual|usage|style}.md
  • OBreadcrumb — Breadcrumb · references/breadcrumb.{visual|usage|style}.md
  • OButton — Button · references/button.{visual|usage|style}.md
  • OCard — Card · references/card.{visual|usage|style}.md
  • OCarousel — Carousel · references/carousel.{visual|usage|style}.md
  • OCascader — Cascader · references/cascader.{visual|usage|style}.md
  • OCascaderV2 — Cascader (PC refactored version) · references/cascader-v2.{visual|usage|style}.md
  • OCheckbox / OCheckboxGroup — Checkbox · references/checkbox.{visual|usage|style}.md
  • OCollapse — Collapse · references/collapse.{visual|usage|style}.md
  • OConfigProvider — ConfigProvider · references/config-provider.{visual|usage|style}.md
  • ODataTable — Data Table (Advanced) · references/data-table.{visual|usage|style}.md
  • ODatePicker series — DatePicker · references/date-picker.{visual|usage|style}.md
  • ODialog — Dialog · references/dialog.{visual|usage|style}.md
  • ODivider — Divider · references/divider.{visual|usage|style}.md
  • ODropdown — Dropdown · references/dropdown.{visual|usage|style}.md
  • OFigure — Image · references/figure.{visual|usage|style}.md
  • OForm / OFormItem — Form · references/form.{visual|usage|style}.md
  • ORow / OCol — Grid · references/grid.{visual|usage|style}.md
  • OIcon — Icon · references/icon.{visual|usage|style}.md
  • OInput — Input · references/input.{visual|usage|style}.md
  • OInputNumber — Input Number · references/input-number.{visual|usage|style}.md
  • OIpInput — IP Address Input · references/ip-input.{visual|usage|style}.md
  • OLayer — Float Layer · references/layer.{visual|usage|style}.md
  • OLink — Link · references/link.{visual|usage|style}.md
  • OLoading — Loading · references/loading.{visual|usage|style}.md
  • OMenu — Menu · references/menu.{visual|usage|style}.md
  • OMessage — Message · references/message.{visual|usage|style}.md
  • OPagination — Pagination · references/pagination.{visual|usage|style}.md
  • OPopover — Popover · references/popover.{visual|usage|style}.md
  • OPopup — Popup · references/popup.{visual|usage|style}.md
  • OProgress — Progress · references/progress.{visual|usage|style}.md
  • ORadio / ORadioGroup — Radio · references/radio.{visual|usage|style}.md
  • ORate — Rate · references/rate.{visual|usage|style}.md
  • OResult — Result · references/result.{visual|usage|style}.md
  • OScrollbar / OScroller — Scrollbar · references/scrollbar.{visual|usage|style}.md
  • OSelect — Select · references/select.{visual|usage|style}.md
  • OSkeleton — Skeleton · references/skeleton.{visual|usage|style}.md
  • OSlider — Slider · references/slider.{visual|usage|style}.md
  • OStep / OStepItem — Steps · references/step.{visual|usage|style}.md
  • OSwitch — Switch · references/switch.{visual|usage|style}.md
  • OTab / OTabPane — Tabs · references/tab.{visual|usage|style}.md
  • OTag — Tag · references/tag.{visual|usage|style}.md
  • OTextarea — Textarea · references/textarea.{visual|usage|style}.md
  • OTimePicker series — TimePicker · references/time-picker.{visual|usage|style}.md
  • OToast — Toast · references/toast.{visual|usage|style}.md
  • OToggle — Select Block · references/toggle.{visual|usage|style}.md
  • OUpload — Upload · references/upload.{visual|usage|style}.md
  • OVirtualList — Virtual List · references/virtual-list.{visual|usage|style}.md

Pixso MCP Design Recognition Guide

When reading design file nodes through Pixso MCP, use this section to map layer data to OpenDesign components, then call that component's references/{name}.visual.md to get visual identification information,references/{name}.usage.md to get the full API.

Matching Process

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

① Layer name keyword recognition

Pixso layers or component instance names usually contain the following keywords and can be mapped directly:

Name contains (case-insensitive) Preferred matching component Reference
button / btn / button OButton references/button.visual.md
input / input field / text-field OInput references/input.visual.md
textarea / text area / multiline input OTextarea references/textarea.visual.md
input-number / number input OInputNumber references/input-number.visual.md
ip-input / IP input OIpInput references/ip-input.visual.md
select / dropdown / dropdown-select OSelect references/select.visual.md
cascader / cascade OCascader references/cascader.visual.md
checkbox / multi-select box / checkbox OCheckbox references/checkbox.visual.md
radio / radio button ORadio references/radio.visual.md
switch / toggle switch OSwitch references/switch.visual.md
slider / slider OSlider references/slider.visual.md
toggle / selection block OToggle references/toggle.visual.md
tag / tag OTag references/tag.visual.md
badge / badge / corner badge OBadge references/badge.visual.md
progress / progress bar / progress ring OProgress references/progress.visual.md
rate / rating / star rating ORate references/rate.visual.md
result / result page OResult references/result.visual.md
skeleton / skeleton screen / placeholder OSkeleton references/skeleton.visual.md
loading / loading OLoading references/loading.visual.md
message / message / notification bar OMessage references/message.visual.md
toast / light toast / floating toast OToast references/toast.visual.md
dialog / dialog / modal ODialog references/dialog.visual.md
popover / popover OPopover references/popover.visual.md
popup / popup layer OPopup references/popup.visual.md
dropdown / dropdown menu ODropdown references/dropdown.visual.md
layer / floating layer OLayer references/layer.visual.md
card / card OCard references/card.visual.md
carousel / slideshow / carousel OCarousel references/carousel.visual.md
collapse / collapse OCollapse references/collapse.visual.md
menu / menu / sidebar-nav OMenu references/menu.visual.md
tab / tab page OTab references/tab.visual.md
step / step bar OStep references/step.visual.md
breadcrumb / breadcrumb OBreadcrumb references/breadcrumb.visual.md
anchor / anchor OAnchor references/anchor.visual.md
pagination / pagination OPagination references/pagination.visual.md
figure / image / image OFigure references/figure.visual.md
icon / icon OIcon references/icon.visual.md
link / link OLink references/link.visual.md
divider / divider ODivider references/divider.visual.md
upload / upload OUpload references/upload.visual.md
scrollbar / scroller / scroll OScrollbar references/scrollbar.visual.md
virtual-list / virtual list OVirtualList references/virtual-list.visual.md
data-table / table / table ODataTable references/data-table.visual.md
row / col / grid / grid ORow/OCol references/grid.visual.md
form / form OForm references/form.visual.md

② Visual structure feature quick reference

When the name cannot be matched, based on the layer'sgeometric shape + internal content + layout directiondetermine:

Interactive control

Visual feature Component Reference
Rounded rectangle + text, with filled background or stroke, clickable to trigger an action OButton references/button.visual.md
Horizontal rectangular stroked box + internal text/placeholder, allows free character input OInput references/input.visual.md
Horizontal rectangular stroked box + internal text + fixed chevron down arrow on the right OSelect references/select.visual.md
Multiline input area, with stroke, supports vertical stretching (or fixed-height multiline) OTextarea references/textarea.visual.md
Number input box + left and right (or up and down) increment/decrement control buttons OInputNumber references/input-number.visual.md
Four segmentshorizontal input box, each segment accepts 0-255, with a dot between segments . separator OIpInput references/ip-input.visual.md
Smallsquarebox (or check icon) + label text on the right OCheckbox references/checkbox.visual.md
Smallcircularbox (with inner dot state) + label text on the right ORadio references/radio.visual.md
Horizontalcapsule-shapedtrack + circular slider (two states on/off, no value) OSwitch references/switch.visual.md
Horizontallong bartrack + draggable circular thumb (with value tick marks) OSlider references/slider.visual.md
rectangular/capsule-shaped area + text,can toggle between selected/unselectedtwo states OToggle references/toggle.visual.md
multi-levelprogressively expandingdropdown panel (triggers the next level upon selection) OCascader references/cascader.visual.md

Status / feedback type

Visual features Component Reference
small rounded rectangle or capsule + short text,embedded in the content flowin OTag references/tag.visual.md
floating over other elementstop-right corner/cornersmall dot or numeric bubble OBadge references/badge.visual.md
Horizontalthin-line progress bar(with a background track, read-only display of percentage) OProgress(line) references/progress.visual.md
circular progress ring(read-only display of percentage) OProgress(circle) references/progress.visual.md
a row of ★ star icons (partially filled or half-filled) ORate references/rate.visual.md
pagecentered large icon + bold title + description text (success/warning/error status page) OResult references/result.visual.md
multiplegray rectangular placeholder blocks, simulating text/image loading OSkeleton references/skeleton.visual.md
spinning animation icon or full-screen overlay + "Loading" text OLoading references/loading.visual.md
horizontal bar embedded in the page content flow, containing icon + text (does not disappear automatically) OMessage references/message.visual.md
floats above the pageshort prompt bar appearing at the bottom or top, with a disappearing animation OToast references/toast.visual.md

Navigation / structural type

Visual features Component Reference
horizontal text > text > text chained structure (separated by arrows/slashes) OBreadcrumb references/breadcrumb.visual.md
vertical side navigation, hierarchyindentation, with collapsible sub-items and selected highlight OMenu references/menu.visual.md
top horizontaltab row + belowswitchable content area OTab references/tab.visual.md
horizontal numbers/iconssequence + connecting lines(process steps) OStep references/step.visual.md
vertically arrangedanchor link list, usually floating on the side of the page OAnchor references/anchor.visual.md
Horizontalnumeric page button group(including previous/next page, jump input) OPagination references/pagination.visual.md

Container / overlay type

Visual features Component Reference
rounded rectangle card, with insidecover image/icon + title + description + actionsstructure OCard references/card.visual.md
centered modal + semi-transparent full-screen overlay + title bar + close button ODialog references/dialog.visual.md
small popup attached to the trigger element,with a pointing arrow OPopover references/popover.visual.md
menu panel expanding against the trigger element,no pointing arrow ODropdown references/dropdown.visual.md
generic popup container (has no style of its own, positioned near the trigger element) OPopup references/popup.visual.md
generic overlay/full-screen floating layer container (no fixed internal structure) OLayer references/layer.visual.md
expandable/collapsible content panel,Clickable header area for switching OCollapse references/collapse.visual.md
Horizontal or verticalFlexible columnLayout container (arranges child elements with flex) ORow/OCol references/grid.visual.md
Form container, inside areLabel + controlarranged in pairs OForm references/form.visual.md

Media / Other

Visual features Component Reference
Image container (fixed aspect ratio rectangle, hover to preview/zoom) OFigure references/figure.visual.md
Multiple images/content carousel, with indicator dots and left/right switch arrows OCarousel references/carousel.visual.md
Dashed borderarea + upload icon + hint text OUpload references/upload.visual.md
Long list container, withcustom scrollbarstyle OScrollbar/OScroller references/scrollbar.visual.md
Multiple rows and columnsTable(with header, supports sorting/filtering/multi-select) ODataTable references/data-table.visual.md
PureText + underline, click to navigate, no background or border OLink references/link.visual.md
Single SVG icon element OIcon references/icon.visual.md
Horizontal or verticalThin line divider ODivider references/divider.visual.md
Very long list,list items outside the visible area are not rendered OVirtualList references/virtual-list.visual.md

③ Common ambiguity identification rules

Ambiguous scenario Basis for judgment
OButton vs OLink Button has a background color or an outlined rectangular box; Link is pure text (optionally underlined), with no background/border
OButton vs OTag Button height is usually ≥32px, triggers primary actions; Tag height is usually ≤24px, marks status or category, does not trigger primary actions
OTag vs OBadge Tag appears independently in the text flow/list; Badge overlaysin the corner of other elements (with absolute positioning offset)
OSelect vs OInput Select has on the right afixedchevron down arrow, click to expand the option list; Input has no arrow, allows free typing
OSelect vs ODropdown Select's trigger is fixed as an input box style; Dropdown's trigger can be any content (button, icon, etc.)
ODropdown vs OPopover Dropdown content is a menu option list, with no pointing arrow; Popover content is free-form, with a small triangular arrow pointing to the trigger element
OMessage vs OToast Message is embedded in the page content flow (inline),does not auto-dismiss; Toast floats above the page, withauto-dismisstimer
ODialog vs OLayer Dialog has a fixed three-part structure of title bar + close button + bottom action area; Layer is a generic floating layer with no preset structure
OCollapse vs OTab When Collapse expands, the content is below the titleexpands vertically, multiple items can be expanded at the same time; Tab switches horizontally,only one panel is shown at a time
OProgress vs OSlider Progress only displays progress (read-only, no interactive handle); Slider has a draggable circular thumb (interactive)
OSwitch vs OCheckbox Switch is acapsule-shapedtoggle, expressing the overall on/off state; Checkbox issquare, used for multi-select list scenarios
OCard vs ordinary container OCard has a cover image/icon, title, and content area'sfixed internal structure; a regular div container has no internal partition conventions

④ Pixso visual attributes → Props mapping

Color / Theme (color + variant)

Pixso visual representation prop Value
Bluesolid fill background, white text color + variant color="primary" variant="solid"
Bluestroke, transparent interior, blue text color + variant color="primary" variant="outline"
no fill, no stroke,text onlyBlue color + variant color="primary" variant="text"
gradientfill background (brand-exclusive gradient color) color + variant color="brand" variant="solid"
gray/neutral fill or stroke color color="normal"
green tones color color="success"
orange/yellow tones color color="warning"
red tones color color="danger"

⚠️ color="brand" only for gradient solid buttons(--o-color-main2 gradient background), regular blue buttons (solid/outline/text) always use color="primary"。

Size (size)

Pixso element height (reference value) size Value
≈24px "small"
≈32px "medium"(default, may be omitted)
≈40px "large"

Corner radius (round)

Pixso corner radius characteristic round Value
corner radius = half the height (fully rounded capsule) round="pill"
specific value (e.g., 8px, 12px) round="8px" / round="12px"
standard small corner radius (within 4px) usually the default value, no need to pass

State

Pixso visual representation prop
reduced opacity (opacity ≈ 0.4), non-interactive disabled
contains a rotating animation icon loading

⑤ Complete matching example

Pixso layer information: rounded rectangle (border-radius: 20px, height: 40px), brand blue fill background, white text "Submit", with an SVG icon layer on the right.

Matching process:

  1. layer name contains "button" → OButton
  2. visual features: rounded rectangle + text + fill → confirm OButton
  3. visual attribute mapping: brand blue fill → color="brand" variant="solid"; height 40px → size="large"; corner radius 20px = half the height → round="pill"; right-side icon → #suffix slot
  4. call references/button.visual.md

generate code:

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

Style blind spots of INSTANCE nodes and remedies

Problem background

When a Pixso node's type is INSTANCE(component library instance),getNodeDSL only returns the override properties (overrides) of the instance's outer container, without expanding the component's internal child nodes. Specific manifestations:

  • pixDslNodes this nodehas no child nodes(query parentGuid === instanceGuid result is empty)
  • on the node, cornerRadius / fillPaints and other properties belong to theouter container, and do not represent the actual styles of internal elements (such as buttons, icons)
  • the styles of internal elements (such as capsule buttons, icons) are defined by the component master, and in the DSLare completely invisible

Identification method

When parsing the DSL, if the following situations are found, it indicates that a style blind spot has been encountered:

  1. node type === "INSTANCE"
  2. in pixDslNodes cannot find any child nodes with the node guid as parentGuid child node of
  3. In the DSL, cornerRadius is inconsistent with the design mockup visual (e.g., the DSL says 4, but the design mockup looks like a capsule shape)

Remedies

Method 1 (preferred):getImage visual confirmation

Call getImage(itemId)on the INSTANCE node to directly obtain the component rendering image, read all visible visual attributes from the image, and then use the "attribute mapping table" to infer the complete Props.

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

⚠️ When using getImage , you must simultaneously confirm all of the following dimensions; do not look only at the corner radius:

Dimensions to confirm Observe from the image Corresponding Prop
Corner shape Right angle / small rounded corner / capsule shape round
Background color Brand color fill / transparent + stroke / no background pure text variant(solid / outline / text)
Foreground color Blue brand color→color="primary" / gradient brand color→color="brand"(solid only) / gray→color="normal" color
Size Estimated height: ≈24px→small / ≈32px→medium / ≈40px→large size

Method 2: In Pixso, enter the component and select child nodes

In the Pixso design tool, double-click to enter the INSTANCE component, select the target child element (such as an inner button), obtain its item-id, and then call getNodeDSLto get the real style data of the inner element.

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

Typical case

Upload button (上传 Upload/按钮,type: INSTANCE) In the DSL, cornerRadius: 4(outer container),fillPaints: [](no fill information). getImage image shows: capsule shape, blue stroke, blue text "+ Upload File", height about 32px. ✅ Correct approach:<OButton color="primary" variant="outline" size="medium" round="pill"> ❌ Incorrect approach:<OButton color="brand" variant="outline" round="pill">(color="brand" is only used for gradient solid buttons; in outline scenarios, blue should use the color="primary")


OAnchor

size attribute

  • Description: Specifies the size style of the anchor (default value: medium)

container attribute

  • Description: Specifies the scroll container listened to by the anchor (default value: window)
  • Example:container="#wrap" means listening to the scroll event of the container with id wrap

targetOffset attribute

  • Description: The offset from the top of the container when the target element jumps or is activated (default value: 0)

bounds attribute

  • Description: Sets the boundary for determining anchor activation (default value: 5)

changeHash attribute

  • Description: Whether to change the hash value in the browser address bar when clicking an anchor (default value: true)

Anchor nesting:OAnchorItem can be nested to form a multi-level anchor structure

Example code

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

For detailed usage instructions and the complete attribute list, see references/anchor.usage.md


OBadge

The badge includes primary、success、warning、danger four theme colors.

Badge value parameter supports both numeric and text values; when it is numeric, max parameter affects the display of the value.

The badge supports a small red dot style; the badge content is not displayed in the small red dot.

The badge can set an offset position via offset .

For detailed usage instructions and the complete attribute list, see references/badge.usage.md


OBreadcrumb

Set the link jump address via the href attribute, or use to property together with Vue Router to implement route navigation. When href and to properties are both unset, theOBreadcrumbItem component will use the span tag to render as plain text (beneficial for SEO).

href property and the target property are used in combination; theto property and the replace property are used in combination; when both the href property and the to property are passed at the same time, the to form of navigation will be used with priority.

Example code

<OBreadcrumb>
  <OBreadcrumbItem>Home</OBreadcrumbItem>
  <OBreadcrumbItem>Category</OBreadcrumbItem>
  <OBreadcrumbItem>Current Page</OBreadcrumbItem>
</OBreadcrumb>

For detailed usage instructions and the complete property list, see references/breadcrumb.usage.md


OButton

Theme color color:normal(default),brand

Size size:small、medium(default),large

Shape variant:solid、outline(default),text

Disabled:disabled

Loading state:loading

Rounded corner round:

  • round="pill" set to semi-rounded corner
  • round="16px" set a specific rounded corner value (with unit)
  • Supports any value of border-radius any value of

Other properties:

  • href — after being set, renders with the <a> tag
  • icon — button icon (Component)
  • tag — root tag type (default button)

Slots:default(content),icon(icon),suffix(suffix)

Events:@click="(evt: MouseEvent) => void"

Example code

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

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

For detailed usage instructions and the complete property list, see references/button.usage.md


OCard

OCard is divided into image-text cards and icon cards.

Image-text card: set the image link for cover , set the image aspect ratio via coverRatio , set the image fill mode via coverFit set image fill mode

Icon card: set a value (image link or component) for icon set value (image link or component)

Set the card layout mode via layout set card layout mode (vertical/horizontal/horizontal-reverse)

Set the card title:

  • title — title content
  • titleRow — title height (number of lines)
  • titleMaxRow — maximum number of title lines (overflow shows an ellipsis)
  • titleIcon — icon at the start of the title

Set the card content:

  • detail — card content
  • detailRow — content height (number of lines)
  • detailMaxRow — maximum number of content lines
  • textOverflow — text overflow handling method (ellipsis or fade)

Other:

  • hoverable — mouse hover shadow
  • href — navigation link (after being set, renders with the <a> tag)
  • cursor — mouse hover style
  • noResponsive — disable responsive size

For detailed usage instructions and the complete property list, see references/card.usage.md


OCarousel

The slideshow has two playback effects:

  • effect="gallery"(default) — scrolling effect
  • effect="toggle" — switching effect

Autoplay:autoPlay、interval(default 5000ms),pauseOnHover

Indicators:hideIndicator、indicatorClick

Arrows:arrow(hover/always/never)

Other:clickToSwitch、manualInit、activeIndex(supports two-way binding)

For detailed usage instructions and the complete property list, see references/carousel.usage.md


OCascader

Selected value: bound two-way via v-model , type is CascaderValueT

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

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

Properties:

  • options — option data (CascaderOptionT[])
  • round — rounded corner
  • variant — button style:solid/outline/text
  • optionPosition — option box position (top/bottom/left/right/tl/tr/bl/br/lt/lb/rt/rb)

Example code

<OCascader v-model="selectedValue" :options="options" />

For detailed usage instructions and the complete property list, see references/cascader.usage.md


OCheckbox / OCheckboxGroup

Checkbox value:

  • value — set the value contained in modelValue when selected
  • modelValue type is Array<string | number>

Indeterminate:indeterminate="true" is in the indeterminate state when

Checkbox group: can be used alone OCheckbox, or nested in OCheckboxGroup to uniformly manage v-model。

Example code

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

For detailed usage instructions and the complete property list, see references/checkbox.usage.md


OCollapse

Through the accordion property, enable accordion mode (only one item is expanded at a time).

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

For detailed usage instructions and the complete property list, see references/collapse.usage.md


OConfigProvider

Global configuration component; it does not render any visible content itself, and injects unified configuration into descendant components through Vue provide/inject.

Properties:

  • locale — language entry object ({ locale: string; [key: string]: string }), with higher priority than the global useLocale() setting. Entries support the {0} placeholder for variable substitution
  • link — OLink global click configuration ({ click: (e, params, attrs) => void }), triggered only when the OLink global property is true (default)

Slots:default(child component content)

Example code

<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>

For detailed usage instructions and the complete property list, see references/config-provider.usage.md


ODataTable

Advanced data table, supporting complex features such as sorting, filtering, multiple selection, and column width adjustment.

Main properties:

Property Type Description
data TableRowT[] Table data (required)
columns DataTableColumnT[] Column configuration (required)
size 'medium' | 'small' Size (default medium)
height number | string Table height
maxHeight number | string Maximum height (default fit-content)
rowKey string Row unique key (default 'id')
border TableBorderT Border style (default 'row')
stripe boolean Zebra stripes
loading boolean Loading state
highlightCurrentRow boolean Highlight current row
columnResizable boolean Column widths adjustable
spanMethod Function Cell merge method

Two-way binding (v-model):

  • v-model:conditions — filter conditions
  • v-model:selection-keys — list of selected row keys

Slots:

  • #th_{key} — custom column header
  • #td_{key} — custom cell,props: { column, row, cellValue, index }
  • #header — customize the entire header
  • #loading / #empty — loading/empty state

Events:

  • @condition-update — filter conditions update
  • @sort-update — sort update
  • @selection / @selection-change / @selection-all — selection related

Example code

<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>

For detailed usage instructions and the complete property list, see references/data-table.usage.md


ODialog

Size size:exlarge、large、medium(default),small、auto

  • auto — automatically resize based on content
  • Fixed size — has a fixed width, height changes with content

Responsive: by default adjusts based on viewport size,noResponsive="true" disables

Mobile half-screen:phoneHalfFull="true" displays full-width at the bottom on small screens (<600px)

For detailed usage instructions and a complete property list, see references/dialog.usage.md


ODivider

variant:solid(solid),dashed(dashed),dotted(dotted)

direction:h(horizontal, fills the container by default),v(vertical, default height 1em)

darker:true(dark) / false(light)

Label (horizontal divider only):

  • labelPosition:left、center、right
  • Label content is placed in the default slot
<ODivider direction="h" variant="dashed" label-position="center">
  分隔文字
</ODivider>

For detailed usage instructions and a complete property list, see references/divider.usage.md


ODropdown

Trigger method:none、click、click-outclick、hover、hover-outclick、focus、contextmenu

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

Example code

<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>

For detailed usage instructions and a complete property list, see references/dropdown.usage.md


OFigure

ratio — Image aspect ratio (implemented via padding-top percentage)

fit(default contain):

  • background=false(<img> tag):cover/contain/fill/none/scale-down
  • background=true(background image):cover/contain/auto/percentage

hoverable — Hover zoom effect (automatically enabled when href/preview/videoPoster is set)

preview — Click to preview (takes over click events when enabled)

previewClose — Preview close method:'none'/'mask'/'button'/'body', supports array combinations

href — Link (rendered as <a> tag)

Note:preview and href cannot be used at the same time

For detailed usage instructions and a complete property list, see references/figure.usage.md


OForm / OFormItem

OForm properties:

  • layout:h(horizontal),v(vertical),inline(inline)
  • labelAlign:top/center/bottom
  • labelJustify:left/center/right
  • labelWidth: Label width (recommended for PC horizontal layout 96px)
  • hasRequired: Show required asterisk

Supported form items:OInput、OInputNumber、OTextarea、OSelect、OCheckboxGroup、ORadioGroup、OUpload

Multi-column form grid layout rules

In a multi-column form, the width of each OFormItem must align to grid columns (see section 3 "Form component grid rules" of the opendesign-tokens skill).

Breakpoint Items per row Width per item layout labelWidth
>1200px (desktop/laptop) 4 items/row var(--o-r-grid-6) h 96px
841–1200px (tablet landscape) 3 items/row var(--o-r-grid-4) h 96px
≤840px (phone) 1 item/row Full width v —

Row spacing:32px(>840px horizontal layout) / 12px(≤840px stacked layout); in horizontal mode, Hint leaves 24px on the right side of the input box.

Example code

<!-- 桌面端 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>

For detailed usage instructions and a complete property list, see references/form.usage.md


ORow / OCol

ORow properties:

  • align — Cross-axis alignment
  • justify — Main-axis alignment
  • wrap — flex-wrap value
  • direction — flex-direction value
  • gap / gapX / gapY — Child element spacing
  • inline — Use inline-flex
  • Responsive properties:pcS、laptop、pad、padV、phone(controls gap at different breakpoints)

OCol properties:

  • flex — flex style value
  • align — Cross-axis alignment
  • Responsive properties:pcS、laptop、pad、padV、phone(controls flex at different breakpoints)

For detailed usage instructions and a complete property list, see references/grid.usage.md


OIcon

General-purpose icon container that displays SVG icons and can also be used as an icon button. Icon size inherits the context font-size (default 1em).

Properties:

  • icon — Icon component (e.g., OIconAdd、OIconEdit)
  • button — Icon button mode (hover/active styles, automatically sets pointer cursor and tabindex)
  • disabled — Disabled (used together with button)
  • loading — Loading state (displays a spinning animation replacing the original icon)

Slot:default(Custom icon content; after use, the icon prop and loading built-in icon will not render)

Example code

<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>

For detailed usage instructions and the complete icon list, please see references/icon.usage.md


OInput

Theme color color:normal(default),success、warning、danger

Size size:small、medium(default),large

Variant variant:solid、outline(default),text

Input type type:text(default),password

Other props:disabled、readonly、clearable、maxLength、placeholder、autoWidth、inputId

Character count showLength:'always'(always displayed),'auto'(default, displayed when maxLength is present),'never'(not displayed)

Excess input inputOnOutlimit: whether input is still allowed when maxLength is exceeded. Default true

Formatting and validation:format(formatter function),validate(validation function),valueOnInvalidChange(whether to update modelValue when validation fails)

Password field:showPasswordEvent(trigger method for toggling plaintext 'click'/'mousedown')、passwordPlaceholder(password placeholder)

round: border radius value (pill or CSS border-radius value)

Slot:prepend、append、prefix、suffix、extra

Event:@update:modelValue、@change、@input、@blur、@focus、@clear、@pressEnter

Exposed methods:focus()、blur()、clear()、inputEl()、togglePassword()

Example code

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

For detailed usage instructions and the complete props list, please see references/input.usage.md


OInputNumber

Number input box, supports step control.

Props:

Prop Type Description
modelValue number Bound value (v-model)
step number Step (default 1)
min number Minimum value
max number Maximum value
controls 'both' | 'right' | 'left' | 'none' Control button position (default 'both')
clearable boolean Clearable
disabled boolean Disabled
readonly boolean Read-only
size SizeT Size
variant VariantT Variant
color Color2T Theme color
placeholder string Placeholder text
format Function Formatter function

Slot:prefix、suffix、plus(plus button),minus(minus button)

Event:@change、@input、@blur、@focus、@clear、@pressEnter、@plus、@minus

Example code

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

For detailed usage instructions and the complete props list, please see references/input-number.usage.md


OIpInput

IP address input box, automatically segments IPv4 addresses.

Props:

Prop Type Description
modelValue string Bound value (v-model), format such as "192.168.1.1"
disabled boolean Disabled
readonly boolean Read-only
segmentsLen number Number of segments (default 4, i.e. IPv4)
size SizeT Size
round RoundT Border radius
color string Theme color (default 'normal')
variant string Variant (default 'outline')

Event:

  • @update:modelValue — (value: string) => void
  • @change — (valid: boolean, ip: string) => void(valid indicates whether it is a valid IP)

Example code

<OIpInput v-model="ipAddress" @change="(valid, ip) => console.log(valid, ip)" />

For detailed usage instructions and the complete props list, please see references/ip-input.usage.md


OLayer

transitionOrigin: origin of the content box scale animation:

  • 'mouse'(default) — mouse click position
  • 'css' — set via CSS variable --layer-origin Settings

wrapper: parent node for rendering the overlay:

  • 'body'(default) — rendered to body,position: fixed
  • string-selector — via querySelector Element to query
  • HTMLElement — Specify the element directly
  • null — Renders under the current element,position: absolute

mask: Whether to render the mask layer

maskClose: Whether to close the popup when the mask layer is clicked

buttonClose: Whether to render the close button

For detailed usage instructions and the complete property list, see references/layer.usage.md


OLink

Theme color color:normal、primary、success、warning、danger

Size size:auto、small、medium、large

Navigation method target:_blank、_parent、_self、_top

Status:disabled、loading

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

For detailed usage instructions and the complete property list, see references/link.usage.md


OLoading

Via the label property, control the text displayed during loading;

Via the icon property, customize the icon shown during loading;

Via the iconRotating property, control whether the custom loading icon rotates;

Other properties are used in the same way as OLayer.

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

For detailed usage instructions and the complete property list, see references/loading.usage.md


OMenu

Size size:small、medium(default)

Use the accordion property to enable accordion mode;

Use the expanded property to control the expanded node values;

Use subMenu 's icon to control the menu icon (small size does not support custom icons);

Use selectable to control whether subMenu itself can be selected;

Use the CSS variable --menu-item-base-indent、--sub-menu-base-indent to control the indent distance per level.

<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>

For detailed usage instructions and the complete property list, see references/menu.usage.md


OMessage

Inline usage:

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

For detailed usage instructions and the complete property list, see references/message.usage.md


OPagination

layout: Set the displayed controls (array combination):

  • total — Total data count label
  • pagesize — Items per page selector
  • pager — Page number buttons
  • jumper — Page number jump input

variant:outline(default) / solid

showPageCount: Maximum number of page number buttons to display

showMore: Whether to show the omitted page numbers when hovering over the ellipsis button

simple: Whether to use the simple layout (once enabled, layout and showPageCount become invalid)

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

For detailed usage instructions and the complete property list, see references/pagination.usage.md


OPopover

OPopover is a popover card component built on OPopup , with adjusted default values for trigger method, offset, and anchor.

  1. Popup position:position property
  2. Trigger method:trigger property
  3. Distance from the trigger target:offset property
  4. Width setting:adjustMinWidth、adjustWidth
  5. Mount container class name:wrapClass

Example code

<OPopover>
  <div>气泡内容文本</div>
  <template #target>
    <OButton round="pill">触发按钮</OButton>
  </template>
</OPopover>

For detailed usage instructions and the complete property list, see references/popover.usage.md


OPopup

General popup layer component,OPopover、ODropdown、OSelect the underlying implementation of components such as .

  1. visible — Display state (two-way binding)
  2. position — Popup position
  3. trigger — Trigger method
  4. offset — Distance from the trigger target
  5. anchor — Popup anchor
  6. adjustMinWidth、adjustWidth — Width setting
  7. wrapClass — Mount container class name
  8. bodyClass — Content body class name

Slots:default(popup content),target(trigger target),anchor(anchor content, rendered when theanchor property is true)

Events:@update:visible、@change

For detailed usage instructions and the full list of properties, see references/popup.usage.md


OProgress

Type type:line(default),circle

Size size:medium(default),small

Color color:primary、success、warning、danger

Other properties:

  • percentage — progress percentage (0-100)
  • strokeWidth — progress bar line width
  • trackWidth — progress bar track width
<OProgress type="line" :percentage="60" color="primary" />
<OProgress type="circle" :percentage="75" color="success" :stroke-width="8" />

For detailed usage instructions and the full list of properties, see references/progress.usage.md


ORadio / ORadioGroup

Radio value:

  • value — sets the value of modelValue after selection
  • modelValue type is string | number | boolean

Radio group: use ORadioGroup to wrap multiple ORadio, managing v-model。

Example code

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

For detailed usage instructions and the full list of properties, see references/radio.usage.md


ORate

Rating component, supports half stars, clearing, and custom icons.

Properties:

Property Type Default Description
modelValue number — Bound value (v-model)
defaultValue number 0 Default value in uncontrolled mode
count number 5 Total number of stars
size 'large' | 'medium' — Size
color ColorT 'normal' Theme color
readonly boolean false Read-only
allowHalf boolean false Allow half stars
clearable boolean false Clearable (clears when the same value is clicked again)
labels string[] — Description text for each star level

Slots:

  • #icon — custom star icon,props: { index: number, status: RateItemStatusT }

Events:

  • @update:modelValue — (val: number) => void
  • @change — (val: number) => void

Example code

<ORate v-model="score" :count="5" allow-half clearable />
<ORate v-model="score" readonly :labels="['很差', '较差', '一般', '较好', '很好']" />

For detailed usage instructions and the full list of properties, see references/rate.usage.md


OResult

  1. status — display state:info、success、warning、danger
  2. title — result title
  3. description — supplementary description

Example code

<OResult status="success" title="提交成功" description="您的申请已成功提交,请等待审核" />

For detailed usage instructions and the full list of properties, see references/result.usage.md


OScrollbar / OScroller

Size size:medium(default),small

Display mode visibility:auto(default),always、hover、never

auto mode, via duration controls how long it continues to display after scrolling stops.

Example code

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

For detailed usage instructions and the full list of properties, see references/scrollbar.usage.md


OSelect

Theme color color:normal(default),success、warning、danger

Size size:small、medium(default),large

Shape variant:solid、outline(default),text

Properties:disabled、multiple、clearable、placeholder、loading

maxTagCount: maximum number of tags to display when multiple selection is enabled

showFoldTags: display mode for collapsed tags (true/false/'hover'/'click')

optionPosition: option box position (same as OCascader)

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

Child components:

  • OOption — single option (label、value、disabled)
  • OOptionGroup — option group (name property sets the group name)

Slots:default(option),empty(empty state),arrow(dropdown arrow, slot props: { active })、suffix(suffix, slot props: { active })、tag-fold(collapsed tags),action(bottom action area)

Events:@change、@clear、@options-visible-change

Example code

<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>

For detailed usage instructions and the full list of properties, see references/select.usage.md


OSlider

Slider component, select values by dragging. Supports single value and range selection, with optional input boxes, tooltips, and custom marks.

Properties:

Property Type Default Description
modelValue number | number[] 0 Bound value (v-model), pass an array for range mode
min number 0 Minimum value
max number 100 Maximum value
step number 1 Step
range boolean false Range selection mode
showStops boolean false Show interval tick marks
showInput boolean false Show input box (non-range mode)
showPopover boolean true Show value bubble
marks Record<number, string | { style, label }> — Custom marks
unit string — Input box unit text
disabled boolean false Disabled

Slots:unit(replaces the input box unit text)

Events:@input(triggered in real time during sliding),@change(triggered after sliding ends)

Example code

<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: '高' }" />

For detailed usage instructions and the complete property list, see references/slider.usage.md


OSkeleton

  1. loading — controls skeleton screen visibility (shows real content when false)
  2. animation — animation effect (wave/noneetc.)
  3. rows — number of text lines displayed

Example code

<OSkeleton :loading="isLoading" :rows="3">
  <div>真实内容</div>
</OSkeleton>

For detailed usage instructions and the complete property list, see references/skeleton.usage.md


OStep / OStepItem

Steps component, used to display task process progress.

OStep properties:

  • direction:'h'(horizontal, default) / 'v'(vertical)

OStepItem properties:

Property Type Default Description
title string — Step title
description string — Step description
status 'finished' | 'processing' | 'waiting' | 'failed' 'finished' Status
stepIndex number — Step number (required)
icon boolean | Component — Custom icon

Example code

<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>

For detailed usage instructions and the complete property list, see references/step.usage.md


OSwitch

Size size:small、medium(default)

Status:disabled、loading

round: border radius value

Custom value: via checkedValue、uncheckedValue customize the values for checked/unchecked states

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

For detailed usage instructions and the complete property list, see references/switch.usage.md


OTab / OTabPane

OTab properties:

Property Type Default Description
modelValue string | number — Currently active tab (v-model)
variant 'solid' | 'text' | 'button' 'text' Tab style
size SizeT — Size
round RoundT — Border radius
lazy boolean — Lazy loading (render only on first display)
addable boolean — Whether new tabs can be added
maxShow number — Maximum number of tabs to display (excess is collapsed)
line boolean true Whether to show the bottom line
headerClass string | Array | Object — Custom class name for the header

OTabPane properties:

Property Type Default Description
value string | number — Identifier value
label string — Tab text
disabled boolean false Disabled
closable boolean false Whether closable
lazy boolean false Lazy loading
unmountOnHide boolean false Unmount when hidden

OTab slots:prefix(header prefix),suffix(header suffix)

OTab events:

  • @change — (value, oldValue) => void
  • @delete — (value) => void(triggered when a tab is closed)
  • @add — (evt: MouseEvent) => void(triggered when the add button is clicked)

Example code

<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>

For detailed usage instructions and the complete property list, see references/tab.usage.md


OTag

Theme color color:normal(default),info、primary、success、warning、danger、pending(blue pending state),disabled(gray disabled state),main2(brand gradient)

Shape variant:solid(default),outline

Size size:large(default),medium、small

round: border radius value

interactive state:interactive(new in v1.2.6; when set to true, background/border changes on hover;closable automatically enabled when true)

closable:closable、v-model:visible(controls show/hide),beforeClose(before-close hook)

Slots:default(text content),icon(icon)

Events:@close、@update:visible

Example code

<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>

For detailed usage instructions and the complete property list, please see references/tag.usage.md


OTextarea

Theme color color:normal(default),success、warning、danger

Size size:small、medium(default),large

Shape variant:solid、outline(default),text

Properties:disabled、readonly、clearable、maxLength、showLength、placeholder

autoSize: automatically adjust height (true or { minRows, maxRows })

resize: adjustment method (none/vertical/horizontal/both)

scrollbar: whether to show the scrollbar

Slots:prepend、append、suffix

Events:@update:modelValue、@change、@input、@blur、@focus、@clear

Exposed methods:focus()、blur()、clear()、inputEl()

Example code

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

For detailed usage instructions and the complete property list, please see references/textarea.usage.md


OToast

Lightweight toast component, used for instant feedback after an action. Supports inline usage and imperative invocation (useToast)。

Inline properties:

  • visible(v-model) — whether visible
  • message — prompt text
  • duration — auto-dismiss time (ms); if not passed or ≤0, it will not auto-dismiss
  • position — positioning direction:'top'、'center'、'bottom'(default)
  • long — long prompt mode (imperative default 3500ms)
  • beforeClose — before-close hook

Imperative invocation:

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

Imperative default duration: 2000ms(3500ms in long mode),position: 'bottom'. Supports targetAlign/targetOffset to position near the specified target element.

Slots:default(replaces the prompt content; after use, message becomes invalid)

Events:@duration-end、@close

Example code

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

For detailed usage instructions and the complete property list, please see references/toast.usage.md


OToggle

Selection block, a form control that indicates the current state and provides a toggle action.

Properties:

  • checked (v-model:checked) — two-way binding of the checked state
  • defaultChecked — whether checked by default in uncontrolled mode
  • round — border radius value
  • icon — prefix icon
  • disabled — disabled

Can be used with ORadio、ORadioGroup to implement single selection.

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

For detailed usage instructions and the complete property list, please see references/toggle.usage.md


OUpload

Properties:

Properties Type Description
modelValue FileItem[] File list (v-model)
accept string MIME type restrictions
disabled boolean Disabled
multiple boolean Multiple selection
draggable boolean Drag-and-drop upload
listType string File list type
lazyUpload boolean Delayed upload timing
btnLabel string Button text
onAfterSelect Function Callback after selection
uploadRequest Function Custom upload request

Example code

<OUpload
  v-model="fileList"
  accept=".jpg,.png"
  multiple
  draggable
  :upload-request="handleUpload"
/>

For detailed usage instructions and the complete property list, please see references/upload.usage.md


OVirtualList

Virtual scrolling list for high-performance rendering of large amounts of data.

Property:

Property Type Default Description
list unknown[] [] Data list (required, must contain id)
itemSize number | ((item, index) => number) — Item height. Number = fixed height; function = per-item height; not passed = variable height (measured at runtime)
defaultItemSize number 80 Estimated default height for each item when height is variable
buffer number 1 Buffer multiplier (extra rendering amount above and below relative to the visible area)
defaultStartIndex number 0 Initial index to scroll to
scrollbar boolean | Object true Scrollbar configuration
layout 'vertical' | 'horizontal' 'vertical' Layout direction (added in v1.2.6)
threshold number | null null Data volume threshold, below which virtualization is not enabled (added in v1.2.6)

Slots:

  • #default — list item template,props: { item: any, index: number }

Events:

  • @renderChange — rendering range changes,props: { start, end, visible, count }

Exposed methods:

  • scrollToView(index, align?, behavior?) — scroll to the specified index item. align supports 'start'/'end'/'center'/'nearest'/numeric offset
  • scrollToOffset(px) — scroll to the specified pixel offset (added in v1.2.6)

Example code

<OVirtualList :list="bigDataList" :item-size="60" style="height: 400px;">
  <template #default="{ item, index }">
    <div class="list-item">
      {{ index }}: {{ item.name }}
    </div>
  </template>
</OVirtualList>

For detailed usage instructions and the complete property list, please see references/virtual-list.usage.md


Common combination patterns

Form page

<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>

Data display

<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" />

Interaction feedback

<!-- 对话框 -->
<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="加载中..." />