x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/input-number-api.md

@@ -0,0 +1,66 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# InputNumber 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## InputNumber API
+
+公开声明：`dist/components/form-input-number/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 绑定值 | undefined &#124; number | 否 | 未声明 |
+| defaultValue | 默认值，非受控模式 | undefined &#124; number | 否 | 未声明 |
+| mode | 按钮模式 | undefined &#124; "button" &#124; "embed" | 否 | "embed" |
+| precision | 数字精度 | undefined &#124; number | 否 | 未声明 |
+| step | 数字变化步长 | undefined &#124; number | 否 | 1 |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| error | 是否错误状态 | undefined &#124; false &#124; true | 否 | false |
+| max | 最大值 | undefined &#124; number | 否 | Infinity |
+| min | 最小值 | undefined &#124; number | 否 | -Infinity |
+| formatter | 展示值格式化 | undefined &#124; Function | 否 | 未声明 |
+| parser | 将展示值解析为数字字符串 | undefined &#124; Function | 否 | 未声明 |
+| placeholder | 占位提示 | undefined &#124; string | 否 | 未声明 |
+| hideButton | 是否隐藏步进按钮；mode="button" 时同时用于让出 prepend / append 插槽 | undefined &#124; false &#124; true | 否 | false |
+| size | 输入框尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| allowClear | 是否允许清空 | undefined &#124; false &#124; true | 否 | false |
+| modelEvent | 触发 v-model 更新的事件 | undefined &#124; "input" &#124; "change" | 否 | "change" |
+| readOnly | 是否只读 | undefined &#124; false &#124; true | 否 | false |
+| inputAttrs | 内部 input 元素属性 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: number &#124; undefined) => any |
+| change | 值变化时触发 | undefined &#124; (value: number &#124; undefined, ev: Event) => any |
+| focus | 获取焦点时触发 | undefined &#124; (ev: FocusEvent) => any |
+| blur | 失去焦点时触发 | undefined &#124; (ev: FocusEvent) => any |
+| clear | 点击清除按钮时触发 | undefined &#124; (ev: Event) => any |
+| input | 输入时触发 | undefined &#124; (value: number &#124; undefined, inputValue: string, ev: Event) => any |
+| keydown | 按下键盘时触发 | undefined &#124; (ev: KeyboardEvent) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| prefix | 前缀内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| suffix | 后缀内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| prepend | 前置标签 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| append | 后置标签 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| plus | 自定义增加按钮图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| minus | 自定义减少按钮图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | () => void |
+| blur | () => void |
+
+
+返回 [InputNumber 用法](./input-number.md)。

package/AI_USAGE/components/input-number.md

@@ -0,0 +1,294 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# InputNumber AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`InputNumber`；主要模型：v-model。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./input-number-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/form-input-number`（包含 base.css、button.css、form-input.css、form-input-number.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/input-number.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./input-number-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于金额、数量、比例等需要数值约束的输入场景。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputNumber } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(12);
+</script>
+<template>
+<InputNumber v-model="value" :min="0" :max="100" />
+  <InputNumber :default-value="32" :min="0" :max="100" />
+  <InputNumber :default-value="500" disabled />
+</template>
+```
+
+### 按钮模式
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputNumber } from 'x-next';
+import { ref } from 'vue';
+const value = ref(12);
+</script>
+<template>
+<InputNumber v-model="value" :min="0" :max="100" />
+  <InputNumber v-model="value" mode="button" :min="0" :max="100" />
+</template>
+```
+
+### 尺寸
+
+四种尺寸的高度分别为 `24px`、`28px`、`32px`、`36px`；`mode="button"` 时两侧按钮与输入框等高。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputNumber } from 'x-next';
+import { ref } from 'vue';
+const value = ref(12);
+</script>
+<template>
+<InputNumber v-model="value" size="mini" />
+  <InputNumber v-model="value" size="small" />
+  <InputNumber v-model="value" size="medium" />
+  <InputNumber v-model="value" size="large" />
+
+  <InputNumber v-model="value" mode="button" size="mini" />
+  <InputNumber v-model="value" mode="button" size="small" />
+  <InputNumber v-model="value" mode="button" size="medium" />
+  <InputNumber v-model="value" mode="button" size="large" />
+</template>
+```
+
+### 精度和步长
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputNumber } from 'x-next';
+import { ref } from 'vue';
+const value = ref(12);
+</script>
+<template>
+<InputNumber v-model="value" :step="1.2" :precision="2" />
+</template>
+```
+
+### 格式化展示
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputNumber } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(12000);
+const formatter = (value: string) => {
+  const values = value.split('.');
+  values[0] = values[0].replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  return values.join('.');
+};
+const parser = (value: string) => value.replace(/,/g, '');
+</script>
+<template>
+<InputNumber
+    v-model="value"
+    :min="0"
+    :formatter="formatter"
+    :parser="parser"
+  />
+</template>
+```
+
+### 前缀和后缀
+
+`mode="button"` 时左右两端是加减按钮，`prepend` / `append` 插槽会被按钮占用。
+需要自定义前后置内容时，请同时指定 `hide-button`（如上例第四项）。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputNumber } from 'x-next';
+import { ref } from 'vue';
+const value = ref(12);
+</script>
+<template>
+<InputNumber v-model="value" allow-clear>
+    <template #prefix>￥</template>
+  </InputNumber>
+  <InputNumber v-model="value" allow-clear hide-button>
+    <template #suffix>%</template>
+  </InputNumber>
+  <InputNumber v-model="value">
+    <template #prepend>数量</template>
+    <template #append>件</template>
+  </InputNumber>
+  <InputNumber v-model="value" mode="button" hide-button>
+    <template #prepend>数量</template>
+    <template #append>件</template>
+  </InputNumber>
+</template>
+```
+
+### 自定义图标
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputNumber } from 'x-next';
+import { ref } from 'vue';
+const value = ref(12);
+</script>
+<template>
+<InputNumber v-model="value" :min="0" :max="100">
+    <template #plus>+</template>
+    <template #minus>-</template>
+  </InputNumber>
+</template>
+```
+
+### 触发时机
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputNumber } from 'x-next';
+import { ref } from 'vue';
+const value = ref(12);
+</script>
+<template>
+<InputNumber
+    v-model="value"
+    :min="10"
+    :max="100"
+    model-event="input"
+  />
+</template>
+```
+
+### 状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputNumber } from 'x-next';
+
+</script>
+<template>
+<InputNumber :default-value="12" read-only />
+  <InputNumber :default-value="12" error />
+  <InputNumber :default-value="12" disabled />
+
+  <InputNumber :default-value="12" mode="button" read-only />
+  <InputNumber :default-value="12" mode="button" error />
+  <InputNumber :default-value="12" mode="button" disabled />
+</template>
+```
+
+### 事件回调
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputNumber } from 'x-next';
+import { ref } from 'vue';
+const value = ref(12);
+const eventLog = ref('等待操作');
+const handleInput = (value: number | undefined, inputValue: string) => {
+  eventLog.value = `input: ${inputValue || '空'} / ${value ?? '空'}`;
+};
+const handleChange = (value: number | undefined) => {
+  eventLog.value = `change: ${value ?? '空'}`;
+};
+const handleClear = () => {
+  eventLog.value = 'clear';
+};
+</script>
+<template>
+<InputNumber
+    v-model="value"
+    allow-clear
+    @input="handleInput"
+    @change="handleChange"
+    @clear="handleClear"
+  />
+  <p role="status">{{ eventLog }}</p>
+</template>
+```
+
+### 方法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputNumber, Button } from 'x-next';
+import { ref } from 'vue';
+const value = ref(12);
+const inputNumberRef = ref();
+</script>
+<template>
+<InputNumber ref="inputNumberRef" v-model="value" />
+  <Button @click="inputNumberRef?.focus()">聚焦</Button>
+  <Button @click="inputNumberRef?.blur()">失焦</Button>
+</template>
+```
+
+### 在 Form 中校验
+
+组件放进 `x-form-item` 后会自动继承 Form 的尺寸与禁用状态，并按 FormItem 的校验规则展示错误。默认 `validateTrigger` 为 `change`，即值变化时触发校验。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, InputNumber, Space, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+
+const formState = reactive({ quantity: undefined as number | undefined });
+const formRules: Record<string, FieldRule[]> = {
+  quantity: [{ required: true, type: 'number', min: 1, message: '数量至少为 1' }],
+};
+const formRef = ref<FormInstance>();
+const validateResult = ref('');
+
+const handleValidate = async () => {
+  const errors = await formRef.value!.validate();
+  validateResult.value = errors
+    ? `校验失败：${Object.values(errors).map((error) => error.message).join('；')}`
+    : '校验通过';
+};
+const handleReset = () => {
+  formRef.value!.resetFields();
+  validateResult.value = '已重置';
+};
+</script>
+<template>
+<Form ref="formRef" :model="formState" :rules="formRules">
+    <FormItem field="quantity" label="数量">
+      <InputNumber v-model="formState.quantity" :min="1" placeholder="请输入数量" />
+    </FormItem>
+    <FormItem>
+      <Space>
+        <Button type="primary" @click="handleValidate">校验</Button>
+        <Button @click="handleReset">重置</Button>
+      </Space>
+    </FormItem>
+  </Form>
+  <p role="status">{{ validateResult }}</p>
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./input-number-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/input-tag-api.md

@@ -0,0 +1,114 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# InputTag 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## InputTag API
+
+公开声明：`dist/components/form-input-tag/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 绑定值 | undefined &#124; (string &#124; number &#124; TagData)[] | 否 | 未声明 |
+| defaultValue | 默认值，非受控模式 | undefined &#124; (string &#124; number &#124; TagData)[] | 否 | [] |
+| inputValue | 输入框绑定值 | undefined &#124; string | 否 | 未声明 |
+| defaultInputValue | 输入框默认值 | undefined &#124; string | 否 | "" |
+| placeholder | 占位提示 | undefined &#124; string | 否 | 未声明 |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| error | 是否错误状态 | undefined &#124; false &#124; true | 否 | false |
+| readonly | 是否只读 | undefined &#124; false &#124; true | 否 | false |
+| allowClear | 是否允许清空 | undefined &#124; false &#124; true | 否 | false |
+| size | 输入框尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| maxTagCount | 最多展示标签个数，0 不限制 | undefined &#124; number | 否 | 0 |
+| retainInputValue | 创建或失焦后是否保留输入内容 | undefined &#124; false &#124; true &#124; { create?: boolean; blur?: boolean; } | 否 | false |
+| formatTag | 格式化标签内容 | undefined &#124; (data: TagData) => string | 否 | 未声明 |
+| uniqueValue | 是否仅创建唯一值 | undefined &#124; false &#124; true | 否 | false |
+| fieldNames | 自定义 TagData 字段名 | undefined &#124; { [x: string]: string &#124; undefined; value?: string &#124; undefined; label?: string &#124; undefined; closable?: string &#124; undefined; tagProps?: string &#124; undefined; } | 否 | 未声明 |
+| tagNowrap | 标签内容是否不换行 | undefined &#124; false &#124; true | 否 | false |
+| baseCls | 见场景用法与类型 | undefined &#124; string | 否 | 未声明 |
+| focused | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| disabledInput | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| uninjectFormItemContext | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| inputAttrs | 见场景用法与类型 | undefined &#124; { [x: string]: unknown; } | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: (string &#124; number &#124; TagData)[]) => any |
+| update:inputValue | 输入值更新时触发 | undefined &#124; (inputValue: string) => any |
+| change | 标签值变化时触发 | undefined &#124; (value: (string &#124; number &#124; TagData)[], ev: Event) => any |
+| inputValueChange | 输入值变化时触发 | undefined &#124; (inputValue: string, ev: Event) => any |
+| pressEnter | 按下回车且输入内容非空时触发 | undefined &#124; (inputValue: string, ev: KeyboardEvent) => any |
+| remove | 删除标签时触发 | undefined &#124; (removed: string &#124; number, ev: Event) => any |
+| clear | 点击清除按钮时触发 | undefined &#124; (ev: MouseEvent) => any |
+| focus | 获取焦点时触发 | undefined &#124; (ev: FocusEvent) => any |
+| blur | 失去焦点时触发 | undefined &#124; (ev: FocusEvent) => any |
+| keydown | 按下键盘时触发 | undefined &#124; (ev: KeyboardEvent) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| prefix | 前缀内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| suffix | 后缀内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| tag | 自定义标签内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | () => void |
+| blur | () => void |
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+interface TagData {
+    /**
+     * @zh 标签值
+     * @en Tag value
+     */
+    value?: string | number;
+    /**
+     * @zh 标签内容
+     * @en Tag content
+     */
+    label?: string;
+    /**
+     * @zh 是否可关闭
+     * @en Whether to close
+     */
+    closable?: boolean;
+    /**
+     * @zh 标签属性
+     * @en Tag props
+     */
+    tagProps?: TagProps;
+    [other: string]: any;
+}
+
+type InputTagFieldNames = FieldString<TagData>;
+
+interface TagDataInfo extends TagData {
+    raw: Record<string, unknown>;
+    originalIndex: number;
+    value: string | number;
+    label: string;
+    closable: boolean;
+}
+
+interface InputTagInstance {
+    focus: () => void;
+    blur: () => void;
+}
+```
+
+
+返回 [InputTag 用法](./input-tag.md)。