本指南规定了在项目中添加具有“手工创建/编辑”与“自动排版”能力的动态数组组件的标准流程。以 metrics(信息矩阵)组件为例,这套流程确保了数据一致性、编辑器交互的一致性以及渲染器的自动布局能力。
- 数据解耦:所有动态项以数组形式存储在
PageData中。 - 手动录入:编辑器提供专用的列表编辑界面(Add/Delete/Edit)。
- 自动排版:渲染引擎通过
Repeater节点结合Grid/Flex/Modular布局,根据数组长度自动流转,无需手动指定每个项的坐标。
在 src/types.ts 中定义该组件的数据接口,并确保它包含在 PageData 的扩展类型中。
// 1. 定义单项数据结构
export interface MetricData {
id: string;
value: string;
label: string;
unit?: string;
}
// 2. 确保 PageData 具备承载该数组的能力(通常在 PageData 接口中作为可选属性)
export interface PageData {
// ...
metrics?: MetricData[];
// ...
}在 src/components/editor/fields/ 目录下创建对应的表单组件(如 MetricsField.tsx)。
- 必须使用
FieldWrapper:保持统一的标题和图标样式。 - 支持增删改:
addItem(): 向数组 push 一个初始对象。removeItem(index): 根据索引过滤数组。updateItem(index, updates): 局部更新数组中的某个对象。
- UI 规范:使用
src/components/ui/Base.tsx中的原子组件,确保符合工业精密感审美。
export const MetricsField: React.FC<FieldProps> = React.memo(({ page, onUpdate }) => {
const metrics = page.metrics || [];
// 实现 addItem, removeItem, updateItem 逻辑...
return (
<FieldWrapper page={page} onUpdate={onUpdate} fieldKey="metrics" label="Metrics Grid" icon={Activity}>
{metrics.map((m, idx) => (
<div className="group relative bg-slate-50 p-4 rounded-xl ...">
{/* 输入框绑定 */}
</div>
))}
<button onClick={addItem}>Add Item</button>
</FieldWrapper>
);
});- FieldType 注册:在
src/types.ts的FieldType联合类型中增加键名(如'metrics')。 - 组件映射:在
src/components/editor/FieldRenderer.tsx的componentMap中添加:const componentMap: Record<string, React.FC<any>> = { // ... metrics: MetricsField, };
- 模板声明:在
src/templates/registry.ts中,为需要支持该功能的模板添加字段配置:fields: withBaseFields([ { key: 'metrics', label: 'Data Points' }, ])
在模板的 root 结构中,使用 Repeater 节点绑定数据,并由外层 Container 控制其排版。
- 排版控制:通过
layout: 'grid'(固定列数) 或layout: 'modular'(24x24 模块化网格) 实现自动布局。 - 变量绑定:在
template节点中使用{item.xxx}语法访问数据项属性。
{
type: 'Container',
layout: 'modular',
layoutProps: { columns: 3, rows: 1 }, // 定义为 3 列的矩阵
children: [
{
type: 'Repeater',
bind: 'page.metrics',
itemVariable: 'item', // 默认为 item
template: {
type: 'Container',
layout: 'flex',
layoutProps: { direction: 'column' },
children: [
{
type: 'Component',
componentType: 'ZineCaption',
props: { text: '{item.label}' }
},
{
type: 'Component',
componentType: 'ZineCaption',
props: { text: '{item.value}', className: '!text-lg !font-bold' }
}
]
}
}
]
}- 默认值处理:在模板 Schema 的表达式中,建议使用
{page.metrics || []}或在组件层处理空数组,防止渲染崩溃。 - 样式黑名单:在
LayoutRenderer.tsx中,filterZineClassName会强制剔除shadow-*、blur-*、drop-shadow-*或animate-bounce/pulse/wiggle等不符合项目审美的 Tailwind 类名,即使在动态组件中也不应使用。 - ID 管理:虽然目前很多组件通过数组
index操作,但为了更好的 React 渲染性能,建议在addItem时使用crypto.randomUUID()生成唯一id。 - 模块化对齐:当使用
layout: 'modular'时,Repeater内部的template节点无需指定modular坐标,它们会自动按网格流式填充。
双语阅读套件(Bilingual Suite)是动态数组组件的最佳实践:
-
数据模型 (
src/types.ts):VocabItem包含id,word,phonetic,pos,meaning,example,exampleZH,挂载在PageData.vocabItems。 -
编辑器表单 (
src/components/editor/fields/VocabItemsField.tsx): 提供词汇列表的可视化抽屉编辑、音标快速输入与中英对照例句折叠卡片。 -
原子组件 (
src/components/ui/slide/atoms/ZineVocabList.tsx): 内置多列自适应排版、8px 基线字阶解析 (resolveModularFontSize),并硬编码了物理像素下限(词头$\ge 16\text{px}$ 、释义$\ge 14\text{px}$ 、音标$\ge 12\text{px}$ ),彻底防止在极端视口缩放时文字坍塌。