# `naisi_region_list`

获取指定类型有效地区；忽略已删除记录。
parent_code=null 返回元信息和全部 items；显式 0 返回根节点，其他父编码返回有效直属下级。
元信息为 region_type、version、source_version、updated_at、total_count、active_count、deleted_count、items。
updated_at 为 UTC Unix 秒；deleted_count 是数据包提供的版本删除统计。
元素公共字段为 region_code、parent_code、region_kind、level、name；国内另含 short_name，
国际另含 en_name、zh_name、numeric，籍贯另含 native_place_name。元素不附 parents 或 region_type。
籍贯 region_kind 按 area_code 关联国内表读取；native_place_name 空字符串原样返回。
成功读取的空数据集保留元信息；未授权或加载失败返回 []。

## 函数签名

```php
function naisi_region_list(int $region_type, ?int $parent_code = null): array
```

## 调用前提

应用入口先调用 [naisi_is_ext_license_valid](/web/developers/naisilib/naisi-is-ext-license-valid) 并确认返回 `true`。只验证同一请求内已有的有效 FULL/BASIC 证明；没有证明或证明失效时立即返回失败值，不现场补做完整校验。

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

## 参数

### `$region_type`

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

整数选择器：NAISI_REGION_TYPE_CHINA=1（国内行政区划）、NAISI_REGION_TYPE_GLOBAL=2（全球）、NAISI_REGION_TYPE_NATIVE_PLACE=3（籍贯）。其他整数为业务失败。

### `$parent_code`

- 类型：`?int`
- 必填：否
- 默认值：`null`
- 方向：输入参数。

直属父级编码；null 获取完整数据集，0 获取根节点。

## 返回值

成功时返回全量元信息或直属下级数组，结构见上方说明；未授权或加载失败返回 `[]`。

## 关联常量

- [`NAISI_REGION_TYPE_CHINA`](/web/developers/naisilib/const#naisi-region-type-china) = `1` — 国内行政区划。 选择地区列表、名称解析和搜索的数据集。
- [`NAISI_REGION_TYPE_GLOBAL`](/web/developers/naisilib/const#naisi-region-type-global) = `2` — 全球国家地区。 选择地区列表、名称解析和搜索的数据集。
- [`NAISI_REGION_TYPE_NATIVE_PLACE`](/web/developers/naisilib/const#naisi-region-type-native-place) = `3` — 国内籍贯，与行政区划共用编码。 选择地区列表、名称解析和搜索的数据集。

## 调用示例

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

```php
$region_type = 1;
$parent_code = 361100;

$result = naisi_region_list($region_type, $parent_code);
var_export($result);
```

## 编码与异常

籍贯与国内行政区划共用编码。get/code_to_name 不增加类型参数，国内编码使用行政区划名称和父链；列表、搜索、名称解析按传入类型选择数据。get/code_to_name 可读取库中仍保留的软删除记录，其余接口过滤软删除记录；物理删除的历史记录无法查询。

参数必须与签名声明的原始 PHP 类型一致，不做弱类型转换；类型不匹配返回 `[]`。参数数量错误仍遵循 PHP 标准异常规则。文本使用 UTF-8，地区文本及分隔符最多 4096 字节，不允许 NUL。没有引用输出参数。

## 版本信息

- 实现模块：`region`
- 授权类别：`LICENSE` / `PROOF`
- 失败回退：`[]`
- 文档同步：`2026-10-18`