PhotoCropTool

qxs-photo-crop-tool 是 @qxs-bns/components 里的图片裁剪组件，适合上传前封面裁剪、头像裁剪、活动海报截取这类需要先拿到 File 再提交接口的场景。

基础用法

import '@qxs-bns/components/photo-crop-tool'

如果你已经全量引入：

import '@qxs-bns/components'

使用说明

qxs-photo-crop-tool 的图片输入不是字符串 URL，而是宿主直接传入的 File。
zoom-type="fixed" 会锁定 aspect-ratio；zoom-type="free" 允许自由拖拽宽高。
实例方法 crop() 返回 Promise<File | null>，resize() 会重置裁剪框。

常见场景

宿主接入示例

API

属性

Name	Description	Type	Default
`imgFile`	待裁剪图片文件。只支持通过 DOM property 传入 `File`	`File \| null`	`null`
`aspect-ratio`	裁剪框宽高比，格式如 `16 / 9`、`1 / 1`	`string`	`'16 / 9'`
`default-width`	裁剪框默认宽度	`number`	`320`
`default-height`	裁剪框默认高度	`number`	`180`
`zoom-type`	裁剪框缩放模式	`'fixed' \| 'free'`	`'fixed'`

方法

Name	Description	Return
`crop()`	生成裁剪后的 PNG 文件	`Promise<File \| null>`
`resize()`	重置裁剪框到默认尺寸和居中位置	`void`

事件

Name	Description
-	`qxs-photo-crop-tool` 不额外抛出业务事件

CSS Parts

Part	Description
`container`	外层裁剪容器
`image`	图片预览层
`crop-box`	裁剪框本体
`handle`	四角拖拽控制点

常见问题

为什么 `imgFile` 不是字符串 URL？

因为这个组件的目标是“上传前裁剪”，最终要返回一个新的 File 再交给宿主上传。
如果你的数据源一开始只有 URL，先把它转成 Blob / File 再传给组件会更稳定。

Vue 模板里为什么推荐写 `:img-file.prop`？

imgFile 是对象属性，不是 HTML attribute。
在 Vue 里用 .prop 可以明确告诉编译器这是往 Custom Element 实例上写 File。

PhotoCropTool ​

基础用法 ​

使用说明 ​

常见场景 ​

宿主接入示例 ​

API ​

属性 ​

方法 ​

事件 ​

CSS Parts ​

常见问题 ​

为什么 imgFile 不是字符串 URL？ ​

Vue 模板里为什么推荐写 :img-file.prop？ ​

相关文档 ​