搜尋套件、儲存庫與 APP 分類

套件詳情v1.5.0

floor

適用於您 Flutter 應用程式的類型安全、反應式且輕量級的 SQLite 抽象。此庫是執行時依賴項。

近 30 天下載
3.2萬
喜歡數
1000
Pub 分數
110

安裝套件

flutter pub add floor

套件介紹

根據套件公開資料產生的選型評估,僅供參考。

Floor 是一個類型安全、反應式且輕量級的 SQLite 抽象層,專為 Flutter 應用程式設計。它透過使用註解和程式碼產生,提供一種清晰且編譯時期安全的方式來操作 SQLite 資料庫。Floor 透過易於使用的 DAO(資料存取物件)簡化資料庫操作,並透過串流支援反應式查詢。該庫注重效能與開發者體驗,可無縫整合至 Flutter 專案中,無需手動撰寫 SQL。透過在編譯時期驗證資料庫模式,該庫確保類型安全並減少執行時錯誤。

適用情境

  • 移動應用中的離線數據存儲
  • 與本機資料庫的即時資料同步
  • 管理使用者設定或設定等結構化應用資料
  • 建構離線優先的應用程式
  • 儲存快取的API回應
  • 追蹤使用者活動記錄

主要特色

  • 類型安全的資料庫模式定義
  • 透過串流實現的反應式查詢
  • DAO 的程式碼產生
  • 資料庫結構的編譯時驗證
  • 輕量且快速的性能
  • 與Flutter狀態管理的輕鬆整合

適合對象

  • 開發離線功能的 Flutter 應用程式開發者
  • 重視類型安全性與可維護性的團隊
  • 需要高效本地資料持久化的專案
  • 需要從本地數據獲取即時更新的應用程式
  • 尋求最小樣板程式碼的 Flutter 開發者

使用建議

  • 需要代碼生成設定
  • 僅限 SQLite 為底層資料庫
  • 不支援複雜的連接或原始 SQL
  • 遷移處理需要仔細規劃
  • 不適合大規模伺服器端資料庫

原始 README

以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。

Floor

See the project's website for the full documentation.

Floor provides a neat SQLite abstraction for your Flutter applications inspired by the Room persistence library. It comes with automatic mapping between in-memory objects and database rows while still offering full control of the database with the use of SQL. As a consequence, it's necessary to have an understanding of SQL and SQLite in order to harvest Floor's full potential.

  • null-safe
  • typesafe
  • reactive
  • lightweight
  • SQL centric
  • no hidden magic
  • no hidden costs
  • iOS, Android, Linux, macOS, Windows

⚠️ The library is open to contributions! Refer to GitHub Discussions for questions, ideas, and discussions.

pub package build status codecov

Getting Started

1. Setup Dependencies

Add the runtime dependency floor as well as the generator floor_generator to your pubspec.yaml. The third dependency is build_runner which has to be included as a dev dependency just like the generator.

  • floor holds all the code you are going to use in your application.
  • floor_generator includes the code for generating the database classes.
  • build_runner enables a concrete way of generating source code files.
dependencies:
  flutter:
    sdk: flutter
  floor: ^1.4.2

dev_dependencies:
  floor_generator: ^1.4.2
  build_runner: ^2.1.2
2. Create an Entity

It will represent a database table as well as the scaffold of your business object. @entity marks the class as a persistent class. It's required to add a primary key to your table. You can do so by adding the @primaryKey annotation to an int property. There is no restriction on where you put the file containing the entity.

// entity/person.dart

import 'package:floor/floor.dart';

@entity
class Person {
  @primaryKey
  final int id;

  final String name;

  Person(this.id, this.name);
}
3. Create a DAO (Data Access Object)

This component is responsible for managing access to the underlying SQLite database. The abstract class contains the method signatures for querying the database which have to return a Future or Stream.

  • You can define queries by adding the @Query annotation to a method. The SQL statement has to get added in parenthesis. The method must return a Future or Stream of the Entity you're querying for.
  • @insert marks a method as an insertion method.
// dao/person_dao.dart

import 'package:floor/floor.dart';

@dao
abstract class PersonDao {
  @Query('SELECT * FROM Person')
  Future<List<Person>> findAllPeople();

  @Query('SELECT name FROM Person')
  Stream<List<String>> findAllPeopleName();

  @Query('SELECT * FROM Person WHERE id = :id')
  Stream<Person?> findPersonById(int id);

  @insert
  Future<void> insertPerson(Person person);
}
4. Create the Database

It has to be an abstract class which extends FloorDatabase. Furthermore, it's required to add @Database() to the signature of the class. Make sure to add the created entity to the entities attribute of the @Database annotation. In order to make the generated code work, it's required to also add the listed imports.

Make sure to add part 'database.g.dart'; beneath the imports of this file. It's important to note that 'database' has to get exchanged with the filename of the database definition. In this case, the file is named database.dart.

// database.dart

// required package imports
import 'dart:async';
import 'package:floor/floor.dart';
import 'package:sqflite/sqflite.dart' as sqflite;

import 'dao/person_dao.dart';
import 'entity/person.dart';

part 'database.g.dart'; // the generated code will be there

@Database(version: 1, entities: [Person])
abstract class AppDatabase extends FloorDatabase {
  PersonDao get personDao;
}
5. Run the Code Generator

Run the generator with flutter packages pub run build_runner build. To automatically run it, whenever a file changes, use flutter packages pub run build_runner watch.

6. Use the Generated Code

For obtaining an instance of the database, use the generated $FloorAppDatabase class, which allows access to a database builder. The name is being composed by $Floor and the database class name. The string passed to databaseBuilder() will be the database file name. For initializing the database, call build() and make sure to await the result.

In order to retrieve the PersonDao instance, invoking the persoDao getter on the database instance is enough. Its functions can be used as shown in the following snippet.

final database = await $FloorAppDatabase.databaseBuilder('app_database.db').build();

final personDao = database.personDao;
final person = Person(1, 'Frank');

await personDao.insertPerson(person);
final result = await personDao.findPersonById(1);

For further examples take a look at the example and test directories.

Naming

The library's name derives from the following. Floor as the bottom layer of a Room which points to the analogy of the database layer being the bottom and foundation layer of most applications. Where fl also gives a pointer that the library is used in the Flutter context.

Bugs, Ideas, and Feedback

For bugs please use GitHub Issues. For questions, ideas, and discussions use GitHub Discussions.

License

Copyright 2023 The Floor Project Authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

所屬分類

依賴

依賴清單 9 項

原始碼儲存庫

使用此套件的專案