# informat.ftp FTP相关

## 概述

使用`informat.ftp`实现ftp客户端相关功能。

## createClient

初始化ftp客户端实例

```javascript
informat.ftp.createClient()
```

**返回值**
类型为[FtpClient](/guide/script/ftp.md#ftpclient)

## FtpClient

### connect

建立与 FTP 服务器的连接

```js
client.connect(host, port)
```

| 参数   | 类型        | 描述       |
|------|-----------|----------|
| host | `String`  | ftp服务器主机 |
| port | `Integer` | ftp服务器端口 |

**示例**

```js
client.connect('127.0.0.1', 21)
```

### login

账号密码登录ftp服务器

```js
client.login(username, password)
```

| 参数       | 类型       | 描述  |
|----------|----------|-----|
| username | `String` | 用户名 |
| password | `String` | 密码  |

**返回值**

类型为`Boolean`
返回是否登录成功

**示例**

```js
client.login('ftpuser', '123456')
```

### printWorkingDirectory

返回当前的工作目录路径

```js
client.printWorkingDirectory()
```

**返回值**

类型为`String`
返回当前的工作目录路径

### changeToParentDirectory

改变当前工作目录到其父目录

```js
client.changeToParentDirectory()
```

**返回值**

类型为`Boolean`
返回是否改变当前工作目录到其父目录成功

### changeWorkingDirectory

改变当前连接的 FTP 服务器的工作目录

```js
client.changeWorkingDirectory(path)
```

| 参数   | 类型       | 描述           |
|------|----------|--------------|
| path | `String` | 指定要更改到的目录的路径 |

**返回值**

类型为`Boolean`
返回是否改变工作目录成功

**示例**

```js
client.changeWorkingDirectory('/')
```

### uploadFile

上传文件到 FTP 服务器

```js
client.uploadFile(localPath, remotePath)
```

| 参数         | 类型       | 描述              |
|------------|----------|-----------------|
| localPath  | `String` | 上传的app沙盒环境文件的路径 |
| remotePath | `String` | FTP服务器的文件路径     |

**返回值**

类型为`Boolean`
返回是否上传成功

**示例**

```js
client.uploadFile('demo.png', 'test/demo.png');
```

### downloadFile

从FTP服务器下载指定文件到本地app沙盒环境

```js
client.downloadFile(remotePath, localPath)
```

| 参数         | 类型       | 描述            |
|------------|----------|---------------|
| remotePath | `String` | 远程文件路径        |
| localPath  | `String` | 本地app沙盒环境文件路径 |

**返回值**

类型为`Boolean`
返回是否下载成功

**示例**

```js
client.downloadFile("test/demo.png", "ftp/demo.png");
```

### makeDirectory

在FTP服务器创建文件夹

```js
client.makeDirectory(path)
```

| 参数   | 类型       | 描述      |
|------|----------|---------|
| path | `String` | 远程文件夹路径 |

**返回值**

类型为`Boolean`
返回是否创建成功

**示例**

```js
client.makeDirectory('test');
```

### listFiles

列出 FTP 服务器上当前工作目录下的文件和目录

```js
client.listFiles()
```

**返回值**

类型为`Array<FtpFile>`
返回文件列表

::: warning 如果返回为空，且目录下有文件则需要设置被动传输模式

```js
let client = null;
try {
    // 创建连接
    client = informat.ftp.createClient();
    client.connect('127.0.0.1', 21);
    // 登录
    let login = client.login('ftpuser', '123456');
    console.log('login:', login);
    // 获取当前路径
    console.log(client.printWorkingDirectory());
    // 开启被动传输模式                // [!code focus]     
    client.getFtpClient().enterLocalPassiveMode(); // [!code focus]
    // 获取当前目录下的文件和目录
    let files = client.listFiles();
    files.forEach(f => {
        console.log(f);
        console.log(f.getGroup()); // 文件群组
        console.log(f.getName()); // 文件名称
        console.log(f.getSize()); // 文件大小
        console.log(f.isDirectory()); // 是否文件夹
        console.log(f.isFile()); // 是否文件
    })

} finally {
    if (client != null) {
        // 关闭连接
        client.disconnect();
    }
}
```

:::

### disconnect

关闭与 FTP 服务器的连接

```js
client.disconnect()
```

***完整示例***

```js
let client = null;
try {
    // 创建连接
    client = informat.ftp.createClient();
    client.connect('127.0.0.1', 21);
    // 登录
    let login = client.login('ftpuser', '123456');
    console.log('login:', login);
    // 获取当前路径
    console.log(client.printWorkingDirectory());
    // 获取当前目录下的文件和目录
    let files = client.listFiles();
    files.forEach(f => {
        console.log(f);
        console.log(f.getGroup()); // 文件群组
        console.log(f.getName()); // 文件名称
        console.log(f.getSize()); // 文件大小
        console.log(f.isDirectory()); // 是否文件夹
        console.log(f.isFile()); // 是否文件
    })
    // 创建目录
    client.makeDirectory('test');
    // 上传文件
    var ret = client.uploadFile('demo.png', 'test/demo.png');
    console.log('uploadFile ret:', ret)
    // 下载文件
    ret = client.downloadFile("test/demo.png", "ftp/demo.png");
    console.log('downloadFile ret:', ret)
} finally {
    if (client != null) {
        // 关闭连接
        client.disconnect();
    }
}
```
