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:
- Identify the visual structure → Compare each visual area/interactive element in the design mockup against the OpenDesign component list
- 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
- 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
- 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
:deepcases in blocks) - Any rule starting with
:deep(.o-*)Rules at the beginning
Allowed alternatives:
- 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 inmain.tsunified import in - 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 - 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:
- Check whether the mixin file exists: in the project
src/search the directory for files containing@mixin respondof the.scssfiles - If it does not exist: in
src/styles/mixin.scss(or the project's agreed-upon common styles directory), create the initialization file below - 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:
additionalDatain the path@alias must match theresolve.aliasconfiguration. If the project uses an absolute path, change it to'@use "/abs/path/to/mixin" as *;\n'. After configuration, all.scssfiles 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@mediabreakpoint 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.mdto get visual identification information,references/{name}.usage.mdto 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-main2gradient background), regular blue buttons (solid/outline/text) always usecolor="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:
- layer name contains "button" → OButton
- visual features: rounded rectangle + text + fill → confirm OButton
- 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 →#suffixslot - 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:
pixDslNodesthis nodehas no child nodes(queryparentGuid === instanceGuidresult is empty)- on the node,
cornerRadius/fillPaintsand 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:
- node
type === "INSTANCE" - in
pixDslNodescannot find any child nodes with the node guid asparentGuidchild node of - In the DSL,
cornerRadiusis inconsistent with the design mockup visual (e.g., the DSL says4, 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).getImageimage 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 thecolor="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 cornerround="16px"set a specific rounded corner value (with unit)- Supports any value of
border-radiusany value of
Other properties:
href— after being set, renders with the<a>tagicon— button icon (Component)tag— root tag type (defaultbutton)
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 contenttitleRow— 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 contentdetailRow— content height (number of lines)detailMaxRow— maximum number of content linestextOverflow— text overflow handling method (ellipsisor fade)
Other:
hoverable— mouse hover shadowhref— navigation link (after being set, renders with the<a>tag)cursor— mouse hover stylenoResponsive— 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 effecteffect="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 cornervariant— button style:solid/outline/textoptionPosition— 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 inmodelValuewhen selectedmodelValuetype isArray<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 globaluseLocale()setting. Entries support the{0}placeholder for variable substitutionlink— OLink global click configuration ({ click: (e, params, attrs) => void }), triggered only when the OLinkglobalproperty 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 conditionsv-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
defaultslot
<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-downbackground=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/bottomlabelJustify:left/center/rightlabelWidth: Label width (recommended for PC horizontal layout96px)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 alignmentjustify— Main-axis alignmentwrap—flex-wrapvaluedirection—flex-directionvaluegap/gapX/gapY— Child element spacinginline— Useinline-flex- Responsive properties:
pcS、laptop、pad、padV、phone(controls gap at different breakpoints)
OCol properties:
flex—flexstyle valuealign— 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-originSettings
wrapper: parent node for rendering the overlay:
'body'(default) — rendered to body,position: fixedstring-selector— viaquerySelectorElement to queryHTMLElement— Specify the element directlynull— 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 labelpagesize— Items per page selectorpager— Page number buttonsjumper— 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.
- Popup position:
positionproperty - Trigger method:
triggerproperty - Distance from the trigger target:
offsetproperty - Width setting:
adjustMinWidth、adjustWidth - 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 .
visible— Display state (two-way binding)position— Popup positiontrigger— Trigger methodoffset— Distance from the trigger targetanchor— Popup anchoradjustMinWidth、adjustWidth— Width settingwrapClass— Mount container class namebodyClass— 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 widthtrackWidth— 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 ofmodelValueafter selectionmodelValuetype isstring | 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
status— display state:info、success、warning、dangertitle— result titledescription— 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 (nameproperty 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
loading— controls skeleton screen visibility (shows real content when false)animation— animation effect (wave/noneetc.)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 visiblemessage— prompt textduration— auto-dismiss time (ms); if not passed or ≤0, it will not auto-dismissposition— 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 statedefaultChecked— whether checked by default in uncontrolled moderound— border radius valueicon— prefix icondisabled— 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 offsetscrollToOffset(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="加载中..." />