FlutterUnit 数据表结构总览：widget 组件库的 SQLite 表设计与关系建模

FlutterUnit 数据表结构总览widget 组件库的 SQLite 表设计与关系建模【免费下载链接】FlutterUnitAll Platform Flutter Experience App项目地址: https://gitcode.com/GitHub_Trending/fl/FlutterUnitFlutterUnit 是一个覆盖 Android、iOS、Web、Windows、macOS、Linux 等全平台的 Flutter 体验应用其组件知识库需要同时支撑 Widget 检索、继承关系展示、字段属性说明、示例代码展示与分类收藏等功能。modules/widget_system/widget_repository模块负责组件数据的仓储层而 tables_overview.md 正是这一仓储层的数据基石——它以 8 张 SQLite 表完整刻画了组件知识库的数据模型。读完本文你将掌握每一张表的字段含义、表与表之间的关联关系以及这些表在 DAO、Repository 与展示模型中的实际落地方式为二次开发或理解 FlutterUnit 组件知识库的数据流打下基础。一、数据模型概览为什么需要 8 张表组件知识库的核心对象是 Flutter 的 Widget但 Widget 本身信息维度众多基本信息、继承链、构造字段属性、多语言描述、示例代码节点等。若全部塞进一张表会造成大量冗余与查询混乱。FlutterUnit 采用「主表 从表 关联表」的设计核心表6 张widget、widget_inheritance、widget_fields、widget_desc、node、node_desc负责 Widget 本体及其周边信息的存储扩展表2 张category、category_widget负责用户收藏分类与 Widget 的多对多关联。所有表统一使用id INTEGER PRIMARY KEY AUTOINCREMENT作为自增主键外键通过widget_id、node_id、categoryId等字段表达配合索引字段priority、field_order控制展示顺序。整套 DDL 定义集中在文档 tables_overview.md而与之对应的持久化对象PO位于 lib/src/database/po 目录。二、核心表详解6 张1. widget —— Widget 基本信息表CREATE TABLE widget( id INTEGER PRIMARY KEY AUTOINCREMENT, name VARCHAR(64) NOT NULL UNIQUE, path TEXT NOT NULL, is_abstract INTEGER NOT NULL DEFAULT 0, is_private INTEGER NOT NULL DEFAULT 0, deprecated INTEGER DEFAULT 0, family INTEGER NOT NULL, lever FLOAT(2) NOT NULL, linkWidget TEXT DEFAULT );字段类型说明idINTEGER自增主键Widget 唯一标识nameVARCHAR(64)Widget 类名如Container、ListView唯一约束pathTEXT该 Widget 对应的源码/文档路径is_abstractINTEGER是否抽象类默认 0is_privateINTEGER是否为私有组件默认 0deprecatedINTEGER废弃标记默认 01表示已废弃-1表示已死亡删除familyINTEGER组件族枚举值见下文leverFLOAT(2)重要度/星级浮点类型支持3.8、2.8这类小数linkWidgetTEXT关联组件 id 列表以英文逗号分隔如74,85,80,78,70,123源码印证family字段在展示层映射为WidgetFamily枚举见 widget_filter.dart0stateless、1stateful、2singleChildRender、3multiChildRender、4sliver、5proxy、6other。而 widget_model.dart 中的WidgetModel.toFamily(int id)完成了从整数到枚举的转换deprecated 1对应deprecated状态、deprecated -1对应death状态。linkWidget则由formatLinkTo()方法按逗号拆分为Listint用于详情页展示关联组件入口。lever字段的取值可以参考真实数据 widget.json例如Container与Text为 5 星Card为 3 星Icon为 2 星FlutterLogo为 1 星还有UserAccountsDrawerHeader的3.8、SizedOverflowBox的2.8等小数星值体现了星级可以细分的设计。2. widget_inheritance —— Widget 继承关系表CREATE TABLE widget_inheritance ( id INTEGER PRIMARY KEY AUTOINCREMENT, widget_id INTEGER NOT NULL, parent_name TEXT NOT NULL, inheritance_order INTEGER NOT NULL );字段类型说明idINTEGER自增主键widget_idINTEGER所属 Widget 的 idparent_nameTEXT父类名称存类名字符串而非外键 idinheritance_orderINTEGER继承链上的次序用于还原自底向上的继承层级这张表以widget_id一对多关联widget表一个 Widget 可有多个父级还原多级继承链parent_name直接保存父类名inheritance_order决定绘制继承树时的先后顺序。3. widget_fields —— Widget 字段属性信息表CREATE TABLE widget_fields ( id INTEGER PRIMARY KEY AUTOINCREMENT, widget_id INTEGER NOT NULL, field_name TEXT NOT NULL, field_type TEXT NOT NULL, field_desc TEXT, field_desc_zh TEXT, field_order INTEGER NOT NULL, is_required INTEGER NOT NULL DEFAULT 0 );字段类型说明idINTEGER自增主键widget_idINTEGER所属 Widget 的 idfield_nameTEXT构造参数名如radius、backgroundColorfield_typeTEXT参数类型如double、Color、ImageProviderfield_descTEXT参数英文描述field_desc_zhTEXT参数中文描述field_orderINTEGER字段展示次序is_requiredINTEGER是否必填参数默认 0源码印证查询该表的核心 SQL 位于 widget_dao.dart它按照is_required DESC, field_order ASC排序——必填字段永远排在前面其余按声明的field_order展示保证详情页属性列表的顺序稳定可读。字段的最终展示模型为WidgetFieldModel见 widget_field_model.dart通过WidgetRepository.loadWidgetFields(widgetId)见 widget_repository.dart对外提供。4. widget_desc —— Widget 描述信息表CREATE TABLE widget_desc( id INTEGER PRIMARY KEY AUTOINCREMENT, widget_id INTEGER NOT NULL, name VARCHAR(128) NOT NULL, info TEXT NOT NULL, locale VARCHAR(16) DEFAULT zh-cn );字段类型说明idINTEGER自增主键widget_idINTEGER所属 Widget 的 idnameVARCHAR(128)本地化名称如中文名容器组件infoTEXT本地化描述文本localeVARCHAR(16)语言区域默认zh-cn这是全库的多语言核心同一widget_id可对应多条locale不同的记录。真实数据中widget.json 的每条记录同时带有name英文类名与nameCN中文名展示层在查询时按locale过滤。例如 widget_dao.dart 的queryByIds使用INNER JOIN widget_desc ON widget.id widget_desc.widget_id并以widget_desc.locale ?限定语言WidgetPo.fromJson见 widget_po.dart中nameCN: map[nameCN] ?? map[localeName] ?? 的兜底逻辑也正是为了兼容不同数据源的字段命名。5. node —— 示例代码节点表CREATE TABLE node( id INTEGER PRIMARY KEY AUTOINCREMENT, widgetId INTEGER NOT NULL, priority INTEGER DEFAULT 0, code TEXT NOT NULL );字段类型说明idINTEGER自增主键widgetIdINTEGER所属 Widget 的 idpriorityINTEGER节点展示优先级默认 0codeTEXT示例代码正文含import与完整可运行类node存储可运行示例代码本体。真实数据 node.json 中每个节点都包含一段完整代码例如CircleAvatar节点的code是一个继承StatelessWidget的完整类实现priority控制其在详情页多个示例 Tab 中的排序。6. node_desc —— 节点描述信息表CREATE TABLE node_desc( id INTEGER PRIMARY KEY AUTOINCREMENT, node_id INTEGER NOT NULL, name VARCHAR(128) NOT NULL, subtitle TEXT NOT NULL, locale VARCHAR(16) DEFAULT zh-cn );字段类型说明idINTEGER自增主键node_idINTEGER所属 node 的 idnameVARCHAR(128)节点名称如CircleAvatar的表现subtitleTEXT节点副标题常为参数说明列表localeVARCHAR(16)语言区域默认zh-cnnode_desc与node构成一对多关系一个示例节点可有多语言描述。在 node.json 中可以看到subtitle的真实形态它是一段以换行拼接的参数清单如【radius】 : 半径 【double】即把该示例涉及的构造参数以结构化文本存于subtitle供详情页展示。源码印证NodeDao.queryById见 node_dao.dart通过INNER JOIN node_desc ON node.id node_desc.node_id按locale过滤后以ORDER BY priority排序一次性取出节点的priority、code、name、subtitle——这正是详情页示例代码区块的完整数据来源。三、扩展表详解2 张7. category —— Widget 分类表CREATE TABLE category( id INTEGER PRIMARY KEY AUTOINCREMENT, name VARCHAR(64) NOT NULL UNIQUE, type INTEGER DEFAULT 0, color VARCHAR(9) DEFAULT #FF2196F3, info VARCHAR(256) DEFAULT 这里什么都没有..., created DATETIME NOT NULL, updated DATETIME NOT NULL, priority INTEGER DEFAULT 0, image VARCHAR(128) DEFAULT );字段类型说明idINTEGER自增主键nameVARCHAR(64)分类名称唯一约束typeINTEGER分类类型默认 01表示系统收藏集默认收藏夹colorVARCHAR(9)分类主题色8 位 ARGB 十六进制字符串默认#FF2196F3infoVARCHAR(256)分类说明默认这里什么都没有...created/updatedDATETIME创建/更新时间priorityINTEGER分类排序值默认 0imageVARCHAR(128)分类图片地址默认空串源码印证CategoryPo见 category_po.dart对type的注释明确写着「1表示系统收藏集」其fromNetJson还提供了历史兼容逻辑_legacyCategoryType——当云端快照缺少type字段时通过id 1 || name 收藏集推断为系统收藏集说明表结构演化中对旧数据做了兼容处理。CategoryDao见 category_dao.dart提供了完整的 CRUD 与查询queryAll用LEFT JOIN category_widget配合COUNT(cw.categoryId)统计每个分类下的组件数并按priority DESC, created DESC排序existByName用于校验分类名唯一性clear会先清空category_widget再清空category保证删除顺序正确。8. category_widget —— 分类 Widget 关联表CREATE TABLE category_widget( id INTEGER PRIMARY KEY AUTOINCREMENT, categoryId INTEGER NOT NULL, widgetId INTEGER NOT NULL );字段类型说明idINTEGER自增主键categoryIdINTEGER分类 idwidgetIdINTEGERWidget id这张表是category与widget之间的多对多关联表一个分类可收藏多个 Widget一个 Widget 也可被多个分类收藏。其典型用法在 category_dao.dart 中addWidget/addWidgets向分类中添加一个/批量 WidgetremoveWidget/toggleCollect移除或切换收藏状态existWidgetInCollect判断某 Widget 是否已在分类中loadCollectWidgetsLEFT JOIN widget_desc按指定locale一次性取出分类下所有 Widget 的完整展示信息并按lever DESC排序。特别值得一提的是LikeDao见 like_dao.dart它并不新建喜欢表而是复用category_widgetcategory.type 1来表达收藏——like方法执行INSERT INTO category_widget (categoryId, widgetId) SELECT id, ? FROM category WHERE type 1unlike则反向删除isLiked用EXISTS子查询判断。这种默认收藏夹即系统分类的设计让收藏与分类共用同一套关联机制非常简洁。四、表关系图与 ER 语义文档 tables_overview.md 给出了完整的表关系widget (1) ←→ (N) widget_inheritance widget (1) ←→ (N) widget_fields widget (1) ←→ (N) widget_desc widget (1) ←→ (N) node node (1) ←→ (N) node_desc widget (N) ←→ (N) category [through category_widget]归纳为三类关系1:N 主从关系widget是绝对主表widget_inheritance、widget_fields、widget_desc、node都以widget_id为外键挂在其下node_desc又挂在node之下。查询时通常用INNER JOIN拼接见 widget_dao.dart、node_dao.dart。多语言扩展widget_desc与node_desc通过locale字段实现一主多从的多语言存储默认zh-cn。N:M 关联category与widget通过category_widget间接关联category.type 1的特殊分类承担默认收藏夹职责实现组件收藏功能。五、从表到模型的落地Repository 调用链理解表结构后再看仓储层的调用链会非常清晰。WidgetDbRepository见 widget_db_repository.dart实现了WidgetRepository接口见 widget_repository.dart典型流程为UI 层 → WidgetRepository 接口 → WidgetDbRepository 实现 → WidgetDao / LikeDaoSQL 查询 → WidgetPo数据库持久化对象 → WidgetModel展示模型含 family 枚举、links、lever 等派生字段其中searchWidgets对应 widget_dao.dart 的分页搜索 SQL——支持按名称/描述LIKE模糊匹配、按family精确过滤、按lever IN (?,?,?,?,?)星级过滤配合LIMIT ? OFFSET ?实现分页对应WidgetFilter见 widget_filter.dart中的page、pageSize、stars、family等筛选参数。此外WidgetStatisticsDao见 widget_statistics_dao.dart在widget、widget_fields之上提供了统计能力getFamilyCount按family分组统计组件数量、getLeverDistribution按lever取整统计星级分布、getAverageFields计算平均字段数用于首页/统计页的数据展示。需要注意的是该 DAO 的name为widget_statistics其统计均基于前述核心表实时聚合不额外建表。六、设计要点与二次开发提示主表尽量精简细节按需拆分widget表仅保留标识、枚举、星级与关联 id 字符串把多语言描述、字段明细、示例代码全部下沉到从表保证核心查询如分页搜索轻量高效。用priority/order系列字段控制顺序node.priority、field_order、category.priority在各类 SQL 的ORDER BY中反复出现新增内容时务必设置合理的排序值。linkWidget是短字符串外键它以逗号分隔的 id 列表表达组件间推荐关联由展示层formatLinkTo解析不属于强外键约束写入时需保证 id 有效。收藏与分类复用一张关联表通过category.type 1区分系统收藏集与用户自定义分类扩展新收藏语义时优先考虑复用category_widget而非新建表。多语言扩展遵循locale约定默认zh-cn新增语言只需插入同widget_id/node_id且locale不同的记录无需改动表结构。相关代码与数据文件索引表结构定义文档tables_overview.md持久化对象POwidget_po.dart、node_po.dart、category_po.dartDAO 层widget_dao.dart、node_dao.dart、category_dao.dart、like_dao.dart、widget_statistics_dao.dartRepository 层widget_repository.dart、widget_db_repository.dart展示模型与筛选widget_model.dart、widget_filter.dart真实数据示例widget.json、node.json【免费下载链接】FlutterUnitAll Platform Flutter Experience App项目地址: https://gitcode.com/GitHub_Trending/fl/FlutterUnit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考