x-next 1.13.0 → 1.15.0

package/AI_USAGE/components/finicon.md

@@ -0,0 +1,88 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Finicon AI 用法
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+先读 [通用接入](../core.md)。本地组件文档导入的选型和配套资源用法。
+
+### 用途与选型
+
+Finicon 是面向金融科技场景的图标库。x-next 将其接入为 `finicon:*` 命名空间，保持和通用 `<x-icon name="..." />` 一致的调用方式。来源见 [Finicon 官网](https://finicon.app/)。
+
+
+### 图标浏览器
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Icon } from 'x-next';
+
+import { registerFiniconIcons } from 'x-next';
+registerFiniconIcons();
+</script>
+<template>
+<Icon name="finicon:stock-chart-square-line-up" />
+  <Icon name="finicon:ticker-tsla" color="var(--x-color-primary-6)" />
+  <Icon name="finicon:region-cn" />
+</template>
+```
+
+### 尺寸、颜色和描边
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Icon } from 'x-next';
+
+import { registerFiniconIcons } from 'x-next';
+registerFiniconIcons();
+</script>
+<template>
+<Icon name="finicon:trade-trending-up" :size="18" />
+  <Icon
+    name="finicon:trade-trending-up"
+    :size="26"
+    color="var(--x-color-success-6)"
+  />
+  <Icon
+    name="finicon:stock-chart-candlestick"
+    :size="32"
+    color="var(--x-color-danger-6)"
+    :stroke-width="1.5"
+  />
+  <Icon name="finicon:region-us" :size="32" />
+</template>
+```
+
+### 业务组合
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Icon, Tag } from 'x-next';
+
+import { registerFiniconIcons } from 'x-next';
+registerFiniconIcons();
+</script>
+<template>
+<Button type="primary">
+    <template #icon>
+      <Icon name="finicon:trade-buy" :stroke-width="2.6" />
+    </template>
+    买入
+  </Button>
+
+  <Tag color="green">
+    <Icon name="finicon:fund-piggy-bank" :stroke-width="2.6" />
+    基金
+  </Tag>
+</template>
+```
+
+### 来源与授权
+
+Finicon 图标来自 [`finicon@1.0.12`](https://www.npmjs.com/package/finicon)，官方站点是 [https://finicon.app/](https://finicon.app/)。x-next 保留 `finicon:` 前缀，便于区分金融图标来源。
+
+
+
+返回 [AI 索引](../index.md)。

package/AI_USAGE/components/form-api.md

@@ -0,0 +1,524 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Form 完整公开 API
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Form API
+
+公开声明：`dist/components/form/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| model | 表单数据对象 | { [x: string]: any; } | 是 | 未声明 |
+| layout | 表单布局 | undefined &#124; "horizontal" &#124; "vertical" &#124; "inline" | 否 | "horizontal" |
+| size | 表单控件尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| labelColProps | 标签栅格配置 | undefined &#124; { [x: string]: any; } | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| wrapperColProps | 控件栅格配置 | undefined &#124; { [x: string]: any; } | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| labelColStyle | 标签列样式 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| wrapperColStyle | 控件列样式 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| labelAlign | 标签对齐方式 | undefined &#124; "right" &#124; "left" | 否 | "right" |
+| disabled | 是否禁用整个表单 | undefined &#124; false &#124; true | 否 | undefined |
+| rules | 表单校验规则 | undefined &#124; { [x: string]: FieldRule<any> &#124; FieldRule<any>[]; } | 否 | 未声明 |
+| autoLabelWidth | 自动计算标签宽度，仅水平布局生效 | undefined &#124; false &#124; true | 否 | false |
+| id | 表单 id 属性和表单控件 id 前缀 | undefined &#124; string | 否 | 未声明 |
+| scrollToFirstError | 校验失败后滚动到第一个错误字段，可传滚动配置 | undefined &#124; false &#124; true &#124; StandardBehaviorOptions &#124; CustomBehaviorOptions<unknown> | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| submit | 表单提交时触发 | undefined &#124; (data: { values: Record<string, any>; errors: Record<string, ValidatedError> &#124; undefined; }, ev: Event) => any |
+| submitSuccess | 校验成功时触发 | undefined &#124; (values: Record<string, any>, ev: Event) => any |
+| submitFailed | 校验失败时触发 | undefined &#124; (data: { values: Record<string, any>; errors: Record<string, ValidatedError>; }, ev: Event) => any |
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| validate | (callback?: (errors: undefined &#124; Record<string, ValidatedError>) => void) => Promise<undefined &#124; Record<string, ValidatedError>> |
+| validateField | (field: string &#124; string[], callback?: (errors: undefined &#124; Record<string, ValidatedError>) => void) => Promise<undefined &#124; Record<string, ValidatedError>> |
+| resetFields | (field?: string &#124; string[]) => void |
+| clearValidate | (field?: string &#124; string[]) => void |
+| setFields | (data: Record<string, FieldData>) => void |
+| scrollToField | (field: string, options?: Options<unknown>) => void |
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+declare const VALIDATE_STATUSES: readonly ["success", "warning", "error", "validating"];
+
+type ValidateStatus = (typeof VALIDATE_STATUSES)[number];
+
+declare const VALIDATE_TRIGGERS: readonly ["change", "input", "focus", "blur"];
+
+type ValidateTrigger = (typeof VALIDATE_TRIGGERS)[number];
+
+interface FormInstance {
+    validate: (callback?: (errors: undefined | Record<string, ValidatedError>) => void) => Promise<undefined | Record<string, ValidatedError>>;
+    validateField: (field: string | string[], callback?: (errors: undefined | Record<string, ValidatedError>) => void) => Promise<undefined | Record<string, ValidatedError>>;
+    resetFields: (field?: string | string[]) => void;
+    clearValidate: (field?: string | string[]) => void;
+    setFields: (data: Record<string, FieldData>) => void;
+    scrollToField: (field: string, options?: ScrollIntoViewOptions) => void;
+}
+
+interface FieldRule<FieldValue = any> {
+    /**
+     * @zh 校验的值的类型，默认为 `'string'`
+     * @en The type of the value to be checked, the default is `'string'`
+     */
+    type?: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'email' | 'url' | 'ip';
+    /**
+     * @zh 是否必填
+     * @en Is it required
+     */
+    required?: boolean;
+    /**
+     * @zh 校验失败时展示的信息
+     * @en Information displayed when verification fails
+     */
+    message?: string;
+    /**
+     * @zh 校验长度（string, array）
+     * @en Check length (string, array)
+     */
+    length?: number;
+    /**
+     * @zh 最大长度（string）
+     * @en Maximum length (string)
+     */
+    maxLength?: number;
+    /**
+     * @zh 最小长度（string）
+     * @en Minimum length (string)
+     */
+    minLength?: number;
+    /**
+     * @zh 匹配校验（string）
+     * @en Match check (string)
+     */
+    match?: RegExp;
+    /**
+     * @zh 大写（string）
+     * @en Uppercase (string)
+     */
+    uppercase?: boolean;
+    /**
+     * @zh 小写（string）
+     * @en Lowercase (string)
+     */
+    lowercase?: boolean;
+    /**
+     * @zh 最小值（number）
+     * @en Minimum (number)
+     */
+    min?: number;
+    /**
+     * @zh 最大值（number）
+     * @en Maximum (number)
+     */
+    max?: number;
+    /**
+     * @zh 校验数值（number）
+     * @en Check value (number)
+     */
+    equal?: number;
+    /**
+     * @zh 正数（number）
+     * @en Positive number (number)
+     */
+    positive?: boolean;
+    /**
+     * @zh 负数（number）
+     * @en Negative number (number)
+     */
+    negative?: boolean;
+    /**
+     * @zh 是否为 `true`（boolean）
+     * @en Whether it is `true` (boolean)
+     */
+    true?: boolean;
+    /**
+     * @zh 是否为 `false`（boolean）
+     * @en Whether it is `false` (boolean)
+     */
+    false?: boolean;
+    /**
+     * @zh 数组中是否包含给定值（array）
+     * @en Does the array contain the given value (array)
+     */
+    includes?: any[];
+    /**
+     * @zh 数组元素是否相等（array）
+     * @en Are array elements equal (array)
+     */
+    deepEqual?: any;
+    /**
+     * @zh 是否为空（object）
+     * @en Is it empty (object)
+     */
+    empty?: boolean;
+    /**
+     * @zh 对象是否包含给定属性（object）
+     * @en Does the object contain the given attribute (object)
+     */
+    hasKeys?: string[];
+    /**
+     * @zh 自定义校验规则
+     * @en Custom verification rules
+     * @param value
+     * @param callback 通过 callback(message) 添加错误；异步校验返回 Promise 并在完成后 resolve
+     */
+    validator?: (value: FieldValue | undefined, callback: (error?: string) => void) => void | Promise<void>;
+}
+
+interface FieldData {
+    /**
+     * @zh 字段的值
+     * @en Field value
+     */
+    value?: any;
+    /**
+     * @zh 字段的状态
+     * @en Field status
+     */
+    status?: ValidateStatus;
+    /**
+     * @zh 字段的错误信息
+     * @en Field error message
+     */
+    message?: string;
+}
+
+interface ValidatedError {
+    /**
+     * @zh 标签的文本
+     * @en Label text
+     * @version 2.18.0
+     */
+    label: string;
+    /**
+     * @zh 字段名
+     * @en Field name
+     */
+    field: string;
+    /**
+     * @zh 字段值
+     * @en Field value
+     */
+    value: any;
+    /**
+     * @zh 字段类型
+     * @en Field Type
+     */
+    type: string;
+    /**
+     * @zh 是否为 `required` 错误
+     * @en Is it a `required` error
+     */
+    isRequiredError: boolean;
+    /**
+     * @zh 错误信息
+     * @en Error message
+     */
+    message: string;
+}
+
+interface FormItemEventHandler {
+    /**
+     * @zh onChange
+     * @en onChange
+     */
+    onChange?: (ev?: Event) => void;
+    /**
+     * @zh onInput
+     * @en onInput
+     */
+    onInput?: (ev?: Event) => void;
+    /**
+     * @zh onFocus
+     * @en onFocus
+     */
+    onFocus?: (ev?: Event) => void;
+    /**
+     * @zh onBlur
+     * @en onBlur
+     */
+    onBlur?: (ev?: Event) => void;
+}
+```
+
+
+## FormItem API
+
+公开声明：`dist/components/form/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| field | 字段路径 | undefined &#124; string | 否 | "" |
+| label | 标签文本 | undefined &#124; string | 否 | 未声明 |
+| tooltip | 标签提示 | undefined &#124; string | 否 | 未声明 |
+| showColon | 是否显示冒号 | undefined &#124; false &#124; true | 否 | false |
+| noStyle | 是否去除布局样式 | undefined &#124; false &#124; true | 否 | false |
+| disabled | 是否禁用当前项 | undefined &#124; false &#124; true | 否 | undefined |
+| help | 帮助文案 | undefined &#124; string | 否 | 未声明 |
+| extra | 额外文案 | undefined &#124; string | 否 | 未声明 |
+| required | 是否必填 | undefined &#124; false &#124; true | 否 | false |
+| asteriskPosition | 星号位置 | undefined &#124; string | 否 | "start" |
+| rules | 当前项校验规则 | undefined &#124; FieldRule<any> &#124; FieldRule<any>[] | 否 | 未声明 |
+| validateStatus | 手动指定校验状态 | undefined &#124; "success" &#124; "warning" &#124; "error" &#124; "validating" | 否 | 未声明 |
+| validateTrigger | 触发校验的事件 | undefined &#124; "focus" &#124; "blur" &#124; "input" &#124; "change" &#124; ("focus" &#124; "blur" &#124; "input" &#124; "change")[] | 否 | "change" |
+| labelColProps | 当前项标签列配置 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| wrapperColProps | 当前项控件列配置 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| hideLabel | 是否隐藏标签 | undefined &#124; false &#124; true | 否 | false |
+| hideAsterisk | 是否隐藏星号 | undefined &#124; false &#124; true | 否 | false |
+| labelColStyle | 标签列样式 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| wrapperColStyle | 控件列样式 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| rowProps | 当前项 Row 配置 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| rowClass | 当前项 Row class | undefined &#124; string &#124; { [x: string]: any; } &#124; unknown[] | 否 | 未声明 |
+| contentClass | 控件包裹层 class | undefined &#124; string &#124; { [x: string]: any; } &#124; unknown[] | 否 | 未声明 |
+| contentFlex | 内容层是否启用 flex | undefined &#124; false &#124; true | 否 | true |
+| labelColFlex | 标签列 flex 宽度 | undefined &#124; string &#124; number | 否 | 未声明 |
+| feedback | 是否显示反馈图标 | undefined &#124; false &#124; true | 否 | false |
+| labelComponent | 标签渲染元素 | undefined &#124; string | 否 | "label" |
+| labelAttrs | 标签元素属性 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 表单控件内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| label | 自定义标签 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| help | 自定义帮助信息 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| extra | 自定义额外内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+declare const VALIDATE_STATUSES: readonly ["success", "warning", "error", "validating"];
+
+type ValidateStatus = (typeof VALIDATE_STATUSES)[number];
+
+declare const VALIDATE_TRIGGERS: readonly ["change", "input", "focus", "blur"];
+
+type ValidateTrigger = (typeof VALIDATE_TRIGGERS)[number];
+
+interface FormInstance {
+    validate: (callback?: (errors: undefined | Record<string, ValidatedError>) => void) => Promise<undefined | Record<string, ValidatedError>>;
+    validateField: (field: string | string[], callback?: (errors: undefined | Record<string, ValidatedError>) => void) => Promise<undefined | Record<string, ValidatedError>>;
+    resetFields: (field?: string | string[]) => void;
+    clearValidate: (field?: string | string[]) => void;
+    setFields: (data: Record<string, FieldData>) => void;
+    scrollToField: (field: string, options?: ScrollIntoViewOptions) => void;
+}
+
+interface FieldRule<FieldValue = any> {
+    /**
+     * @zh 校验的值的类型，默认为 `'string'`
+     * @en The type of the value to be checked, the default is `'string'`
+     */
+    type?: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'email' | 'url' | 'ip';
+    /**
+     * @zh 是否必填
+     * @en Is it required
+     */
+    required?: boolean;
+    /**
+     * @zh 校验失败时展示的信息
+     * @en Information displayed when verification fails
+     */
+    message?: string;
+    /**
+     * @zh 校验长度（string, array）
+     * @en Check length (string, array)
+     */
+    length?: number;
+    /**
+     * @zh 最大长度（string）
+     * @en Maximum length (string)
+     */
+    maxLength?: number;
+    /**
+     * @zh 最小长度（string）
+     * @en Minimum length (string)
+     */
+    minLength?: number;
+    /**
+     * @zh 匹配校验（string）
+     * @en Match check (string)
+     */
+    match?: RegExp;
+    /**
+     * @zh 大写（string）
+     * @en Uppercase (string)
+     */
+    uppercase?: boolean;
+    /**
+     * @zh 小写（string）
+     * @en Lowercase (string)
+     */
+    lowercase?: boolean;
+    /**
+     * @zh 最小值（number）
+     * @en Minimum (number)
+     */
+    min?: number;
+    /**
+     * @zh 最大值（number）
+     * @en Maximum (number)
+     */
+    max?: number;
+    /**
+     * @zh 校验数值（number）
+     * @en Check value (number)
+     */
+    equal?: number;
+    /**
+     * @zh 正数（number）
+     * @en Positive number (number)
+     */
+    positive?: boolean;
+    /**
+     * @zh 负数（number）
+     * @en Negative number (number)
+     */
+    negative?: boolean;
+    /**
+     * @zh 是否为 `true`（boolean）
+     * @en Whether it is `true` (boolean)
+     */
+    true?: boolean;
+    /**
+     * @zh 是否为 `false`（boolean）
+     * @en Whether it is `false` (boolean)
+     */
+    false?: boolean;
+    /**
+     * @zh 数组中是否包含给定值（array）
+     * @en Does the array contain the given value (array)
+     */
+    includes?: any[];
+    /**
+     * @zh 数组元素是否相等（array）
+     * @en Are array elements equal (array)
+     */
+    deepEqual?: any;
+    /**
+     * @zh 是否为空（object）
+     * @en Is it empty (object)
+     */
+    empty?: boolean;
+    /**
+     * @zh 对象是否包含给定属性（object）
+     * @en Does the object contain the given attribute (object)
+     */
+    hasKeys?: string[];
+    /**
+     * @zh 自定义校验规则
+     * @en Custom verification rules
+     * @param value
+     * @param callback 通过 callback(message) 添加错误；异步校验返回 Promise 并在完成后 resolve
+     */
+    validator?: (value: FieldValue | undefined, callback: (error?: string) => void) => void | Promise<void>;
+}
+
+interface FieldData {
+    /**
+     * @zh 字段的值
+     * @en Field value
+     */
+    value?: any;
+    /**
+     * @zh 字段的状态
+     * @en Field status
+     */
+    status?: ValidateStatus;
+    /**
+     * @zh 字段的错误信息
+     * @en Field error message
+     */
+    message?: string;
+}
+
+interface ValidatedError {
+    /**
+     * @zh 标签的文本
+     * @en Label text
+     * @version 2.18.0
+     */
+    label: string;
+    /**
+     * @zh 字段名
+     * @en Field name
+     */
+    field: string;
+    /**
+     * @zh 字段值
+     * @en Field value
+     */
+    value: any;
+    /**
+     * @zh 字段类型
+     * @en Field Type
+     */
+    type: string;
+    /**
+     * @zh 是否为 `required` 错误
+     * @en Is it a `required` error
+     */
+    isRequiredError: boolean;
+    /**
+     * @zh 错误信息
+     * @en Error message
+     */
+    message: string;
+}
+
+interface FormItemEventHandler {
+    /**
+     * @zh onChange
+     * @en onChange
+     */
+    onChange?: (ev?: Event) => void;
+    /**
+     * @zh onInput
+     * @en onInput
+     */
+    onInput?: (ev?: Event) => void;
+    /**
+     * @zh onFocus
+     * @en onFocus
+     */
+    onFocus?: (ev?: Event) => void;
+    /**
+     * @zh onBlur
+     * @en onBlur
+     */
+    onBlur?: (ev?: Event) => void;
+}
+```
+
+
+返回 [Form 用法](./form.md)。