TolyUI 案例风格规范

一、案例组织原则

1.1 渐进式展示

案例按照从简单到复杂的顺序组织，让开发者能够循序渐进地理解组件功能。案例数量根据组件复杂度灵活调整，通常包含 3-7 个案例。

典型的案例组织方式：

第一个案例通常展示基础用法，介绍组件的核心功能和基本配置。这是开发者接触组件的第一步，应该简单直接，让人一眼就能理解组件的作用。

后续案例逐步引入进阶功能，如状态管理、用户交互、动态数据处理等。每个案例都应该在前一个案例的基础上有所延伸，但又保持独立性，可以单独理解和使用。

最后的案例可以展示组件的高级应用或特殊场景，帮助开发者理解组件的完整能力边界。这些案例往往结合了多个特性，展示了组件在实际项目中的应用方式。

1.2 功能聚焦

每个案例专注于展示一个核心功能点，避免在单个案例中混杂过多特性。通过多个独立案例的组合，完整呈现组件的能力边界。

1.3 实用导向

案例设计基于真实应用场景，而非纯粹的技术演示。每个案例都应该能够直接应用到实际项目中，或者稍作调整即可使用。

二、DisplayNode 规范

2.1 标题命名

标题应简洁明确，直接点明案例的核心功能。

推荐模式：

• 基础标签
• 可关闭标签
• 动态添加标签
• 可选择标签
• 状态标签

避免模式：

• 标签的基本使用方法
• 如何实现可关闭的标签
• 标签组件高级功能演示

2.2 描述规范

描述应包含以下要素：

功能说明: 清晰描述案例展示的核心功能
交互细节: 说明用户可以进行的操作和预期效果
技术特点: 突出实现方式的特色（如数据驱动、状态管理等）
应用场景: 列举实际使用场景，帮助开发者理解使用时机

desc 要一行展示

示例：

@DisplayNode(
  title: '动态添加标签',
  desc: '展示标签的动态增删功能。用户可以通过关闭按钮删除已有标签，也可以点击虚线边框的添加按钮创建新标签。点击添加后会出现输入框，'
)

2.3 语言风格

• 使用白话文描述，避免过于技术化的表达
• 语言优雅简练，每句话都有明确的信息量
• 禁止使用 emoji 表情符号
• 少使用列表式的 AI 风格表达

三、代码组织规范

3.1 数据驱动模式

对于涉及状态管理的案例，优先采用数据驱动的方式。

推荐模式：

class _TagDemoState extends State<TagDemo> {
  final List<TagData> _initialTags = [
    TagData(label: '编程技术', variant: TagVariant.outlined),
    TagData(label: '拍摄影像', icon: Icons.camera, color: Colors.green),
  ];

  late List<TagData> tags;

  @override
  void initState() {
    super.initState();
    tags = List.from(_initialTags);
  }

  @override
  Widget build(BuildContext context) {
    return Wrap(
      children: tags.map((tag) => Tag(
        closable: true,
        onClose: () => setState(() => tags.remove(tag)),
        child: Text(tag.label),
      )).toList(),
    );
  }
}

避免模式：

// 硬编码的组件列表
Widget build(BuildContext context) {
  return Wrap(
    children: [
      Tag(closable: true, child: Text('标签1')),
      Tag(closable: true, child: Text('标签2')),
      Tag(closable: true, child: Text('标签3')),
    ],
  );
}

3.2 状态管理

• 简单案例使用 StatelessWidget
• 涉及交互的案例使用 StatefulWidget
• 状态变量命名清晰，避免使用 _data、_list 等模糊名称
• 合理使用 late 和 final 修饰符

3.3 代码简洁性

• 避免过度封装，保持案例代码的可读性
• 提取重复逻辑到独立方法，但不要过度抽象
• 使用有意义的变量名和方法名
• 适当添加注释说明关键逻辑

四、交互反馈规范

4.1 消息提示

使用 TolyUI 的 Message 组件提供统一的交互反馈。

onClose: () {
  setState(() => tags.remove(tag));
  $message.success(message: '已删除: ${tag.label}');
}

4.2 视觉反馈

• 操作前后应有明显的视觉变化
• 使用合适的过渡动画（由组件内部处理）
• 禁用状态应有明确的视觉区分

4.3 错误处理

• 对用户输入进行必要的验证
• 提供清晰的错误提示
• 避免应用崩溃，优雅降级

五、样式规范

5.1 颜色使用

• 优先使用 Material Design 标准颜色
• 状态相关的颜色应符合用户认知（成功-绿色、错误-红色、警告-橙色等）
• 避免使用过于鲜艳或刺眼的颜色

5.2 尺寸规范

• 图标尺寸通常为 12-16px
• 间距使用 4 的倍数（4、8、12、16、20、24）
• 保持组件之间的视觉平衡

5.3 字体规范

• 标题使用 14-16px，加粗
• 正文使用 12-14px，常规
• 辅助信息使用 12px，灰色

六、文档规范

6.1 文章结构

每篇组件文章应包含以下部分：

1. 系列前言: 统一的 TolyUI 介绍
2. 设计动机: 说明组件的设计背景和解决的问题
3. 独立模块: 介绍组件所属的模块和引入方式
4. 功能演示: 按照 Demo 顺序逐一介绍，案例数量根据组件复杂度灵活调整
5. 小结: 总结组件的设计原则和应用价值
6. 尾声: 统一的结束语和链接

功能演示部分是文章的核心，每个案例都应该有独立的章节。章节标题直接使用案例的核心功能作为标题，如“基础标签展示”、“可关闭标签”等。每个章节包含功能说明、代码示例和应用场景说明。

6.2 代码示例

• 代码应完整可运行，或明确标注省略部分
• 关键代码突出显示，非关键代码可以简化
• 代码后应有文字说明，解释实现思路和注意事项

6.3 图片使用

• 每个功能演示配图展示效果
• 静态展示使用截图，动态交互使用 GIF
• 图片清晰，尺寸适中，不影响阅读体验

七、命名规范

7.1 文件命名

• Demo 文件：{component}_demo{number}.dart
• 文章文件：Flutter TolyUI 框架#{number}@{module} {title}.md

7.2 类命名

• Demo 类：{Component}Demo{Number}
• State 类：_{Component}Demo{Number}State
• 数据类：{Component}Data 或 {Feature}Data

7.3 变量命名

• 初始数据：_initial{Name}s
• 当前数据：{name}s
• 控制器：_{name}Controller
• 焦点节点：_{name}FocusNode
• 状态标志：_is{Action}ing

八、最佳实践

8.1 案例设计

• 从用户视角出发，而非技术视角
• 每个案例都应该"有用"，而不仅仅是"能用"
• 考虑边界情况，展示组件的健壮性
• 提供完整的交互闭环，不留半成品

8.2 代码质量

• 遵循 Dart 语言规范和 Flutter 最佳实践
• 使用 const 构造函数优化性能
• 合理使用 Key 管理组件状态
• 及时释放资源（Controller、FocusNode 等）

8.3 用户体验

• 操作应该符合直觉，不需要额外说明
• 提供即时反馈，让用户知道操作结果
• 考虑无障碍访问，支持键盘导航和屏幕阅读器
• 响应式设计，适配不同屏幕尺寸

九、检查清单

在提交案例前，请确认以下事项：

功能完整性

• [ ] 案例能够独立运行
• [ ] 核心功能正常工作
• [ ] 边界情况处理得当
• [ ] 没有明显的 bug

代码质量

• [ ] 代码风格统一
• [ ] 命名清晰易懂
• [ ] 没有冗余代码
• [ ] 资源正确释放

文档完善

• [ ] DisplayNode 描述准确
• [ ] 代码有必要的注释
• [ ] 应用场景说明清楚
• [ ] 文章结构完整

用户体验

• [ ] 交互流畅自然
• [ ] 视觉效果美观
• [ ] 反馈及时明确
• [ ] 符合用户预期

十、总结

TolyUI 的案例设计遵循"简洁、实用、优雅"的原则。每个案例都应该是一个完整的故事，从问题出发，通过代码展示解决方案，最后说明应用场景。好的案例不仅能够帮助开发者快速上手，更能够启发他们思考如何在自己的项目中应用这些组件。

通过统一的规范和持续的优化，TolyUI 的案例库将成为 Flutter 开发者的重要参考资源，推动整个生态的发展和进步。