教程：使用 FTXUI 的 Atlas Device Sync for C++

向模型添加属性

既然您已确认一切都按预期进行，您可以添加更改了。在本教程中，您将向每个Item添加一个priority属性，以便可以按其优先级筛选项目。

在生产应用程序中，您可以添加 PriorityLevel 枚举来限制可能的值。在本教程中，我们将使用数字属性来简化 UI 框架的使用。

为此，请按照以下步骤操作：

1. 在首选 IDE 中打开客户端代码。

2. 在 state/ 目录中，ppen item.hpp 文件。

3. 将以下属性添加到 Item 结构体：

   int64_t priority;

4. 将新的 priority 属性添加到 REALM_SCHEMA() 中：

   REALM_SCHEMA(Item, _id, isComplete, summary, owner_id, priority)

   Item 模型现在应类似于：

   namespace realm {
   struct Item {
     realm::primary_key<realm::object_id> _id{realm::object_id::generate()};
     bool isComplete;
     std::string summary;
     std::string owner_id;
     int64_t priority;
   };
   REALM_SCHEMA(Item, _id, isComplete, summary, owner_id, priority)
   }  // namespace realm

在用户界面中添加元素以设置优先级

1. 在 state 目录中，转到 home_controller_state.hpp。在现有的 newTaskIsComplete 属性下添加新的 int 属性。然后，添加 static const int 来存储该属性的默认 int 值。

   HomeControllerState 结构现在可能类似于：

   struct HomeControllerState {
     static const int DEFAULT_TASK_PRIORITY = 3;
     // Used for creating a new task.
     std::string newTaskSummary;
     bool newTaskIsComplete{false};
     int newTaskPriority{DEFAULT_TASK_PRIORITY};
     ...more code here...
   };

2. 在 controllers 目录中，转到 home_controller.hpp。此控制器呈现应用的主视图。

   导入 string 和向量库：

   #include <string>
   #include <vector>

   为新的优先级 UI 元素创建字符串标签数组：

   std::vector<std::string> priorityLevelLabels = {
     "Severe", "High", "Medium", "Low"
   };

3. 仍在 controllers 目录中，转到 home_controller.cpp。我们在此处添加 UI 元素，以便用户设置列项的优先级。FTXUI 提供了两个 UI 元素，适用于此功能：Radiobox 或 Dropdown。在本教程中，我们将使用 Dropdown，但如果您不喜欢 UI 在重排时以下拉列表的形式呈现，则可能更喜欢使用 Radiobox。

   在 auto newTaskCompletionStatus 行之后添加这个新的用户界面元素输入：

   auto newTaskPriorityDropdown = ftxui::Dropdown(
     &priorityLevelLabels,
     &_homeControllerState.newTaskPriority
   );

   在 auto saveButton 函数闭包中，将任务优先级选择传递给 _dbManager.addNew() 函数调用：

   _dbManager.addNew(
     _homeControllerState.newTaskIsComplete,
     _homeControllerState.newTaskSummary,
     _homeControllerState.newTaskPriority);

   然后添加一行，将优先级选择重置为默认值：

   _homeControllerState.newTaskPriority = HomeControllerState::DEFAULT_TASK_PRIORITY;

   将下拉选择器添加到为项目行容器中的交互式元素设置布局的 auto newTaskLayout：

   auto newTaskLayout = ftxui::Container::Horizontal(
     {inputNewTaskSummary, newTaskCompletionStatus, newTaskPriorityDropdown, saveButton});

   这部分代码现在应类似于：

   auto newTaskCompletionStatus = ftxui::Checkbox("Complete", &_homeControllerState.newTaskIsComplete);
   auto newTaskPriorityDropdown = ftxui::Dropdown(
     &priorityLevelLabels,
     &_homeControllerState.newTaskPriority);
   auto saveButton = ftxui::Button("Save", [this] {
     _dbManager.addNew(
       _homeControllerState.newTaskIsComplete,
       _homeControllerState.newTaskSummary,
       _homeControllerState.newTaskPriority);
     _homeControllerState.newTaskSummary = "";
     _homeControllerState.newTaskIsComplete = false;
     _homeControllerState.newTaskPriority = HomeControllerState::DEFAULT_TASK_PRIORITY;
   });
   auto newTaskLayout = ftxui::Container::Horizontal(
     {inputNewTaskSummary, newTaskCompletionStatus, newTaskPriorityDropdown, saveButton});

4. 最后，在 home_controller.cpp 文件下文中，将新用户界面元素添加到 auto itemListRenderer：

   inputNewTaskSummary->Render() | ftxui::flex,
   newTaskCompletionStatus->Render() | ftxui::center,
   newTaskPriorityDropdown->Render(),
   saveButton->Render(),

   这会在用户界面中的“保存”按钮之前显示新元素。

将新属性保存到数据库

1. 在 managers 目录中，转到 database_manager.hpp。更新 addNew() 函数签名，使其包含我们从 home_controller.cpp 传入的 int newItemPriority：

   void addNew(
     bool newItemIsComplete,
     std::string newItemSummary,
     int newItemPriority);

2. 现在转到 database_manager.cpp，更新 addNew() 实现。在函数参数中添加 int newItemProperty：

   void DatabaseManager::addNew(
     bool newItemIsComplete,
     std::string newItemSummary,
     int newItemPriority) {
     ...implementation...
     }

   在函数中添加一个新行，以便在将 Item 保存到数据库时设置 priority 属性的值：

   .priority = newItemPriority

   您的 addNew() 实现现在应该类似于：

   void DatabaseManager::addNew(bool newItemIsComplete, std::string newItemSummary, int newItemPriority) {
     auto item = realm::Item {
       .isComplete = newItemIsComplete,
       .summary = std::move(newItemSummary),
       .owner_id = _userId,
       .priority = newItemPriority
     };
     _database->write([&]{
       _database->add(std::move(item));
     });
   }

运行和测试

此时，再次构建并运行应用程序。在构建目录中，根据所作更改重建可执行文件：

cmake --build .

并运行应用程序：

./sync_todo /path-to-file/atlasConfig.json

使用本教程前面创建的帐户登录。您将看到先前创建的一个列项。添加新列项，您将看到现在可以设置优先级。为优先级选择 High 并保存条目。

现在切换回浏览器中的 Atlas 数据页面，并刷新 Item 集合。您现在应该会看到添加了 priority 字段并将其设置为1 的新项目。现有项目没有 priority 字段。

点击放大

更新订阅

要更改订阅，请前往 managers 目录并打开 database_manager.cpp 文件。更新查询语句以包含优先级等于或小于 1 的文档。这应当仅包括“严重”（0）或“高”（1）优先级的项目。

if (!subs.find(_myItemSubscriptionName)) {
  subs.add<realm::Item>(
    _myItemSubscriptionName,
    [&](auto &item){
      return item.owner_id == _userId && item.priority <= 1;
    }
  );
}

运行和测试

再次运行应用程序。使用本教程前面创建的账号登录。在 Subscription 框中，按 Switch to Mine 按钮。在 SDK 最初重新同步文档集合后，您将只能看到创建的新的高优先级项目。您可能需要移动鼠标或使用箭头键使用户界面重新呈现已在后台同步的新项目。

您最初创建的事项文档未显示在设备上，因为它没有 priority 字段。如果希望此事项同步到设备，您可以在 Atlas 用户界面中编辑文档并为 priority 字段添加值。

如果要进一步测试此功能，您可以创建各种优先级的事项。您将看到一个优先级较低的新事项短暂出现在事项清单中，继而又消失。同步错误处理程序提供了一条说明此行为的消息，十分有帮助：

A sync error occurred. Message:
"Client attempted a write that is not allowed; it has been reverted"

在这种情况下，SDK 会在本地创建该事项并将其与后端进行同步，然后撤销写入操作，因为它不符合订阅规则。