@origen-ui/tabs

OgTabs is a strictly controlled Vue 3 and Element Plus workspace tab component. It never creates, reorders, removes, stores, or navigates tabs itself. Every change is emitted as a request; the consuming application decides whether to update items and modelValue.

<script setup lang="ts">
import type { OgTabItem } from '@origen-ui/tabs'
import { OgTabs } from '@origen-ui/tabs'
import { ref } from 'vue'
import '@origen-ui/tabs/style.css'

const active = ref('overview')
const tabs = ref<OgTabItem[]>([
  { key: 'overview', label: 'Overview', pinned: true },
  { key: 'reports', label: 'Reports', badge: 3, dirty: true },
])
</script>

<template>
  <OgTabs
    v-model="active"
    v-model:items="tabs"
    variant="workspace"
    :features="{ pin: true, finder: true }"
    :context-menu="{ hiddenActions: ['close-all'] }"
    @refresh-request="({ tab }) => reload(tab)"
  >
    <template #default="{ tab }">{{ tab.label }} panel</template>
  </OgTabs>
</template>

Controlled contract

• items is required. defaultItems, defaultActiveKey, maxTabs, actions, add, remove, and internal state are removed.
• update:modelValue and update:items carry proposed values only. Leaving props unchanged leaves the UI unchanged.
• action-request is emitted for every accepted operation. Semantic events include close-request, refresh-request, pin-change-request, and reorder-request.
• OgTabs has one navigation implementation: Element Plus ElTabs and ElTabPane. Closing, pinning, refreshing, dragging, finder, and keyboard actions are configured through features; contextMenu is the single menu configuration entry.
• actionPolicy uses { mode: 'allow' | 'deny', actions }. It preserves both former whitelist and blacklist outcomes without allowing both policies to create an implicit precedence rule.
• dirty communicates unsaved work in both the tab label and finder. It is presentation state; applications decide whether beforeAction permits closing it.
• The finder is an auxiliary navigator for the same native tab strip. It appears when the strip overflows or reaches finderThreshold (default 8).
• Use density="compact" for dense operational screens, and the default density for general workspaces.
• The component defaults to Chinese action, finder, status, and accessibility labels. Pass locale to override individual entries for another language.
• The component has no router, store, cache, persistence, or business dependency.

Styles

Import @origen-ui/tabs/style.css once in the application entry point. The stylesheet is intentionally unscoped so it can style Element Plus descendants; all selectors are rooted in the og-tabs namespace to limit collisions.

Application Defaults

Install createOgTabs() once to supply presentation and feature defaults to every tab surface in one Vue app:

import { createOgTabs } from '@origen-ui/tabs'

app.use(
  createOgTabs({
    variant: 'workspace',
    density: 'compact',
    features: { finder: true, keyboard: true },
    finderThreshold: 12,
    contextMenu: { hiddenActions: ['close-all'] },
  }),
)

Built-in values are resolved before app defaults and instance props. locale, features, contextMenu, and tabsProps are shallow-merged; arrays and callbacks are atomic. items, modelValue, busy, action policies, and action callbacks remain controlled by each component instance, and separate Vue apps do not share configuration.

tabsProps is the typed Element Plus Tabs escape hatch for native presentation options outside OgTabs-owned state. OgTabs applies modelValue and navigation guards last. getNativeTabs() returns the mounted Element Plus Tabs instance.

Migration

This release is breaking. Replace uncontrolled defaults with ref values and own the updates in the parent. Replace add() with a parent-side array update. Move former custom actions into the header or extra slots. Replace beforeClose, beforePin, and other operation-specific guards with beforeAction. Use action-request or semantic request events instead of remove, pinChange, reorder, and limitExceeded. Locking, favorites, grouping, synchronization, middle/double-click actions, custom shortcuts, virtual navigation, and custom overflow handling are removed.

公共契约

由 components.v2.json 自动生成。请先修改公开的 TypeScript 契约，然后运行 pnpm component-contracts:sync 同步。

• 标准导入：import { OgTabs } from '@origen-ui/tabs'
• 核心 props：items, contextMenu, actionPolicy
• 事件：update:modelValue
• 暴露的方法：getNativeTabs