diff --git a/docs/assets/hummingbird CC BY-SA 4.0.jpg b/docs/assets/hummingbird CC BY-SA 4.0.jpg new file mode 100644 index 000000000..967146ca4 Binary files /dev/null and b/docs/assets/hummingbird CC BY-SA 4.0.jpg differ diff --git a/docs/assets/img_sample_for_kimg.png b/docs/assets/img_sample_for_kimg.png deleted file mode 100644 index f06c72c46..000000000 Binary files a/docs/assets/img_sample_for_kimg.png and /dev/null differ diff --git a/docs/common/DocsShow.vue b/docs/common/DocsShow.vue index cd1a8acec..97d9b29ae 100644 --- a/docs/common/DocsShow.vue +++ b/docs/common/DocsShow.vue @@ -29,6 +29,20 @@ type: Boolean, required: false, }, + /** + * Container width + */ + width: { + type: String, + required: false, + }, + /** + * Container max width + */ + maxWidth: { + type: String, + required: false, + }, }, computed: { style() { @@ -36,6 +50,8 @@ display: this.block ? 'block' : 'inline-block', padding: this.padding ? '8px 24px' : null, backgroundColor: this.dark ? this.$themePalette.grey.v_500 : undefined, + width: this.width ? this.width : undefined, + maxWidth: this.maxWidth ? this.maxWidth : undefined, }; }, }, diff --git a/docs/pages/kimg.vue b/docs/pages/kimg.vue index 9e738f74f..1251a11a6 100644 --- a/docs/pages/kimg.vue +++ b/docs/pages/kimg.vue @@ -2,83 +2,204 @@ -
- The component displays images based on an image source and optional image - dimensions provided by the implementer. +

It displays an image and provides additional functionality to manipulate it such as setting dimensions, aspect ratio, scaling, letter boxing, and more.

+ + + +

When setting the dimensions of an image by using any of the supported methods, note that the settings are applied to the container of the image, rather than the image itself. Depending on the scale type and other settings, the image may be letterboxed. If you need to apply dimensions directly to the image, you can use 'fitXY' scale type. This, and other modes, are illustrated in the examples below, where the original image dimensions are 200×114 px.

+ +

Unless you set fixed dimensions, KImg is responsive by default.

+ +

Rendering within inline and block elements

+ +

Inline

-

Sample implementations of including props:

+

When rendered within an inline element, an image preserves its original dimensions.

+ + + + + + + + + + + + +

Block

+ +

When rendered within a block element, an image scales to its parent element with the 'centerInside' scale type (see below) by default.

+ +
- Dimensions may be either numbers or strings consisting of a numeral and valid units (e.g. px, - em, vh). + +
+ + +
+
+ -
- - - - - - +

Dimensions

+ +

You can use the most common dimensions right on the KImg via props like width, maxHeight, etc. See Props for the full list of available props. Values may be either numbers or strings consisting of a numeral and valid units. The following units are supported: %, cm, em, ex, ch, in, lh, mm, px, rem, rlh, vh, vw. If you don't provide a unit, px will be used by default.

+ + +
+
-
+ -
- requires alternative text that describes the image unless - isDecorative is true. In that case, any alt text provided will be overwritten to an - empty string. +

Alternative text

+ +

Unless an image is , you need to provide alternative text via altText. If it's meant to be decorative, then use isDecorative to indicate it. Then, alternative text won't be required, and the image will be hidden from assistive technologies.

+ +
-
- - - -
- - - +
-
+ + +

Scaling

-
- If dimensions for the image are not specified, the size will default to the height and width of the source - image. - +

'centerInside' scale type

+ +

Scales an image uniformly and maintains its original aspect ratio so that both its width and height are equal to or less than the container. The image can be letterboxed. It's the safest mode as it never distorts the image.

+ + +
- - +
+ + +
- +
+ + +

'contain' scale type

-
+

Behaves like 'centerInside' except it ensures that at least one axis of the image fits the container exactly. The original aspect ratio is maintained. The image can be letterboxed. This mode may distort the image by enlarging it above its original size.

+ + +
+ +
+ + +
+ +
+ + +

'fitXY' scale type

+ +

Scales X and Y axis of an image independently, so that the image matches the container exactly. This mode may distort the image as its original aspect ratio is ignored. The image is never letterboxed. It could also distort the image by enlarging it above its original size.

+ + +
+ +
+ + +
+ +
+ + +

Aspect ratio

+ +

You can set aspect ratio via aspectRatio on an image and combine it with any of the scale types.

+ +

Note that ratio styles are based on the width information, therefore it needs to be available in some way. For example, it could be provided directly to KImg, or you could ensure that its parent element has width by setting it explicitly or by using a block element.

+ + +
+ +
+ + +
+ +
+ + @@ -93,23 +214,13 @@ diff --git a/lib/KImg.vue b/lib/KImg.vue index 829e6f5cf..fa3787d41 100644 --- a/lib/KImg.vue +++ b/lib/KImg.vue @@ -1,19 +1,57 @@