CKFinder 3 – ASP.NET 连接器文档
命令

目录

CKFinder 命令的行为就像控制器。它们封装了处理请求并生成适当响应（在 CKFinder 中通常是 JSON）所需的逻辑。命令是根据command URL 参数解析的。

每个命令都必须实现ICommand接口。

当需要命令时，依赖项会注入构造函数。

每个命令类的核心是它的ExecuteAsync方法，所有处理都在这里进行。

定义权限

执行每个 CKFinder 命令都需要在ACL 配置设置中设置适当的权限。可以使用IRequestAcl接口验证命令所需的权限

using System.Threading;
using System.Threading.Tasks;
using CKSource.CKFinder.Connector.Core.Acl;
using CKSource.CKFinder.Connector.Core.Commands;
using CKSource.CKFinder.Connector.Core.Nodes;
using CKSource.CKFinder.Connector.Core.Resources;
public class SomeCommand : ICommand
{
private readonly IRequestAcl _requestAcl;
private readonly IResourceTypeRepository _resourceRepository;
private readonly INodeFactory _nodeFactory;
public SomeCommand(IRequestAcl requestAcl, IResourceTypeRepository resourceRepository, INodeFactory nodeFactory)
{
_requestAcl = requestAcl;
_resourceRepository = resourceRepository;
_nodeFactory = nodeFactory;
}
public async Task<CommandResponse> ExecuteAsync(CancellationToken cancellationToken)
{
var resource = await _resourceRepository.GetByNameAsync("Resource name", cancellationToken);
var folder = _nodeFactory.CreateFolder(resource, "/path/to/folder");
_requestAcl.RequirePermission(folder, Permission.FolderView);
return new StringCommandResponse("Everything OK!");
}
}

修改现有命令

所有现有的 CKFinder 命令都可以使用事件系统进行修改（例如添加额外信息或更改默认 JSON 响应）。有关更详细的信息，请参阅事件文章。

在某些情况下，修改从 CKFinder 传递到服务器端连接器的命令参数可能很有用。有关如何执行此操作的示例，请查看AlterCommand插件，该插件位于CKFinder 3 示例 JavaScript 插件存储库中。

创建自定义命令

自定义 CKFinder 命令可以注入到连接器中。有关更多信息，请参阅 HOWTO 中的自定义命令部分。

查看ImageInfo插件（位于CKFinder 3 示例 JavaScript 插件存储库中）可能也很有用，以了解如何从 JavaScript 插件请求命令。您可以在将命令发送到服务器部分（位于CKFinder 3 JavaScript 文档中）找到更多信息。

CKFinder 命令列表

常见 URL 参数

名称描述
command 要执行的命令的名称。
type 资源类型名称。
currentFolder 当前工作文件夹路径。

CopyFiles

描述从选定的文件夹复制文件。
方法POST
示例请求

将Files资源类型的sub1目录中的两个文件复制到Images资源类型的根目录（/）。

files参数结构示例（JSON 表示法）

request["files"] = [
{
"name": "file1.jpg",
"type": "Files",
"folder": "/sub1/"
"options": ""
},
{
"name": "file2.png",
"type": "Files",
"folder": "/sub1/"
"options": ""
}
]
/ckfinder/connector?command=CopyFiles&type=Images&currentFolder=/
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/images/",
"acl": 255
},
"copied": 2
}
注意请求应包含一个名为files的数组参数，其元素定义要复制的源文件。每个数组元素应包含以下参数
  • name – 文件名。
  • type – 文件资源类型。
  • folder – 文件夹。
  • options – 定义如果目标文件夹中已存在同名文件，则应如何复制该文件的参数。option参数可以包含以下值
    • 默认情况下，它是一个空字符串，在这种情况下，如果文件已存在，则会向响应添加适当的错误。
    • overwrite – 覆盖目标文件。
    • autorename – 在这种情况下，复制文件的名称会通过在文件名中添加数字来更改，例如自动重命名后的file.txt为file(1).txt。

CreateFolder

描述创建子文件夹。
方法POST
示例请求

在Files资源类型的根文件夹（/）中创建My Folder文件夹

/ckfinder/connector?command=CreateFolder&type=Files&currentFolder=/&newFolderName=My Folder
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/files/",
"acl": 255
},
"newFolder": "My Folder",
"created": 1
}

DeleteFiles

描述删除给定的文件。
方法POST
示例请求

删除Files资源类型的sub1目录中的两个文件。

files参数结构示例（JSON 表示法）

request["files"] = [
{
"name": "file1.jpg",
"type": "Files",
"folder": "/sub1/"
},
{
"name": "file2.png",
"type": "Files",
"folder": "/sub1/"
}
]
/ckfinder/connector?command=DeleteFiles&type=Files&currentFolder=/
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/files/",
"acl": 255
},
"deleted": 2
}
注意请求应包含一个名为files的数组参数，其元素定义要删除的源文件。每个数组元素应包含以下参数
  • name – 文件名。
  • type – 文件资源类型。
  • folder – 文件夹。

DeleteFolder

描述删除给定的文件夹。
方法POST
示例请求

删除Files资源类型的sub1目录

/ckfinder/connector?command=DeleteFolder&type=Files&currentFolder=/sub1/
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/sub1/",
"url": "/ckfinder/userfiles/files/sub1/",
"acl": 255
},
"deleted": 1
}

DownloadFile

描述从服务器下载文件。
方法GET
示例请求

从Files资源类型的根目录（/）下载名为Test.jpg的文件

/ckfinder/connector?command=DownloadFile&type=Files&currentFolder=/&fileName=Test.jpg
注意此命令不希望连接器返回文本响应。相反，它必须将文件数据流式传输到客户端。

FileUpload

描述将文件上传到给定文件夹。
方法POST
示例请求

将文件上传到Files资源类型的根目录（/）

/ckfinder/connector?command=FileUpload&type=Files&currentFolder=/
示例响应

{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/files/",
"acl": 255
},
"fileName": "fileName.jpg",
"uploaded": 1
}
注意
  • 文件数据应编码为multipart/form-data。
  • 包含上传文件的POST参数应命名为upload。
  • 上传的文件名可以包含非 ASCII 字符。

GetFiles

描述返回给定文件夹的文件列表。
方法GET
示例请求获取Images资源类型的/Docs/文件夹中的文件列表
/ckfinder/connector?command=GetFiles&type=Images&currentFolder=/Docs/
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/Docs/",
"url": "/ckfinder/userfiles/images/Docs/",
"acl": 255
},
"files": [
{
"name": "image1.png",
"date": "201406080924",
"size": 1
},
{
"name": "測試.png",
"date": "201406080924",
"size": 12
}
]
}
注意

文件名可以包含非 ASCII 字符，例如上面的示例中使用的中文。

date属性对应于最后一次文件修改时间，格式为YYYYMMDDHHmm，其中

  • YYYY – 年（4 位数）。
  • MM – 月（用零填充的 2 位数）。
  • DD – 日（用零填充的 2 位数）。
  • HH – 小时（24 小时制，用零填充的 2 位数）。
  • mm – 分钟（用零填充的 2 位数）。

size属性包含文件大小（以千字节为单位）。

GetFileUrl

描述返回指向文件的直接 URL。
方法GET
示例请求获取存储在Images资源类型的/kittens/文件夹中的名为longcat.jpg的文件的直接 URL
/ckfinder/connector?command=GetFileUrl&type=Images&currentFolder=/kittens/&fileName=longcat.jpg
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/kittens/",
"url": "/ckfinder/userfiles/images/kittens/",
"acl": 255
},
"url": "/ckfinder/userfiles/images/kittens/longcat.jpg"
}
注意此命令返回的 URL 取决于为资源类型定义的后端。在大多数情况下，需要为后端定义一个baseUrl才能获得指向文件的有效直接 URL。

GetFolders

描述返回给定文件夹的子文件夹列表。
方法GET
示例请求获取Images资源类型的/Docs/文件夹中的子文件夹。
/ckfinder/connector?command=GetFolders&type=Images&currentFolder=/Docs/
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/Docs/",
"url": "/ckfinder/userfiles/images/Docs/",
"acl": 255
},
"folders": [
{
"name": "folder1",
"hasChildren": false,
"acl": 255
},
{
"name": "繁體中文字",
"hasChildren": false,
"acl": 255
}
]
}
注意文件夹名称可以包含非 ASCII 字符，例如上面的示例中使用的中文。

GetResizedImages

描述返回图像文件调整大小版本的列表。
方法GET
示例请求获取存储在Images资源类型的/kittens/文件夹中的longcat.jpg图像的调整大小版本
/ckfinder/connector?command=GetResizedImages&type=Images&currentFolder=/kittens/&fileName=longcat.jpg
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/kittens/",
"url": "/ckfinder/userfiles/images/kittens/",
"acl": 255
},
"originalSize":"1920x1200",
"resized": {
"small": "longcat__480x300.jpg",
"medium": "longcat__600x375.jpg",
"large": "longcat__800x500.jpg",
"__custom": ["longcat__200x125.jpg", "longcat__300x188.jpg"]
}
}
注意图像调整大小版本始终保留原始图像的纵横比。当图像调整大小版本与images.sizes配置选项中定义的任何大小匹配时，它会附加到响应中的适当键下（如上面的示例中的small、medium、large）。所有其他现有的调整大小版本都存储在名为__custom的键下。

ImageEdit

描述执行基本的图像修改：裁剪、旋转、调整大小。
方法POST
示例请求

要执行的操作以及所需参数在 actions 数组参数中发送。

actions 参数结构示例（JSON 表示法）

request["actions"] = [
{
"action": "rotate",
"angle": 90 // 顺时针旋转的度数。
},
{
"action": "resize",
"width": 300, // 图像最大宽度。
"height": 300 // 图像最大高度。
},
{
"action": "crop",
"x": 0, // 裁剪区域左上角的 X 坐标。
"y": 0, // 裁剪区域左上角的 Y 坐标。
"width": 225, // 裁剪区域宽度。
"height": 150 // 裁剪区域高度。
}
]

取决于 newFileName 参数是否提供

  • 如果提供，则会创建一个具有给定名称的新文件。
  • 如果省略，则替换当前文件。
/ckfinder/connector?command=ImageEdit&type=Images&currentFolder=/kittens/&fileName=longcat.jpg
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/kittens/",
"url": "/ckfinder/userfiles/images/kittens/",
"acl": 255
},
"saved": 1
}

ImageInfo

描述返回有关图像文件尺寸的信息。
方法GET
示例请求

获取存储在 Images 资源类型 /kittens/ 文件夹中的 longcat.jpg 图像的尺寸。

/ckfinder/connector?command=ImageInfo&type=Images&currentFolder=/kittens/&fileName=longcat.jpg
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/kittens/",
"url": "/ckfinder/userfiles/images/kittens/",
"acl": 255
},
"width": 1440,
"height": 900
}

ImagePreview

描述创建图像文件的调整大小版本。
方法GET
示例请求

创建存储在 Images 资源类型 /kittens/ 文件夹中的 longcat.jpg 图像的调整大小版本。将其调整为 450x450

/ckfinder/connector?command=ImagePreview&type=Images&currentFolder=/kittens/&fileName=longcat.jpg&size=450x450
示例响应此命令不希望连接器返回文本响应。相反，它必须将图像数据流式传输到客户端。
注意

返回的图像始终保留原始图像的纵横比（使用为边框计算出的较高缩放因子）。当请求的大小与原始图像的纵横比不匹配时，将更正请求的大小。

使用此命令生成的图像不会存储在服务器端。

ImageResize

描述创建图像文件的调整大小版本。
方法POST
示例请求

创建存储在 Images 资源类型 /kittens/ 文件夹中的 longcat.jpg 图像的调整大小版本。将其调整为 450x450

/ckfinder/connector?command=ImageResize&type=Images&currentFolder=/kittens/&fileName=longcat.jpg&size=450x450
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/kittens/",
"url": "/ckfinder/userfiles/images/kittens/",
"acl": 255
},
"url":"/ckfinder/userfiles/images/kittens/__thumbs/longcat.jpg/longcat__450x281.jpg" // 文件的直接 URL
}
注意

返回的图像始终保留原始图像的纵横比（使用为边框计算出的较低缩放因子）。当请求的大小与原始图像的纵横比不匹配时，将更正请求的大小。

使用此命令生成的图像存储在当前文件文件夹中创建的名为 __thumbs 的特殊文件夹中。

Init

描述这是 CKFinder 发出的第一个命令。它返回连接器的常规设置和所有已配置的资源类型。
方法GET
示例请求
/ckfinder/connector?command=Init
示例响应
{
"enabled": true,
"s": "",
"c": "",
"thumbs": ["150x150", "300x300", "500x500"],
"images":{"max":"500x400","sizes":{"small":"480x320","medium":"600x480","large":"800x600"}},
"uploadMaxSize": "425167",
"uploadCheckImages": true,
"resourceTypes": [
{
"name": "Files",
"url": "/ckfinder/userfiles/files",
"allowedExtensions": "7z,aiff,asf,avi,bmp,csv,doc,docx,fla,flv,gif,gz,gzip,jpeg,zip",
"deniedExtensions": "",
"hash": "8b787e3ea25b5079",
"hasChildren": false,
"acl": 1023,
"maxSize": 32768
},
{
"name": "Images",
"url": "/ckfinder/userfiles/images",
"allowedExtensions": "bmp,gif,jpeg,jpg,png",
"deniedExtensions": "",
"hash": "b8de0a3f3cb3cd1f",
"hasChildren": false,
"acl": 1023,
"maxSize": 65536
}
]
}

MoveFiles

描述将文件从选定的文件夹移动。
方法POST
示例请求

将两个文件从 Files 资源类型的 sub1 目录移动到 Images 资源类型的根 (/) 目录。

files参数结构示例（JSON 表示法）

request["files"] = [
{
"name": "file1.jpg",
"type": "Files",
"folder": "/sub1/"
"options": ""
},
{
"name": "file2.png",
"type": "Files",
"folder": "/sub1/"
"options": ""
}
]
/ckfinder/connector?command=MoveFiles&type=Files&currentFolder=/
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/files/",
"acl": 255
},
"moved": 2
}
注意请求应包含一个名为 files 的数组参数，其元素定义要移动的源文件。每个数组元素应包含以下参数
  • name – 文件名。
  • type – 文件资源类型。
  • folder – 文件夹。
  • options – 定义文件在目标文件夹中已存在具有相同名称的文件时如何移动的方式的参数。option 参数可以包含以下值
    • 默认情况下，它是一个空字符串，在这种情况下，当文件已存在时，会将相应的错误添加到响应中。
    • overwrite – 覆盖目标文件。
    • autorename – 在这种情况下，移动文件的名称会通过在文件名中添加一个数字来更改，例如，file.txt 在自动重命名后为 file(1).txt。

Operation

自从
CKFinder 3.1.0
描述跟踪时间消耗的连接器命令中操作的进度。
方法GET
示例请求

可以通过传递一个名为 operationId 的附加参数来启动时间消耗的命令的进度跟踪

/ckfinder/connector?command=RenameFolder&type=Files&currentFolder=/foo/&newFolderName=bar&operationId=i52q7a7db83rz3n6

operationId 是一个唯一的操作标识符，它应与以下正则表达式匹配：^[a-z0-9]{16}。

然后可以使用对 Operation 命令的请求定期检查操作的状态

/ckfinder/connector?command=Operation&operationId=i52q7a7db83rz3n6
示例响应
{
"total": 291,
"current": 128
}
注意

并非所有命令都支持操作跟踪，此功能可能取决于为后端定义的存储类型。

此命令可以使用以下可选参数

  • abort – 如果此布尔参数存在，则将立即中止时间消耗的操作。

Proxy

自从
CKFinder 3.1.0
描述

将文件提供给浏览器，而不强制下载。此命令在您想要在网页上使用没有直接访问权限的文件的情况下很有用。这些可能是存储在后端（如私有 FTP 服务器）上的文件，或者不在 Web 服务器根文件夹中的文件。如果后端定义为 Proxy，则 CKFinder 生成的所有链接都将指向 Proxy 命令。

注意：如果您决定使用此选项，则 CKFinder 生成的所有链接都将指向 Proxy 命令，并将依赖 CKFinder 连接器才能正常工作。

方法GET
示例请求
/ckfinder/connector?command=Proxy&type=Files&currentFolder=/&fileName=foo.jpg
示例响应此命令不希望连接器返回文本响应。相反，它必须将文件数据流式传输到客户端。
注意此命令可以使用以下可选参数
  • cache – 一个整数，定义以秒为单位的缓存生存期（这对应于 Expires 和 Cache-Control 响应标头）。请参阅 配置。
  • thumbnail – 公开缩略图文件的名称，如果应提供图像的调整大小版本。

QuickUpload

描述将文件上传到给定文件夹。此命令与 FileUpload 非常相似，它用于处理来自 CKEditor 图像或链接对话框的上传。
方法POST
示例请求

此命令接受一个名为 responseType 的附加 URL 参数，该参数定义返回的响应的格式。

将文件上传到Files资源类型的根目录（/）

/ckfinder/connector?command=FileUpload&type=Files&currentFolder=/
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/files/",
"acl": 255
},
"fileName": "fileName.jpg",
"uploaded": 1
}
注意
  • 文件数据应编码为multipart/form-data。
  • 包含上传文件的POST参数应命名为upload。
  • 上传的文件名可以包含非 ASCII 字符。

RenameFile

描述重命名文件。
方法POST
示例请求

将 Files 资源类型 sub1 目录中的文件 foo.jpg 重命名为 bar.jpg

/ckfinder/connector?command=RenameFile&type=Files&currentFolder=/sub1/&fileName=foo.jpg&newFileName=bar.jpg
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/sub1/",
"url": "/ckfinder/userfiles/files/sub1/",
"acl": 255
},
"name": "foo.jpg",
"newName":"bar.jpg",
"renamed": 1
}

RenameFolder

描述重命名文件夹。
方法POST
示例请求

将 Files 资源类型中的 sub1 文件夹重命名为 sub1_renamed

/ckfinder/connector?command=RenameFolder&type=Files&currentFolder=/sub1/&newFolderName=sub1_renamed
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/sub1/",
"url": "/ckfinder/userfiles/files/sub1/",
"acl": 255
},
"newName": "sub1_renamed",
"newPath": "/sub1_renamed/",
"renamed": 1
}

SaveImage

描述将 Base64 编码的 PNG 图像保存到文件。
方法POST
示例请求

将 content 参数中发送的 Base64 编码图像保存为 Files 资源类型的根 (/) 目录中的 Test.jpg 文件

/ckfinder/connector?command=SaveImage&type=Files&currentFolder=/&fileName=Test.jpg
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/files/",
"acl": 255
},
"saved": 1,
"date": "201406080924",
"size": 1
}

Thumbnail

描述下载图像文件的缩略图。
方法GET
示例请求

从 Files 资源类型的根 (/) 目录中下载名为 Test.jpg 的文件的缩略图

/ckfinder/connector?command=Thumbnail&type=Files&currentFolder=/&fileName=Test.jpg&size=150x150
响应此命令不希望连接器返回文本响应。相反，它必须将缩略图文件数据流式传输到浏览器。
注意

size 参数可用于控制返回的缩略图图像的大小。默认情况下，CKFinder 3 for ASP.NET 连接器支持以下缩略图尺寸

  • 150x150
  • 300x300
  • 500x500

可以在主配置文件中覆盖默认尺寸。