@@ -361,6 +361,95 @@ const register = {
361361}
362362```
363363
364+ #### 3.3 仅支持在第一层声明（子层声明不会生效）
365+
366+ 自 v2.7 起，我们只读取注册表对象的“第一层”。只有第一层的键会被注册进 ` metaHashMap ` 。
367+
368+ 也就是说：把插件/配置项写在子层（无论是把唯一 ID 放到某个插件的子属性里，还是通过 ` metas ` 往里塞）都不会被注册，` getMergeMeta ` /` getMergeMetaByType ` /` getAllMergeMeta ` 也就找不到它们。
369+
370+ 简而言之：请把所有需要生效的插件/配置项，都放到注册表的第一层来声明。
371+
372+ 错误示例（不会生效）：
373+ ``` javascript
374+ import { META_APP } from ' @opentiny/tiny-engine'
375+ import testMeta from ' ./testMeta'
376+
377+ export default {
378+ // 1) 在子层直接再次声明插件/配置项（无效，不会注册到 metaHashMap）
379+ [META_APP .Materials ]: {
380+ ' engine.plugins.test' : testMeta
381+ },
382+
383+ // 2) 通过 metas 在子层注入（无效，不会注册到 metaHashMap）
384+ [META_APP .Materials ]: {
385+ options: {
386+ displayComponentIds: [' engine.plugins.test'
387+ metas: [testMeta]
388+ }
389+ }
390+ }
391+ ```
392+
393+ 正确示例（第一层声明 + 通过 ID 引用）：
394+ ``` javascript
395+ import { META_APP } from ' @opentiny/tiny-engine'
396+ import testMeta from ' ./testMeta' // testMeta.id = 'engine.plugins.test'
397+
398+ export default {
399+ // 作为第一层键单独注册
400+ [testMeta .id ]: testMeta,
401+
402+ // 在需要的插件或布局中通过 ID 引用
403+ [META_APP .Materials ]: {
404+ options: {
405+ displayComponentIds: [' engine.plugins.test'
406+ }
407+ }
408+ }
409+ ```
410+
411+ 适用范围：所有插件与配置项都遵循该规则。用户注册表只支持：
412+ - 把已有的插件/配置项设为 ` false ` （删除默认）；
413+ - 在第一层新增插件/配置项；
414+ - 在第一层用相同 ID 覆盖默认配置。
415+
416+ ##### 物料插件（Materials 插件）迁移建议
417+
418+ 如果你旧版本是在 ` Materials ` 插件内部（例如 ` Materials.metas ` 或把自定义 ID 放到 ` Materials ` 的子属性里）扩展物料插件，请按下面方式迁移：
419+
420+ 错误示例（不会生效）：
421+ ``` javascript
422+ import { META_APP } from ' @opentiny/tiny-engine'
423+ import MyMaterial from ' ./MyMaterial' // MyMaterial.id = 'engine.plugins.myMaterial'
424+
425+ export default {
426+ [META_APP .Materials ]: {
427+ // 通过 metas 向物料插件塞入物料项（无效）
428+ options: {
429+ metas: [MyMaterial]
430+ }
431+ }
432+ }
433+ ```
434+
435+ 正确示例（第一层声明 + 在物料插件中引用）：
436+ ``` javascript
437+ import { META_APP } from ' @opentiny/tiny-engine'
438+ import MyMaterial from ' ./MyMaterial' // MyMaterial.id = 'engine.plugins.myMaterial'
439+
440+ export default {
441+ // 1) 物料项作为第一层键单独注册
442+ [MyMaterial .id ]: MyMaterial,
443+
444+ // 2) 在 Materials 插件中通过 ID Tab 组件显示
445+ [META_APP .Materials ]: {
446+ options: {
447+ displayComponentIds: [' engine.plugins.myMaterial'
448+ }
449+ }
450+ }
451+ ```
452+
364453### 4. 注册表热修复功能
365454
366455v2.7 版本新增了注册表热修复（hotfix）功能，可以通过覆盖官方插件的特定函数或模板，实现紧急 bug 修复，而不需要等待官方版本发布。
0 commit comments