@rxdrag/website-lib-core 0.0.122 → 0.0.124

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxdrag/website-lib-core",
-  "version": "0.0.122",
+  "version": "0.0.124",
   "type": "module",
   "exports": {
     ".": "./index.ts"
@@ -34,10 +34,10 @@
     "hls.js": "^1.6.13",
     "lodash-es": "^4.17.21",
     "@rxdrag/entify-lib": "0.0.24",
-    "@rxdrag/rxcms-models": "0.3.98"
+    "@rxdrag/rxcms-models": "0.3.105"
   },
   "peerDependencies": {
-    "astro": "^4.0.0 || ^5.0.0",
+    "astro": "^5.16.6",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },

package/src/astro/background.ts

@@ -1,33 +1,30 @@
-export type ImageMetadata = import("astro").ImageMetadata;
+import { ImageLayout, ImageMetadata } from "./image";
+
 // 背景样式类型定义，支持tailwind类
 export type ColorBackgroundConfig = {
   id?: string;
   type: "color";
   class?: string; // 颜色 ，模糊，图案等，如 "bg-blue-500", "bg-gradient-to-r from-blue-500 to-purple-600"
-  className?: string;//兼容旧的
 };
 
 export type BlurBackgroundConfig = {
   id?: string;
   type: "blur";
   class?: string; // 模糊，如 "backdrop-blur"
-  className?: string;//兼容旧的
 };
 
 export type ImageBackgroundConfig = {
   id?: string;
   type: "image";
   class?: string; // 图片，如 "bg-cover bg-center bg-no-repeat"
-  className?: string;//兼容旧的
-  //实际组件中还会传入ImageMetadata
-  src?: string; // 图片源
+  layout?: ImageLayout;
+  src?: string | ImageMetadata; // 图片源
 };
 
 export type SvgBackgroundConfig = {
   id?: string;
   type: "svg";
   class?: string; // 图案，如 "bg-dots-sm bg-gray-100"
-  className?: string;//兼容旧的
   code?: string; // SVG代码
 };
 
@@ -35,17 +32,14 @@ export type VideoBackgroundConfig = {
   id?: string;
   type: "video";
   class?: string; // 视频，如 "bg-cover bg-center bg-no-repeat"
-  className?: string;//兼容旧的
   mediaRef?: string; // 视频源
-  //实际组件中还会传入ImageMetadata
-  poster?: string; // 视频封面图源
+  poster?: string | ImageMetadata; // 视频封面图源
 };
 
 export type SplineBackgroundConfig = {
   id?: string;
   type: "spline";
   class?: string; // Spline，如 "bg-cover bg-center bg-no-repeat"
-  className?: string;//兼容旧的
   spline?: string; // Spline ID
   url?: string; // Spline 场景 URL
 };

package/src/astro/image.ts

@@ -0,0 +1,239 @@
+import type { HTMLAttributes } from "astro/types";
+import type { ImageLayout } from "astro/dist/assets/types";
+export type ImageMetadata = import("astro").ImageMetadata;
+
+export type { ImageLayout };
+
+/**
+ * 图片输出格式
+ */
+export type ImageFormat = "webp" | "avif" | "png" | "jpg" | "gif" | "svg";
+
+/**
+ * 图片在页面中的布局位置（用于优化下载尺寸）
+ */
+export type ImageSizePreset =
+  | "auto"      // 自动处理（让 layout 决定）
+  | "full"      // 全宽内容
+  | "half"      // 两栏布局（约 50%）
+  | "third"     // 三栏布局（约 33%）
+  | "quarter"   // 四栏布局（约 25%）
+  | "sidebar";  // 侧边栏内图片
+
+
+/**
+ * ============================================================
+ * 图片组件属性
+ * ============================================================
+ *
+ * 设计原则：
+ * 1. Props 只处理图片核心功能（来源、加载、优化）
+ * 2. 样式相关属性通过 Tailwind class 设置
+ *
+ * ============================================================
+ * 样式设置指南（通过 class 属性使用 Tailwind）
+ * ============================================================
+ *
+ * 【尺寸】
+ *   - 宽度：w-full, w-1/2, w-64, w-[300px]
+ *   - 高度：h-auto, h-64, h-screen, h-[200px]
+ *   - 最大宽度：max-w-md, max-w-lg, max-w-full
+ *
+ * 【宽高比】
+ *   - 正方形：aspect-square
+ *   - 视频：aspect-video (16:9)
+ *   - 自定义：aspect-[4/3], aspect-[3/2]
+ *
+ * 【填充模式】
+ *   - 裁剪填满：object-cover（推荐用于背景图、卡片图）
+ *   - 完整显示：object-contain（推荐用于 logo）
+ *   - 拉伸填满：object-fill
+ *   - 原始尺寸：object-none
+ *
+ * 【位置（配合 object-cover/contain 使用）】
+ *   - 居中：object-center（默认）
+ *   - 顶部：object-top
+ *   - 底部：object-bottom
+ *   - 左右：object-left, object-right
+ *
+ * 【圆角】
+ *   - 小：rounded-sm
+ *   - 中：rounded-md, rounded-lg
+ *   - 大：rounded-xl, rounded-2xl
+ *   - 圆形：rounded-full
+ *
+ * 【阴影】
+ *   - 小：shadow-sm
+ *   - 中：shadow, shadow-md
+ *   - 大：shadow-lg, shadow-xl
+ *
+ * 【边框】
+ *   - 细边框：border
+ *   - 边框颜色：border-gray-200, border-white
+ *
+ * 【滤镜效果】
+ *   - 灰度：grayscale
+ *   - 模糊：blur-sm, blur-md
+ *   - 亮度：brightness-50, brightness-150
+ *   - 悬停效果：hover:scale-105, hover:brightness-110
+ *
+ * 使用示例：
+ * ```astro
+ * <Image
+ *   src="/hero.jpg"
+ *   alt="英雄图"
+ *   class="w-full aspect-video object-cover rounded-lg shadow-lg"
+ * />
+ * ```
+ */
+export interface ImageProps extends Omit<HTMLAttributes<"img">, "src" | "width" | "height"> {
+  /**
+   * 图片来源
+   * - 本地图片：使用 import 导入
+   * - 远程图片：使用完整 URL
+   * - CMS 图片：使用媒体库路径
+   */
+  src: string | ImageMetadata;
+
+  /**
+   * 图片宽度
+   * - 本地图片可自动推断，可不填
+   * - 本地图片使用 layout="fixed" 时必须填写
+   * - 远程图片不需要填写，用 Tailwind 样式代替
+   */
+  width?: number;
+
+  /**
+   * 图片宽度列表
+   * - Astro Image/Picture 的 widths 参数
+   */
+  widths?: number[];
+
+  /**
+   * 图片高度
+   * - 本地图片可自动推断，可不填
+   * - 本地图片使用 layout="fixed" 时必须填写
+   * - 远程图片不需要填写，用 Tailwind 样式代替
+   */
+  height?: number;
+
+  /**
+   * 图片描述（用于无障碍访问和 SEO）
+   * - 内容图片：填写描述文字
+   * - 装饰性图片：设为空字符串 alt=""，屏幕阅读器会忽略
+   */
+  alt?: string;
+
+  /**
+   * 响应式布局模式（Astro 原生值）
+   * - responsive: 跟随容器宽度，最大不超过原图尺寸（推荐）
+   * - full-width: 填满父容器（100% 宽度）
+   * - fixed: 固定尺寸，不响应屏幕变化
+   * - none: 不使用 Astro 响应式处理
+   */
+  layout?: ImageLayout;
+
+  /**
+   * 输出格式（用于 Picture 组件）
+   * - 浏览器会自动选择最优格式
+   * - 推荐：['avif', 'webp'] 获得最佳压缩
+   * @example ['avif', 'webp']
+   */
+  formats?: ImageFormat[];
+
+  /**
+   * 加载策略
+   * - lazy: 延迟加载，首屏外的图片使用
+   * - eager: 立即加载，首屏图片使用
+   * @default "lazy"
+   */
+  loading?: "lazy" | "eager";
+
+  /**
+   * 是否为重要图片（LCP 优化，Astro 原生支持）
+   * - 设为 true 会自动设置 loading="eager" 和 fetchpriority="high"
+   * - 仅对首屏最大的图片使用
+   */
+  priority?: boolean;
+
+  /**
+   * 图片质量（1-100）
+   * - 数值越高质量越好，文件越大
+   * - 推荐 80-90 平衡质量和大小
+   * 备注：这个可以先不提供可视化支持，小白理解不了
+   * @default 80
+   */
+  quality?: number;
+
+  /**
+   * sizes 属性（兼容 Astro Image 原生）
+   * - 用于响应式图片选择
+   * - 传递原生 CSS sizes 字符串
+   * @example "(max-width: 768px) 100vw, 50vw"
+   */
+  sizes?: string;
+
+  /**
+   * 图片在页面中的布局位置预设（用于优化下载尺寸）
+   * - auto: 自动处理（推荐，让 layout 决定）
+   * - full: 全宽内容
+   * - half: 两栏布局
+   * - third: 三栏布局
+   * - quarter: 四栏布局
+   * - sidebar: 侧边栏内图片
+   * 会自动映射为 sizes 属性值
+   * @default "auto"
+   */
+  sizeHint?: ImageSizePreset;
+
+  /**
+   * 样式类（使用 Tailwind）
+   *
+   * 【避免布局偏移】
+   *   设置宽高比可预留空间，防止图片加载时页面跳动：
+   *   - aspect-square（1:1）
+   *   - aspect-video（16:9）
+   *   - aspect-[4/3]、aspect-[3/2] 等自定义比例
+   *
+   * 【常用宽高比】
+   *   - 1:1 - 正方形，电商产品、头像、社交卡片
+   *   - 4:3 - 传统屏幕，博客卡片、新闻缩略图
+   *   - 3:2 - 单反照片，摄影作品、画廊
+   *   - 16:9 - 宽屏视频，英雄图、视频封面
+   *   - 21:9 - 超宽屏，电影海报、横幅广告
+   *   - 4:5 - 竖版，Instagram、社交媒体
+   *   - 9:16 - 竖屏视频，Stories、短视频封面
+   *
+   * 【快捷模板】
+   *   - 英雄图：w-full aspect-video object-cover
+   *   - 博客卡片：w-full aspect-[16/9] object-cover rounded-lg
+   *   - 新闻卡片：w-full aspect-[4/3] object-cover rounded-lg
+   *   - 电商卡片：w-full aspect-square object-cover rounded-lg
+   *   - 社交卡片：w-full aspect-[4/5] object-cover rounded-lg
+   *   - 缩略图：w-32 aspect-square object-cover rounded
+   *   - 头像（小）：w-8 h-8 object-cover rounded-full
+   *   - 头像（中）：w-12 h-12 object-cover rounded-full
+   *   - 头像（大）：w-16 h-16 object-cover rounded-full
+   *   - Logo：h-8 w-auto object-contain
+   *   - 产品图：w-full aspect-square object-contain bg-white
+   *   - 背景图：w-full h-full object-cover absolute inset-0
+   *   - 画廊图：w-full aspect-[3/2] object-cover hover:scale-105 transition
+   *   - 横幅广告：w-full aspect-[21/9] object-cover
+   *
+   * 【常用样式】
+   *   - 尺寸：w-full, w-1/2, w-32, h-64, max-w-lg, max-w-screen-xl
+   *   - 填充：object-cover（裁剪填满）, object-contain（完整显示）, object-fill（拉伸）
+   *   - 位置：object-center, object-top, object-bottom, object-left, object-right
+   *   - 圆角：rounded-sm, rounded, rounded-md, rounded-lg, rounded-xl, rounded-full
+   *   - 阴影：shadow-sm, shadow, shadow-md, shadow-lg, shadow-xl
+   *   - 边框：border, border-2, border-white, border-gray-200
+   *   - 滤镜：grayscale, blur-sm, brightness-75, contrast-125
+   *   - 过渡：transition, hover:scale-105, hover:brightness-110, hover:shadow-xl
+   *
+   * @example "w-full aspect-video object-cover rounded-lg"
+   */
+  class?: string;
+  //兼容react组件
+  className?: string;
+}
+

package/src/astro/index.ts

@@ -3,5 +3,6 @@ export * from "./grid";
 export * from "./section";
 export * from "./background";
 export * from "./media";
+export * from "./image";
 
 

package/src/astro/media.ts

@@ -52,7 +52,7 @@ export const DEFAULT_POST_THUMBNAIL_IMAGE_SIZE: ImageResize = {
 };
 
 //TODO：以后还要加transform参数
-export type ImageProps = {
+export type MediaImageProps = {
   alt?: string;
   className?: string;
   src?: string;