Ancestry 项目技术文档

1. 安装指南

1.1 添加 Gem 到 Gemfile

首先，在项目的 Gemfile 中添加 ancestry gem：

# Gemfile
gem 'ancestry'

然后运行以下命令安装 gem：

$ bundle install

1.2 添加 ancestry 列到数据库表

生成并运行迁移文件，将 ancestry 列添加到目标表中：

$ rails g migration add_ancestry_to_table ancestry:string:index

编辑生成的迁移文件，确保 ancestry 列的配置正确：

class AddAncestryToTable < ActiveRecord::Migration[6.1]
  def change
    change_table(:table) do |t|
      # PostgreSQL
      t.string "ancestry", collation: 'C', null: false
      t.index "ancestry"
      # MySQL
      t.string "ancestry", collation: 'utf8mb4_bin', null: false
      t.index "ancestry"
    end
  end
end

运行迁移：

$ rake db:migrate

1.3 配置 ancestry 默认值

在 config/initializers/ancestry.rb 中配置默认的 ancestry 格式：

# config/initializers/ancestry.rb
Ancestry.default_ancestry_format = :materialized_path2
# Ancestry.default_update_strategy = :sql

1.4 在模型中添加 ancestry

在目标模型中添加 has_ancestry 方法：

# app/models/model.rb
class Model < ActiveRecord::Base
  has_ancestry
end

至此，模型已经具备了树形结构的功能。

2. 项目使用说明

2.1 组织记录为树形结构

可以通过 parent_id 或 parent 属性将记录组织成树形结构。这些属性可以作为参数传递给 new、create 和 update 方法：

TreeNode.create! :name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky')

也可以通过 children 关系创建子节点：

node.children.create :name => 'Stinky'

2.2 树形导航

Ancestry 提供了多种导航方法，用于在树形结构中查找节点：

• parent: 获取当前节点的父节点。
• root: 获取当前节点的根节点。
• ancestors: 获取当前节点的所有祖先节点。
• children: 获取当前节点的所有子节点。
• descendants: 获取当前节点的所有后代节点。
• siblings: 获取当前节点的所有兄弟节点。
• subtree: 获取当前节点及其所有后代节点。
• path: 获取从根节点到当前节点的路径。

3. 项目 API 使用文档

3.1 导航方法

• parent: 返回当前节点的父节点。
• root: 返回当前节点的根节点。
• ancestors: 返回当前节点的所有祖先节点。
• children: 返回当前节点的所有子节点。
• descendants: 返回当前节点的所有后代节点。
• siblings: 返回当前节点的所有兄弟节点。
• subtree: 返回当前节点及其所有后代节点。
• path: 返回从根节点到当前节点的路径。

3.2 类级别命名范围

• roots: 返回所有根节点。
• ancestors_of(node): 返回指定节点的所有祖先节点。
• children_of(node): 返回指定节点的所有子节点。
• descendants_of(node): 返回指定节点的所有后代节点。
• indirects_of(node): 返回指定节点的所有间接子节点。
• subtree_of(node): 返回指定节点及其所有后代节点。

4. 项目安装方式

项目的安装方式已经在“安装指南”部分详细说明。总结如下：

1. 在 Gemfile 中添加 ancestry gem 并运行 bundle install。
2. 生成并运行迁移文件，将 ancestry 列添加到目标表中。
3. 在 config/initializers/ancestry.rb 中配置默认的 ancestry 格式。
4. 在目标模型中添加 has_ancestry 方法。

通过以上步骤，您可以成功安装并使用 Ancestry gem 来组织 ActiveRecord 模型为树形结构。