Nop Frontend Dev

Nop 前端页面开发

什么时候用我

必读文档路径

以下路径相对于 {DOCS-FOR-AI} 目录。{DOCS-FOR-AI} 的实际位置由当前项目 AGENTS.md 的 "Nop Platform Documentation" 部分指定（本项目中为 ../nop-entropy/docs-for-ai/）。

全局必读（写任何前端/页面代码前全部读完）

按场景选读

自检纪律

每完成一个 .view.xml / .page.yaml 文件后，对照下方反模式表逐项校验。 自检在每个文件完成后执行，不是逐操作检查。任何不通过项必须修复后才能提交。

项目文件位置

XView 三层模型

view.xml
├── grids    → 列表/表格 (grid)
├── forms    → 表单 (form: edit/add/query)
└── pages    → 页面组织 (crud/simple/tabs/picker)

最小理解模型

<view x:extends="_gen/_LitemallOrder.view.xml"
      x:schema="/nop/schema/xui/xview.xdef"
      xmlns:x="/nop/schema/xdsl.xdef">

    <grids>
        <grid id="list">
            <cols x:override="bounded-merge">
                <col id="id"/>
                <col id="orderSn" label="订单编号"/>
            </cols>
        </grid>
    </grids>

    <forms>
        <form id="edit" size="lg">
            <layout>
                orderSn[订单编号] orderStatus[订单状态]
            </layout>
        </form>
    </forms>

    <pages>
        <crud name="main" grid="list" filterForm="query">
            <rowActions x:override="bounded-merge">
                <action id="row-update-button" actionType="drawer"/>
            </rowActions>
        </crud>
    </pages>
</view>

核心操作模式

1. x:override — 继承链（x:extends）中的合并算子

用于 x:extends 继承链中控制当前节点如何与基类合并：

bounded-merge 适合的场景： 继承了一个很大的列表配置（cols、rowActions、listActions），但你只想保留其中一小部分。它等价于"白名单"——你写什么就留什么，没写的全部丢弃。

<!-- 只保留 id 和 name 两列，其余继承来的列全部丢弃 -->
<cols x:override="bounded-merge">
    <col id="id"/>
    <col id="name" label="名称"/>
</cols>

2. x:prototype — 克隆同层级兄弟节点作为模板

基于同一个 view 中已存在的 grid/form/crud 克隆出变体。变体之间通常只有 filter、action 的局部差异。

<!-- 克隆 "list" grid 作为 "wait-list" 的起点 -->
<grid id="wait-list" x:prototype="list"/>

<!-- 克隆 "main" crud 作为 "wait-approve" 的起点 -->
<crud name="wait-approve" x:prototype="main"/>

<!-- 克隆 "edit" form 作为 "add" form -->
<form id="add" x:prototype="edit" editMode="add"/>

3. x:prototype-override — prototype 变体的合并算子

合并分两个阶段：先 x:extends 继承合并（用 x:override），再 x:prototype 克隆合并（用 x:prototype-override）。需要两个属性是因为同一节点会经历两次合并，可能需要不同策略。

x:prototype-override 支持与 x:override 完全相同的值，但只在 prototype 克隆阶段生效：

<!-- 从 "main" crud 克隆，但 rowActions 只保留自己列出的按钮 -->
<crud name="wait-approve" x:prototype="main">
    <listActions x:prototype-override="remove"/>
    <rowActions x:prototype-override="bounded-merge">
        <action id="row-approve-button"/>
    </rowActions>
</crud>

什么时候用 x:prototype-override： 当你用 x:prototype 克隆了一个变体，但需要裁剪克隆结果中的某些子节点（如只保留部分按钮、删除部分 action）时使用。

区别总结：

4. 删除继承/克隆来的节点

<layout x:override="remove"/>

5. 复用已有 form 结构（x:prototype）

<form id="add" x:prototype="edit" editMode="add"/>

6. 无 objMeta 的表单必须配置 domain

<form id="queryForm" editMode="edit" title="查询">
    <layout>
        indexId[索引ID] qualifiedName[全限定类型名]
    </layout>
    <cells>
        <cell id="indexId" label="索引ID" domain="string"/>
        <cell id="qualifiedName" label="全限定类型名" domain="string"/>
    </cells>
</form>

7. 自定义字段（非实体属性）

<cell id="__password2" custom="true" notSubmit="true"/>

8. Delta 覆盖平台页面

<!-- _delta/default/nop/auth/pages/NopAuthUser/NopAuthUser.view.xml -->
<view x:extends="super" ...>
    <!-- 只写需要改的部分 -->
</view>

页面任务路由

先判断任务类型，再走对应路径：

1. 字段上屏 → make-field-reach-page.md
2. 复杂控件 → replace-field-with-complex-control.md
3. 子表编辑 → add-child-table-editor-to-page.md
4. 业务按钮 → add-page-business-action.md
5. 树形/关联/工作台 → 对应 runbook
6. 平台页面覆盖 → override-platform-page-with-delta.md

反模式表

项目内高价值样例

参考文件

• {DOCS-FOR-AI}/03-runbooks/admin-page-development-roadmap.md — 页面任务路由总入口
• {DOCS-FOR-AI}/02-core-guides/view-and-page-customization.md — view.xml完整规范
• {DOCS-FOR-AI}/02-core-guides/page-dsl-pattern-catalog.md — 复杂页面DSL模式目录