Vol移动端 AI Skill（uni-app / Vue3）

当前ai skill用于实现移动端、app、小程序生成页面及完全自定义页面功能开发 【点击下载 ai skill】

1. 使用方式：点击下载ai skill，将下载的skill放在vol-app-next项目里,以 Cursor为例，打开移动端项目 vol-app-next,

AI 执行契约（最高优先级，冲突时以本节为准）

收到需求
  → §12.Z 关键词检索
  → 判定：独立 vol-form / 独立 vol-table / 生成列表 vol-view / 编辑页 vol-edit / 自定义页
  → 写文件：{表}.vue | {表}Edit.vue | 同目录子组件.vue | 必要时 pages.json
  → 禁止：改 {表}Options.js | 改 components/ 源码 | 把 Web 的 view-grid / .jsx 写法套到 App
  → 后台：只调 api/{表}/{Action}；实现细节读本地 vol-skill.md，不要在本 Skill 编造 Service 代码

文档源： 优先本 Skill 模板 → 不足时 WebFetch http://app.volcore.xyz/docs/app/{分区}/。不要假设用户仓库有 doc.app。

技术栈（仅移动端）： Vue 3 script setup（无 lang="jsx"）、uni-app、uView、vol-form / vol-table / vol-view / vol-edit。HTTP：proxy.http.get/post。提示：proxy.$toast / proxy.$message。

零、AI 工作流

官方在线文档：http://app.volcore.xyz

开发者描述业务
    ↓
① 本 Skill §12.Z 检索 → 定位 §四–§十 模板
    ↓
② 不够 → 访问 app.volcore.xyz 对应分区
    ↓
③ 读用户项目 pages/.../{表}/{表}.vue、{表}Edit.vue、{表}Options.js（只读 Options，改写在 vue）
    ↓
④ 只改业务 vue / 新建子组件；禁止改 components/、禁止手改 Options.js
    ↓
⑤ 需要改后台 → 打开本地 vol-skill.md（若存在）写 Partial；移动端只调接口

文档体系（AI 路由必读）

四类文档职责不同。vol-view 是生成列表页容器，内嵌 vol-table；编辑独立页用 vol-edit。

生成页组件关系（必知）

三层扩展： ① vol-view / vol-edit 的 props Hook → ② onInited($vm) 改 buttons → ③ 字段/列事件写在 formOptions / columns 项上。

一、项目结构

vol-app-next/
├── pages/{模块}/{表}/
│   ├── {表}.vue              ← 【列表】vol-view 业务（★）
│   ├── {表}Edit.vue          ← 【独立编辑】vol-edit 业务（★）
│   └── {表}Options.js        ← 生成器配置（会被覆盖，禁止手改）
├── pages.json                ← 新页面必须注册 path
├── components/               ← 框架组件，禁止改业务
│   ├── vol-form / vol-table / vol-view / vol-edit
│   └── vol-permission        ← proxy.base.getPermission

路径以用户项目实际生成为准（常见 pages/dbtest/{表}/）。路由：/{表}、/{表}Edit?id=。

1.0 业务写哪里

二、核心原则（MUST）

1. Vue 写法： script setup。不要用 Web 的 script setup lang="jsx"、不要用 view-grid、el-button、gridRef.getFormOption（App 用 proxy.base.getFormOption(editFormOptions, field)）。
2. 小程序插槽： 只能固定插槽名（#field #title #extra #header #bottom 等）。列/字段必须设 slot:true / titleSlot:true / extraSlot:true / headerSlot:true，漏配不生效。用 v-if="data.item.field === 'xxx'" 或 data.field === 'xxx' 区分字段。禁止动态插槽名。
3. saveBefore： 签名 (formData, isAdd, callback)，必须 callback(true) 才会保存；callback(false) 中止。不要只 return true。
4. searchBefore / loadBefore： return true/false。生成列表页须把 vol-view 查询条件写入 params.wheres。
5. Options.js 会被生成覆盖。 动态改 searchFormOptions、columns、editFormOptions 在 vue 的 onInited 或加载后执行。
6. 不要改 components/。
7. 新页面： 同步改 pages.json；跳转 uni.navigateTo({ url: '/pages/.../{表}Edit?id=' + id })。
8. 后台： 标准接口已存在。自定义查询/写库打开 vol-skill.md。移动端 proxy.http.post('api/{表}/{Action}', body, true)，第三参数 true=显示 loading。

三、代码生成默认能力

生成表后已具备（业务用 Hook 扩展，不要重写组件）：

保存体：

// 无明细 / 弹框编辑
{ mainData: proxy.base.getFormValues(editFormFields, editFormOptions) }

// 单明细
{ mainData, detailData: details[0].tableData, delKeys }

// 一对多
{ mainData, details: [{ table, data, delKeys }, ...] }

四、vol-form（重点）

在线：http://app.volcore.xyz/docs/app/form/params.html · 插槽 http://app.volcore.xyz/docs/app/form/slot.html

4.1 最小用法

<template>
  <vol-form ref="formRef" :form-options="formOptions" :formFields="formFields" :labelWidth="80" labelPosition="left"
    @onChange="onChange">
    <template #field="{ data }">
      <view v-if="data.item.field === 'custom'">自定义</view>
    </template>
  </vol-form>
</template>
<script setup>
import { ref, reactive, getCurrentInstance } from 'vue'
const { proxy } = getCurrentInstance()
const formRef = ref(null)
const formFields = reactive({ name: '', orderType: '' })
const formOptions = reactive([
  { title: '名称', field: 'name', type: 'input', required: true },
  { title: '类型', field: 'orderType', type: 'select', data: [], key: '订单类型' }
])
const onChange = (field, value, item, data) => {}
</script>

4.2 组件 props

formOptions formFields inline(快捷搜索等宽、隐藏标题) height loadKey labelWidth labelPosition padding titleFontSize valueFontSize textAlign titleStyle valueStyle getStyle uploadBefore

4.3 字段 type

常用项：title field required readonly hidden placeholder data key/dataKey 字典、bind、extra、slot/titleSlot/extraSlot、formatter、min/max/range。

extra： { text, button:true, type:'primary', icon:'search', color, size, style }

4.4 字段事件（写在 option 项上，优先）

const opt = proxy.base.getFormOption(editFormOptions, 'Qty')
opt.onChange = (field, value, item, data) => { editFormFields.Amount = value * editFormFields.Price }
opt.onKeyPress = (field, value, item, e) => {}
opt.onInputConfirm = (field, value, item, e) => {}
opt.onExtraClick = (item, formFields) => {}
opt.click = (item, formFields) => {}

组件也可 @onChange @inputConfirm @extraClick。实时计算也可用 watch(() => editFormFields.Qty, ...)。

4.5 插槽

data：item value formFields readonly。

4.6 方法 / base

formRef.value.validate()           // false 时已 toast
formRef.value.reset(source?)
formRef.value.setReadonly(true)
formRef.value.initDicKeys()
proxy.base.getFormValues(fields, options)     // 提交
proxy.base.resetForm(fields, options, row)    // 回填（图片走 getImg）
proxy.base.getFormOption(options, field)
proxy.base.getFormDicData(options, field)
proxy.base.setFormFocus(options, field, 400)

五、vol-table（重点）

在线：http://app.volcore.xyz/docs/app/table/params.html

5.1 两种 direction（MUST 先判定）

生成页 table.direction 写在 Options 的 table 上，vue 里改 table.direction。

5.2 最小用法

<vol-table ref="tableRef" :url="table.pageUrl" :columns="columns" :table-data="tableData"
  :direction="table.direction" :titleField="table.titleField" :ck="table.ck" :index="table.rowIndex"
  :loadBefore="loadBefore" :loadAfter="loadAfter" @rowClick="rowClick">
  <template #field="{ data }">
    <view v-if="data.field === 'oper'">
      <vol-button size="small" type="primary" :block="false" @click="viewClick(data.row)">查看</vol-button>
    </view>
  </template>
</vol-table>

自定义 url 时后台须返回 { rows, total }，查询体含 wheres/page/rows/sort（实现见 vol-skill.md ConvertQueryFilter + TakePage）。

5.3 组件 props（常用）

url tableData columns direction titleField index ck height(0 占满 / -1 自适应) minHeight readonly(默认 true) textInline textAlign labelWidth labelPosition loadKey defaultLoad padding paddingBottom contentPadding rowStyle columnStyle selectable formatter getButtons loadBefore loadAfter getStyle titleStyle valueStyle

5.4 columns

通用：title field width align fixed hidden type bind:{key,data} slot headerSlot formatter click btn cellStyle。

list 另：titleSlot extraSlot extra readonly required 及与 vol-form 相同的 type。

操作列：{ field:'oper', title:'操作', width:140, slot:true, headerSlot:true } + #field。

5.5 插槽

#data 替代整表；#columnHeader（headerSlot）；#field（slot）；#custom horizontal 追加；list：#header #title #extra #bottom；默认插槽=表底。

5.6 事件与方法

事件：onChange inputConfirm rowClick cellClick ckChange ckChangeAll extraClick dicInited。list 编辑事件写在 列上：onChange:(value,item,row)=>{}。

tableRef.value.load()
tableRef.value.load(null, true) // 重置第一页
tableRef.value.getSelectedRows()
tableRef.value.clearSelectedRows()
tableRef.value.delRows()
const col = proxy.base.getColumn(columns, 'Qty')

5.7 loadBefore

const loadBefore = (params) => {
  params.wheres = params.wheres || []
  params.wheres.push({ name: 'OrderNo', value: kw, displayType: 'like' })
  params.sort = params.sort || table.sortName
  return true
}

displayType 常用：equal like thanorequal lessorequal。

六、vol-view 生成列表页（重点）

在线：http://app.volcore.xyz/docs/app/page/params.html · 插槽 /docs/app/page/slot.html

这是代码生成后的列表页容器。 业务写 {表}.vue。

6.1 标准结构（按此改，不要换成 view-grid）

<template>
  <vol-view ref="viewRef" :table="table" :columns="columns" :table-data="tableData"
    :searchFormFields="searchFormFields" :searchFormOptions="searchFormOptions"
    :editFormFields="editFormFields" :editFormOptions="editFormOptions"
    @searchClick="loadData" @addClick="modelOpenBefore"
    :saveBefore="saveBefore" :saveAfter="saveAfter" :delBefore="delBefore" :onInited="onInited">
    <template #button><!-- 右上筛选旁 --></template>
    <template #search-input><!-- 快捷搜索右侧，如扫码 --></template>
    <template #content><!-- 表格上方 --></template>
    <vol-table ref="tableRef" :ck="table.ck" :index="table.rowIndex" :default-load="true"
      :url="table.pageUrl" :direction="table.direction" :titleField="table.titleField"
      :columns="columns" :table-data="tableData" :padding-bottom="table.paddingBottom"
      :loadBefore="searchBefore" :loadAfter="searchAfter"
      @rowClick="(row) => modelOpenBefore(row, false)">
    </vol-table>
  </vol-view>
</template>
<script setup>
import options from './{表}Options.js'
import { onLoad } from '@dcloudio/uni-app'
import { ref, reactive, getCurrentInstance, nextTick } from 'vue'
const { proxy } = getCurrentInstance()
const viewRef = ref(null)
const tableRef = ref(null)
const tableData = ref([])
const { table, searchFormFields, searchFormOptions, editFormFields, editFormOptions, columns } = reactive(options())
let gridRef
const onInited = async ($vm) => { gridRef = $vm }
const loadData = () => { tableRef.value?.load(null, true) }
</script>

6.2 table（Options.js，vue 里改对象不要改文件）

table = {
  tableName, tableCNName, titleField, key, sortName,
  pageUrl: 'api/{表}/getPageData',
  quickSearchFields: 'Field1,Field2',
  direction: 'horizontal', // 或 list
  ck: true, rowIndex: true, paddingBottom: 0
}

vol-view 常用 props：tableAction(权限表名) showTotal searchInput/showSearchInput searchField labelWidth labelPosition defaultLoad
Hooks：searchBefore/After searchModelOpenBefore addBefore/After updateBefore/After delBefore/delBeforeAsync/delAfter modelOpenBefore* saveBefore/After rowClick onInited getBottomButton

6.3 查询（生成页固定套路）

const searchBefore = (params) => {
  if (viewRef.value && !params.wheres?.length) {
    params.wheres = viewRef.value.getSearchParameters().wheres
  }
  params.sort = params.sort || table.sortName
  return true
}
const searchAfter = (res) => {
  nextTick(() => { viewRef.value?.searchAfter(res) })
  return true
}

默认查询值：vol-table :default-load="false"，onLoad 里给 searchFormFields 赋值后 loadData()。日期区间：searchFormFields.date = [begin, end]，datetime 必须带时分秒。proxy.base.getDate(true) / addDays。

6.4 新建/编辑打开

const modelOpenBefore = (row, isAdd) => {
  // A. 独立编辑页
  uni.navigateTo({
    url: '/pages/{模块}/{表}/{表}Edit?id=' + ((row || {})[table.key] || '')
  })
  // B. 当前页弹框（不要同时开两种）
  // viewRef.value.showEdit(row, isAdd)
}

弹框保存：saveBefore(formData, isAdd, callback){ callback(true) }。删除：delBefore 返回 false 中止。

6.5 按钮

const onInited = async ($vm) => {
  gridRef = $vm
  gridRef.buttons.push({
    name: '测试', value: '', hidden: false, type: 'success',
    onClick: () => { proxy.$toast('点击了测试') }
  })
}

权限按钮由 vol-view 按 table.tableName 自动过滤。插槽按钮：#button #btn-left #btn-right #search-button。

6.6 vol-view 插槽

#header #button #content #quick-search #search-input 默认(vol-table) #btn-left #btn-right #search-header #search-button #modelHeader #modelBody #edit-button #modelFooter

表格行插槽写在 内嵌 vol-table 上（#header #bottom #field）。

6.7 实例方法

viewRef.getSearchParameters() searchAfter(res) showEdit(row,isAdd) search()；tableRef.load。

列格式化：columns 项 formatter / cellStyle / rowStyle；见 /docs/app/page/format1.html。

七、vol-edit 编辑页（重点）

在线：http://app.volcore.xyz/docs/app/edit/params.html · 插槽 /docs/app/edit/slot.html

有 {表}Edit.vue 即独立页编辑。列表点新建/编辑 navigateTo 带 id。

7.1 标准结构

<template>
  <vol-edit ref="editRef" :id="id" :table="table" :detail="detail" :details="details"
    :editFormFields="editFormFields" :editFormOptions="editFormOptions"
    :saveBefore="saveBefore" :saveAfter="saveAfter" :delBefore="delBefore"
    :loadFormAfter="loadFormAfter" :delRowBefore="delRowBefore" :delRowAfter="delRowAfter"
    :onInited="onInited" @onChange="onChange" :labelWidth="70" labelPosition="right">
    <template #content="{ editFormFields }"><!-- 主表与明细之间 --></template>
    <template #button><!-- 底栏左侧 --></template>
    <template #detail-button><!-- 明细表头 --></template>
  </vol-edit>
</template>
<script setup>
import options from './{表}Options.js'
import { onLoad } from '@dcloudio/uni-app'
import { ref, reactive, getCurrentInstance } from 'vue'
const props = defineProps({ id: '' })
const id = ref(props.id)
const isAdd = !id.value
const { proxy } = getCurrentInstance()
const editRef = ref(null)
const { table, editFormFields, editFormOptions, detail, details } = reactive(options())
onLoad((ops) => { if (ops?.id) id.value = ops.id })
</script>

加载主表：api/{表}/getPageData，wheres 主键。保存 api/{表}/add|update。删除 api/{表}/del 传 [id]。

7.2 常用 props / Hook

checkAuth readonly editChange(新建保存后变编辑) tableAction saveName direction(明细 horizontal/list) index ck
onInited loadFormBefore/After saveBefore/After delBefore/After loadDetailBefore/After delRowBefore/After addRow detailFormInited detailFormSaveBefore/After modelOpenBefore* rowClick

事件：onChange inputConfirm extraClick detailOnChange detailInputConfirm detailExtraClick dicInited

7.3 onInited 追加按钮

const onInited = async ($vm) => {
  $vm.buttons.push({ name: '扫码', type: 'success', onClick: () => {
    uni.scanCode({ success: (res) => { editFormFields.OrderNo = res.result } })
  }})
  $vm.detailButtons.push({ name: '选择商品', type: 'success', onClick: () => {} })
  $vm.boxOptions.buttons.unshift({ name: '测试', type: 'success', onClick: () => {} })
}

隐藏：$vm.buttons.forEach(c => { c.hidden = true })（同样 detailButtons）。

7.4 保存 / 明细

const saveBefore = (formData, isAdd, callback) => {
  // formData.mainData / detailData / details
  callback(true)
}
const loadFormAfter = (result, row) => {
  // editFormFields.xxx = 默认值
}
const delRowBefore = async (rows, table, ops) => { return true }

明细弹框字段 extra：在 detailFormInited(table) 里 table.edit.formOptions.find(x => x.field==='GoodsName').extra = { text:'选择', button:true, type:'primary', icon:'search' }，点击走 @detailExtraClick。

明细列事件写在 detail.columns（与 vol-table list 相同）。

一对多：Options 的 details 数组，多项 tab；加载 params.tableName、params.value=主键。

7.5 vol-edit 插槽

#header #form #content 默认 #detail-button #detail-header #detail-footer #button #buttonRight #modelHeader #modelBody #modelData #box-button #modelFooter

主表字段插槽仍是 vol-form 规则；明细单元格是 vol-table 规则。

方法：editRef.save() reset() search() getTable()。

八、HTTP、权限、base、后台

在线：http://app.volcore.xyz/docs/app/guide/

8.1 HTTP

const { proxy } = getCurrentInstance()
proxy.http.post('api/{表}/{Action}', { ... }, true).then((res) => {
  proxy.$toast(res.message)
})
proxy.http.get('api/{表}/{Action}', {}, true)

标准：getPageData add update del upload。自定义 Action 与 Web 相同，见 vol-skill.md（Partial 三件套、JsonNormal、EF TakePage）。

8.2 权限

const permission = await proxy.base.getPermission('Demo_Order') // 菜单 tableName
const btns = permission?.permission || [] // Search Add Update Delete
const hasAdd = btns.includes('Add')

vol-view / vol-edit 已自动按表名过滤按钮。tableAction 可指定另一张表的权限。

8.3 base 常用

getDate(withTime) addDays addMonth isEmpty getImg setItem/getItem(全局缓存) getColumn getColumnDicData

8.4 后台（本 Skill 不展开）

若工作区有 vol-skill.md：查询过滤、保存前后、自定义分页按该文件写 Partial/{表}Service.cs。
禁止在本 Skill 中发明 Web view-grid / .jsx / Element Plus 代码。
无 vol-skill.md 时：只完成 App 调用，接口约定 { status, message, data } 或表格 { rows, total }，并提示用户补后端。

九、其他组件（次要）

在线：http://app.volcore.xyz/docs/app/other/

弹框选数：vol-box + vol-table url + getSelectedRows() 回写 editFormFields。

十、业务场景模板

10.1 列表扫码搜

<template #search-input>
  <vol-button @click="scanClick" type="success" :block="false" customStyle="margin-left:8rpx;">扫码</vol-button>
</template>

const scanClick = () => {
  uni.scanCode({
    success: (res) => { searchFormFields.OrderNo = res.result; loadData() }
  })
}

10.2 表单 extra 弹框选数据

const opt = proxy.base.getFormOption(editFormOptions, 'Customer')
opt.readonly = true
opt.extra = { text: '选择', button: true, type: 'primary', icon: 'search' }
opt.onExtraClick = () => { boxVisible.value = true }
const onSelect = (rows) => {
  editFormFields.Customer = rows[0].Customer
  editFormFields.CustomerId = rows[0].CustomerId
  boxVisible.value = false
}

10.3 下拉联动

proxy.base.getFormOption(editFormOptions, 'Province').onChange = (field, val) => {
  editFormFields.City = ''
  const city = proxy.base.getFormOption(editFormOptions, 'City')
  proxy.http.post('api/{表}/GetCity', { parentId: val }, true).then((res) => { city.data = res })
}

10.4 列操作按钮

columns 增加 { field:'oper', title:'操作', width:140, slot:true }，#field 里 v-if="data.field==='oper'"。

10.5 行样式

const rowStyle = (row, index) => row.OrderStatus == 1 ? { background: '#fef0f0' } : {}
const columnStyle = (row, column) => column.field === 'TotalPrice' ? { color: 'red' } : {}

十一、自然语言 → 解析

【表名】{TableName}
【页面】列表 {表}.vue / 编辑 {表}Edit.vue / 独立表单或表格
【direction】horizontal 表格 / list 列表（未说则看现有 table.direction）
【业务】查询条件、按钮、扫码、弹框选数、明细、跳转编辑还是当前页弹框
【后台】若需新接口 → vol-skill.md

判定：存在 {表}Edit.vue 且需求是保存主从 → §七；只改列表查询/按钮 → §六；纯表单页 → §四；纯表格页 → §五。

十二、全量索引（§12.Z）

收到需求先检索本表。

十三、在线文档 URL

站点： http://app.volcore.xyz/
拼接：http://app.volcore.xyz/docs/app/{form|table|page|edit|guide|other}/{页名}.html（部分为目录 /）。

本 Skill 不覆盖： HBuilder 安装、菜单配置、代码生成器操作界面、Web PC、审批流程设计器。表级 App 业务用 §四–§十；后台用 vol-skill.md。

AI 勿混淆：

• App 生成列表 = vol-view，不是 view-grid
• App 编辑独立页 = vol-edit 在 {表}Edit.vue
• 字段配置数组名是 formOptions，不是 Web 的 formRules
• 不要改 Options.js，不要改 components/

Vol.Pro 移动端 AI 开发技能 · vol-form / vol-table / vol-view / vol-edit · 在线文档 app.volcore.xyz · 后台参照 vol-skill.md