Product Tag 組件使用指南

⚠️ 內部使用套件 - 此套件僅供 Astral Web 內部使用，未經授權不得用於其他用途。

概覽

Product Tag 產品標籤模組為 Nuxt 應用程式提供完整的產品標籤顯示功能，支援文字標籤、圖片標籤、多種樣式配置、時間過濾等功能。模組設計簡潔易用，提供自動註冊組件和 composable，並提供完整的 TypeScript 型別支援。

安裝與設定

1. 安裝套件

在 apps/web 安裝

yarn add @astralweb/nova-product-tag

2. 註冊模組

在 nuxt.config.ts 中註冊模組

// apps/web/nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxtjs/tailwindcss',
    '@astralweb/nova-product-tag',
  ],
});

⚠️ 注意：Product Tag 模組需要 @nuxtjs/tailwindcss 模組，請確保已安裝。

3. CustomQuery 新增欄位

// apps/web/api/magento/product/customQuery.ts
import { productTagFields } from '@astralweb/nova-product-tag/api';

export const productListCustomQuery: Record<string, any> = {
  products: 'product-list-custom-query',
  metadata: {
    fields: `
      total_count
      page_info {
        current_page
        page_size
        total_pages
      }
      // ... 其他欄位
      items {
        uid
        sku
        name
        stock_status
        // ... 其他基本欄位
        ${productTagFields}
      }
    `,
  },
};

export const productDrawerCustomQuery: Record<string, any> = {
  products: 'product-drawer-custom-query',
  metadata: {
    fields: `
      items {
        uid
        sku
        name
        // ... 其他基本欄位
        ${productTagFields}
        ... on ConfigurableProduct {
          configurable_options {
            attribute_code
            label
            // ... 其他選項設定
          }
        }
        // ... 更多產品類型
      }
    `,
  },
};

export const productSliderCustomQuery: Record<string, any> = {
  products: 'product-slider-custom-query',
  metadata: {
    fields: `
      items {
        uid
        sku
        name
        // ... 其他基本欄位
        ${productTagFields}
      }
    `,
  },
};

// apps/web/api/magento/products/customQuery.ts
import { productTagFields } from '@astralweb/nova-product-tag/api';

export const productCustomQuery: Record<string, any> = {
  products: 'product-custom-query',
  metadata: {
    fields: `
      items {
        uid
        sku
        name
        // ... 其他基本欄位
        ${productTagFields}
        ... on ConfigurableProduct {
          configurable_options {
            attribute_code
            label
            // ... 其他選項設定
          }
        }
        // ... 更多產品類型
      }
    `,
  },
};

4. 輸出 productTags 資料

// composables/useProductData/useProductData.ts
export const useProductData = (product: Ref<ExtendProductInterface>) => {
  const productTags = computed(() => product.value.product_tags ?? []);

  return {
    // ... 其他產品相關資料
    productTags,
  };
};

組件基本使用

在產品卡片中顯示標籤

<template>
  <NovaProductTag :product-tags="productTags" />
</template>

<script setup lang="ts">
const { productTags } = useProductData(product);
</script>

自定義樣式

<template>
  <div class="relative">
    <p>目前有效標籤數量：{{ activeProductTags.length }}</p>
    <NovaProductTag :product-tags="productTags" :style-config="styleConfig" />
  </div>
</template>

<script setup lang="ts">
import type { ProductTag } from '@astralweb/nova-magento-types';
import { computed } from 'vue';

interface Props {
  productTags: ProductTag[];
}

const props = defineProps<Props>();

// 使用 composable 取得有效標籤（自動過濾過期標籤）
const { activeProductTags } = useProductTag(props.productTags, computed(() => ({})));

const styleConfig = computed(() => ({
  borderRadius: '12px',
  containerClass: 'custom-tags', // 會與預設值 'absolute left-3 top-3' 合併
  containerStyle: { zIndex: 20 },
  itemClass: 'custom-tag', // 會與預設值 'absolute top-0 left-0' 合併
  itemStyle: { padding: '4px 8px' },
  textClass: 'custom-text', // 會與預設文字樣式合併
  textStyle: { fontSize: '14px' },
  imageClass: 'custom-image', // 會與預設圖片樣式合併
  imageStyle: { maxWidth: '100px' },
}));
</script>

注意：styleConfig 中的類別會與預設類別合併，而不是完全覆蓋。如果需要完全自訂樣式，可以透過 styleConfig 的 style 屬性使用 inline styles，或使用 CSS 選擇器覆蓋預設樣式。

使用 Slot 自訂標籤顯示

自訂整個標籤容器 (tag slot)

<template>
  <NovaProductTag :product-tags="productTags">
    <template #tag="{ tag }">
      <div class="my-custom-tag" :style="{ zIndex: tag.sort }">
        <span>{{ tag.label_text }}</span>
      </div>
    </template>
  </NovaProductTag>
</template>

自訂文字標籤 (textTag slot)

<template>
  <NovaProductTag :product-tags="productTags">
    <template #textTag="{ tag }">
      <div class="custom-text-tag">
        <span class="tag-icon">🏷️</span>
        <span>{{ tag.label_text }}</span>
      </div>
    </template>
  </NovaProductTag>
</template>

自訂圖片標籤 (imageTag slot)

<template>
  <NovaProductTag :product-tags="productTags">
    <template #imageTag="{ tag }">
      <div class="custom-image-wrapper">
        <img 
          :src="tag.frame_image" 
          :alt="tag.label_text"
          loading="lazy"
        />
      </div>
    </template>
  </NovaProductTag>
</template>

組合使用多個 Slot

<template>
  <NovaProductTag :product-tags="productTags">
    <!-- 文字標籤使用自訂樣式 -->
    <template #textTag="{ tag }">
      <div 
        class="px-4 py-2 rounded-lg font-bold"
        :style="{ backgroundColor: tag.tag_color, color: tag.label_color }"
      >
        {{ tag.label_text }}
      </div>
    </template>
    
    <!-- 圖片標籤保持預設樣式或使用另一種客制化 -->
    <template #imageTag="{ tag }">
      <img 
        :src="tag.frame_image" 
        :alt="tag.label_text"
        class="w-full h-full object-cover rounded"
      />
    </template>
  </NovaProductTag>
</template>

自動註冊的組件

模組會自動註冊以下組件，可直接在模板中使用：

• <NovaProductTag /> - 產品標籤顯示組件

Composables API

useProductTag

產品標籤處理的主要 composable，自動註冊可直接使用。

const {
  activeProductTags,
  isActive,
  getBorderRadius,
  getFontStyle,
  getFontWeight,
  containerClass,
  containerStyle,
  itemClass,
  itemStyles,
  textClass,
  textStyle,
  imageClass,
  imageStyle,
} = useProductTag(productTags, styleConfig);

參數

| 參數名稱 | 類型 | 說明 | | --- | --- | --- | | productTags | ProductTag[] | 產品標籤陣列 | | styleConfig | ComputedRef<ProductTagStyleConfig> | 樣式配置的 computed ref（選填） |

返回值

| 名稱 | 類型 | 說明 | | --- | --- | --- | | activeProductTags | ComputedRef<ProductTag[]> | 過濾後的有效標籤 | | isActive | Function | 判斷標籤是否在有效期內 | | getBorderRadius | Function | 根據樣式類型取得 border-radius | | getFontStyle | Function | 轉換字體樣式為 CSS font-style | | getFontWeight | Function | 轉換字體樣式為 CSS font-weight | | containerClass | ComputedRef<string[]> | 容器 class（合併預設值與自訂值） | | containerStyle | ComputedRef | 容器 style | | itemClass | ComputedRef<string[]> | 標籤項目 class（合併預設值與自訂值） | | itemStyles | ComputedRef | 標籤項目 style | | textClass | ComputedRef<string[]> | 文字 class（合併預設值與自訂值） | | textStyle | ComputedRef | 文字 style | | imageClass | ComputedRef<string[]> | 圖片 class（合併預設值與自訂值） | | imageStyle | ComputedRef | 圖片 style |

預設樣式

useProductTag 提供以下預設樣式類別，這些預設值會與 styleConfig 中提供的自訂類別合併：

• containerClass: 'absolute left-3 top-3' - 容器預設定位在左上角
• itemClass: 'absolute top-0 left-0' - 標籤項目預設絕對定位
• textClass: 'typography-caption-regular flex size-full items-center justify-center truncate px-2 py-1' - 文字標籤預設樣式
• imageClass: 'size-full object-contain object-center' - 圖片標籤預設樣式

注意：圖片標籤（tag_type === 'frame'）在組件中會額外套用固定尺寸 h-6 w-[3.25rem]。

組件 API 參考

NovaProductTag

Props

| 屬性 | 類型 | Required | 預設值 | 說明 | | --- | --- | --- | --- | --- | | productTags | ProductTag[] | Yes | - | 產品標籤陣列 | | styleConfig | ProductTagStyleConfig | No | { borderRadius: '16px' } | 樣式配置 |

Slots

| 名稱 | 參數 | 說明 | | --- | --- | --- | | tag | { tag: ProductTag } | 自定義整個標籤內容 | | textTag | { tag: ProductTag } | 自定義文字標籤內容 | | imageTag | { tag: ProductTag } | 自定義圖片標籤內容 |

類型定義

ProductTag

產品標籤資料結構（來自 @astralweb/nova-magento-types）

interface ProductTag {
  id: string;                    // 標籤 ID
  from: number;                  // 開始時間（Unix timestamp）
  to: number;                    // 結束時間（Unix timestamp）
  sort: number;                  // 排序順序
  frame_image: string;           // 框架圖片 URL
  tag_type: 'tag' | 'frame';    // 標籤類型：文字或圖片
  tag_color: string;             // 標籤背景顏色
  tag_style: string;             // 標籤樣式：round_corner, circle, oval, square
  label_text: string;            // 標籤文字
  label_color: string;           // 文字顏色
  label_font_style: string;      // 字體樣式：bold, italic, normal
}

ProductTagStyleConfig

樣式配置選項

interface ProductTagStyleConfig {
  borderRadius?: string;           // 自訂圓角大小
  containerClass?: string;         // 容器 CSS class
  containerStyle?: CSSProperties;  // 容器 inline style
  itemClass?: string;              // 標籤項目 CSS class
  itemStyle?: CSSProperties;       // 標籤項目 inline style
  textClass?: string;              // 文字 CSS class
  textStyle?: CSSProperties;       // 文字 inline style
  imageClass?: string;             // 圖片 CSS class
  imageStyle?: CSSProperties;      // 圖片 inline style
}

細節說明

標籤類型 (tag_type)

• tag - 文字標籤，顯示 label_text
• frame - 圖片標籤，顯示 frame_image

標籤樣式 (tag_style)

• round_corner - 圓角矩形（預設 border-radius: 16px）
• circle - 圓形（border-radius: 50%）
• oval - 橢圓形（border-radius: 50%）
• square - 方形（border-radius: 0）

字體樣式 (label_font_style)

• bold - 粗體（font-weight: bold）
• italic - 斜體（font-style: italic）
• normal - 正常（預設）

時間過濾

標籤會根據 from 和 to 時間自動過濾：

• 只顯示當前時間在有效期內的標籤
• from = 0 表示無開始時間限制
• to = 0 表示無結束時間限制

多標籤顯示

• 標籤會根據 sort 欄位排序
• 多個標籤會堆疊顯示
• 預設位置在左上角（absolute left-3 top-3）
• 標籤項目預設使用絕對定位（absolute top-0 left-0），會根據 sort 值設定 zIndex

樣式合併機制

組件使用樣式合併機制，預設樣式會與自訂樣式合併：

• Class 合併：styleConfig 中的 *Class 屬性會與對應的預設類別合併為陣列
• Style 覆蓋：styleConfig 中的 *Style 屬性會直接使用（不會與預設值合併）

授權聲明

此套件僅供 Astral Web 內部使用，未經授權不得用於其他用途。