From a89c0dd229c2b6557b53e8c9280e5dffbbdbb97c Mon Sep 17 00:00:00 2001 From: l0ng-ai Date: Sun, 15 Nov 2026 03:33:29 +0800 Subject: [PATCH] feat(ui): small raster data-URI images as icons (#3446) Icon draws a raster data: URI (PNG, JPEG, GIF or WebP, base64, at most 64 KiB) as an image of the icon's size, so plugin view items and buttons can show avatars and status badges the plugin fetched with its net grant; the UI never loads URLs for icons, and older hosts show the file icon. Documented in the views guide. --- docs/en/plugins/guides/views.mdx | 5 +++++ docs/zh/plugins/guides/views.mdx | 2 ++ src/ui/icons.module.css | 5 +++++ src/ui/icons.test.tsx | 27 +++++++++++++++++++++++++ src/ui/icons.tsx | 34 ++++++++++++++++++++++++++++++-- 5 files changed, 71 insertions(+), 2 deletions(-) diff --git a/docs/en/plugins/guides/views.mdx b/docs/en/plugins/guides/views.mdx index be468df11..37a95d58d 100644 --- a/docs/en/plugins/guides/views.mdx +++ b/docs/en/plugins/guides/views.mdx @@ -136,6 +136,11 @@ buttons can act on what the user is editing. Toolbar buttons: `View::new(body).button(Button::new("refresh", "Refresh").icon("refresh"))` and `.status("12 items")`. +An item or button `icon` is an IDE icon name, a registered plugin icon, or a small raster image as a `data:` URI +(`data:image/png;base64,…`; PNG, JPEG, GIF or WebP, at most 64 KiB), drawn at the icon's size: an avatar or a pipeline +status badge. Fetch the image yourself (a `net` grant) and pass it inline; the IDE never loads URLs for an icon. Older +hosts show the generic file icon in its place. + ### Events `ViewEvent` carries `Button(id)`, `Activate(key)` (double click or Enter), `Select(key)`, diff --git a/docs/zh/plugins/guides/views.mdx b/docs/zh/plugins/guides/views.mdx index 6bf8de59c..2045bb050 100644 --- a/docs/zh/plugins/guides/views.mdx +++ b/docs/zh/plugins/guides/views.mdx @@ -126,6 +126,8 @@ register_plugin!(TodoFinder, views); 工具栏按钮:`View::new(body).button(Button::new("refresh", "Refresh").icon("refresh"))`,状态行:`.status("12 items")`。 +条目和按钮的 `icon` 可以是 IDE 图标名、已注册的插件图标,或者以 `data:` URI 给出的小尺寸位图(`data:image/png;base64,…`,支持 PNG、JPEG、GIF、WebP,最大 64 KiB),按图标尺寸绘制,适合头像或流水线状态徽章。图片由插件自己获取(需要 `net` 授权)后内联传入,IDE 不会为图标加载 URL。较旧的宿主会在该位置显示通用文件图标。 + ### 事件 `ViewEvent` 包括 `Button(id)`、`Activate(key)`(双击或回车)、`Select(key)`、`Expand(key)`、`Collapse(key)`、 diff --git a/src/ui/icons.module.css b/src/ui/icons.module.css index d85e4d045..0d2fa7220 100644 --- a/src/ui/icons.module.css +++ b/src/ui/icons.module.css @@ -3,6 +3,11 @@ display: block; } +.image { + object-fit: cover; + border-radius: var(--radius-small); +} + .mono { color: var(--icon-color, currentColor); } diff --git a/src/ui/icons.test.tsx b/src/ui/icons.test.tsx index 285ee8293..1504e622a 100644 --- a/src/ui/icons.test.tsx +++ b/src/ui/icons.test.tsx @@ -284,3 +284,30 @@ describe("fileIconName", () => { } }); }); + +describe("image icons", () => { + const png = + "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="; + + it("renders a raster data URI as an image of the icon's size", () => { + const { container } = render(); + const img = container.querySelector("img")!; + expect(img.getAttribute("src")).toBe(png); + expect([img.width, img.height]).toEqual([14, 14]); + expect(container.querySelector("svg")).toBeNull(); + }); + + it("falls back to the file icon for other URIs and oversized images", () => { + for (const name of [ + "https://example.com/avatar.png", + "data:image/svg+xml;base64,PHN2Zz48L3N2Zz4=", + `data:image/png;base64,${"A".repeat(70 * 1024)}`, + "data:image/png;base64,not base64!", + ]) { + const { container, unmount } = render(); + expect(container.querySelector("img")).toBeNull(); + expect(container.querySelector("svg")).toBeTruthy(); + unmount(); + } + }); +}); diff --git a/src/ui/icons.tsx b/src/ui/icons.tsx index ddfcc9957..a1045b59e 100644 --- a/src/ui/icons.tsx +++ b/src/ui/icons.tsx @@ -816,8 +816,19 @@ const withIds = (p: Prepared, prefix: string) => (p.hasIds ? p.html.replace(/__I // --------------------------------------------------------------------------- +/** Largest `data:` image accepted as an icon (an avatar or a status badge a plugin fetched). */ +const MAX_IMAGE_ICON = 64 * 1024; + +/** A small raster image given as a `data:` URI (PNG, JPEG, GIF, WebP), shown in place of an icon. */ +function isImageIcon(name: string): boolean { + return name.length <= MAX_IMAGE_ICON && /^data:image\/(png|jpeg|gif|webp);base64,[A-Za-z0-9+/]+=*$/.test(name); +} + export interface IconProps { - /** Icon name; unknown names render the generic file icon. `symbol-` renders a symbol node icon. */ + /** + * Icon name; unknown names render the generic file icon. `symbol-` renders a symbol node icon, + * and a raster `data:` image URI (see `isImageIcon`) renders that image. + */ name: IconName | (string & {}); size?: number; className?: string; @@ -826,7 +837,26 @@ export interface IconProps { label?: string; } -export function Icon({ name, size = 16, className, style, label }: IconProps) { +export function Icon(props: IconProps) { + return isImageIcon(props.name) ? : ; +} + +function ImageIcon({ name, size = 16, className, style, label }: IconProps) { + return ( + {label + ); +} + +function SvgIcon({ name, size = 16, className, style, label }: IconProps) { useFileIconRevision(); const uid = useId(); const path = iconPath(name);