开发指南

Admin SDK

管理端扩展页面是免编译 ESM：宿主经原生 import map 共享 React 单例，扩展页动态 import 即挂载。本章讲加载机制、routes.json 声明与 SDK 接口面。

免编译加载是怎么工作的

  1. 1宿主页面内联原生 import map，把 react、react/jsx-runtime、react-dom、react-router-dom、@tanstack/react-query、@tenraft/admin-sdk 等裸模块名映射到宿主导出的共享模块。
  2. 2宿主启动时把真实模块发布为全局单例——宿主与全部扩展共享同一份 React 实例（否则会出现 Invalid hook call 双 React 事故）。
  3. 3宿主拉取扩展清单（当前站点可见的应用与插件及其 routes.json），对每条路由做 SDK 版本与 React 大版本兼容检查后动态 import() 挂载。
  4. 4每个扩展路由包裹独立的 ErrorBoundary 与 Suspense：加载失败 / 版本不兼容 / 运行时崩溃分别降级为带重试的卡片，不影响宿主与其他扩展。

routes.json 声明

admin/routes.json

{

"minSdk": "1.0.0",

"reactVersion": "18",

"routes": [

{

"path": "app/shop/goods",

"componentUrl": "./goods.mjs",

"scope": "site",

"perm": "app.shop.goods.view",

"actions": [{ "perm": "app.shop.goods.manage", "name": "管理商品" }],

"menu": { "title": "商品管理", "icon": "package", "sort": 10 }

}

]

}

  • scope：site（站点后台，默认）或 platform（平台后台）。
  • perm 控制路由与菜单可见性；actions 把细粒度动作权限点登记进权限目录，供角色配置界面勾选。
  • 组件文件是手写或构建出的 ESM（.mjs），默认导出 React 组件，并导出 __react_version 供运行期断言。
  • componentUrl 相对于扩展资源根，宿主加载时自动带版本参数（cache-bust）。

SDK 接口面

扩展页面骨架（index.mjs）

import React from 'react';

import sdk, { http, useAuth, ProTable } from '@tenraft/admin-sdk';

export const __react_version = React.version;

export default function GoodsPage() {

const { hasPermission } = useAuth();

// http 自动携带 token 与 X-Site-Id，自动解包 {code,msg,data}

// code!==0 抛 SdkApiError；登录失效自动跳转

...

}

模块接口说明
httphttp.get(url, params) · http.post(url, body) · http.request(cfg)基址 /adminapi，自动鉴权头；code===0 时直接返回 data
权限useAuth() → { siteId, permissions, hasPermission }hasPermission 与服务端权限匹配规则完全镜像（manage 蕴含、view 地板、跨域不蕴含）
ProTablecolumns / dataSource / loading / pagination / toolbar标准列表页组件，列渲染函数可自定义
ProFormfields / initialValues / onSubmit字段类型 text / password / number / textarea，必填校验内置
DetailPagetitle / children详情页容器
Uploadvalue / onChange / type / accept对接素材库上传接口（image / video / audio / file）
RichTextvalue / onChange富文本编辑器，输出经服务端同款净化
其他menu.register · useBreadcrumb · ui.toast / confirm · message.* · useTheme菜单注册、面包屑、消息与确认框、主题 token 读取

主题 token

  • useTheme() 返回只读 token：主色、前景色、背景、边框、圆角、按钮风格。
  • 扩展页面样式使用宿主提供的品牌类（如 bg-brand / text-brand-foreground）——OEM 白标换色时扩展页自动跟随。
  • 不要硬编码颜色：这是扩展开发规范的硬性红线。

版本与兼容承诺

  • SDK 独立版本号；宿主主版本内不做破坏性变更，破坏性变更随框架大版本并提供迁移说明。
  • 扩展声明 minSdk 与 reactVersion，宿主加载前静态检查、加载后运行期断言，双保险防止版本漂移导致的隐性崩溃。
  • 共享模块清单是冻结的公共契约：新增共享模块属大版本变更。