本页面介绍数据交换的参数配置机制，这是进行数据导入导出操作前的关键步骤。通过正确配置数据交换参数，您可以精确控制数据转换的行为，包括格式映射、编码规则、坐标系统等关键属性。掌握参数配置是构建可靠数据交换流程的基础。

Sources: [PySSDataX.py](PySSDataX.py#L113-L173)

## 核心概念与架构

数据交换参数配置基于 **DataXScript** 类实现，该类采用经典的 **参数-执行模式** 设计。用户首先通过一系列参数设置方法配置数据转换的各项属性，然后调用执行方法触发实际的导入或导出操作。这种设计将配置逻辑与执行逻辑分离，提高了代码的可读性和可维护性。

```mermaid
graph LR
    A[创建 DataXScript 实例] --> B[配置交换参数<br/>setDataXParameter]
    B --> C[可选：读取参数<br/>getDataXParameter]
    C --> D{参数配置完成?}
    D -->|否| B
    D -->|是| E[选择操作类型]
    E -->|导入| F[调用 importData]
    E -->|导出| G[调用 exportData]
    F --> H[数据交换完成]
    G --> H
    H --> I[可选：清理参数<br/>clearDataXParameter]
```

DataXScript 类的实例不作为 sunvpy 的全局单例对象暴露，因此每次需要进行数据交换时都需要创建新的实例。这种设计确保了不同数据交换任务的参数不会相互干扰，提高了脚本的隔离性和安全性。

Sources: [PySSDataX.py](PySSDataX.py#L113-L173)

## 参数管理核心方法

DataXScript 类提供了三个核心方法用于参数的配置、读取和清理操作。这些方法是所有数据交换操作的基础，理解它们的用法是掌握数据交换功能的第一步。

| 方法名称 | 方法签名 | 功能描述 | 返回值 |
|---------|---------|---------|--------|
| `setDataXParameter` | `setDataXParameter(name, value)` | 设置单个数据转换参数 | 无 |
| `getDataXParameter` | `getDataXParameter(name)` | 获取指定参数的当前值 | 字符串形式的参数值 |
| `clearDataXParameter` | `clearDataXParameter()` | 清除所有已配置的参数 | 无 |

这些方法的设计遵循简单直观的原则，所有参数都以字符串形式传入和传出，底层会根据参数名称自动进行类型转换和验证。

Sources: [PySSDataX.py](PySSDataX.py#L120-L146)

### 设置数据交换参数

`setDataXParameter()` 方法是配置数据交换的主要方法，它接受两个参数：参数名称和参数值。参数名称是系统预定义的键，用于标识特定的配置项；参数值则是用户希望设置的值，可以是字符串、数字等各种类型，但都会以字符串形式传递。

```python
from sunvpy.PySSDataX import DataXScript

# 创建数据交换脚本实例
datax = DataXScript()

# 设置文件路径参数
datax.setDataXParameter("ImportPath", "D:\\data\\import\\roads.shp")
datax.setDataXParameter("ExportPath", "D:\\data\\export\\output.mdb")

# 设置编码参数
datax.setDataXParameter("SourceEncoding", "GBK")
datax.setDataXParameter("TargetEncoding", "UTF-8")

# 设置坐标系统参数
datax.setDataXParameter("CoordSystem", "EPSG:4326")
```

参数名称通常采用大驼峰命名法，如 `ImportPath`、`CoordSystem` 等。在实际使用中，应根据具体的导入导出格式选择合适的参数名称。错误的参数名称可能会被忽略或导致后续执行失败。

Sources: [PySSDataX.py](PySSDataX.py#L120-L128)

### 读取数据交换参数

`getDataXParameter()` 方法允许您获取当前已设置的参数值，这对于参数验证和调试非常有用。该方法接受一个参数名称，返回该参数的当前值。如果参数未被设置，可能返回空字符串或默认值。

```python
# 读取之前设置的参数
import_path = datax.getDataXParameter("ImportPath")
print(f"导入路径: {import_path}")

# 检查关键参数是否已设置
coord_system = datax.getDataXParameter("CoordSystem")
if not coord_system:
    print("警告：坐标系统未设置，将使用默认值")
else:
    print(f"坐标系统: {coord_system}")
```

使用 `getDataXParameter()` 可以在执行数据交换前验证参数配置的完整性，避免因缺少必要参数而导致的执行失败。

Sources: [PySSDataX.py](PySSDataX.py#L130-L140)

### 清除数据交换参数

`clearDataXParameter()` 方法会清除所有已设置的参数，将 DataXScript 实例恢复到初始状态。这个方法在需要复用同一个 DataXScript 实例执行多次不同的数据交换任务时特别有用。

```python
# 执行第一次数据导入
datax.setDataXParameter("ImportPath", "data1.shp")
datax.importData()

# 清除所有参数
datax.clearDataXParameter()

# 执行第二次数据导入（使用新参数）
datax.setDataXParameter("ImportPath", "data2.shp")
datax.importData()
```

需要注意的是，`clearDataXParameter()` 会清除所有参数，包括您可能希望保留的参数。如果只想修改部分参数，应该直接调用 `setDataXParameter()` 覆盖原有值，而不需要先清除。

Sources: [PySSDataX.py](PySSDataX.py#L117-L119)

## 数据交换工作流程

数据交换参数配置是数据导入导出流程中的关键环节。完整的导入和导出操作都遵循相同的参数配置模式，区别仅在于最终调用的执行方法不同。

### 数据导入流程

数据导入是指将外部文件或数据源中的数据加载到当前 SunvStation 工作空间中的过程。导入前必须正确配置源文件路径、编码方式等关键参数。

```mermaid
flowchart TD
    A[开始导入流程] --> B[创建 DataXScript 实例]
    B --> C[设置源文件路径<br/>ImportPath]
    C --> D[配置文件编码<br/>SourceEncoding]
    D --> E[设置坐标系统<br/>CoordSystem]
    E --> F[配置其他可选参数]
    F --> G[调用 importData 执行导入]
    G --> H{导入成功?}
    H -->|是| I[获取导入文件名<br/>getImportFileName]
    H -->|否| J[检查错误日志]
    I --> K[完成导入流程]
    J --> K
```

以下是数据导入的完整代码示例：

```python
from sunvpy.PySSDataX import DataXScript

# 创建数据交换脚本实例
datax = DataXScript()

# 配置导入参数
datax.setDataXParameter("ImportPath", "D:\\gis_data\\survey.shp")
datax.setDataXParameter("SourceEncoding", "GBK")
datax.setDataXParameter("CoordSystem", "EPSG:4326")
datax.setDataXParameter("LayerMapping", "道路")
datax.setDataXParameter("OverwriteExisting", "true")

# 执行数据导入
success = datax.importData()

if success:
    import_file = datax.getImportFileName()
    print(f"数据导入成功: {import_file}")
else:
    print("数据导入失败，请检查参数配置和文件格式")
```

`importData()` 方法会根据配置的参数执行实际的导入操作。导入成功后，可以调用 `getImportFileName()` 获取实际导入的文件名称，这个名称可能与原始文件名不同，因为系统可能会根据命名规则进行调整。

Sources: [PySSDataX.py](PySSDataX.py#L148-L152)

### 数据导出流程

数据导出是指将当前工作空间中的数据保存为外部文件的过程。导出前需要配置目标文件路径、导出格式、编码方式等参数。

```mermaid
flowchart TD
    A[开始导出流程] --> B[创建 DataXScript 实例]
    B --> C[设置目标文件路径<br/>ExportPath]
    C --> D[选择导出格式<br/>ExportFormat]
    D --> E[配置文件编码<br/>TargetEncoding]
    E --> F[设置坐标系统<br/>CoordSystem]
    F --> G[配置图层过滤<br/>LayerFilter]
    G --> H[调用 exportData 执行导出]
    H --> I{导出成功?}
    I -->|是| J[验证导出文件]
    I -->|否| K[检查错误日志]
    J --> L[完成导出流程]
    K --> L
```

以下是数据导出的完整代码示例：

```python
from sunvpy.PySSDataX import DataXScript

# 创建数据交换脚本实例
datax = DataXScript()

# 配置导出参数
datax.setDataXParameter("ExportPath", "D:\\export_data\\result.mdb")
datax.setDataXParameter("ExportFormat", "MDB")
datax.setDataXParameter("TargetEncoding", "UTF-8")
datax.setDataXParameter("CoordSystem", "EPSG:4326")
datax.setDataXParameter("LayerFilter", "道路,建筑,水系")
datax.setDataXParameter("IncludeAttributes", "true")
datax.setDataXParameter("CompressGeometry", "true")

# 执行数据导出
success = datax.exportData()

if success:
    print("数据导出成功")
else:
    print("数据导出失败，请检查参数配置和写入权限")
```

导出操作通常比导入操作涉及更多的参数配置，因为导出时需要指定目标格式、是否包含属性、是否压缩几何等信息。合理配置这些参数可以优化导出文件的性能和兼容性。

Sources: [PySSDataX.py](PySSDataX.py#L154-L157)

## 常见参数类型参考

虽然 DataXScript 类本身没有在 Python 层面硬编码参数名称列表，但基于常见的 GIS 数据交换场景，以下是一些常用的参数类型和说明。实际使用时应参考 SunvStation 的完整参数文档。

### 文件路径相关参数

| 参数名称 | 参数说明 | 示例值 | 适用场景 |
|---------|---------|--------|---------|
| `ImportPath` | 导入文件的完整路径 | `D:\data\input.shp` | 数据导入 |
| `ExportPath` | 导出文件的完整路径 | `D:\data\output.mdb` | 数据导出 |
| `WorkingDir` | 临时工作目录 | `D:\temp\workdir` | 导入导出 |

### 格式和编码相关参数

| 参数名称 | 参数说明 | 示例值 | 适用场景 |
|---------|---------|--------|---------|
| `ExportFormat` | 导出文件格式 | `SHP`, `MDB`, `GDB`, `DXF` | 数据导出 |
| `SourceEncoding` | 源文件字符编码 | `GBK`, `UTF-8`, `BIG5` | 数据导入 |
| `TargetEncoding` | 目标文件字符编码 | `UTF-8`, `GBK` | 数据导出 |

### 坐标系统和投影参数

| 参数名称 | 参数说明 | 示例值 | 适用场景 |
|---------|---------|--------|---------|
| `CoordSystem` | 坐标系统定义 | `EPSG:4326`, `EPSG:4490` | 导入导出 |
| `SourceCoordSystem` | 源数据坐标系统 | `EPSG:3857` | 数据导入 |
| `TargetCoordSystem` | 目标数据坐标系统 | `EPSG:4326` | 数据导出 |
| `TransformMode` | 坐标转换模式 | `AUTO`, `MANUAL` | 坐标转换 |

### 数据处理相关参数

| 参数名称 | 参数说明 | 示例值 | 适用场景 |
|---------|---------|--------|---------|
| `LayerMapping` | 图层映射规则 | `道路` | 导入导出 |
| `LayerFilter` | 图层过滤条件 | `道路,建筑,水系` | 数据导出 |
| `IncludeAttributes` | 是否包含属性数据 | `true`, `false` | 数据导出 |
| `OverwriteExisting` | 是否覆盖已有数据 | `true`, `false` | 数据导入 |
| `CompressGeometry` | 是否压缩几何数据 | `true`, `false` | 数据导出 |
| `Tolerance` | 几何容差值 | `0.001`, `0.01` | 导入导出 |

Sources: [PySSDataX.py](PySSDataX.py#L120-L152)

## 完整实践示例

以下是一个完整的数据交换参数配置和执行示例，展示了如何将一个 Shapefile 格式的道路数据导入到 SunvStation 工作空间中，然后再将处理后的数据导出为 MDB 格式。

```python
from sunvpy.PySSDataX import DataXScript

def import_and_export_data():
    """
    完整的数据导入导出流程示例
    """
    
    # ========== 第一阶段：数据导入 ==========
    print("开始数据导入流程...")
    
    # 创建导入专用的 DataXScript 实例
    import_datax = DataXScript()
    
    # 配置导入参数
    import_datax.setDataXParameter("ImportPath", "D:\\gis_projects\\source\\roads.shp")
    import_datax.setDataXParameter("SourceEncoding", "GBK")
    import_datax.setDataXParameter("CoordSystem", "EPSG:4326")
    import_datax.setDataXParameter("LayerMapping", "道路")
    import_datax.setDataXParameter("OverwriteExisting", "true")
    import_datax.setDataXParameter("Tolerance", "0.001")
    
    # 验证关键参数
    import_path = import_datax.getDataXParameter("ImportPath")
    print(f"导入文件路径: {import_path}")
    
    # 执行导入
    import_success = import_datax.importData()
    
    if not import_success:
        print("错误：数据导入失败")
        return False
    
    import_file = import_datax.getImportFileName()
    print(f"数据导入成功: {import_file}")
    
    # 清理导入参数（可选）
    import_datax.clearDataXParameter()
    
    # ========== 第二阶段：数据处理（示例）==========
    # 这里可以添加数据处理逻辑，如选择集操作、属性修改等
    print("数据处理中...")
    
    # ========== 第三阶段：数据导出 ==========
    print("开始数据导出流程...")
    
    # 创建导出专用的 DataXScript 实例
    export_datax = DataXScript()
    
    # 配置导出参数
    export_datax.setDataXParameter("ExportPath", "D:\\gis_projects\\output\\roads_processed.mdb")
    export_datax.setDataXParameter("ExportFormat", "MDB")
    export_datax.setDataXParameter("TargetEncoding", "UTF-8")
    export_datax.setDataXParameter("CoordSystem", "EPSG:4490")  # 转换为 CGCS2000
    export_datax.setDataXParameter("LayerFilter", "道路")
    export_datax.setDataXParameter("IncludeAttributes", "true")
    export_datax.setDataXParameter("CompressGeometry", "true")
    
    # 验证关键参数
    export_path = export_datax.getDataXParameter("ExportPath")
    export_format = export_datax.getDataXParameter("ExportFormat")
    print(f"导出路径: {export_path}")
    print(f"导出格式: {export_format}")
    
    # 执行导出
    export_success = export_datax.exportData()
    
    if not export_success:
        print("错误：数据导出失败")
        return False
    
    print("数据导出成功")
    
    # 清理导出参数
    export_datax.clearDataXParameter()
    
    print("数据交换流程完成")
    return True

# 执行完整流程
if __name__ == "__main__":
    import_and_export_data()
```

这个完整示例展示了数据交换的最佳实践：为导入和导出分别创建独立的 DataXScript 实例，在每个阶段完成后验证参数配置，并使用清晰的注释标记代码的不同阶段。

Sources: [PySSDataX.py](PySSDataX.py#L113-L173)

## 最佳实践与注意事项

在使用数据交换参数配置时，遵循以下最佳实践可以避免常见问题，提高脚本的可靠性和可维护性。

### 参数配置建议

| 实践建议 | 说明 | 示例 |
|---------|------|------|
| 使用绝对路径 | 避免相对路径导致的路径解析错误 | `D:\data\input.shp` |
| 验证参数值 | 在执行前检查关键参数是否正确设置 | `if not import_path: raise Error` |
| 使用独立实例 | 为每次数据交换创建新的实例，避免参数污染 | `import_datax = DataXScript()` |
| 添加错误处理 | 捕获执行失败的情况，提供有意义的错误信息 | `if not success: log_error()` |
| 记录参数配置 | 保存使用的参数配置，便于问题排查和复现 | `save_config(params)` |

### 常见问题排查

| 问题现象 | 可能原因 | 解决方法 |
|---------|---------|---------|
| 执行失败但无错误信息 | 参数名称拼写错误 | 检查参数名称是否正确 |
| 导入数据乱码 | 字符编码不匹配 | 设置正确的 `SourceEncoding` |
| 坐标位置偏移 | 坐标系统未设置或错误 | 配置正确的 `CoordSystem` |
| 导出文件过大 | 未启用几何压缩 | 设置 `CompressGeometry=true` |
| 部分图层未导出 | 图层过滤设置不当 | 检查 `LayerFilter` 参数 |

### 性能优化建议

对于大规模数据交换任务，可以通过合理的参数配置优化性能：

```python
# 性能优化的参数配置示例
datax = DataXScript()

# 使用较大的容差值减少精度但提高处理速度
datax.setDataXParameter("Tolerance", "0.01")

# 启用几何压缩减少文件大小和I/O时间
datax.setDataXParameter("CompressGeometry", "true")

# 批量导入导出时关闭不必要的日志
datax.setDataXParameter("Verbose", "false")

# 对于MDB格式，使用索引加速后续查询
datax.setDataXParameter("CreateIndex", "true")
```

性能优化需要在数据精度和处理速度之间取得平衡，应根据实际应用场景选择合适的参数值。

Sources: [PySSDataX.py](PySSDataX.py#L117-L157)

## 学习路径建议

掌握了数据交换参数配置的基础知识后，建议按照以下路径深入学习：

1. 继续学习 **[导入外部数据](27-dao-ru-wai-bu-shu-ju)**，了解特定格式（如 SHP、MDB、DXF）的导入细节和特殊参数配置。

2. 学习 **[导出数据到文件](28-dao-chu-shu-ju-dao-wen-jian)**，掌握不同导出格式的参数要求和优化技巧。

3. 探索 **[自定义数据交换流程](29-zi-ding-yi-shu-ju-jiao-huan-liu-cheng)**，了解如何结合选择集操作、属性修改等功能构建复杂的数据处理流程。

4. 参考 **[数学计算工具](43-shu-xue-ji-suan-gong-ju)** 和 **[坐标转换工具](44-zuo-biao-zhuan-huan-gong-ju)**，学习如何在数据交换过程中进行几何计算和坐标变换。

通过系统地学习这些内容，您将能够构建强大的数据交换和处理自动化脚本，大幅提升 GIS 数据管理效率。