best-lowcode-runtime

BEST 的 React 低代码运行时统一入口，包含 Schema 驱动的 CRUD 页面、运行时 Registry 与基础 UI 组件。

安装

npm install best-lowcode-runtime

本包将 React、React DOM、Ant Design、Ant Design Pro Components 和 Day.js 声明为 peer dependencies；应用应使用与项目兼容的版本安装它们。

快速开始

import 'best-lowcode-runtime/style.css'
import {
  BestPage,
  CRUD_SCHEMA_ID,
  CRUD_SCHEMA_VERSION,
  type CrudPageSchema
} from 'best-lowcode-runtime'

const schema = {
  $schema: CRUD_SCHEMA_ID,
  version: CRUD_SCHEMA_VERSION,
  id: 'customer-list',
  kind: 'crud',
  title: '客户列表',
  dataSource: { list: 'customer.list' },
  table: {
    rowKey: 'id',
    columns: [{ field: 'name', title: '名称' }]
  }
} satisfies CrudPageSchema

export function CustomerPage() {
  const tableHeight = 480 // 固定表体高度；也可传 auto 或 natural
  return <BestPage tableHeight={tableHeight} registry={{ services: { 'customer.list': async () => ({ list: [], total: 0 }) } }} schema={schema} />
}

组合列

表格列可以通过 composite 在 JSON Schema 中组合多个记录字段，无需编写 Slot：

table: {
  rowKey: 'id',
  columns: [{
    title: '客户信息',
    width: 220,
    composite: {
      layout: 'vertical',
      items: [
        { label: '客户ID', field: 'customerId' },
        { label: '姓名', field: 'customerName', emptyText: '--' },
        { label: '邮箱', field: 'customerEmail' }
      ]
    }
  }]
}

composite.items 支持 label、dict、format 和 emptyText；组合列也可以继续使用普通列的 width 和 fixed 配置。

异步字典更新

字典可以在页面初始化后通过 useBestDictionaryActions 局部更新，不需要替换完整 Registry：

import { useEffect } from 'react'
import { useBestDictionaryActions } from 'best-lowcode-runtime'

function LoadDictionaries() {
  const { setDictionary } = useBestDictionaryActions()

  useEffect(() => {
    void fetch('/api/status-options')
      .then((response) => response.json())
      .then((items) => setDictionary('customer.status', items))
  }, [setDictionary])

  return null
}

setDictionary 只更新指定字典，并触发使用该字典的字段、表格和详情重新渲染。

开发期校验入口

通用表单和数据能力

Schema 支持 remoteSelect，通过 Registry Service 提供防抖搜索数据。select 和 remoteSelect 字段可设置 multiple: true 启用多选。搜索字段也可设置 component: 'slot' 并注册 slot key，让自定义控件保持在 Runtime 搜索表单中。Slot 接收 field、value、values、 mode: 'search' 和 setValue，字段值仍由 Runtime 表单管理：

{
  field: 'owner',
  label: '负责人',
  component: 'remoteSelect',
  multiple: true,
  remoteService: 'user.search',
  searchField: 'keyword',
  labelField: 'name',
  valueField: 'id'
}

{
  field: 'status',
  label: '状态',
  component: 'slot',
  slot: 'statusFilter'
}

字段可声明 required、type、min、max、minLength、maxLength、pattern 等通用规则。 createBestCrudAdapter 和 normalizeBestValues 可用于统一清理空字符串、转换创建/更新 payload，提交期间 Runtime 会自动显示 loading 并防止重复提交。

CLI 或工具链可从 best-lowcode-runtime/dev 导入不依赖页面渲染的能力：

import { getBuiltinCapabilities, validateUnknownCrudPageSchema } from 'best-lowcode-runtime/dev'

发布内容

发布包只包含编译后的 dist 与本 README。npm pack --dry-run 可用于在不发布的情况下检查最终包内容。

本包当前标记为 UNLICENSED；在对外公开前，应由代码所有方确定正式许可证。

tableHeight 默认为 "auto"：在宿主提供明确高度的容器内自动使用剩余空间。正数表示表体最大高度；"natural" 让表格随内容自然撑开。自动模式按实际渲染的搜索区、工具栏、表头和分页测量；宿主负责提供确定的容器高度。

auto 的宿主布局约定

auto 不读取浏览器窗口高度，也不查找宿主 DOM。项目公共布局负责提供受约束的可用空间，Runtime 负责在其中安排搜索区、Tabs、工具栏、表体和分页。普通页面可以省略 tableHeight，无需计算表体高度。

例如在项目公共布局中统一设置（类名由项目自行定义）：

.app-shell {
  height: 100dvh;
  display: flex;
  flex-direction: column;
  min-width: 0;
}
.app-header { flex: none; }
.page-viewport {
  display: flex;
  flex-direction: column;
  flex: 1 1 0%;
  min-width: 0;
  min-height: 0;
  overflow: hidden;
}

<div className="app-shell">
  <header className="app-header">项目导航</header>
  <main className="page-viewport">
    <BestPage schema={schema} registry={registry} />
  </main>
</div>

已有微前端壳或弹窗应沿用其分配的空间，不要再嵌套一个 100dvh。路由、KeepAlive、项目自定义 Tabs 等中间容器也需传递剩余空间（通常使用上述 page-viewport 规则）；仅设置 height: 100% 而父级没有确定高度是不够的。Runtime 内置 Tabs 已处理高度传递，项目自定义布局由项目适配。

宽表在表格内部横向滚动，不反向撑宽宿主。搜索折叠、容器缩放和缓存页重新显示会重新测量；隐藏页不写入零尺寸。空间过小时保留至少 80px 的表体滚动区域，让页面整体滚动，保证分页和搜索可达。短数据和空表不会为了填满空间拉高数据行。

自定义 Slot 中的组件仍需自行约束宽高和滚动。内容自然撑开的长页面应显式使用 natural；需要精确控制表体最大高度时仍可传正数。已有显式数字 tableHeight 的调用继续使用该固定高度，省略属性的页面会使用 auto。

浏览器布局回归

在仓库根目录复用或启动 Vite 服务后执行 pnpm test:layout。默认测试地址为 http://127.0.0.1:6789，可通过 LAYOUT_TEST_URL 覆盖。测试使用系统 Chrome，验证的是构建后的 Runtime JS 和 CSS。