x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/tabs-api.md

@@ -0,0 +1,135 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Tabs 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## TabPane API
+
+公开声明：`dist/components/tabs/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| title | 标签标题 | undefined &#124; string | 否 | 未声明 |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| closable | 是否允许关闭 | undefined &#124; false &#124; true | 否 | true |
+| destroyOnHide | 隐藏时是否销毁内容，优先级高于 Tabs 的全局设置 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type TabsPosition = 'left' | 'right' | 'top' | 'bottom';
+
+type TabsType = 'line' | 'card' | 'card-gutter' | 'text' | 'rounded' | 'capsule';
+
+interface TabData {
+    key: string | number;
+    title?: string;
+    disabled?: boolean;
+    closable?: boolean;
+    slots: Slots;
+    /** tab 自身 id，供 panel 的 aria-labelledby 引用（TabPane 按实例 uid 生成） */
+    tabId?: string;
+    /** 对应 panel 的 id，供 tab 的 aria-controls 引用 */
+    panelId?: string;
+}
+
+type TabTriggerEvent = 'click' | 'hover';
+
+type ScrollPosition = 'start' | 'end' | 'center' | 'auto' | number;
+```
+
+
+## Tabs API
+
+公开声明：`dist/components/tabs/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| activeKey | 当前激活标签 key | undefined &#124; string &#124; number | 否 | undefined |
+| defaultActiveKey | 默认激活标签 key | undefined &#124; string &#124; number | 否 | undefined |
+| position | 标签位置 | undefined &#124; "top" &#124; "bottom" &#124; "right" &#124; "left" | 否 | "top" |
+| size | 标签尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| type | 标签类型 | undefined &#124; "text" &#124; "line" &#124; "card" &#124; "card-gutter" &#124; "rounded" &#124; "capsule" | 否 | "line" |
+| direction | 方向，设置为 vertical 时等同左侧标签栏 | undefined &#124; "horizontal" &#124; "vertical" | 否 | "horizontal" |
+| editable | 是否开启可编辑模式，仅 line、card、card-gutter 显示关闭/新增入口 | undefined &#124; false &#124; true | 否 | false |
+| showAddButton | 是否显示新增按钮 | undefined &#124; false &#124; true | 否 | false |
+| destroyOnHide | 隐藏时是否销毁内容 | undefined &#124; false &#124; true | 否 | false |
+| lazyLoad | 是否首次展示时再挂载内容 | undefined &#124; false &#124; true | 否 | false |
+| justify | 是否撑满容器 | undefined &#124; false &#124; true | 否 | false |
+| animation | 是否开启内容切换动画 | undefined &#124; false &#124; true | 否 | false |
+| headerPadding | 线条和文本类型下是否保留头部水平边距 | undefined &#124; false &#124; true | 否 | true |
+| autoSwitch | 新增标签后是否自动切到最后一个标签 | undefined &#124; false &#124; true | 否 | false |
+| hideContent | 是否隐藏内容区域 | undefined &#124; false &#124; true | 否 | false |
+| trigger | 触发方式 | undefined &#124; "click" &#124; "hover" | 否 | "click" |
+| scrollPosition | 激活标签滚动位置 | undefined &#124; number &#124; "center" &#124; "start" &#124; "end" &#124; "auto" | 否 | "auto" |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:activeKey | 激活标签变化时触发 | undefined &#124; (key: string &#124; number) => any |
+| change | 激活标签变化时触发 | undefined &#124; (key: string &#124; number) => any |
+| tabClick | 点击或触发标签时触发 | undefined &#124; (key: string &#124; number, ev: Event) => any |
+| add | 点击新增按钮时触发 | undefined &#124; (ev: Event) => any |
+| delete | 点击删除按钮时触发 | undefined &#124; (key: string &#124; number, ev: Event) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| 组件 | 插槽名 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| Tabs | default | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| TabPane | default | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type TabsPosition = 'left' | 'right' | 'top' | 'bottom';
+
+type TabsType = 'line' | 'card' | 'card-gutter' | 'text' | 'rounded' | 'capsule';
+
+interface TabData {
+    key: string | number;
+    title?: string;
+    disabled?: boolean;
+    closable?: boolean;
+    slots: Slots;
+    /** tab 自身 id，供 panel 的 aria-labelledby 引用（TabPane 按实例 uid 生成） */
+    tabId?: string;
+    /** 对应 panel 的 id，供 tab 的 aria-controls 引用 */
+    panelId?: string;
+}
+
+type TabTriggerEvent = 'click' | 'hover';
+
+type ScrollPosition = 'start' | 'end' | 'center' | 'auto' | number;
+```
+
+
+返回 [Tabs 用法](./tabs.md)。

package/AI_USAGE/components/tabs.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Tabs AI 使用
 
-适用版本：x-next@1.12.0；来源指纹：`9f9adf42b42dc1e551f500aabdcb7fb07b69a93ea44ff3dc1d16dab1a4c85843`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Tabs`；模型：v-model:active-key；已核对事件：change。
+先读 [通用接入](../core.md)。公开导出：`TabPane, Tabs`；主要模型：v-model:active-key。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./tabs-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/tabs`（包含 base.css、tabs.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/tabs)。使用 `v-model:active-key`，类型为 `string | number`；TabPane 用 Vue 的 `key` 标识页签，键类型须与模型一致。默认 `type='line'`、`position='top'`、`trigger='click'`、`lazyLoad=false`、`destroyOnHide=false`。
 
 `change(key)` 返回键值，`tab-click(key, event)` 还返回 `Event`。禁用配置放在 TabPane；TabPane 默认插槽放正文，`title` 插槽自定义标题，Tabs 的 `extra` 放额外内容。可编辑模式的 `add` / `delete` 事件需要业务维护页签数据。
@@ -30,4 +32,307 @@ function changed(key: string | number) { feedback.value = `当前页签：${key}
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/tabs.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./tabs-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于同层级内容分组切换。
+
+
+### 何时使用
+
+- 页面中有多个平级视图，需要在同一区域切换展示。
+- 内容之间相互独立，切换时希望保留或按需销毁面板状态。
+- 需要可关闭、可新增或横向滚动的页签导航。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tabs, TabPane } from 'x-next';
+import { ref } from 'vue';
+
+const activeKey = ref('overview');
+</script>
+<template>
+<Tabs v-model:active-key="activeKey">
+    <TabPane key="overview" title="概览">组件能力总览</TabPane>
+    <TabPane key="api" title="API">属性、事件与插槽</TabPane>
+    <TabPane key="guide" title="指南">使用建议</TabPane>
+  </Tabs>
+</template>
+```
+
+### 受控值和事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tabs, TabPane } from 'x-next';
+import { ref } from 'vue';
+
+const activeKey = ref('task');
+const handleChange = (key: string | number) => {
+  console.log('change', key);
+};
+const handleTabClick = (key: string | number) => {
+  console.log('tab-click', key);
+};
+</script>
+<template>
+<Tabs v-model:active-key="activeKey" @change="handleChange" @tab-click="handleTabClick">
+    <TabPane key="task" title="任务">任务面板</TabPane>
+    <TabPane key="member" title="成员">成员面板</TabPane>
+    <TabPane key="disabled" title="禁用" disabled>禁用面板</TabPane>
+  </Tabs>
+</template>
+```
+
+### 类型和尺寸
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup, Tabs, TabPane } from 'x-next';
+import { ref } from 'vue';
+
+const activeKey = ref('line');
+const type = ref<'line' | 'card' | 'card-gutter' | 'text' | 'rounded' | 'capsule'>('card-gutter');
+const size = ref<'mini' | 'small' | 'medium' | 'large'>('large');
+const typeOptions = [
+  { label: 'Line', value: 'line' },
+  { label: 'Card', value: 'card' },
+  { label: 'Card Gutter', value: 'card-gutter' },
+  { label: 'Text', value: 'text' },
+  { label: 'Rounded', value: 'rounded' },
+  { label: 'Capsule', value: 'capsule' },
+];
+const sizeOptions = [
+  { label: 'Mini', value: 'mini' },
+  { label: 'Small', value: 'small' },
+  { label: 'Medium', value: 'medium' },
+  { label: 'Large', value: 'large' },
+];
+</script>
+<template>
+<RadioGroup v-model="type" type="button" :options="typeOptions" />
+  <RadioGroup v-model="size" type="button" :options="sizeOptions" />
+  <Tabs v-model:active-key="activeKey" :type="type" :size="size">
+    <TabPane key="line" title="线条">线条样式</TabPane>
+    <TabPane key="card" title="卡片">卡片样式</TabPane>
+    <TabPane key="capsule" title="胶囊">胶囊样式</TabPane>
+  </Tabs>
+</template>
+```
+
+### 标签位置
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup, Tabs, TabPane } from 'x-next';
+import { ref } from 'vue';
+
+const position = ref<'top' | 'right' | 'bottom' | 'left'>('left');
+const positionOptions = [
+  { label: 'Top', value: 'top' },
+  { label: 'Right', value: 'right' },
+  { label: 'Bottom', value: 'bottom' },
+  { label: 'Left', value: 'left' },
+];
+</script>
+<template>
+<RadioGroup v-model="position" type="button" :options="positionOptions" />
+  <Tabs :position="position" type="card">
+    <TabPane key="overview" title="概览">当前标签栏位置：{{ position }}</TabPane>
+    <TabPane key="config" title="配置">左侧和右侧会切换为纵向导航</TabPane>
+    <TabPane key="log" title="日志">底部标签栏会显示在内容之后</TabPane>
+  </Tabs>
+</template>
+```
+
+### 可编辑标签
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tabs, TabPane } from 'x-next';
+import { ref } from 'vue';
+
+const activeKey = ref('1');
+const seed = ref(3);
+const tabs = ref([
+  { key: '1', title: '需求' },
+  { key: '2', title: '设计' },
+]);
+
+const addTab = () => {
+  const key = String(seed.value++);
+  tabs.value.push({ key, title: `新标签 ${key}` });
+};
+const removeTab = (key: string | number) => {
+  tabs.value = tabs.value.filter((item) => item.key !== key);
+};
+</script>
+<template>
+<Tabs
+    v-model:active-key="activeKey"
+    type="card-gutter"
+    editable
+    show-add-button
+    auto-switch
+    @add="addTab"
+    @delete="removeTab"
+  >
+    <TabPane v-for="item in tabs" :key="item.key" :title="item.title">
+      {{ item.title }} 内容
+    </TabPane>
+  </Tabs>
+</template>
+```
+
+### 插槽和额外内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tabs, TabPane } from 'x-next';
+import { ref } from 'vue';
+
+const activeKey = ref('message');
+</script>
+<template>
+<Tabs v-model:active-key="activeKey">
+    <template #extra>
+      <button>额外操作</button>
+    </template>
+    <TabPane key="message">
+      <template #title>消息</template>
+      自定义标题插槽
+    </TabPane>
+    <TabPane key="notice">
+      <template #title>通知</template>
+      标签栏右侧可以放置额外内容
+    </TabPane>
+  </Tabs>
+</template>
+```
+
+### 懒加载和销毁
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tabs, TabPane } from 'x-next';
+import { defineComponent, h, onBeforeUnmount, onMounted, ref } from 'vue';
+
+const activeKey = ref('first');
+const mountCount = ref(0);
+const unmountCount = ref(0);
+const LifecyclePanel = defineComponent({
+  props: {
+    name: {
+      type: String,
+      required: true,
+    },
+  },
+  setup(props) {
+    onMounted(() => {
+      mountCount.value += 1;
+    });
+    onBeforeUnmount(() => {
+      unmountCount.value += 1;
+    });
+    return () => h('span', `${props.name} 已挂载`);
+  },
+});
+</script>
+<template>
+<Tabs v-model:active-key="activeKey" lazy-load destroy-on-hide animation>
+    <TabPane key="first" title="首次">
+      <LifecyclePanel name="首次面板" />
+    </TabPane>
+    <TabPane key="second" title="销毁">
+      <LifecyclePanel name="销毁面板" />
+    </TabPane>
+    <TabPane key="third" title="动画">
+      <LifecyclePanel name="动画面板" />
+    </TabPane>
+  </Tabs>
+  <p>挂载次数：{{ mountCount }}；销毁次数：{{ unmountCount }}</p>
+</template>
+```
+
+### Hover 触发
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tabs, TabPane } from 'x-next';
+import { ref } from 'vue';
+
+const activeKey = ref('preview');
+</script>
+<template>
+<Tabs v-model:active-key="activeKey" trigger="hover">
+    <TabPane key="preview" title="预览">鼠标移入即可切换</TabPane>
+    <TabPane key="detail" title="详情">适合轻量预览场景</TabPane>
+  </Tabs>
+</template>
+```
+
+### 滚动标签
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup, Button, Tabs, TabPane } from 'x-next';
+import { ref } from 'vue';
+
+const activeKey = ref('tab-8');
+const position = ref<'top' | 'right' | 'bottom' | 'left'>('top');
+const scrollPosition = ref<'auto' | 'start' | 'center' | 'end'>('auto');
+const positionOptions = [
+  { label: 'Left', value: 'left' },
+  { label: 'Top', value: 'top' },
+  { label: 'Right', value: 'right' },
+  { label: 'Bottom', value: 'bottom' },
+];
+const scrollPositionOptions = [
+  { label: 'auto', value: 'auto' },
+  { label: 'start', value: 'start' },
+  { label: 'center', value: 'center' },
+  { label: 'end', value: 'end' },
+];
+const tabs = Array.from({ length: 30 }, (_, index) => ({
+  key: `tab-${index + 1}`,
+  title: `标签 ${index + 1}`,
+}));
+
+const handleChangeActive = () => {
+  activeKey.value = `tab-${Math.floor(Math.random() * tabs.length) + 1}`;
+};
+</script>
+<template>
+<RadioGroup v-model="position" type="button" :options="positionOptions" />
+  <RadioGroup v-model="scrollPosition" type="button" :options="scrollPositionOptions" />
+  <Button size="small" @click="handleChangeActive">Change: {{ activeKey }}</Button>
+  <Tabs
+    v-model:active-key="activeKey"
+    :position="position"
+    :scroll-position="scrollPosition"
+    style="width: 100%; height: 300px"
+  >
+    <TabPane v-for="item in tabs" :key="item.key" :title="item.title">
+      {{ item.title }} 内容
+    </TabPane>
+  </Tabs>
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./tabs-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/tag-api.md

@@ -0,0 +1,124 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Tag 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Tag API
+
+公开声明：`dist/components/tag/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| color | 标签颜色，支持内置色或自定义 CSS 色值 | undefined &#124; string | 否 | 未声明 |
+| size | 标签尺寸 | undefined &#124; "small" &#124; "medium" &#124; "large" | 否 | "medium" |
+| bordered | 是否显示边框 | undefined &#124; false &#124; true | 否 | false |
+| visible | 标签是否可见，支持 v-model:visible | undefined &#124; false &#124; true | 否 | undefined |
+| defaultVisible | 默认是否可见，非受控模式 | undefined &#124; false &#124; true | 否 | true |
+| loading | 是否为加载状态 | undefined &#124; false &#124; true | 否 | false |
+| closable | 是否可关闭 | undefined &#124; false &#124; true | 否 | false |
+| selectable | 是否可选择 | undefined &#124; false &#124; true | 否 | false |
+| checked | 是否选中，仅 selectable 时有效，支持 v-model:checked | undefined &#124; false &#124; true | 否 | undefined |
+| defaultChecked | 默认是否选中，非受控模式 | undefined &#124; false &#124; true | 否 | true |
+| nowrap | 标签内容是否不换行 | undefined &#124; false &#124; true | 否 | false |
+| closeAriaLabel | 关闭按钮的无障碍名称，默认“关闭标签” | undefined &#124; string | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:visible | 可见状态变化时触发 | undefined &#124; (visible: boolean) => any |
+| update:checked | 选中状态变化时触发 | undefined &#124; (checked: boolean) => any |
+| close | 点击关闭按钮时触发 | undefined &#124; (ev: MouseEvent) => any |
+| check | 点击可选择标签时触发 | undefined &#124; (checked: boolean, ev: MouseEvent) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 标签内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| icon | 自定义图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| close-icon | 自定义关闭图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+declare const TAG_COLORS: readonly ["red", "orangered", "orange", "gold", "lime", "green", "cyan", "blue", "better-blue", "purple", "pink-purple", "magenta", "gray"];
+
+type TagColor = (typeof TAG_COLORS)[number];
+
+interface TagProps {
+    /**
+     * @zh 标签的颜色
+     * @en Label color
+     */
+    color?: TagColor | string;
+    /**
+     * @zh 标签的大小
+     * @en Label size
+     */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * @zh 标签是否可见
+     * @en Whether the tag is visible
+     */
+    visible?: boolean;
+    /**
+     * @zh 标签默认是否可见
+     * @en Whether the tag is visible by default
+     */
+    defaultVisible?: boolean;
+    /**
+     * @zh 标签是否为加载中状态
+     * @en Whether the tag is loading state
+     */
+    loading?: boolean;
+    /**
+     * @zh 标签是否可关闭
+     * @en Whether the tag can be closed
+     */
+    closable?: boolean;
+    /**
+     * @zh 标签是否可选中
+     * @en Whether the tag can be checked
+     */
+    selectable?: boolean;
+    /**
+     * @zh 标签是否选中（标签可选中时可用）
+     * @en Whether the tag is checked (available when the tag is selectable)
+     */
+    checked?: boolean;
+    /**
+     * @zh 标签默认选中状态（标签可选中时可用）
+     * @en Whether the tag is checked by default (available when the tag is selectable)
+     */
+    defaultChecked?: boolean;
+    /**
+     * @zh 是否显示边框
+     * @en Whether the tag is bordered
+     */
+    bordered?: boolean;
+    /**
+     * @zh 标签内容不换行
+     * @en Tag content does not wrap
+     */
+    nowrap?: boolean;
+    /**
+     * @zh 关闭按钮的无障碍名称，默认“关闭标签”
+     * @en Accessible name of the close button, defaults to "关闭标签"
+     */
+    closeAriaLabel?: string;
+}
+```
+
+
+返回 [Tag 用法](./tag.md)。