naisi_tree_get_descendant_ids

按深度优先顺序返回平级节点列表中指定节点的全部后代 ID。

同级节点保持输入顺序。节点 ID 接受正整数或规范的非负十进制整数字符串，父节点 ID 还可为 0；输出统一为整数。目标不存在、字段缺失、ID 无效或重复、目标子树存在循环、 未授权或内部处理失败时返回 false。与目标无关的孤立节点不影响结果。

函数签名

function naisi_tree_get_descendant_ids(
    array $nodes,
    int $node_id,
    bool $include_self = false,
    string $id_key = 'id',
    string $parent_key = 'parent_id'
): array|false

调用前提

应用入口先调用 naisi_is_ext_license_valid 并确认返回 true。只验证同一请求内已有的有效 FULL/BASIC 证明；没有证明或证明失效时立即返回失败值，不现场补做完整校验。

授权类别：LICENSE；执行模式：PROOF。许可不代替登录、租户或权限上下文；身份与数据要求见本页参数及用途说明。

参数

$nodes

• 类型：array
• 必填：是
• 默认值：无
• 方向：输入参数。

平级节点列表。每个节点必须是数组，并至少包含由 $id_key 和 $parent_key 指定的两个字段；其他字段被忽略。

$node_id

• 类型：int
• 必填：是
• 默认值：无
• 方向：输入参数。

要查询的目标节点 ID，必须大于 0，并且必须出现在 $nodes 中。

$include_self

• 类型：bool
• 必填：否
• 默认值：false
• 方向：输入参数。

是否在结果首位包含目标节点自身，默认 false。

$id_key

• 类型：string
• 必填：否
• 默认值：'id'
• 方向：输入参数。

节点 ID 字段名，默认 "id"。

$parent_key

• 类型：string
• 必填：否
• 默认值：'parent_id'
• 方向：输入参数。

父节点 ID 字段名，默认 "parent_id"。

返回值

类型：array|false

成功时返回按先序深度优先排列的整数 ID 数组；叶子节点返回空数组，包含自身时返回仅含目标 ID 的数组；失败时返回 false。

调用示例

当前请求须满足上方调用前提；请检查实际返回值和引用输出，随机结果及数据包内容以运行环境为准。

$nodes = [
    [
        'id' => 1,
        'parent_id' => 0
    ],
    [
        'id' => 2,
        'parent_id' => 1
    ],
    [
        'id' => 3,
        'parent_id' => 2
    ]
];
$node_id = 1;
$include_self = false;
$id_key = 'id';
$parent_key = 'parent_id';

$result = naisi_tree_get_descendant_ids($nodes, $node_id, $include_self, $id_key, $parent_key);
var_export($result);

节点格式与失败规则

节点列表按输入顺序处理，同级顺序不变；输出为先序深度优先的整数 ID 数组。节点 ID 接受正整数或规范的非负十进制整数字符串，父 ID 还可为 0。目标不存在、必需字段缺失、ID 无效或重复、目标子树有循环时返回 false；与目标无关的孤立节点不影响结果。叶子节点成功时可返回空数组。

版本信息

• 自版本：1.0.6
• 实现模块：array
• 授权类别：LICENSE / PROOF
• 失败回退：false
• 文档同步：2026-10-18