前端约定
列表页
参照 views/system/user/index.vue:根元素 class="table-page",表格卡片 table-card,表格 :scroll="{ x: scrollX, y: '100%' }",即可获得固定页头、只有表格滚动的效果。
- 列宽:
useColumns(columns, 存储键)返回的scrollX作为scroll.x,不要写死数字。所有列默认显示,一列只放一项信息,宽度不够时横向滚动,用户可在「列设置」中隐藏列。字典列在列定义中写dict: 字典类型。 - 查询条件放在
<SearchForm>中,每个a-form-item一格,超过 3 个时可展开;日期范围等宽条件加data-wide。 - 字典:
useDict('ecom_order_type')+<DictTag>。 - 订单这类按状态分组的列表用页签并显示数量(如平台订单的待审核、缺货、待打单、待发货、已发货、异常 / 挂起、全部)。
操作列
统一用 <TableActions :actions="rowActions(record)" />,列定义用 actionColumn(图标数):
- 操作显示为图标按钮,悬停显示文字,图标之间用竖线分隔,右对齐;一行只有一个操作时显示「图标 + 文字」。
- 顺序:查看 → 编辑 → 主操作(审核、发货、推送等)→ 删除 → 更多;不常用的操作写
more: true放进「更多」(三个点)。每行直接显示的图标不超过 4 个。 - 每个操作
{ type 或 key, label, icon, onClick, perm, show, disabled, confirm, more },perm代替v-perm,show代替v-if。
表单、详情与子页
- 表单用
useFormDrawer+<FormDrawer>:自带加载详情、校验、保存、未保存修改的关闭确认、Ctrl / ⌘ + Enter 保存。 - 抽屉还是子页:字段少的简单资料(仓库、库位、物流渠道、订单标签等)用抽屉;字段多、有明细行、有多个分区的表单(编辑店铺、在线商品、订单规则、广告规则、刊登模板、供应商、客户等)加
<FormDrawer page>,详情用<SubPage>(用法同a-drawer)。子页占满内容区、覆盖在列表之上,返回后列表的筛选、分页、滚动位置不变。 - 从详情进入编辑时不要关闭详情,保存后调用详情组件暴露的
reload()。 - 页面超过 500 行时,把弹窗、标签页、表单拆成同目录子组件(
defineExpose({ open })+ 事件)。
常用组件与函数
| 场景 | 用法 |
|---|---|
| 单条操作 | useAction(api, { confirm, successKey, reload: () => load() }):确认 → 调接口 → 提示 → 刷新 |
| 明细行 | useLineItems(() => form.value.items, { newRow }) + <LineItemsTable> |
| 金额、数量 | utils/number.js 的 money、price、qty、round2、sumBy,与后端 Decimals 精度一致 |
| 远程下拉 | 店铺 components/ecom/StoreSelect、物流渠道 ChannelSelect、客户 / 供应商 PartnerSelect、物料 MaterialSelect(支持扫码)、人员 IdentityUserSelect;其他用 RemoteSelect / useRemoteOptions。下拉接口分页(默认 20、最多 50),支持按 ids 回显 |
| 附件、变更历史、自定义字段 | <AttachmentPanel>、<ChangeLogPanel>、useCustomFields |
| AI 草拟 / 翻译按钮 | components/ecom/ai/AiTextButton.vue 与 useEcomAi |
样式
- 强调色用 CSS 变量
--app-primary等(随主题色变化),不要写死#1677ff;图表系列色、平台品牌色是数据颜色,不跟随主题。 - 深色模式样式写在非 scoped 的
<style>中(html[data-theme='dark'] ...)。
小程序
lemon-mp 只放随时随地、操作轻、能用上手机能力的功能(审批、消息与公告、商品速查、快速开单 / 入库、单据草稿、库存查询与扫码作业),接口与 Web 端共用;电商的订单出库、头程签收等在电脑端处理。约定见主项目 lemon-mp/README.md。