Keel v0.5.1 中文 GitHub

Image

Live example: a real Keel application compiled to WebAssembly. Interact with it here. The initial download is about 10 MB.Open full screen
Example sourceGo · Copyable

This is the complete source for the gallery example above.examples/components/image.go

Reuse the component construction and Render methods in a scaffolded project. The example’s registerSection and shared helpers are provided by the component gallery.

package main

import (
	"bytes"
	"encoding/base64"
	"image"
	"image/color"
	"image/gif"
	"image/png"
	"net/url"

	"github.com/dyike/keel/ui/core"
	"github.com/dyike/keel/ui/el"
	"github.com/dyike/keel/ui/kit"
	"github.com/dyike/keel/ui/theme"
)

func init() {
	registerSection("image", "display", func() core.Widget {
		img := image.NewNRGBA(image.Rect(0, 0, 240, 72))
		colors := []color.NRGBA{{R: 224, G: 96, B: 86, A: 255}, {R: 89, G: 171, B: 137, A: 255}, {R: 87, G: 139, B: 209, A: 255}}
		for y := 0; y < 72; y++ {
			for x := 0; x < 240; x++ {
				img.SetNRGBA(x, y, colors[x/80])
			}
		}
		msg := demoText("Click the image to preview; Esc closes it", "点击图片预览;Esc 关闭")
		photo := kit.Image(img, demoText("Red, green, and blue blocks", "红绿蓝色块")).Rounded(8).Preview().OnClick(func() { msg = demoText("Image clicked", "已点击图片") })
		loading := kit.Image(nil, demoText("Image that fails to load", "加载失败的图片")).Width(240)
		loading.SetError(demoText("Connection lost", "网络中断"))
		loading.OnRetry(func() { loading.SetImage(img) })
		var encoded bytes.Buffer
		_ = png.Encode(&encoded, img)
		source := "data:image/png;base64," + base64.StdEncoding.EncodeToString(encoded.Bytes())
		sourced := kit.Image(nil, demoText("Async loading example", "异步加载示例")).Size(240, 72).LoadingContent(kit.Label(demoText("Loading…", "正在加载…"))).Fallback(kit.Label(demoText("Cannot read image", "无法读取图片"))).Source(source)
		crop := kit.Image(img, demoText("Center crop", "居中裁剪")).Size(120, 100).Fit(kit.ImageCover).Rounded(16).Preview()
		contain := kit.Image(img, demoText("Show in full", "完整显示")).Size(120, 100).Fit(kit.ImageContain).Rounded(16)
		vector := kit.Image(nil, demoText("SVG vector image", "SVG 矢量图")).Size(120, 100).Source("data:image/svg+xml," + url.PathEscape(demoSVG))
		animated := kit.Image(nil, demoText("Animated GIF", "GIF 动图")).Size(120, 100).Source("data:image/gif;base64," + base64.StdEncoding.EncodeToString(demoGIF()))
		return el.Embed(el.ViewFunc(func(cx *el.Context) el.Element {
			return el.Div().P(24).Gap(12).Items(el.Start).Child(photo.Render(cx), el.Text(msg).TextColor(theme.Muted), el.Div().Row().Gap(12).Child(crop.Render(cx), contain.Render(cx)), el.Div().Row().Gap(12).Child(vector.Render(cx), animated.Render(cx)), loading.Render(cx), sourced.Render(cx), kit.Button(demoText("Reload source image", "重新加载源图片"), sourced.Retry).Render(cx))
		}))
	})
}

const demoSVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 100">
<circle cx="60" cy="50" r="40" fill="#578bd1"/><path d="M40 50 l14 14 l28 -28" stroke="#fff" stroke-width="8" fill="none" stroke-linecap="round"/></svg>`

// demoGIF builds a small looping animation: a dot moving along a track.
func demoGIF() []byte {
	pal := color.Palette{color.NRGBA{235, 238, 243, 255}, color.NRGBA{87, 139, 209, 255}}
	g := &gif.GIF{}
	for i := 0; i < 8; i++ {
		frame := image.NewPaletted(image.Rect(0, 0, 120, 100), pal)
		cx := 20 + i*80/7
		for y := 40; y < 60; y++ {
			for x := cx - 10; x < cx+10; x++ {
				if (x-cx)*(x-cx)+(y-50)*(y-50) < 100 {
					frame.SetColorIndex(x, y, 1)
				}
			}
		}
		g.Image = append(g.Image, frame)
		g.Delay = append(g.Delay, 12)
	}
	var b bytes.Buffer
	_ = gif.EncodeAll(&b, g)
	return b.Bytes()
}

Display a decoded image, or load an image asynchronously from a Source, scaling by width and maintaining aspect ratio.

logo := kit.Image(img, "Company logo").Width(160).Rounded(8)
photo := kit.Image(nil, "Avatar") // Display the placeholder first; after loading, call photo.SetImage(img) in core.Update
  • By default, it fills the width of the parent container, but does not exceed the pixel width of the image itself; Width(dp) sets the maximum width.
  • Displays a placeholder block with alt text when there is no image. It can be loaded with Source, or SetImage can be called after decoding elsewhere.
  • OnClick makes the image clickable and focusable, SetDisabled disables clicks.

Agent: role image, name is alt text, value is loaded or loading.

Verify: go run ./examples/components -section image, add -theme dark to check the dark theme.

Size(width, height) specifies the view frame, Fit(ImageContain) displays it completely and is centered, ImageCover is centered and cropped, and ImageFill is stretched and filled. The width is still constrained by the parent container; a height of 0 remains proportional to the actual width. Sizes and rounded corners ignore negative numbers and NaN/Inf, and a width of 0 returns to automatic width. Corner clipping works on both pixels and hit areas.

Preview() allows the loaded image to open a modal preview by clicking or keyboard; Esc, close button and background can be closed, and the focus returns to the original image. Removing an image or disabling the associated area will turn off the preview. OnClick can be shared with previews.

SetError(reason) clears the old image and displays the error; OnRetry(fn) adds a retry button. Click to clear the error and return to the loading state before calling the callback. Call SetImage on successful loading. Manual background loading uses core.Update to submit results; you can also use the built-in Source/Cache below. Every time SetImage replaces the draw cache, the old cache reference is released immediately with nil/empty drawing and error status. Do not modify the image pixels after passing them in; call SetImage again when changes are needed. The Agent's image status is increased by error and the retry button name contains alt text.

Loading, caching and state content

cache := kit.NewImageCache(32 << 20)
photo := kit.Image(nil, "Product photo").Size(320, 180).
    LoadingContent(kit.Spinner().Label("Loading image")).
    Fallback(kit.Label("Image unavailable")).
    Cache(cache).Source("https://example.com/photo.webp")

Source supports local path/file URL, data URL, and HTTP(S) address - the network address must be introduced in the application _ "github.com/dyike/keel/ui/netimage" (about 4 MB, if not introduced, core.ErrNoImageFetcher will be returned); the formats are PNG, JPEG, WebP, GIF (including animations) and SVG, and the size limit is the same as core.DecodeImage. Requests are executed in the background with a default timeout of 15 seconds; results are submitted through the UI queue. Repeating the same address does not overload; Source("") cancels and clears. SetImage/SetError also cancels and removes the current Source, old results cannot overwrite them. Component uninstallation is not automatically canceled and the app can call Source("") when it is no longer in use.

Loading returns the request status and ImageError returns the loading error. LoadingContent/Fallback accepts custom View, nil restores the default alternative text/error; fixed Size can reserve the loading area, and the custom content should fit in this area. Retain built-in retry button after customizing failure content. In Source mode, Retry clears the current source cache and reloads it; when there is no Source, the original OnRetry callback is used. Disabling the blocking button on itself or its parent, the program Source/SetImage can still be updated.

The default shared ImageCache of 64MiB estimated capacity; Cache(nil) disables caching, and custom caches can be scoped. The cache is distinguished by source string, LRU is eliminated, the source string is included in the budget, and each pixel is conservatively billed at 8 bytes (animated images are accumulated based on the number of frames); images that exceed the budget can still be displayed but will not be retained. Concurrent requests from the same source are merged, and canceling one waiter does not affect others; the request is interrupted after all waiters are cancelled. Failure is not cached. Delete(source)/Clear clears the results and prevents old requests from being refilled, existing waiters still receive their results.

Retry/Delete is called when the content of the source address changes. Cached images are shared as read-only and pixels should not be modified. Network requests are subject to browser CORS, system network, and file permissions.

SVG and GIF animations

  • SVG: Draw vectors in real time according to the layout size, and it will be clear at any zoom; the natural size is the viewBox, and all three types of Fit are applicable. The identification is based on the content (<svg / <?xml) and has nothing to do with the extension. Scripts, external references, and CSS animations are not supported.
  • GIF animation: Loop playback is delayed for each frame, and the frames are synthesized according to the processing method. The effect is consistent with the browser; frames with a delay of 0 or 1 are played at 100ms. Turn on reduce motion (theme.ReducedMotion) or stop at first frame when disabled. Only the first frame is displayed when all frames exceed 96MB after decoding.

Disk cache

dir, _ := os.UserCacheDir()
cache := kit.NewImageCache(32 << 20).Disk(filepath.Join(dir, "myapp", "images"), 256<<20, 24*time.Hour)

Disk(directory, maxBytes, lifetime) (also requires ui/netimage) saves the raw bytes of the HTTP(S) image to disk, without having to download it again after restarting. Use the local copy directly during the validity period; after expiration, use If-None-Match / If-Modified-Since to re-verify. If the server returns 304, continue to use the local copy and refresh the validity period. Use expired copy in case of network failure or server 5xx. When the total size exceeds the upper limit, it will be eliminated based on the latest usage time. The response of Cache-Control: no-store is not written to disk; local files and data URLs are not copied. The local copy will be deleted if it fails to decode. Directory is empty or upper limit ≤ 0 Turn off disk caching. The memory layer still works according to the original rules, and the disk layer only reads when the memory misses.

SVG images use the same encoding policy as SVG icons: UTF-8 by default, with legacy encodings available through -tags keel_legacy_svg.