@fox-js/phone-skills 4.0.1-0

package/foxui/references/fox-steps-bar/doc.md

@@ -0,0 +1,610 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: StepsBar 组件使用规范
+impact: HIGH
+type: capability
+description: 步骤栏
+tags: [foxui, fox-steps-bar, FoxStepsBar]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-group","fox-row-item","fox-text"]
+---
+
+# StepsBar 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+StepsBar 是 foxui 中用于 **步骤栏** 的标准组件。
+- **基于**: NutUI `nut-steps-bar` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、支持 v-model 双向绑定、支持禁用/只读状态、适配 H5 与小程序多端、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 步骤栏
+
+> 💡 **关键原则**: 在所有 步骤栏 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `direction` | 显示方向，horizontal,vertical | string | horizontal |
+| `mode` | 步骤栏模式 | simple | - |
+| `model-value` | 当前步骤 | string \ | number \ |
+| `disabled` | 是否禁用 | boolean | false |
+| `data` | 步骤数据源 | Array,Function,String | - |
+| `params` | 查询参数 | Record<string,any> | - |
+| `text-key` | 指定异构数据源的text key | String | "text" |
+| `value-key` | 指定异构数据源的value key | String | "value" |
+| `disabled-key` | 指定异构数据源的disabled key | String | "disabled" |
+| `status-key` | 指定异构数据源的status key | String | "status" |
+| `visible-key` | 指定异构数据源的visible key | String | "visible" |
+| `doit-key` | 点状 key item doit映射-异构转换 | String | "doit" |
+| `label-key` | icon中标签名item label映射-异构转换 | String | "label" |
+| `item-options` | option样式设置 | ItemOption | - |
+| `icon` | 步骤 icon | Component | - |
+| `icon-size` | icon大小 | number | - |
+| `mark-icon` | 激活指示icon | Component | - |
+| `mark-icon-size` | 指示icon大小 | number | - |
+| `step` | 步长。direction为vertical为高度，direction为horizontal为宽度 | number | - |
+| `click-navigate-policy` | 点击导航策略 | 'only-back' \ | 'only-back-reset' \ |
+| `layout` | 布局，mode优先高于layout，mode可以看成预设的layout | head \ | main \ |
+| `scroll` | 可滚动 | boolea | false |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `change` | 步骤改变 | value: Value, options: Record<string,any> |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `main` | 步骤内容 |
+| `sub` | 步骤次内容 |
+| `icon` | 步骤图标 |
+| `mark` | 步骤指示图标 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+
+### 基本用法
+
+```html
+<template>
+  <h2>基础用法</h2>
+  <div class="my-steps-wrap">
+    <fox-steps-bar v-model="curBasicStep" :data="basicSteps"></fox-steps-bar>
+  </div>
+</template>
+
+<script lang="ts" setup>
+ import { ref } from 'vue'
+ 
+ // setps数据
+ const basicSteps = [
+  {
+    text: '步骤一',
+    value: '01'
+  },
+  {
+    text: '步骤二',
+    value: '02'
+  },
+  {
+    text: '步骤三',
+    value: '03'
+  }
+]
+
+ // 基础step value
+const curBasicStep = ref('01')
+</script>
+```
+
+### 点状形状
+
+```html
+<template>
+  <h2>点状结构</h2>
+  <div class="my-steps-wrap">
+      <fox-steps-bar v-model="curDoitStep" :data="basicSteps" :item-options="itemDoitOptions"></fox-steps-bar>
+    </div>
+</template>
+
+<script lang="ts" setup>
+ import { ref } from 'vue'
+ 
+ // setps数据
+ const basicSteps = [
+  {
+    text: '步骤一',
+    value: '01'
+  },
+  {
+    text: '步骤二',
+    value: '02'
+  },
+  {
+    text: '步骤三',
+    value: '03'
+  }
+]
+
+// 点状step value
+const curDoitStep = ref('02')
+// item 点状 options
+const itemDoitOptions = (item: Record<string, number>, index: number) => {
+  const s: Record<string, any> = {
+    doit: true
+  }
+  if (index < 1) {
+    s['status'] = 'done'
+  }
+  return s
+}
+
+</script>
+```
+
+### 简易布局
+
+组件预设的布局，比较紧凑简单,通过属性`mode=“simple”`设置
+
+```html
+<template>
+  <h2>简易布局</h2>
+    <div class="my-steps-wrap">
+      <fox-steps-bar v-model="curSimpleStep" :data="basicSteps" mode="simple"></fox-steps-bar>
+    </div>
+</template>
+
+<script lang="ts" setup>
+ import { ref } from 'vue'
+ 
+ // setps数据
+ const basicSteps = [
+  {
+    text: '步骤一',
+    value: '01'
+  },
+  {
+    text: '步骤二',
+    value: '02'
+  },
+  {
+    text: '步骤三',
+    value: '03'
+  }
+]
+
+// 简易step value
+const curSimpleStep = ref('')
+</script>
+```
+
+### 状态
+可以通过步骤元素中的`status`设置每个步骤的状态
+
+
+```ts
+/**
+ * Step状态
+ */
+export type StepStatus = 'done' | 'error' | 'half' | ''
+/**
+ * Value类型
+ */
+export type Value = string | number | boolean
+
+/**
+ * Step Item
+ */
+export interface Item {
+  text: string //标题
+  value: Value //value
+  status?: StepStatus //状态
+  visible?: boolean //是否可见
+  disabled?: boolean //是否禁用
+  [propName: string]: any
+}
+
+
+```
+
+```html
+<template>
+  <h2>状态</h2>
+    <div class="my-steps-wrap">
+      <fox-steps-bar v-model="curStatusStep" :data="statusSteps"></fox-steps-bar>
+    </div>
+</template>
+
+<script lang="ts" setup>
+ import { ref } from 'vue'
+ 
+ // setps数据
+ export const statusSteps = [
+  {
+    text: '完成',
+    value: '01',
+    status: 'done'
+  },
+  {
+    text: '错误',
+    value: '02',
+    status: 'error'
+  },
+  {
+    text: '半完成',
+    value: '03',
+    status: 'half'
+  },
+  {
+    text: '当前',
+    value: '04'
+  },
+  {
+    text: '默认',
+    value: '05'
+  }
+]
+
+// 状态step value
+const curStatusStep = ref('04')
+</script>
+```
+
+### 自定义Icon
+
+通过插槽`icon`设置步骤的图标
+
+```html
+<template>
+  <h2>自定义Icon</h2>
+    <div class="my-steps-wrap">
+      <fox-steps-bar v-model="curIconStep" :data="statusSteps">
+        <template v-slot:icon="scope">
+          <Checked v-if="scope.status === 'done'"></Checked>
+          <MaskClose v-else-if="scope.status === 'error'"></MaskClose>
+          <Loading v-else-if="scope.status === 'half'"></Loading>
+          <CheckChecked v-else></CheckChecked>
+        </template>
+      </fox-steps-bar>
+    </div>
+</template>
+
+<script lang="ts" setup>
+ import { ref } from 'vue'
+ import { Checked, Loading, CheckChecked, MaskClose } from '@fox-js/icons-vue'
+ 
+ // setps数据
+ export const statusSteps = [
+  {
+    text: '完成',
+    value: '01',
+    status: 'done'
+  },
+  {
+    text: '错误',
+    value: '02',
+    status: 'error'
+  },
+  {
+    text: '半完成',
+    value: '03',
+    status: 'half'
+  },
+  {
+    text: '当前',
+    value: '04'
+  },
+  {
+    text: '默认',
+    value: '05'
+  }
+]
+
+// 状态step value
+const curIconStep = ref('04')
+</script>
+
+```
+
+### 可滚动
+通过设置属性`scroll`和`step`来设置step栏的可滚动，其中`step`属性来设置步长。`direction`为`vertical`为高度，`direction`为`horizontal`为宽度。
+
+
+
+```html
+<template>
+  <h2>可滚动</h2>
+    <div class="my-steps-wrap">
+      <fox-steps-bar
+        class="my-scroll-steps--"
+        v-model="curScrollStep"
+        :data="moreSteps"
+        :scroll="true"
+        step="80px"
+      ></fox-steps-bar>
+    </div>
+</template>
+
+<script lang="ts" setup>
+ import { ref } from 'vue'
+ 
+ // setps数据
+ export const moreSteps = [
+  {
+    text: '步骤一',
+    value: '01',
+    status: 'done'
+  },
+  {
+    text: '步骤二',
+    value: '02'
+  },
+  {
+    text: '步骤三',
+    value: '03'
+  },
+  {
+    text: '步骤四',
+    value: '04'
+  },
+  {
+    text: '步骤六',
+    value: '06'
+  },
+  {
+    text: '步骤七',
+    value: '07'
+  },
+  {
+    text: '步骤八',
+    value: '08'
+  },
+  {
+    text: '步骤九',
+    value: '09'
+  },
+  {
+    text: '步骤十',
+    value: '10'
+  }
+]
+
+// 可滚动step value
+const curScrollStep = ref('08')
+</script>
+
+```
+
+### 垂直方向
+通过设置属性`direction`设置步骤的方向。
+
+
+
+```html
+<template>
+  <h2>垂直方向</h2>
+    <div class="my-steps-wrap my-steps-wrap--vertical">
+      <fox-steps-bar
+        class="my-scroll-steps--vertical"
+        v-model="curVerticalScrollStep"
+        :data="moreSteps"
+        :scroll="true"
+        step="80px"
+        direction="vertical"
+      ></fox-steps-bar>
+    </div>
+</template>
+
+<script lang="ts" setup>
+ import { ref } from 'vue'
+ 
+ // setps数据
+ export const moreSteps = [
+  {
+    text: '步骤一',
+    value: '01',
+    status: 'done'
+  },
+  {
+    text: '步骤二',
+    value: '02'
+  },
+  {
+    text: '步骤三',
+    value: '03'
+  },
+  {
+    text: '步骤四',
+    value: '04'
+  },
+  {
+    text: '步骤六',
+    value: '06'
+  },
+  {
+    text: '步骤七',
+    value: '07'
+  },
+  {
+    text: '步骤八',
+    value: '08'
+  },
+  {
+    text: '步骤九',
+    value: '09'
+  },
+  {
+    text: '步骤十',
+    value: '10'
+  }
+]
+
+// 可滚动垂直step value
+const curVerticalScrollStep = ref('01')
+</script>
+
+```
+
+### 自定义布局
+通过设置属性`layout`设置步骤栏的布局。
+例如
+
+```html
+
+<!--通过layout设置步骤栏的组成部分(head、main和sub)，并且组成部分的排列属性-->
+ <fox-steps-bar :layout="['head', 'main', 'sub']"></fox-steps-bar>
+
+```
+`layout`数组的可设置部分为
+
+```ts
+/**
+ * layout类型
+ */
+export type LayoutType = 'head' | 'main' | 'sub' | 'mark'
+```
+
+
+```html
+<template>
+  <h2>自定义布局</h2>
+    <div class="my-steps-wrap my-steps-wrap--vertical">
+      <fox-steps-bar
+        class="my-flow-steps"
+        v-model="curCustomStep"
+        :data="formatflowSteps"
+        :scroll="true"
+        step="80px"
+        direction="vertical"
+        value-key="id"
+        :item-options="itemOptions"
+        :layout="['sub', 'head', 'main']"
+      >
+        <template v-slot:sub="scope">
+          <fox-group class="my-flow-steps__left">
+            <fox-row-item align="right">
+              <fox-text class="title">{{ scope.item.time }}</fox-text>
+            </fox-row-item>
+            <fox-row-item align="right">
+              <fox-text>{{ scope.item.date }}</fox-text>
+            </fox-row-item>
+          </fox-group>
+        </template>
+        <template v-slot:main="scope">
+          <fox-group class="my-flow-steps__right">
+            <fox-row-item align="left">
+              <fox-text class="title">{{ getStatusText(scope.index) }}</fox-text>
+            </fox-row-item>
+            <fox-row-item align="space-between">
+              <fox-text>{{ scope.item.name }}({{ scope.item.id }})</fox-text>
+              <fox-text type="success" mark>提交</fox-text>
+            </fox-row-item>
+            <fox-row-item align="left">
+              <fox-text color="#FFAA08FF" text-color="#333333FF">
+                <template v-slot:mark>
+                  <Issue></Issue>
+                </template>
+                {{ scope.item.tip }}
+              </fox-text>
+            </fox-row-item>
+          </fox-group>
+        </template>
+      </fox-steps-bar>
+    </div>
+</template>
+
+<script lang="ts" setup>
+ import { ref } from 'vue'
+ import { Issue } from '@fox-js/icons-vue'
+ 
+ // setps数据
+export const flowSteps = [
+  {
+    id: '01',
+    name: '陈圆圆',
+    tip: '该客户资质尚可，为我行存量客户',
+    date: '02-07',
+    time: '14:35'
+  },
+  {
+    id: '02',
+    name: '貂蝉',
+    tip: '资产负债有风险',
+    date: '03-07',
+    time: '17:35'
+  },
+  {
+    id: '03',
+    name: '杨玉环',
+    tip: '该客户资质尚可，为我行存量客户',
+    date: '03-07',
+    time: '17:35'
+  },
+  {
+    id: '04',
+    name: '王昭君',
+    tip: '该客户资质尚可，为我行存量客户',
+    date: '03-07',
+    time: '17:35'
+  },
+  {
+    id: '05',
+    name: '苏小小',
+    tip: '该客户资质尚可，为我行存量客户',
+    date: '03-07',
+    time: '17:35'
+  }
+]
+
+// 审批流程，倒序排列
+const formatflowSteps = computed(() => {
+  return [...flowSteps].reverse()
+})
+// 自定义step value
+const curCustomStep = ref(formatflowSteps.value[0].id)
+// item options
+const itemOptions = (item: Record<string, number>, index: number) => {
+  if (index > 0) {
+    return {
+      status: 'done'
+    }
+  }
+  return {
+    status: 'done'
+  }
+}
+// 获取状态text
+const getStatusText = (index: number) => {
+  if (index == 0) {
+    return '审批中'
+  }
+  return '审批完成'
+}
+</script>
+
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 StepsBar 配合使用的相关组件
+- **fox-group**: 与 StepsBar 配合使用的相关组件
+- **fox-row-item**: 与 StepsBar 配合使用的相关组件
+- **fox-text**: 与 StepsBar 配合使用的相关组件
+

package/foxui/references/fox-sticky/doc.md

@@ -0,0 +1,68 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Sticky 组件使用规范
+impact: HIGH
+type: capability
+description: 当组件在屏幕范围内时，会按照正常的布局排列，当组件滚出屏幕范围时，始终会固定在距离屏幕固定的距离处
+tags: [foxui, fox-sticky, FoxSticky]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-cell","fox-button"]
+---
+
+# Sticky 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Sticky 是 foxui 中用于 **当组件在屏幕范围内时，会按照正常的布局排列，当组件滚出屏幕范围时，始终会固定在距离屏幕固定的距离处** 的标准组件。
+- **基于**: NutUI `nut-sticky` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、适配 H5 与小程序多端
+- **适用场景**: 当组件在屏幕范围内时，会按照正常的布局排列，当组件滚出屏幕范围时，始终会固定在距离屏幕固定的距离处
+
+> 💡 **关键原则**: 在所有 当组件在屏幕范围内时，会按照正常的布局排列，当组件滚出屏幕范围时，始终会固定在距离屏幕固定的距离处 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `position` | 吸附位置（top、bottom） | String | top |
+| `top` | 吸顶距离 | Number | 0 |
+| `bottom` | 吸底距离 | Number | 0 |
+| `container` | 容器的 HTML 节点或者ID, 在小程序环境下需要同时指定 id | Element | - |
+| `z-index` | 吸附时的层级 | Number | 2000 |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `change` | 吸附状态改变时触发 | val: Boolean |
+| `scroll` | 滚动时触发 |  top: Number, fixed: Boolean  |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+无
+
+## 3. 例子 (Examples)
+
+
+
+## 4. 相关组件 (Related Components)
+- **fox-cell**: 与 Sticky 配合使用的相关组件
+- **fox-button**: 与 Sticky 配合使用的相关组件
+