@open-feishu-card/renderer 0.2.29 → 0.2.31

package/dist/index.cjs

@@ -671,7 +671,8 @@ function resolveImageSrc(p, ctx) {
   if (p.src) return p.src;
   if (p.url) return resolveURL(p.url) || null;
   if (p.img_url) return p.img_url;
-  if (p.imageID && ctx.options.imageBaseURL) return ctx.options.imageBaseURL + p.imageID;
+  const imageId = p.imageID || p.img_key;
+  if (imageId && ctx.options.imageBaseURL) return ctx.options.imageBaseURL + imageId;
   return null;
 }
 function resolveMediaSrc(p, kind, ctx) {
@@ -701,6 +702,7 @@ function personAvatarSrc(person, ctx) {
     const r = ctx.options.resolvePersonAvatar(person);
     if (r) return r;
   }
+  if (person.avatar_url) return person.avatar_url;
   if (!person.avatar_key) return null;
   const base = ctx.options.avatarBaseURL || PERSON_AVATAR_BASE;
   const suffix = ctx.options.avatarURLSuffix ?? PERSON_AVATAR_SUFFIX;
@@ -2017,6 +2019,55 @@ var BASE_STYLES_CSS = `/**
 }
 .universal-card-root.theme-dark .universal-card-markdown { color: #d6d6d6; }
 .universal-card-root.theme-dark .universal-card-hr { background-color: #2e2e30; }
+
+/* ---- Toast \u5BBF\u4E3B\uFF08\u5BF9\u9F50\u5BA2\u6237\u7AEF .ud__toast.ud__notice\uFF1A\u9876\u90E8\u4E0B\u62C9\u3001\u6DF1\u8272\u80F6\u56CA\uFF09 ---- */
+.universal-card-toast-host {
+  position: fixed;
+  top: 32px; /* \u5BA2\u6237\u7AEF\u7EC4\u4EF6\u914D\u7F6E toast:{top:32} */
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  z-index: 300;
+  pointer-events: none;
+}
+.universal-card-toast {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  max-width: 600px; /* \u5BA2\u6237\u7AEF .ud__toast max-width:600px */
+  padding: 10px 16px;
+  border-radius: 8px;
+  background: rgba(31, 35, 41, 0.92); /* N900 \u6DF1\u8272\u534A\u900F\u660E\uFF0C\u767D\u5B57 */
+  color: #fff;
+  font-size: 14px;
+  line-height: 1.5;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.16);
+  margin-bottom: 16px; /* \u5BA2\u6237\u7AEF .ud__toast margin-bottom:16px */
+  animation: universal-card-toast-in 0.3s cubic-bezier(0.2, 0, 0, 1);
+}
+.universal-card-toast--leave {
+  animation: universal-card-toast-out 0.3s cubic-bezier(0.2, 0, 0, 1) forwards;
+}
+.universal-card-toast__icon {
+  flex: none;
+  display: inline-flex;
+}
+.universal-card-toast__text {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  word-break: break-word;
+}
+@keyframes universal-card-toast-in {
+  from { opacity: 0; transform: translateY(-100%); }
+  to { opacity: 1; transform: translateY(0); }
+}
+@keyframes universal-card-toast-out {
+  from { opacity: 1; transform: translateY(0); }
+  to { opacity: 0; transform: translateY(-100%); margin-bottom: 0; }
+}
 `;
 
 // src/icon-font.ts
@@ -6816,6 +6867,60 @@ function feishuCardStyleTag() {
   return `<style data-feishu-card>${ALL_CSS}</style>`;
 }
 
+// src/toast.ts
+var DEFAULT_SHOW_TIME = 2e3;
+var TYPE_ICON = {
+  success: '<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><circle cx="8" cy="8" r="7" fill="#34c724"/><path d="M4.5 8.2l2.2 2.2 4.8-4.8" fill="none" stroke="#fff" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></svg>',
+  info: '<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><circle cx="8" cy="8" r="7" fill="#3370ff"/><circle cx="8" cy="4.6" r="1" fill="#fff"/><rect x="7.2" y="7" width="1.6" height="4.2" rx="0.8" fill="#fff"/></svg>',
+  warning: '<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><circle cx="8" cy="8" r="7" fill="#fad355"/><rect x="7.2" y="3.8" width="1.6" height="4.6" rx="0.8" fill="#1f2329"/><circle cx="8" cy="11.8" r="1" fill="#1f2329"/></svg>',
+  error: '<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><circle cx="8" cy="8" r="7" fill="#f54a45"/><path d="M5.6 5.6l4.8 4.8M10.4 5.6l-4.8 4.8" stroke="#fff" stroke-width="1.6" stroke-linecap="round"/></svg>'
+};
+function escapeHTML(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderToastHTML(type, opts) {
+  const maxLines = opts.maxLines ?? 1;
+  const styleAttr = maxLines > 1 ? ` style="-webkit-line-clamp:${maxLines};"` : "";
+  return `<div class="universal-card-toast universal-card-toast--${type}" role="status" aria-live="polite"><span class="universal-card-toast__icon">${TYPE_ICON[type]}</span><span class="universal-card-toast__text"${styleAttr}>${escapeHTML(opts.content)}</span></div>`;
+}
+function createToastHost(container) {
+  const hostEl = typeof document === "undefined" ? null : container ?? document.body;
+  const ensureHost = () => {
+    if (!hostEl) return null;
+    let el = hostEl.querySelector(".universal-card-toast-host");
+    if (!el) {
+      el = document.createElement("div");
+      el.className = "universal-card-toast-host";
+      hostEl.appendChild(el);
+    }
+    return el;
+  };
+  const push = (type) => (opts) => {
+    const host = ensureHost();
+    if (!host || typeof document === "undefined") return;
+    const wrap = document.createElement("div");
+    wrap.style.cssText = "display:contents";
+    wrap.innerHTML = renderToastHTML(type, opts);
+    const toastEl = wrap.firstElementChild;
+    host.appendChild(toastEl);
+    const showTime = opts.showTime ?? DEFAULT_SHOW_TIME;
+    setTimeout(() => {
+      toastEl.classList.add("universal-card-toast--leave");
+      toastEl.addEventListener("animationend", () => toastEl.remove(), { once: true });
+      setTimeout(() => toastEl.remove(), 400);
+    }, showTime);
+  };
+  return {
+    success: push("success"),
+    info: push("info"),
+    warning: push("warning"),
+    error: push("error"),
+    destroy: () => {
+      hostEl?.querySelectorAll(".universal-card-toast-host .universal-card-toast").forEach((el) => el.remove());
+    }
+  };
+}
+
 // src/remote.ts
 var DEFAULT_API_BASE = "https://open.feishu.cn/open-apis/im/v1";
 function getFetch(options) {
@@ -7072,6 +7177,7 @@ exports.HEADER_BG_LIGHT = HEADER_BG_LIGHT;
 exports.ICON_CODEPOINTS = ICON_CODEPOINTS;
 exports.ICON_FONT_CSS = ICON_FONT_CSS;
 exports.arrayBufferToBase64 = arrayBufferToBase64;
+exports.createToastHost = createToastHost;
 exports.feishuAudioHydrateJs = feishuAudioHydrateJs;
 exports.feishuAudioHydrateScript = feishuAudioHydrateScript;
 exports.feishuCardStyleTag = feishuCardStyleTag;
@@ -7095,3 +7201,4 @@ exports.renderCardToStringAsync = renderCardToStringAsync;
 exports.renderDsl = renderDsl;
 exports.renderDslToString = renderDslToString;
 exports.renderFeishuChart = renderFeishuChart;
+exports.renderToastHTML = renderToastHTML;

package/dist/index.d.cts

@@ -81,6 +81,8 @@ interface ElementProperty {
     hoverTips?: CardElement;
     hasBorder?: boolean;
     imageID?: string;
+    /** DSL 公开字段；dslToRaw 常原样留在 property（未改名为 imageID） */
+    img_key?: string;
     origin_key?: string;
     src?: string;
     url?: string | LinkURL;
@@ -291,7 +293,7 @@ interface RenderOptions {
     /** 音视频地址前缀：最终 src = mediaBaseURL + fileID */
     mediaBaseURL?: string;
     /**
-     * 人员表（open_id -> { content 姓名, avatar_key 头像 }）。
+     * 人员表（open_id -> { content 姓名, avatar_key / avatar_url 头像 }）。
      * person_v1 / person_list 元素只带 ID，姓名/头像在此反查。
      * 异步渲染（renderCardToStringAsync）会自动从 json_attachment.persons 填入；
      * 同步渲染若想出名字/头像，需手动传入。缺省时人员降级为固定头像 +「赵天雄」。
@@ -326,7 +328,8 @@ interface RenderOptions {
  * 人员信息：person_v1 / person_list / at 元素只带 ID，姓名与头像 key 在这里。
  * 取自飞书消息 content 的 json_attachment.persons（按 open_id「ou_...」索引）；
  * fetchCardMessage 还会把信封 mentions 与 at_users 合并进来（含 @_user_N 别名键）。
- * avatar_key 是公开可访问的头像图 key（无需鉴权，见 PERSON_AVATAR_BASE）。
+ * avatar_key 是公开可访问的头像图 key（无需鉴权，见 PERSON_AVATAR_BASE）；
+ * 本地预览也可用 avatar_url（含 data URI）直接给头像地址。
  */
 interface PersonInfo {
     person_id?: string;
@@ -335,6 +338,11 @@ interface PersonInfo {
     type?: number;
     /** 头像图 key（形如 v3_00te_...），拼 avatarBaseURL 取图 */
     avatar_key?: string;
+    /**
+     * 直接可用的头像 URL（含 data URI）。
+     * 本地预览虚拟用户没有飞书 avatar_key 时用这个；优先级低于 resolvePersonAvatar，高于 avatar_key。
+     */
+    avatar_url?: string;
 }
 /**
  * 消息信封上的 @ 提及（data.items[0].mentions），不在 body.content 内。
@@ -606,6 +614,45 @@ declare function feishuAudioHydrateJs(): string;
  */
 declare const CHART_PALETTE: string[];
 
+/**
+ * Toast 宿主（对齐飞书客户端 kernel.toast）。
+ *
+ * 事实依据（feishu-card-extract，pcsdk 7.72.0）：
+ * - 卡片 action 请求响应里带 `toast: { code, content, ... }`（如复制成功、表单校验失败、
+ *   错误码提示），Kernel 收到后调 `options.toast.success/info/warning/error` 弹出。
+ * - 调用形态：`{ type: "TOAST_SUCCESS", content, showTime: 2e3, maxLines: 1 }`。
+ * - DOM 为 `.ud__toast.ud__notice`：顶部下拉动画（translateY(-100%)→0）、
+ *   max-width:600px、box-shadow、margin-bottom:16px、top:32px。
+ *
+ * renderer 是 SSR 字符串渲染器，此处提供浏览器侧 toast 宿主：预览交互里模拟
+ * action 响应（如按钮点击回调）时调用对应方法，视觉与客户端一致。
+ */
+type ToastType = 'success' | 'info' | 'warning' | 'error';
+interface ToastOptions {
+    /** toast 文本内容 */
+    content: string;
+    /** 显示时长 ms，默认 2000（客户端 showTime 常见值 2e3） */
+    showTime?: number;
+    /** 最大行数，超出截断省略，默认 1（客户端 maxLines:1） */
+    maxLines?: number;
+}
+interface ToastAPI {
+    success: (opts: ToastOptions) => void;
+    info: (opts: ToastOptions) => void;
+    warning: (opts: ToastOptions) => void;
+    error: (opts: ToastOptions) => void;
+    /** 清空当前所有 toast */
+    destroy: () => void;
+}
+/** 生成单个 toast 的 HTML 字符串（纯函数，SSR/测试可用） */
+declare function renderToastHTML(type: ToastType, opts: ToastOptions): string;
+/**
+ * 创建 toast 宿主（浏览器侧）。容器挂在 container（默认 document.body），
+ * fixed 顶部居中；每次调用追加一条 toast，showTime 后自动移除。
+ * Node/SSR 环境无 DOM 时返回 no-op API（不抛错），仅可用 renderToastHTML。
+ */
+declare function createToastHost(container?: HTMLElement | null): ToastAPI;
+
 /**
  * 异步渲染：用飞书 access token 自动拉取卡片图片并内联（data URI），
  * 或直接按 message_id 把整条消息拉回来再渲染。
@@ -681,4 +728,4 @@ declare function renderDslToString(dsl: unknown, options?: RenderOptions): strin
 /** 输入公开 DSL，渲染为真实 DOM 节点（浏览器）。= renderCard(dslToRaw(dsl)) */
 declare function renderDsl(dsl: unknown, options?: RenderOptions): Node;
 
-export { ALL_CSS, AUDIO_HYDRATED_ATTR, AUDIO_PAUSE_ICON_SVG, AUDIO_PLAY_ICON_SVG, type AsyncRenderOptions, type AtUserInfo, type BoxSpacing, CHART_HYDRATED_ATTR, CHART_PALETTE, CHART_SPEC_ATTR, type CardElement, type CardInput, type CardMessageInput, type ComponentFn, EMOJI_KEY_TO_NAME, EMOJI_SPRITE_CSS, type ElementProperty, type FetchedCardMessage, HEADER_BG_DARK, HEADER_BG_LIGHT, type HeaderTemplate, ICON_CODEPOINTS, ICON_FONT_CSS, type JsonAttachment, type JsonCard, type LinkURL, type ListItem, type MessageMention, type NamedColor, type PersonInfo, type RenderContext, type RenderOptions, type SizeName, type TableColumn, type TableHeaderStyle, type TextAlign, type TextAttribute, type TextStyle, type VNode, type VNodeChild, type VNodeProps, arrayBufferToBase64, feishuAudioHydrateJs, feishuAudioHydrateScript, feishuCardStyleTag, feishuChartHydrateJs, feishuChartHydrateScript, fetchCardMessage, fetchImageDataUri, getComponent, h, hydrateFeishuAudios, hydrateFeishuCharts, mergeMentionsIntoPersons, parseInline, parseMarkdown, prefetchImages, registerComponent, renderCard, renderCardAsync, renderCardToString, renderCardToStringAsync, renderDsl, renderDslToString, renderFeishuChart };
+export { ALL_CSS, AUDIO_HYDRATED_ATTR, AUDIO_PAUSE_ICON_SVG, AUDIO_PLAY_ICON_SVG, type AsyncRenderOptions, type AtUserInfo, type BoxSpacing, CHART_HYDRATED_ATTR, CHART_PALETTE, CHART_SPEC_ATTR, type CardElement, type CardInput, type CardMessageInput, type ComponentFn, EMOJI_KEY_TO_NAME, EMOJI_SPRITE_CSS, type ElementProperty, type FetchedCardMessage, HEADER_BG_DARK, HEADER_BG_LIGHT, type HeaderTemplate, ICON_CODEPOINTS, ICON_FONT_CSS, type JsonAttachment, type JsonCard, type LinkURL, type ListItem, type MessageMention, type NamedColor, type PersonInfo, type RenderContext, type RenderOptions, type SizeName, type TableColumn, type TableHeaderStyle, type TextAlign, type TextAttribute, type TextStyle, type ToastAPI, type ToastOptions, type ToastType, type VNode, type VNodeChild, type VNodeProps, arrayBufferToBase64, createToastHost, feishuAudioHydrateJs, feishuAudioHydrateScript, feishuCardStyleTag, feishuChartHydrateJs, feishuChartHydrateScript, fetchCardMessage, fetchImageDataUri, getComponent, h, hydrateFeishuAudios, hydrateFeishuCharts, mergeMentionsIntoPersons, parseInline, parseMarkdown, prefetchImages, registerComponent, renderCard, renderCardAsync, renderCardToString, renderCardToStringAsync, renderDsl, renderDslToString, renderFeishuChart, renderToastHTML };

package/dist/index.d.ts

@@ -81,6 +81,8 @@ interface ElementProperty {
     hoverTips?: CardElement;
     hasBorder?: boolean;
     imageID?: string;
+    /** DSL 公开字段；dslToRaw 常原样留在 property（未改名为 imageID） */
+    img_key?: string;
     origin_key?: string;
     src?: string;
     url?: string | LinkURL;
@@ -291,7 +293,7 @@ interface RenderOptions {
     /** 音视频地址前缀：最终 src = mediaBaseURL + fileID */
     mediaBaseURL?: string;
     /**
-     * 人员表（open_id -> { content 姓名, avatar_key 头像 }）。
+     * 人员表（open_id -> { content 姓名, avatar_key / avatar_url 头像 }）。
      * person_v1 / person_list 元素只带 ID，姓名/头像在此反查。
      * 异步渲染（renderCardToStringAsync）会自动从 json_attachment.persons 填入；
      * 同步渲染若想出名字/头像，需手动传入。缺省时人员降级为固定头像 +「赵天雄」。
@@ -326,7 +328,8 @@ interface RenderOptions {
  * 人员信息：person_v1 / person_list / at 元素只带 ID，姓名与头像 key 在这里。
  * 取自飞书消息 content 的 json_attachment.persons（按 open_id「ou_...」索引）；
  * fetchCardMessage 还会把信封 mentions 与 at_users 合并进来（含 @_user_N 别名键）。
- * avatar_key 是公开可访问的头像图 key（无需鉴权，见 PERSON_AVATAR_BASE）。
+ * avatar_key 是公开可访问的头像图 key（无需鉴权，见 PERSON_AVATAR_BASE）；
+ * 本地预览也可用 avatar_url（含 data URI）直接给头像地址。
  */
 interface PersonInfo {
     person_id?: string;
@@ -335,6 +338,11 @@ interface PersonInfo {
     type?: number;
     /** 头像图 key（形如 v3_00te_...），拼 avatarBaseURL 取图 */
     avatar_key?: string;
+    /**
+     * 直接可用的头像 URL（含 data URI）。
+     * 本地预览虚拟用户没有飞书 avatar_key 时用这个；优先级低于 resolvePersonAvatar，高于 avatar_key。
+     */
+    avatar_url?: string;
 }
 /**
  * 消息信封上的 @ 提及（data.items[0].mentions），不在 body.content 内。
@@ -606,6 +614,45 @@ declare function feishuAudioHydrateJs(): string;
  */
 declare const CHART_PALETTE: string[];
 
+/**
+ * Toast 宿主（对齐飞书客户端 kernel.toast）。
+ *
+ * 事实依据（feishu-card-extract，pcsdk 7.72.0）：
+ * - 卡片 action 请求响应里带 `toast: { code, content, ... }`（如复制成功、表单校验失败、
+ *   错误码提示），Kernel 收到后调 `options.toast.success/info/warning/error` 弹出。
+ * - 调用形态：`{ type: "TOAST_SUCCESS", content, showTime: 2e3, maxLines: 1 }`。
+ * - DOM 为 `.ud__toast.ud__notice`：顶部下拉动画（translateY(-100%)→0）、
+ *   max-width:600px、box-shadow、margin-bottom:16px、top:32px。
+ *
+ * renderer 是 SSR 字符串渲染器，此处提供浏览器侧 toast 宿主：预览交互里模拟
+ * action 响应（如按钮点击回调）时调用对应方法，视觉与客户端一致。
+ */
+type ToastType = 'success' | 'info' | 'warning' | 'error';
+interface ToastOptions {
+    /** toast 文本内容 */
+    content: string;
+    /** 显示时长 ms，默认 2000（客户端 showTime 常见值 2e3） */
+    showTime?: number;
+    /** 最大行数，超出截断省略，默认 1（客户端 maxLines:1） */
+    maxLines?: number;
+}
+interface ToastAPI {
+    success: (opts: ToastOptions) => void;
+    info: (opts: ToastOptions) => void;
+    warning: (opts: ToastOptions) => void;
+    error: (opts: ToastOptions) => void;
+    /** 清空当前所有 toast */
+    destroy: () => void;
+}
+/** 生成单个 toast 的 HTML 字符串（纯函数，SSR/测试可用） */
+declare function renderToastHTML(type: ToastType, opts: ToastOptions): string;
+/**
+ * 创建 toast 宿主（浏览器侧）。容器挂在 container（默认 document.body），
+ * fixed 顶部居中；每次调用追加一条 toast，showTime 后自动移除。
+ * Node/SSR 环境无 DOM 时返回 no-op API（不抛错），仅可用 renderToastHTML。
+ */
+declare function createToastHost(container?: HTMLElement | null): ToastAPI;
+
 /**
  * 异步渲染：用飞书 access token 自动拉取卡片图片并内联（data URI），
  * 或直接按 message_id 把整条消息拉回来再渲染。
@@ -681,4 +728,4 @@ declare function renderDslToString(dsl: unknown, options?: RenderOptions): strin
 /** 输入公开 DSL，渲染为真实 DOM 节点（浏览器）。= renderCard(dslToRaw(dsl)) */
 declare function renderDsl(dsl: unknown, options?: RenderOptions): Node;
 
-export { ALL_CSS, AUDIO_HYDRATED_ATTR, AUDIO_PAUSE_ICON_SVG, AUDIO_PLAY_ICON_SVG, type AsyncRenderOptions, type AtUserInfo, type BoxSpacing, CHART_HYDRATED_ATTR, CHART_PALETTE, CHART_SPEC_ATTR, type CardElement, type CardInput, type CardMessageInput, type ComponentFn, EMOJI_KEY_TO_NAME, EMOJI_SPRITE_CSS, type ElementProperty, type FetchedCardMessage, HEADER_BG_DARK, HEADER_BG_LIGHT, type HeaderTemplate, ICON_CODEPOINTS, ICON_FONT_CSS, type JsonAttachment, type JsonCard, type LinkURL, type ListItem, type MessageMention, type NamedColor, type PersonInfo, type RenderContext, type RenderOptions, type SizeName, type TableColumn, type TableHeaderStyle, type TextAlign, type TextAttribute, type TextStyle, type VNode, type VNodeChild, type VNodeProps, arrayBufferToBase64, feishuAudioHydrateJs, feishuAudioHydrateScript, feishuCardStyleTag, feishuChartHydrateJs, feishuChartHydrateScript, fetchCardMessage, fetchImageDataUri, getComponent, h, hydrateFeishuAudios, hydrateFeishuCharts, mergeMentionsIntoPersons, parseInline, parseMarkdown, prefetchImages, registerComponent, renderCard, renderCardAsync, renderCardToString, renderCardToStringAsync, renderDsl, renderDslToString, renderFeishuChart };
+export { ALL_CSS, AUDIO_HYDRATED_ATTR, AUDIO_PAUSE_ICON_SVG, AUDIO_PLAY_ICON_SVG, type AsyncRenderOptions, type AtUserInfo, type BoxSpacing, CHART_HYDRATED_ATTR, CHART_PALETTE, CHART_SPEC_ATTR, type CardElement, type CardInput, type CardMessageInput, type ComponentFn, EMOJI_KEY_TO_NAME, EMOJI_SPRITE_CSS, type ElementProperty, type FetchedCardMessage, HEADER_BG_DARK, HEADER_BG_LIGHT, type HeaderTemplate, ICON_CODEPOINTS, ICON_FONT_CSS, type JsonAttachment, type JsonCard, type LinkURL, type ListItem, type MessageMention, type NamedColor, type PersonInfo, type RenderContext, type RenderOptions, type SizeName, type TableColumn, type TableHeaderStyle, type TextAlign, type TextAttribute, type TextStyle, type ToastAPI, type ToastOptions, type ToastType, type VNode, type VNodeChild, type VNodeProps, arrayBufferToBase64, createToastHost, feishuAudioHydrateJs, feishuAudioHydrateScript, feishuCardStyleTag, feishuChartHydrateJs, feishuChartHydrateScript, fetchCardMessage, fetchImageDataUri, getComponent, h, hydrateFeishuAudios, hydrateFeishuCharts, mergeMentionsIntoPersons, parseInline, parseMarkdown, prefetchImages, registerComponent, renderCard, renderCardAsync, renderCardToString, renderCardToStringAsync, renderDsl, renderDslToString, renderFeishuChart, renderToastHTML };

package/dist/index.js

@@ -670,7 +670,8 @@ function resolveImageSrc(p, ctx) {
   if (p.src) return p.src;
   if (p.url) return resolveURL(p.url) || null;
   if (p.img_url) return p.img_url;
-  if (p.imageID && ctx.options.imageBaseURL) return ctx.options.imageBaseURL + p.imageID;
+  const imageId = p.imageID || p.img_key;
+  if (imageId && ctx.options.imageBaseURL) return ctx.options.imageBaseURL + imageId;
   return null;
 }
 function resolveMediaSrc(p, kind, ctx) {
@@ -700,6 +701,7 @@ function personAvatarSrc(person, ctx) {
     const r = ctx.options.resolvePersonAvatar(person);
     if (r) return r;
   }
+  if (person.avatar_url) return person.avatar_url;
   if (!person.avatar_key) return null;
   const base = ctx.options.avatarBaseURL || PERSON_AVATAR_BASE;
   const suffix = ctx.options.avatarURLSuffix ?? PERSON_AVATAR_SUFFIX;
@@ -2016,6 +2018,55 @@ var BASE_STYLES_CSS = `/**
 }
 .universal-card-root.theme-dark .universal-card-markdown { color: #d6d6d6; }
 .universal-card-root.theme-dark .universal-card-hr { background-color: #2e2e30; }
+
+/* ---- Toast \u5BBF\u4E3B\uFF08\u5BF9\u9F50\u5BA2\u6237\u7AEF .ud__toast.ud__notice\uFF1A\u9876\u90E8\u4E0B\u62C9\u3001\u6DF1\u8272\u80F6\u56CA\uFF09 ---- */
+.universal-card-toast-host {
+  position: fixed;
+  top: 32px; /* \u5BA2\u6237\u7AEF\u7EC4\u4EF6\u914D\u7F6E toast:{top:32} */
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  z-index: 300;
+  pointer-events: none;
+}
+.universal-card-toast {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  max-width: 600px; /* \u5BA2\u6237\u7AEF .ud__toast max-width:600px */
+  padding: 10px 16px;
+  border-radius: 8px;
+  background: rgba(31, 35, 41, 0.92); /* N900 \u6DF1\u8272\u534A\u900F\u660E\uFF0C\u767D\u5B57 */
+  color: #fff;
+  font-size: 14px;
+  line-height: 1.5;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.16);
+  margin-bottom: 16px; /* \u5BA2\u6237\u7AEF .ud__toast margin-bottom:16px */
+  animation: universal-card-toast-in 0.3s cubic-bezier(0.2, 0, 0, 1);
+}
+.universal-card-toast--leave {
+  animation: universal-card-toast-out 0.3s cubic-bezier(0.2, 0, 0, 1) forwards;
+}
+.universal-card-toast__icon {
+  flex: none;
+  display: inline-flex;
+}
+.universal-card-toast__text {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  word-break: break-word;
+}
+@keyframes universal-card-toast-in {
+  from { opacity: 0; transform: translateY(-100%); }
+  to { opacity: 1; transform: translateY(0); }
+}
+@keyframes universal-card-toast-out {
+  from { opacity: 1; transform: translateY(0); }
+  to { opacity: 0; transform: translateY(-100%); margin-bottom: 0; }
+}
 `;
 
 // src/icon-font.ts
@@ -6815,6 +6866,60 @@ function feishuCardStyleTag() {
   return `<style data-feishu-card>${ALL_CSS}</style>`;
 }
 
+// src/toast.ts
+var DEFAULT_SHOW_TIME = 2e3;
+var TYPE_ICON = {
+  success: '<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><circle cx="8" cy="8" r="7" fill="#34c724"/><path d="M4.5 8.2l2.2 2.2 4.8-4.8" fill="none" stroke="#fff" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></svg>',
+  info: '<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><circle cx="8" cy="8" r="7" fill="#3370ff"/><circle cx="8" cy="4.6" r="1" fill="#fff"/><rect x="7.2" y="7" width="1.6" height="4.2" rx="0.8" fill="#fff"/></svg>',
+  warning: '<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><circle cx="8" cy="8" r="7" fill="#fad355"/><rect x="7.2" y="3.8" width="1.6" height="4.6" rx="0.8" fill="#1f2329"/><circle cx="8" cy="11.8" r="1" fill="#1f2329"/></svg>',
+  error: '<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><circle cx="8" cy="8" r="7" fill="#f54a45"/><path d="M5.6 5.6l4.8 4.8M10.4 5.6l-4.8 4.8" stroke="#fff" stroke-width="1.6" stroke-linecap="round"/></svg>'
+};
+function escapeHTML(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderToastHTML(type, opts) {
+  const maxLines = opts.maxLines ?? 1;
+  const styleAttr = maxLines > 1 ? ` style="-webkit-line-clamp:${maxLines};"` : "";
+  return `<div class="universal-card-toast universal-card-toast--${type}" role="status" aria-live="polite"><span class="universal-card-toast__icon">${TYPE_ICON[type]}</span><span class="universal-card-toast__text"${styleAttr}>${escapeHTML(opts.content)}</span></div>`;
+}
+function createToastHost(container) {
+  const hostEl = typeof document === "undefined" ? null : container ?? document.body;
+  const ensureHost = () => {
+    if (!hostEl) return null;
+    let el = hostEl.querySelector(".universal-card-toast-host");
+    if (!el) {
+      el = document.createElement("div");
+      el.className = "universal-card-toast-host";
+      hostEl.appendChild(el);
+    }
+    return el;
+  };
+  const push = (type) => (opts) => {
+    const host = ensureHost();
+    if (!host || typeof document === "undefined") return;
+    const wrap = document.createElement("div");
+    wrap.style.cssText = "display:contents";
+    wrap.innerHTML = renderToastHTML(type, opts);
+    const toastEl = wrap.firstElementChild;
+    host.appendChild(toastEl);
+    const showTime = opts.showTime ?? DEFAULT_SHOW_TIME;
+    setTimeout(() => {
+      toastEl.classList.add("universal-card-toast--leave");
+      toastEl.addEventListener("animationend", () => toastEl.remove(), { once: true });
+      setTimeout(() => toastEl.remove(), 400);
+    }, showTime);
+  };
+  return {
+    success: push("success"),
+    info: push("info"),
+    warning: push("warning"),
+    error: push("error"),
+    destroy: () => {
+      hostEl?.querySelectorAll(".universal-card-toast-host .universal-card-toast").forEach((el) => el.remove());
+    }
+  };
+}
+
 // src/remote.ts
 var DEFAULT_API_BASE = "https://open.feishu.cn/open-apis/im/v1";
 function getFetch(options) {
@@ -7053,4 +7158,4 @@ function renderDsl(dsl, options = {}) {
   return renderCard(dslToRaw(dsl), options);
 }
 
-export { ALL_CSS, AUDIO_HYDRATED_ATTR, AUDIO_PAUSE_ICON_SVG, AUDIO_PLAY_ICON_SVG, CHART_HYDRATED_ATTR, CHART_PALETTE, CHART_SPEC_ATTR, EMOJI_KEY_TO_NAME, EMOJI_SPRITE_CSS, HEADER_BG_DARK, HEADER_BG_LIGHT, ICON_CODEPOINTS, ICON_FONT_CSS, arrayBufferToBase64, feishuAudioHydrateJs, feishuAudioHydrateScript, feishuCardStyleTag, feishuChartHydrateJs, feishuChartHydrateScript, fetchCardMessage, fetchImageDataUri, getComponent, h, hydrateFeishuAudios, hydrateFeishuCharts, mergeMentionsIntoPersons, parseInline, parseMarkdown, prefetchImages, registerComponent, renderCard, renderCardAsync, renderCardToString, renderCardToStringAsync, renderDsl, renderDslToString, renderFeishuChart };
+export { ALL_CSS, AUDIO_HYDRATED_ATTR, AUDIO_PAUSE_ICON_SVG, AUDIO_PLAY_ICON_SVG, CHART_HYDRATED_ATTR, CHART_PALETTE, CHART_SPEC_ATTR, EMOJI_KEY_TO_NAME, EMOJI_SPRITE_CSS, HEADER_BG_DARK, HEADER_BG_LIGHT, ICON_CODEPOINTS, ICON_FONT_CSS, arrayBufferToBase64, createToastHost, feishuAudioHydrateJs, feishuAudioHydrateScript, feishuCardStyleTag, feishuChartHydrateJs, feishuChartHydrateScript, fetchCardMessage, fetchImageDataUri, getComponent, h, hydrateFeishuAudios, hydrateFeishuCharts, mergeMentionsIntoPersons, parseInline, parseMarkdown, prefetchImages, registerComponent, renderCard, renderCardAsync, renderCardToString, renderCardToStringAsync, renderDsl, renderDslToString, renderFeishuChart, renderToastHTML };

package/dist/styles.css

@@ -1049,3 +1049,52 @@
 }
 .universal-card-root.theme-dark .universal-card-markdown { color: #d6d6d6; }
 .universal-card-root.theme-dark .universal-card-hr { background-color: #2e2e30; }
+
+/* ---- Toast 宿主（对齐客户端 .ud__toast.ud__notice：顶部下拉、深色胶囊） ---- */
+.universal-card-toast-host {
+  position: fixed;
+  top: 32px; /* 客户端组件配置 toast:{top:32} */
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  z-index: 300;
+  pointer-events: none;
+}
+.universal-card-toast {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  max-width: 600px; /* 客户端 .ud__toast max-width:600px */
+  padding: 10px 16px;
+  border-radius: 8px;
+  background: rgba(31, 35, 41, 0.92); /* N900 深色半透明，白字 */
+  color: #fff;
+  font-size: 14px;
+  line-height: 1.5;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.16);
+  margin-bottom: 16px; /* 客户端 .ud__toast margin-bottom:16px */
+  animation: universal-card-toast-in 0.3s cubic-bezier(0.2, 0, 0, 1);
+}
+.universal-card-toast--leave {
+  animation: universal-card-toast-out 0.3s cubic-bezier(0.2, 0, 0, 1) forwards;
+}
+.universal-card-toast__icon {
+  flex: none;
+  display: inline-flex;
+}
+.universal-card-toast__text {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  word-break: break-word;
+}
+@keyframes universal-card-toast-in {
+  from { opacity: 0; transform: translateY(-100%); }
+  to { opacity: 1; transform: translateY(0); }
+}
+@keyframes universal-card-toast-out {
+  from { opacity: 1; transform: translateY(0); }
+  to { opacity: 0; transform: translateY(-100%); margin-bottom: 0; }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-feishu-card/renderer",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "description": "零框架依赖的飞书卡片渲染引擎：Web / DOM / SSR，输入 RAW 或公开 DSL，输出真实 DOM 或 HTML 字符串",
   "type": "module",
   "main": "./dist/index.cjs",