H5 端 NeoEntityList 使用说明

一、组件概述

NeoEntityList是对 H5 业务组件 EntityList 的二次封装，支持在「自定义组件」中通过 import 代码方式使用。

底层 EntityList 使用 卡片式列表 展示列表数据，支持 SmartView 切换、搜索、筛选、排序、批量操作、下拉刷新与上拉加载等能力。

技术栈

• React：类组件封装（继承 BaseCmp）
• MobX / MST：底层 EntityList 与 EntityListStore 状态管理
• amis：通过 props.render 渲染 EntityList Schema
• TypeScript：与 RendererProps 等类型配合使用

二、核心功能

1. 列表类型与展示

• 固定为 大列表 场景（tableType: 'list'），列表项为 卡片 形态。
• 可通过 disableTitleView、isShowTitlePicker 控制 标题区 与 视图切换（Picker） 是否展示（封装内默认：隐藏标题区、不展示视图 Picker，详情见属性表）。

2. 数据与分页

• 数据通过 EntityListStore 拉取布局与列表数据，支持分页。
• pageSize 对应请求中的每页条数（内部默认 20）。
• isNoRefresh 为 true 时 禁用下拉刷新与上拉加载。

3. SmartView、搜索、筛选与排序

• 支持 SmartView 及对应的数据范围与列配置（是否展示视图切换受 disableTitleView / isShowTitlePicker 等影响）。
• disableSearch：隐藏顶部搜索相关能力。
• disabledSort / disabledFilter：隐藏列表上的 排序 / 筛选 控件（与《详细分析文档》中「筛选和排序」章节一致）。

4. 批量操作与按钮区

• disabledOperationBtn：为 true 时隐藏 操作按钮区域（如新建、批量操作等，具体以产品实现为准）。
• disabledShortcutBtn：为 true 时隐藏 快捷按钮区域。

5. 列表项交互与详情

• 默认点击列表项会通过 NeoNavigator.openEntityDetail 打开实体详情。
• 可通过 onItemClickIntercept 拦截：返回真值时 不执行默认打开详情逻辑（见下文）。

三、组件属性说明

基础配置属性

属性名	类型	默认值	说明
entityApiKey	string	（必填）	实体 ApiKey；同时作为 objectApiKey 传入 EntityList
render	Function	（必填）	amis 注入的渲染函数，必传，通常为 this.props.render 或 props.render
disableTitleView	boolean	true	为 true 时隐藏 标题区域（封装默认隐藏，需标题时可传 false）
isShowTitlePicker	boolean	false	为 true 时展示 切换视图的 Picker
disableSearch	boolean	false	为 true 时不展示搜索框
disabledSort	boolean	false	为 true 时不展示列表 排序 组件
disabledFilter	boolean	false	为 true 时不展示列表 筛选 组件
disabledOperationBtn	boolean	false	为 true 时隐藏 操作按钮区（含新建、批量操作等）
disabledShortcutBtn	boolean	false	为 true 时隐藏 快捷按钮区
pageSize	number	未传则走内部默认	每页加载条数（search 接口 page.pageSize）
isNoRefresh	boolean	false	为 true 时禁用 下拉刷新 与 上拉加载
autoHeight	boolean	false	为 true 时外层高度为 auto，列表区域使用 body 滚动（与 EntityList 一致）

其他可用属性

属性名	类型	说明
onItemClickIntercept	Function	列表项点击拦截，见 四、核心回调说明
onSearchDataComplete	Function	列表数据请求完成回调，见 四、核心回调说明
style	object	自定义样式对象，传入 EntityList

四、核心回调说明

onItemClickIntercept — 列表项点击拦截

作用：在用户点击列表项准备打开详情 之前 调用；若返回 真值（truthy），则 不会 执行默认的 NeoNavigator.openEntityDetail。

函数签名（典型用法）：

onItemClickIntercept?: (data: any, entity: any, context?: any) => any

参数说明：

• data：当前行 / 卡片对应的数据（含 id、entityType 等）。
• entity：实体元数据相关信息（含 apiKey 等）。
• context：部分调用路径会传入 amis context（与 EntityList 内 listItemClick 实现一致）。

实现逻辑（与 EntityList 一致）：

result = onItemClickIntercept?.(data, entity, context)
若 result 为真 → 不打开详情
否则 → NeoNavigator.openEntityDetail(...)

使用示例见 示例 4。

onSearchDataComplete — 列表数据请求完成

作用：在列表数据请求流程中作为回调传入 Store，用于在 数据刷新、加载 等完成后执行自定义逻辑（例如刷新汇总、埋点等）。具体调用链与 EntityList / EntityListStore 内 getListData、refreshListData 一致，详见《EntityList H5 组件的详细分析文档》。

函数签名（示意）：

onSearchDataComplete?: (data?: any) => void

五、完整使用示例

说明

• 说明1：NeoEntityList 需从 neo-ui-component-h5 导出；
• 说明2：无需在项目中安装 neo-ui-component-h5；组件在 Neo 平台运行时会由平台注入该模块；
• 说明3：render 必须为框架注入的 this.props.render（类组件）或 props.render（函数组件），否则子 Schema 无法渲染。

示例 1：基础实体列表

import * as React from 'react'
import { NeoEntityList } from 'neo-ui-component-h5'

interface Props {
  render: (name: string, schema: object) => React.ReactNode
}

export default class AccountNeoEntityListBasic extends React.Component<Props> {
  render() {
    return (
      <NeoEntityList
        render={this.props.render}
        entityApiKey="account"
        disableTitleView={false}
        isShowTitlePicker
      />
    )
  }
}

示例 2：精简展示（无标题区、无视图切换）

import * as React from 'react'
import { NeoEntityList } from 'neo-ui-component-h5'

export default class ContactNeoEntityListMinimal extends React.Component<{ render: any }> {
  render() {
    return (
      <NeoEntityList
        render={this.props.render}
        entityApiKey="contact"
        disableTitleView
        isShowTitlePicker={false}
        style={{ minHeight: 200 }}
      />
    )
  }
}

示例 3：关闭搜索 / 排序 / 筛选与下拉刷新

import * as React from 'react'
import { NeoEntityList } from 'neo-ui-component-h5'

export default class LeadNeoEntityListNoChrome extends React.Component<{ render: any }> {
  render() {
    return (
      <NeoEntityList
        render={this.props.render}
        entityApiKey="lead"
        disableSearch
        disabledSort
        disabledFilter
        isNoRefresh
        pageSize={15}
      />
    )
  }
}

示例 4：拦截列表项点击（不打开详情）

import * as React from 'react'
import { NeoEntityList } from 'neo-ui-component-h5'

export default class OpportunityNeoEntityListIntercept extends React.Component<{ render: any }> {
  render() {
    return (
      <NeoEntityList
        render={this.props.render}
        entityApiKey="opportunity"
        onItemClickIntercept={(data, entity) => {
          console.log('点击列表项', data, entity)
          // 返回 true 拦截默认打开详情
          return true
        }}
        onSearchDataComplete={(payload) => {
          console.log('列表数据请求完成', payload)
        }}
      />
    )
  }
}

其他用法示例

见 CLI 内置组件模板 neo-h5-cmps。

六、注意事项

1. render 必传

在 Neo 自定义组件内使用 NeoEntityList 时，必须传入 render={this.props.render}（或函数组件的 props.render），用于渲染 EntityList 及其内部 amis 子节点。

2. Store 与注册

底层使用 NeoRegister 注册的 EntityList，且 storeType 为 EntityListStore；由 amis / Neo 运行时按规则创建与注入，无需在业务侧手动 EntityListStore.create。

3. skipExt 与 Nex

NeoEntityList 生成的 Schema 含 skipExt: true：实体类 HOC 在 skipExt 为真时 不再合并 页面级 Nex 扩展配置，直接渲染组件（见 neo-ui-common 中 EntityHoc 的 render 分支）。本文档 不包含 Nex 扩展点与脚本侧 API 说明。

4. 高度与滚动（autoHeight）

• autoHeight={false}（默认）：列表区域在组件内部滚动（具体以 EntityList 布局为准）。
• autoHeight={true}：外层高度随内容变化，列表使用 body 滚动，适用于嵌入长页面等场景。

5. 需要完整 EntityList 能力时

若需使用 requestParams、referConditions、ListItemSchema、expandSchemas 等 未在 NeoEntityList 中透传 的属性，请优先在页面 Schema 中配置完整 EntityList，或扩展封装组件。

七、常见问题

Q1: 点击列表项如何阻止默认打开详情？

A：在 onItemClickIntercept 中返回 真值（例如 true）。返回假值或不返回时，仍会走默认 NeoNavigator.openEntityDetail。

Q2: 如何监听每次列表数据加载完成？

A：使用 onSearchDataComplete，其会随 Store 的数据请求流程被调用（与《详细分析文档》中 Store 行为一致）。若需更细粒度事件，需在页面侧使用完整 EntityList 或扩展封装。

Q3: 为什么传入的部分 props 未生效？

A：当前 NeoEntityList 只对 《三、组件属性说明》表格中的属性 与 onItemClickIntercept / onSearchDataComplete / style 进行合并，其余属性会被忽略。

Q4: 与直接使用 type: 'EntityList' 的 Schema 有何区别？

A：NeoEntityList 适合 代码 import、固定 大列表 且希望 跳过 Nex 合并、且只需要 少量开关与回调 的场景；完整 Schema 方式可配置 全部 EntityList 属性与事件。