Flutter Dartdoc使用问题:如何为StatefulWidget的State对象生成文档?
Dartdoc State类不生成文档问题解答
1. State类未生成文档的原因
这是Dartdoc的默认行为,不是操作错误:
- 常规开发中StatefulWidget对应的State子类都会定义为以下划线开头的私有类型(如
_MyWidgetState) - Dartdoc默认仅为公开类型/成员生成文档,默认排除所有私有内容
2. 为State类生成文档的正确方案
有两种可行方案,按需选择:
- 方案1:运行Dartdoc时添加
--include-private参数,命令示例:dart doc --include-private
该参数会强制Dartdoc生成所有私有类型、私有方法/变量的文档,如果你需要排除部分私有内容,给对应内容加@nodoc注解即可 - 方案2:将State子类改为公开类型(去掉类名前的下划线),该方案不推荐,因为State本身是Widget的内部实现,不应该对外暴露,不符合Flutter设计规范
3. 迁移成员到Widget本体的方案合理性判断
该临时方案不合理,不建议长期使用:
- Flutter中Widget是不可变类,所有成员都应该声明为final,可变状态必须放在State类中管理
- 若强行把可变变量放到Widget类中,会导致状态无法在组件刷新时正确持久化,出现不可预期的运行异常
内容的提问来源于stack exchange,提问作者Zaka
相关产品推荐
相关产品推荐

