onChange这类函数型Props如何在组件库中演示？react-bluekit事件触发器设计全解

onChange这类函数型Props如何在组件库中演示？react-bluekit事件触发器设计全解

【免费下载链接】react-bluekitAutomatically generating a component library from your React components (ES5, ES6, Typescript)项目地址: https://gitcode.com/gh_mirrors/re/react-bluekit

react-bluekit 是一个自动从 React 组件生成组件库的开源工具：把它指向你的组件目录，它就会索引所有组件，生成可浏览的组件库，让你实时修改 Props 并查看预览效果。但这里藏着一个棘手的问题：onChange这类函数型 Props 该如何演示？本文带你拆解 react-bluekit 事件触发器的完整设计——从静态分析、事件桥梁到视觉反馈，一步步讲清楚这个"无法输入"的函数是如何被"点亮"的 👇

一、组件库里函数型 Props 的两难

先想清楚问题所在。在大多数组件库 playground 中，Props 编辑像一张表单：

• string/number→ 输入框填值
• bool→ 开关切换
• func→没有东西可填💡

onChange、onClick是回调函数，用户没法在表单里"输入"一个回调。react-bluekit 的思路是以退为进：给函数型 Props 生成一个"触发器函数"，当组件真的调用它时，发送一个全局事件；组件库监听事件后，把对应的 Props 行高亮出来。用户不需要关心实现，只看到"我点了组件，onChange那一行亮了"，就明白这个回调被触发了。

整个设计由三部分构成，各对应一个核心文件：

阶段	做什么	核心文件
构建时	为函数型 Props 生成"触发器函数"	src/libraries/buildProps.js
运行时	发送全局事件functionTriggered	src/libraries/BluekitEvent.js
UI 层	监听事件并高亮 Props 行	src/app/StateProvider.react.js

二、构建时：自动为函数型 Props 生成"触发器函数"

react-bluekit 通过静态分析（react-docgen）为每个组件生成 propsDefinition（Props 类型定义）。src/libraries/buildProps.js在生成默认值时，对func类型（以及箭头函数签名）的 Props 有一个关键分支：不塞undefined，而是生成一个被调用时会上报"我是谁"的函数——内部执行dispatchEvent({detail: {prop: "onChange"}})。

也就是说，每个函数型 Props 的默认值都不是"空"，而是一枚会喊话的哨兵。

还有两个文件负责"展示"层面的细节：

• src/libraries/filterFunctionProps.js：在"简单 Props"模式下把函数型 Props 直接过滤掉（反正无法编辑），只保留可交互的 Props；
• src/libraries/renderProp.js：在源码视图中，把函数型 Props 渲染成onChange={() => alert('INSERT YOUR onChange function')}的占位写法，提示开发者替换为真实逻辑。

三、运行时：BluekitEvent 事件桥梁

构建期生成的触发函数有一个先天难题：静态生成的代码无法引用 react-bluekit 的实例。那它怎么通知组件库？

react-bluekit 的答案是"无状态、全局化"——用 DOM 的 CustomEvent 当桥梁 🌉：

1. 模板nunjucks/componentsIndex.nunjucks生成的componentsIndex模块里带有一个全局dispatchEvent辅助函数：收到上报后，构造一个名为functionTriggered的 CustomEvent，派发到document上，负载只有{prop: 属性名}；
2. src/libraries/BluekitEvent.js是 CustomEvent 的轻量封装，在浏览器环境把自身原型挂到window.Event.prototype上，让事件表现与原生事件完全一致。

为什么用事件而不是回调注册或全局单例？因为静态代码和库实例分属两个"世界"，事件是它们之间零耦合的通道；事件名固定为functionTriggered，负载极简，好维护、好测试。

四、UI 反馈：监听事件，高亮 1 秒

事件的另一端是src/app/StateProvider.react.js，逻辑非常克制：

• componentDidMount时注册document.addEventListener('functionTriggered', ...)；
• 收到事件后，把属性名推进 state 里的triggeredProps列表；
• 再用setTimeout在1000ms 后清理，高亮一闪即过，不会常驻。

最终的渲染在src/app/component/PropsTable.react.js：每一行判断triggeredProps是否包含自己，命中就套上高亮背景色；同时函数型 Props 的值列统一显示func()。

用户体验因此变得非常直观：点击预览组件 →onChange那一行瞬间亮起 → 确认回调被触发 ✅

五、进阶：onChange 如何真正驱动组件状态？

还有一类函数型 Props 值得单独讲：onChange+value这种受控组合。它们不只是"回调通知"，用户需要真的通过输入框改变组件状态，看到 live 刷新。

src/libraries/extendProps.js专门处理这种情况：当组件同时定义了onChange和value时，自动把onChange替换为库内部的状态 setter（createSetAtomProp('value', 类型)）。这个 setter 定义在src/app/StateProvider.react.js中，能兼容各种事件形态：

• 标准 input 事件 → 取event.target.value
• 自定义事件结构 → 取event.value
• bool类型 → 自动从event.target.checked修正为布尔值

于是你在库的输入框里打字，组件的value会真实更新并重新渲染——受控组件行为在组件库里被完整保留。

一句话总结 react-bluekit 对函数型 Props 的分流策略：

类别	示例	策略
纯回调	onClick	生成触发器函数，被调用时发事件、高亮对应行
受控绑定	onChange+value	回调替换为库内 setter，真实改变状态并 live 刷新

六、小结：一个值得借鉴的最小闭环

react-bluekit 的事件触发器设计，可以浓缩成四步闭环：

1. 静态分析识别函数型 Props（src/libraries/buildProps.js）
2. 生成桩函数，唯一职责是发送全局事件（nunjucks/componentsIndex.nunjucks+src/libraries/BluekitEvent.js）
3. 库监听事件，把被触发的属性名记入 state（src/app/StateProvider.react.js）
4. UI 高亮对应行，1 秒后自动恢复（src/app/component/PropsTable.react.js）

如果你在为自己的 React 组件库搭建 playground，这套"静态桩函数 + 全局事件 + 状态高亮"的组合拳是低成本且可直接借鉴的方案：无需注入真实回调，只要让"谁被触发了"这一条信息流起来即可 🚀

【免费下载链接】react-bluekitAutomatically generating a component library from your React components (ES5, ES6, Typescript)项目地址: https://gitcode.com/gh_mirrors/re/react-bluekit