From 41040f9a2a26c63517a76c0aa68a1b1c4afb9869 Mon Sep 17 00:00:00 2001 From: abhinavr4 <40848950+abhinavr4@users.noreply.github.com> Date: Wed, 30 Jun 2021 15:28:38 +0530 Subject: [PATCH] feat(imagekit): add modifiers and improve docs (#336) --- docs/pages/en/4.providers/imagekit.md | 272 +++++++++++++++++++++++++- playground/providers.ts | 40 ++++ src/runtime/providers/imagekit.ts | 144 +++++++++++++- 3 files changed, 452 insertions(+), 4 deletions(-) diff --git a/docs/pages/en/4.providers/imagekit.md b/docs/pages/en/4.providers/imagekit.md index be23881c8..af6ff43a1 100644 --- a/docs/pages/en/4.providers/imagekit.md +++ b/docs/pages/en/4.providers/imagekit.md @@ -7,7 +7,7 @@ navigation: Integration between [ImageKit](https://docs.imagekit.io/) and the image module. -To use this provider you just need to specify the base url of your service in ImageKit (don't forget to add your [ImageKit ID](https://docs.imagekit.io/integration/url-endpoints#default-url-endpoint)). +To use the ImageKit provider, you need to set your ImageKit account URL-endpoint as the base url like below. ```js{}[nuxt.config.js] export default { @@ -18,3 +18,273 @@ export default { } } ``` + +> You can get [URL-endpoint](https://docs.imagekit.io/integration/url-endpoints#default-url-endpoint) from your ImageKit dashboard - [https://imagekit.io/dashboard#url-endpoints](https://imagekit.io/dashboard#url-endpoints). + +## ImageKit `fit` Parameters + +In addition to the standard [`fit`](/components/nuxt-img#fit) properties of Nuxt Image and Nuxt Picture, ImageKit offers more cropping and resizing options to the users: + +* `extract` - The output image has its height, width as requested, and the aspect ratio is preserved. Unlike the `cover` parameter, we extract out a region of the requested dimension from the original image. +* `pad_extract` - This parameter is similar to `extract`. This comes in handy in scenarios where we want to extract an image of a larger dimension from a smaller image. So, the `pad_extract` mode adds solid colored padding around the image to match the exact size requested. + +Read ImageKit [crop and crop mode documentation](https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#crop-crop-modes-and-focus) for more details and examples of how it works. + +## ImageKit Modifiers + +On top of the standard [Nuxt Image modifiers](/components/nuxt-img#modifiers), a user can also leverage ImageKit-specific transformation parameters provided in the `modifier` prop. + +### `focus` + +This parameter can be used along with resizing and cropping to focus on the desired part of the image. You can use focus parameter values like `left`, `right`, `top`, `bottom`, `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left` and `bottom_right`. + +Custom coordinates can also be used to focus using parameter value `custom`. Learn more from [example](https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#example-focus-using-custom-coordinates). + +Moreover, ImageKit also provides smart cropping that can automatically detect the most important part of the image using `auto`. And, `face` can be used to find a face (or multiple faces) in an image and focus on that. + +Check out ImageKit's documentation on [focus](https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#focus-fo) to learn more. + + +### `blur` + +This can be used to blur an image. Use modifier `blur` to specify the Gaussian Blur radius that is to be applied to the image. Possible values include integers between `1` to `100`. + +```html + +``` + + +### `effectGray` + +Turn your image to a grayscale version using the `effectGray` modifier. + +```html + +``` + + +### `named` + +Use [named transformations](https://docs.imagekit.io/features/named-transformations) as an alias for an entire transformation string. + +For example, we can create a named transformation - `media_library_thumbnail` for a transformation string - `tr:w-100,h-100,c-at_max,fo-auto`. + + +### `border` + +Add a border to your images using the `border` modifier. You can also set its width and color. + +```html + +``` + + +### `rotate` + +Use the `rotate` modifier to rotate your image. Possible values are - `0`, `90`, `180`, `270`, `360`, and `auto`. + +```html + +``` + + +### `radius` + +Give rounded corners to your image using `radius`. Possible values are - positive integers and `max`. + +```html + +``` + + +### `bg` + +Specify background color and its opacity for your image using the `bg` modifier. + +```html + +``` + +> Read more about ImageKit crop, resize, and other common transformations [here](https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations). + +## Overlay Transformation Modifiers +Using ImageKit's Nuxt Image integration, you can overlay images or text over other images for watermarking or creating a dynamic banner using custom text! + +### `overlayImage` + +Overlay an image on top of another image (base image) using the `overlayImage` modifier. You can use this to create dynamic banners, watermarking, etc. + +```html + + + +``` + +### Overlay Text + +You can overlay text on an image and apply various transformations to it as per your needs. + +```html + + + +``` + +Read more about ImageKit's overlay transformation parameters [here](https://docs.imagekit.io/features/image-transformations/overlay). + +## Image Enhancement Modifiers + +### `effectContrast` +Enhance contrast of an image using the `effectContrast` modifier. + +```html + +``` + +### `effectSharpen` +Sharpen the input image using the `effectSharpen` modifier. + +```html + +``` + +## List of supported transforms +ImageKit's Nuxt Image integration provides an easy-to-remember name for each transformation parameter. It makes your code more readable. If you use a property that does not match any of the following supported options, it will be added in the URL as it is. + +| Supported Parameter Name | Translates to Parameter | +| --- | --- | +| bg | bg | +| aspectRatio | ar | +| x | x | +| y | y | +| xc | xc | +| yc | yc | +| oix | oix | +| oiy | oiy | +| oixc | oixc | +| oiyc | oiyc | +| crop | c | +| cropMode | cm | +| focus | fo | +| radius | r | +| border | b | +| rotate | rt | +| blur | bl | +| named | n | +| overlayX | ox | +| overlayY | oy | +| overlayFocus | ofo | +| overlayHeight | oh | +| overlayWidth | ow | +| overlayImage | oi | +| overlayImageTrim | oit | +| overlayImageAspectRatio | oiar | +| overlayImageBackground | oibg | +| overlayImageBorder | oib | +| overlayImageDPR | oidpr | +| overlayImageQuality | oiq | +| overlayImageCropping | oic | +| overlayImageCropMode | oicm | +| overlayText | ot | +| overlayTextFontSize | ots | +| overlayTextFontFamily | otf | +| overlayTextColor | otc | +| overlayTextTransparency | oa | +| overlayTextTypography | ott | +| overlayBackground | obg | +| overlayTextEncoded | ote | +| overlayTextWidth | otw | +| overlayTextBackground | otbg | +| overlayTextPadding | otp | +| overlayTextInnerAlignment | otia | +| overlayRadius | or | +| progressive | pr | +| lossless | lo | +| trim | t | +| metadata | md | +| colorProfile | cp | +| defaultImage | di | +| dpr | dpr | +| effectSharpen | e-sharpen | +| effectUSM | e-usm | +| effectContrast | e-contrast | +| effectGray | e-grayscale | +| original | orig | + +> Learn more about [ImageKit's Image transformations](https://docs.imagekit.io/features/image-transformations) from the official documentation. diff --git a/playground/providers.ts b/playground/providers.ts index 7ff3b7b9b..dc407be81 100644 --- a/playground/providers.ts +++ b/playground/providers.ts @@ -67,6 +67,46 @@ export const providers: Provider[] = [ { src: '/plant.jpeg' } ] }, + // ImageKit + { + name: 'imagekit', + samples: [ + { + src: '/girl.jpeg' + }, + { + src: '/girl.jpeg', + width: 400, + height: 300, + fit: 'fill' + }, + { + src: '/girl.jpeg', + width: 200, + height: 300, + modifiers: { + focus: 'auto' + } + }, + { + src: '/girl.jpeg', + width: 150, + height: 150, + modifiers: { + focus: 'face' + } + }, + { + src: '/girl.jpeg', + width: 150, + height: 150, + modifiers: { + focus: 'face', + radius: 'max' + } + } + ] + }, // imgix { name: 'imgix', diff --git a/src/runtime/providers/imagekit.ts b/src/runtime/providers/imagekit.ts index f2a63b535..4a853667e 100644 --- a/src/runtime/providers/imagekit.ts +++ b/src/runtime/providers/imagekit.ts @@ -9,7 +9,64 @@ const operationsGenerator = createOperationsGenerator({ height: 'h', format: 'f', quality: 'q', - background: 'bg' + bg: 'bg', + background: 'bg', + crop: 'c', + cropMode: 'cm', + aspectRatio: 'ar', + x: 'x', + y: 'y', + xc: 'xc', + yc: 'yc', + oix: 'oix', + oiy: 'oiy', + oixc: 'oixc', + oiyc: 'oiyc', + focus: 'fo', + radius: 'r', + border: 'b', + rotate: 'rt', + blur: 'bl', + named: 'n', + overlayX: 'ox', + overlayY: 'oy', + overlayFocus: 'ofo', + overlayHeight: 'oh', + overlayWidth: 'ow', + overlayImage: 'oi', + overlayImageTrim: 'oit', + overlayImageAspectRatio: 'oiar', + overlayImageBackground: 'oibg', + overlayImageBorder: 'oib', + overlayImageDPR: 'oidpr', + overlayImageQuality: 'oiq', + overlayImageCropping: 'oic', + overlayImageCropMode: 'oicm', + overlayText: 'ot', + overlayTextFontSize: 'ots', + overlayTextFontFamily: 'otf', + overlayTextColor: 'otc', + overlayTextTransparency: 'oa', + overlayTextTypography: 'ott', + overlayBackground: 'obg', + overlayTextEncoded: 'ote', + overlayTextWidth: 'otw', + overlayTextBackground: 'otbg', + overlayTextPadding: 'otp', + overlayTextInnerAlignment: 'otia', + overlayRadius: 'or', + progressive: 'pr', + lossless: 'lo', + trim: 't', + metadata: 'md', + colorProfile: 'cp', + defaultImage: 'di', + dpr: 'dpr', + effectSharpen: 'e-sharpen', + effectUSM: 'e-usm', + effectContrast: 'e-contrast', + effectGray: 'e-grayscale', + original: 'orig' }, valueMap: { fit: { @@ -17,13 +74,90 @@ const operationsGenerator = createOperationsGenerator({ contain: 'pad_resize', fill: 'force', inside: 'at_max', - outside: 'at_least' + outside: 'at_least', + extract: 'extract', + pad_extract: 'pad_extract' }, - background (value = '') { + background (value: string) { if (value.startsWith('#')) { return value.replace('#', '') } return value + }, + crop: { + maintain_ratio: 'maintain_ratio', + force: 'force', + at_max: 'at_max', + at_least: 'at_least' + }, + cropMode: { + pad_resize: 'pad_resize', + pad_extract: 'pad_extract', + extract: 'extract' + }, + format: { + auto: 'auto', + jpg: 'jpg', + jpeg: 'jpeg', + webp: 'webp', + avif: 'avif', + png: 'png' + }, + focus: { + left: 'left', + right: 'right', + top: 'top', + bottom: 'bottom', + custom: 'custom', + center: 'center', + top_left: 'top_left', + top_right: 'top_right', + bottom_left: 'bottom_left', + bottom_right: 'bottom_right', + auto: 'auto', + face: 'face' + }, + rotate: { + auto: 'auto', + 0: '0', + 90: '90', + 180: '180', + 270: '270', + 360: '360' + }, + overlayFocus: { + left: 'left', + right: 'right', + top: 'top', + bottom: 'bottom', + custom: 'custom', + center: 'center', + top_left: 'top_left', + top_right: 'top_right', + bottom_left: 'bottom_left', + bottom_right: 'bottom_right', + auto: 'auto', + face: 'face' + }, + overlayImageCropping: { + maintain_ratio: 'maintain_ratio', + force: 'force', + at_max: 'at_max', + at_least: 'at_least' + }, + overlayImageCropMode: { + pad_resize: 'pad_resize', + pad_extract: 'pad_extract', + extract: 'extract' + }, + overlayTextTypography: { + b: 'b', + i: 'i' + }, + overlayTextInnerAlignment: { + left: 'left', + right: 'right', + center: 'center' } }, joinWith: ',', @@ -32,7 +166,11 @@ const operationsGenerator = createOperationsGenerator({ export const getImage: ProviderGetImage = (src, { modifiers = {}, baseURL = '/' } = {}) => { let operations = operationsGenerator(modifiers) + operations = operations.replace('c-pad_resize', 'cm-pad_resize') + operations = operations.replace('c-pad_extract', 'cm-pad_extract') + operations = operations.replace('c-extract', 'cm-extract') + return { url: joinURL(baseURL, src + (operations ? `?tr=${operations}` : '')) }