插槽标签系统
📋 更新历史
| 日期 | 版本 | 更新内容 |
|---|---|---|
| 2025-12 | v1.2.0 | 全新插槽标签系统（SlotConfigs） |
插槽标签系统（SlotConfigs）是 PSUIP 1.2.0 引入的重要特性，使用语义化的 XML 标签来定义组件内容，替代传统的 Markdown 映射方式。
什么是插槽标签系统
核心概念
插槽标签系统允许你使用明确的语义化标签来指定组件中每个内容插槽的用途，而不是依赖 Markdown 标题的层级顺序。
传统方式 vs 插槽标签
传统 Markdown 映射方式：
<productCard>
## 产品标题
### 产品描述
¥999.00
[购买链接](https://example.com)
</productCard>新的插槽标签方式：
<productCard>
<image src="https://example.com/image.jpg"></image>
<title>产品标题</title>
<description>产品描述</description>
<price>¥999.00</price>
<button href="https://example.com/buy">立即购买</button>
</productCard>插槽标签的优势
1. ✅ 明确的语义
每个标签清晰表示其用途（title、description、price 等），一目了然。
<productCard>
<title>经典设计手表</title>
<description>精致工艺，优雅外观</description>
<price>¥999.00</price>
</productCard>2. ✅ 灵活的顺序
不再依赖 Markdown 标题层级顺序，可以自由调整内容顺序。
<!-- 价格在前也没问题 -->
<productCard>
<price>¥999.00</price>
<title>经典设计手表</title>
<description>精致工艺，优雅外观</description>
</productCard>3. ✅ 属性传递
可以通过属性传递额外配置（如 src、href、key 等）。
<productCard>
<image src="https://example.com/image.jpg"></image>
<button href="https://example.com/buy">立即购买</button>
</productCard>4. ✅ 嵌套支持
支持在插槽中嵌套 layout 标签，创建复杂布局。
<simpleCard>
<layout:row-center>
<itemTitle>安全加密</itemTitle>
<itemDescription>企业级数据保护</itemDescription>
</layout:row-center>
</simpleCard>5. ✅ 数据绑定
支持通过 key 属性进行数据绑定（用于 loop 循环）。
<loop data="products">
<itemContent>
<title key="productName"></title>
<price key="productPrice"></price>
</itemContent>
</loop>组件特定插槽
不同组件可能定义了自己特定的插槽标签，例如：
<simpleCard>
<itemTitle>标题</itemTitle>
<itemDescription>描述</itemDescription>
</simpleCard>
<commentStyleListCard>
<itemContent>
<avatar src="url" key="avatarUrl"></avatar>
<name key="userName"></name>
</itemContent>
</commentStyleListCard>使用示例
简单卡片
<simpleCard>
<itemTitle>云存储</itemTitle>
<itemDescription>1TB免费空间</itemDescription>
</simpleCard>产品卡片
<productCard>
<image src="https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=600&h=400"></image>
<title>经典设计手表</title>
<description>精致工艺，优雅外观，适合各种场合佩戴的经典款式。采用瑞士机芯，316L不锈钢表壳。</description>
<price>¥999.00</price>
<button href="https://example.com/buy">立即购买</button>
</productCard>招聘卡片
<hiringNewTitleCard>
<title>人才筛选详情</title>
<desc>负责核心算法模型的设计、优化与落地</desc>
<badge>算法工程师</badge>
</hiringNewTitleCard>带头像的招聘卡片
<hiringNewAvatarCard>
<title>算法策略</title>
<name>张逸杰</name>
<badge>推荐原因</badge>
<desc>他在算法优化与模型调参方面有出色表现，多次在业务指标上实现显著提升...</desc>
<avatar src="https://images.unsplash.com/photo-1544723795-3fb6469f5b39?w=200&h=200"></avatar>
</hiringNewAvatarCard>插槽与 Layout 结合
插槽标签内部可以使用 layout 标签进行布局：
<simpleCard>
<layout:row-center>
<itemTitle>安全加密</itemTitle>
<itemDescription>企业级数据保护</itemDescription>
</layout:row-center>
</simpleCard><simpleCard>
<layout:column-center-center>
<itemTitle>智能识别</itemTitle>
<itemDescription>AI 驱动的图像识别</itemDescription>
</layout:column-center-center>
</simpleCard>插槽与数据绑定
插槽标签支持 key 属性进行数据绑定，配合 loop 循环使用：
<commentStyleListCard>
<title>项目动态</title>
<subtitle>最新 3 条更新</subtitle>
<loop data="comments" nativeEvent="click">
<itemContent>
<avatar src="avatarUrl" key="avatarUrl"></avatar>
<name key="approveAuditorName"></name>
<text key="applyDeptName"></text>
<desc key="orderSummary"></desc>
<timestamp key="beginTime"></timestamp>
</itemContent>
</loop>
</commentStyleListCard>说明：
key属性指定绑定的数据字段名- 循环会自动从数据数组中提取对应字段的值
- 支持嵌套对象的字段访问
向后兼容性
插槽标签系统与传统的 markdownMapping 方式完全兼容：
混合使用
<card:elegantStandard>
## 传统 Markdown 标题
<description>但描述可以用插槽标签</description>
[按钮](https://example.com)
</card:elegantStandard>平滑迁移
现有使用 Markdown 映射的代码无需修改，可以逐步迁移到插槽标签：
阶段 1：全部使用 Markdown
<productCard>
## 产品标题
### 产品描述
¥999.00
</productCard>阶段 2：部分使用插槽标签
<productCard>
<title>产品标题</title>
### 产品描述
<price>¥999.00</price>
</productCard>阶段 3：全部使用插槽标签
<productCard>
<title>产品标题</title>
<description>产品描述</description>
<price>¥999.00</price>
</productCard>最佳实践
1. 优先使用插槽标签
对于新项目，优先使用插槽标签方式，获得更好的可读性和维护性。
<!-- 推荐 -->
<productCard>
<title>产品标题</title>
<description>产品描述</description>
</productCard>
<!-- 不推荐 -->
<productCard>
## 产品标题
### 产品描述
</productCard>2. 保持一致的风格
在同一个项目中，尽量保持一致的编写风格。
<!-- 好：统一使用插槽标签 -->
<simpleCard>
<itemTitle>标题1</itemTitle>
<itemDescription>描述1</itemDescription>
</simpleCard>
<simpleCard>
<itemTitle>标题2</itemTitle>
<itemDescription>描述2</itemDescription>
</simpleCard>3. 利用属性传递配置
充分利用属性来传递配置，避免硬编码。
<!-- 好：使用属性 -->
<image src="https://example.com/img.jpg"></image>
<button href="https://example.com/action">操作</button>
<!-- 不推荐：在内容中包含 URL -->
<button>https://example.com/action 操作</button>4. 嵌套使用时保持层次清晰
<simpleCard>
<layout:column-center>
<itemTitle>标题</itemTitle>
<layout:row-between>
<itemDescription>描述左</itemDescription>
<itemDescription>描述右</itemDescription>
</layout:row-between>
</layout:column-center>
</simpleCard>常见错误
1. 使用不支持的插槽标签
<!-- 错误：simpleCard 不支持 price 插槽 -->
<simpleCard>
<itemTitle>标题</itemTitle>
<price>¥99.00</price>
</simpleCard>
<!-- 正确：使用 productCard -->
<productCard>
<title>标题</title>
<price>¥99.00</price>
</productCard>2. 忘记闭合标签
<!-- 错误：未闭合 -->
<simpleCard>
<itemTitle>标题
<itemDescription>描述</itemDescription>
</simpleCard>
<!-- 正确 -->
<simpleCard>
<itemTitle>标题</itemTitle>
<itemDescription>描述</itemDescription>
</simpleCard>3. 属性拼写错误
<!-- 错误：应该是 src 而不是 source -->
<image source="url"></image>
<!-- 正确 -->
<image src="url"></image>扩展插槽定义
在组件配置中定义插槽
组件可以在 slotConfigs 中定义支持的插槽：
slotConfigs: {
title: {
slotPath: 'header.title',
supportedAttributes: ['key']
},
description: {
slotPath: 'content.description',
supportedAttributes: ['key']
},
image: {
slotPath: 'content.image',
supportedAttributes: ['src', 'key']
}
}说明：
slotPath：指定插槽在八要素结构中的路径supportedAttributes：指定插槽支持的属性列表
调试技巧
1. 检查插槽是否生效
查看渲染后的八要素结构，确认插槽内容是否正确映射。
2. 使用浏览器开发者工具
检查生成的 DOM 结构，查看插槽内容的实际渲染位置。
3. 查阅组件文档
不同组件支持不同的插槽，查阅具体组件的文档了解支持的插槽列表。
总结
插槽标签系统带来的优势：
| 特性 | 传统方式 | 插槽标签 |
|---|---|---|
| 语义明确 | ❌ 依赖标题层级 | ✅ 标签名称即语义 |
| 顺序灵活 | ❌ 固定顺序 | ✅ 任意顺序 |
| 属性支持 | ❌ 不支持 | ✅ 丰富的属性 |
| 数据绑定 | ❌ 不支持 | ✅ key 属性绑定 |
| 可读性 | ⚠️ 需要记忆映射规则 | ✅ 一目了然 |
| 维护性 | ⚠️ 修改困难 | ✅ 容易维护 |
推荐在新项目中使用插槽标签系统，享受更好的开发体验！
Last updated on