@snack-kit/core

@snack-kit/core

Snack 动态模块加载与渲染 SDK，基于 React + RequireJS 构建。支持从服务端加载 UMD 格式的 Snack 模块，并将设计器页面 JSON 配置渲染为 React 组件树，同时提供完整的表单数据管理、校验、国际化与事件系统。

安装

npm install @snack-kit/core

Peer Dependencies

npm install react react-dom @snack-kit/lib

快速开始

import React from 'react';
import ReactDOM from 'react-dom';
import { createRoot } from 'react-dom/client';
import { SnackSDK } from '@snack-kit/core';
import * as SnackKitLib from '@snack-kit/lib';

const sdk = new SnackSDK({
  service: 'https://your-snack-service.com',
  importMaps: {
    'react': React,
    'react-dom': ReactDOM,
    '@snack-kit/lib': SnackKitLib
  }
});

// 渲染设计器页面为 React 组件
const Page = await sdk.createPageComponent({ id: 'page-id', type: 'portal' });

createRoot(document.getElementById('app')!).render(<Page />);

SnackSDK 构造参数

参数	类型	说明
service	string	Snack 服务端地址
importMaps	object	模块依赖注入，key 为模块名，value 为模块对象
defaultFormAttr	SnackFormAttribute	表单组件 FormAttr 全局默认值
runtime	boolean	是否为运行时模式，默认 true；设计器模式设为 false
runtimeMapping	object	运行时模块名映射
modUrl	string	模块加载根路径，默认 service + modPath
modPath	string	模块请求路径，默认 /package
cdnUrl	string	CDN 根路径，默认 service + cdnPath
cdnPath	string	CDN 路径，默认 /lib
pageUrl	string	页面数据请求根路径
pagePath	string	页面请求路径，默认 /page
staticUrl	string	模块静态资源 CDN 路径
importModules	ImportModules	预置 Snack 模块 class，加载时优先从此查找
basicsType	string	基础模块分类名，默认 basics
i18n	I18nData	国际化数据复写
localeMapping	object	国际化语言映射关系，例如 { zh: 'zh_CN' }
localeDefault	string	默认国际化语言，默认 zh
message	object	消息提示对象，供 evalJS 脚本使用
argv	Record<string, ...>	全局环境变量，在表达式中通过 $.argv 访问

核心 API

页面渲染

sdk.createPageComponent(params, config?)

将设计器页面渲染为 React 函数组件。

const Page = await sdk.createPageComponent(
  { id: 'my-page', type: 'portal' },
  {
    data: { username: 'admin' },  // 表单回填数据
    onComplete: (event) => {
      console.log('渲染完成', event.fields);
    }
  }
);

<Page />

sdk.createPageForElement(el, params, config?)

将页面直接渲染到指定 DOM 元素。

await sdk.createPageForElement(document.getElementById('container')!, { id: 'my-page' });

sdk.renderPage(params, config?)

渲染页面并返回根容器 DropOjb 实例（低层 API）。支持传入数组一次渲染多个页面到同一表单容器。

表单操作

渲染完成后，onComplete 回调参数 event: SnackPageCompleteEvent 提供以下方法：

// 获取表单数据（全量）
const formData = event.getData();

// 获取单个字段值
const username = event.getData('username');

// 设置表单数据
event.setData('username', 'new-value');
event.setData({ username: 'a', password: 'b' });

// 表单校验（返回 Promise<boolean>）
const passed = await event.verify();
const fieldPassed = await event.verify('username');

// 清空表单
event.empty();

// 销毁页面（解绑事件、释放模块）
event.destroy();

模块渲染

sdk.createModuleComponent(args, data?)

加载并渲染单个 Snack 模块为 React 函数组件。

const Editor = await sdk.createModuleComponent(
  { name: 'codeeditor', type: 'code-editor' },
  { readOnly: false }
);

<Editor />

sdk.createClassModule(SnackClass, data?, main?)

通过 Snack Class 直接创建模块实例。

const mod = sdk.createClassModule(MySnackClass, { value: 'hello' });

sdk.createClassModuleComponent(SnackClass, data?, main?)

通过 Snack Class 创建模块并返回 React 函数组件。

模块加载

sdk.module(config)

按模块名称加载 UMD 模块，返回 Snack class 键值对。

const { mymodule } = await sdk.module({
  module: [{ name: 'mymodule', type: 'custom' }]
});

sdk.moduleURL(config)

按模块 URL 加载模块。

const mods = await sdk.moduleURL({
  urls: 'https://cdn.example.com/package/custom/mymodule/index.js',
  cdnUrl: 'https://cdn.example.com/lib'
});

事件系统

// 注册事件
sdk.addEvent('onComplete', (root, params) => {
  console.log('页面加载完成', root);
});

// 页面内组件事件（onChange、onBlur 等）由 SDK 自动分发
// 手动发送事件
sdk.sendEvent('custom-event', [arg1, arg2]);

// 卸载指定回调
sdk.removeEvent('onComplete', myCallback);

// 卸载所有同名事件
sdk.removeEvent('onComplete');

内置事件

事件名	触发时机
onComplete	整个页面加载渲染完成
onRemove	模块被移除
snack-event	组件内部事件（onChange、onBlur 等）分发

国际化

// SDK 级别
sdk.intl('required');               // 返回 string | ReactNode
sdk.setI18n({ zh: { required: '此字段必填' } });
sdk.language('en-US');              // 切换所有已加载模块的语言

// 模块内（Snack 基础类）
this.$intl({ id: 'required' });
this.$intl('required', { label: '用户名' });
this.$lang;                         // 获取当前语言
this.$lang = 'en-US';              // 设置语言

基础类

Snack<T>

所有 Snack 模块的基础类，继承此类实现自定义模块。

import { Snack, SnackData } from '@snack-kit/core';

interface MyData extends SnackData {
  value: string;
  label: { zh: string; en: string };
}

export class MyModule extends Snack<MyData> {
  public $component(data?: MyData) {
    return <div>{data?.value}</div>;
  }
}

常用属性与方法

成员	说明
data	模块数据对象
sdk	所属 SDK 实例
$id	模块唯一实例 ID
$name	模块名称
$parent	父级 Snack 实例（通常为 Drag 容器）
$page	所属页面事件对象
$forceUpdate(reload?)	强制重绘
$style(key?, value?)	读写样式并触发重绘
$display(visible)	显示 / 隐藏当前组件
$intl(ops, params?)	获取国际化文本
$language(lang)	切换语言
$destroy()	销毁模块，从 SDK moduleMaps 中移除
FC(data)	React 渲染入口，由 SDK 调用
$component(data?)	子类重写此方法实现 UI

SnackSetting

设置面板模块的基础类，通过 $setData 同步修改关联主模块（main）的数据。

import { SnackSetting } from '@snack-kit/core';

export class MyModuleSetting extends SnackSetting {
  public $component() {
    return (
      <input
        value={String(this.main.data?.value ?? '')}
        onChange={(e) => this.$setData('value', e.target.value)}
      />
    );
  }
}

表达式系统

页面 JSON 配置中支持 {{$.xxx}} 占位符，在运行时由 SDK 自动替换：

{
  "data": {
    "M": {
      "label": "{{$.argv.username}}"
    }
  }
}

可用变量

变量	说明
$.argv	SDK 构造时传入的 argv 全局变量
$.data	当前组件的 data 对象
$.sdk	SDK 实例

模块打包（UMD 格式）

Snack 模块需打包为 UMD 格式并通过 snackdefine 注册（由 scripts/config/webpack.snack.config.js 提供）：

// webpack.snack.config.js 关键配置
output: {
  filename: 'index.js',
  library: { type: 'umd' }
},
externals: {
  'react': 'react',
  '@snack-kit/lib': '@snack-kit/lib'
}

打包产物头部会自动注入：

if (typeof window !== 'undefined' && window.snackdefine) {
  var define = window.snackdefine;
}

开发

# 本地开发调试（webpack-dev-server）
npm run dev

# 构建库（ESM + CJS + Types）
npm run build

# 运行单元测试
npm test

# 类型检查
npm run lint

# 生成 API 文档
npm run docs

Changelog

0.4.0

Bug 修复

• 修复 tsup ESM 构建产物扩展名问题：新增 outExtension: () => ({ js: '.js' }) 配置，强制输出 dist/es/index.js，与 package.json 的 exports.import 路径一致，解决 Vite 等构建工具无法解析 @snack-kit/core 入口（"Failed to resolve entry"）的问题

0.2.0

新增

• 新增 src/utils/reactAdapter.ts：createReactRoot / SnackReactRoot 运行时兼容层，支持 React 17 / 18 / 19 三版本并存
  • React 18+：使用 createRoot（react-dom/client）
  • React 17：回退至旧版 ReactDOM.render / unmountComponentAtNode
  • 通过变量形式 require，绕过 webpack 静态分析，避免 React 17 宿主环境因 react-dom/client 不存在报 "Module not found"
• 导出 createReactRoot 与 SnackReactRoot 供外部使用

依赖调整

• react / react-dom 由 dependencies 移至 peerDependencies，支持版本范围 >=17.0.0，宿主项目可自行管理 React 版本

0.1.0

破坏性变更

• 移除 Vue 2.0 支持（删除 SnackVue、SnackVueSetting 及相关导出）
• 依赖由 @paraview/lib 迁移至 @snack-kit/lib（@paraview/lib 作为 importMaps 别名保持向后兼容）
• 构建工具由 webpack 迁移至 tsup，产物格式调整为 ESM + CJS + Types

安全修复

• 移除所有 new Function 动态字段访问，改用 safeGet / safeSet 路径工具（消除代码注入风险）
• window.define 全局污染修复：改用 window.snackdefine，不再覆盖标准 AMD define

Bug 修复

• 修复 $defaultDisplay(false) 逻辑反转问题，调用后组件现可正确隐藏
• 修复模块渲染失败时 childCount 未递减，导致 onComplete 永不触发的问题
• 修复渲染错误日志缺少模块 key 信息，现输出 key / field 辅助定位

新增

• 新增 src/utils/pathAccess.ts：safeGet / safeSet 支持 . 与 [] 混合路径语法
• 并发加载去重：同一 URL 的模块并发请求只发出一次网络请求
• destroy() 方法现会清理所有待处理的 verifyTimeout 防抖计时器，防止内存泄漏
• 新增 vitest 单元测试（tests/utils/pathAccess.test.ts）
• 新增 typedoc 支持，npm run docs 生成 API 文档

类型系统

• 全局类型安全审查，大幅减少 any 使用
• 新增导出类型：SnackRequireFunction、SnackDefineFunction、SnackSettingModelItem、ExprArgv
• 支持 React 19

License

ISC