@tnlmedia/inkmagine-gui

v2.13.1

Published

4 months ago

Inkmagine GUI components

0High
0Medium
0Low

tnlmediagene

inkmagine vue components

Inkmagine GUI 工具

Inkmagine 是一個統一的組件和樣式庫，提供了一系列可重用的 Vue 組件。

安裝需求

套件使用 Tailwind 作為樣式基礎，使用前請確保已安裝 Tailwind

安裝

npm install @tnlmedia/inkmagine-gui

如果遇到 peerDependencies 的套件版本過低可以使用忽略 peerDependencies 套件的安裝方式

npm install @tnlmedia/inkmagine-gui --legacy-peer-deps

可用樣式使用說明

tailwind config

import {inkTailwindConfig} from '@tnlmedia/inkmagine-gui/tailwind.config.js'
export default {
  ...inkTailwindConfig,
  content: [
    './node_modules/@tnlmedia/inkmagine-gui/**/*.{js,ts,vue}',
    'Set the file path to be scanned in the project'
  ],
}

全域設定說明

vue-i18n language

在初始化應用程式時，可以透過 inkmagineGui 的選項來設定語言：

import inkmagineGui from "@tnlmedia/inkmagine-gui"

createApp(App)
  .use(inkmagineGui, { lang: 'zh-tw' }) // 設定語言

支援的語言

zh-tw: 繁體中文
en-us: 英文
ja-jp: 日文

如果未指定語言，預設將使用 en-us。

How to import component

import { InkVTooltip, InkMenu, InkMenuButton, InkMenuItems, InkMenuItem, InkMenuItemsWrapper, InkButton } from '@tnlmedia/inkmagine-gui';

容器使用說明

InkNavbar

InkNavbar 是一個導航欄組件，提供網站頂部的導航功能，包含側邊欄切換、應用程式選單和用戶選單等功能。

基本用法

<InkNavbar 
  :timezone="user?.timezone" 
  :user="user" 
  logoutUrl="/logout" 
/>

屬性說明

| 屬性名稱 | 類型 | 必填 | 說明 | |---------|------|------|------| | timezone | string | 否 | 用戶的時區設定 | | user | object | 是 | 用戶資訊物件，包含以下屬性：- nickname: 用戶暱稱- avatar: 用戶頭像 URL- mail: 用戶電子郵件 | | logoutUrl | string | 是 | 登出功能的 URL |

功能說明

側邊欄切換按鈕
時區顯示
應用程式選單（包含 dashboard、member、team、cabinet 等應用）
用戶選單（包含用戶資訊、個人資料和登出功能）

注意事項

應用程式選單的 URL 會根據當前環境（sandbox、stage、production）自動調整
用戶頭像若未設定，將顯示用戶電子郵件的第一個字母
所有文字內容都支援多語言設定

InkSidebar

InkSidebar 是一個側邊欄組件，提供網站的主要導航功能，包含品牌切換、選單導航等功能。

基本用法

<InkSidebar
  :currentAppName="$t('sandwich')" 
  :currentMainSwitchItem="currentConsole?.console" 
  :mainSwitchItems="user.permission.map((item:Permission) => item.console)"
  @mainItemCheckSwitch="checkSwitchEnv"
  :menu="menu"
  :currentMenuItemId="checkCurrentMenuItemId"
/>

進階用法（使用插槽）

<InkSidebar 
  :currentAppName="trans('cabinet.name')" 
  :currentMainSwitchItem="currentTeam" 
  :mainSwitchItems="env.team"
  @mainItemCheckSwitch="checkSwitchEnv"
  @tabItemCheckSwitch="checkSwitchEnv"
  :menu="menu"
  :currentMenuItemId="checkCurrentMenuItemId"
  :currentTabSwitchItemId="env.workspace.console"
  :tabSwitchItems="consoleList"
>
  <!-- 自定義內容 -->
  <InkButton
    as="router-link"
    variant="txt"
    theme="primary"
    :to="{ name: 'article-create' }"
  >
    <i class="far fa-edit tw-text-base"></i>
    <InkSidebarSimpleHide>
      {{ trans('buttons.compose') }}
    </InkSidebarSimpleHide>
  </InkButton>
</InkSidebar>

屬性說明

| 屬性名稱 | 類型 | 必填 | 說明 | |---------|------|------|------| | currentAppName | string | 是 | 當前應用程式名稱 | | currentMainSwitchItem | object | 否 | 當前選中的主要切換項目，包含以下屬性：- id: 項目 ID- name: 項目名稱- logo: 項目圖標 URL | | mainSwitchItems | array | 否 | 主要切換項目列表，每個項目包含與 currentMainSwitchItem 相同的屬性 | | currentTabSwitchItemId | string | number | 否 | 當前選中的 tabSwitchItems 切換項目的 id | | tabSwitchItems | array | 否 | 標籤切換項目列表，每個項目包含與 currentMainSwitchItem 相同的屬性 | | menu | array | 是 | 選單項目列表，每個項目包含以下屬性：- id: 項目 ID- name: 項目名稱- icon: 圖標類名- route: 路由資訊（可選）- children: 子選單項目（可選）- isAllow: 是否允許訪問（可選），false 不顯示該項目 | | currentMenuItemId | string | number | 是 | 當前選中的選單項目 ID |

事件說明

| 事件名稱 | 參數 | 說明 | |---------|------|------| | mainItemCheckSwitch | (item: SwitchItem, close: () => void) | 當主要切換項目被點擊時觸發，parameter close 可以將收風琴關閉 | | tabItemCheckSwitch | (item: SwitchItem) | 當標籤切換項目被點擊時觸發 |

選單結構範例

const menu = [
  {
    id: 'deliveryArticle',
    icon: 'fa-file-waveform',
    name: 'deliveryArticle',
    children: [{
      id: 'deliveryArticleOverview',
      name: 'overview',
      route: {
        name: 'article-delivery-overview',
        query: {
          console_id: currentConsole?.console?.id
        }
      },
      isAllow: true,
    }],
  },
  {
    id: 'setting',
    icon: 'fa-gear',
    name: 'setting',
    children: [{
      id: 'deliveryPosition',
      name: 'deliveryPosition',
      route: {
        name: 'position',
        query: {
          console_id: currentConsole?.console?.id
        }
      },
      isAllow: true,
    }],
  },
];

功能說明

支援多層級選單結構
支援路由導航
支援權限控制
支援自定義內容（通過插槽）

注意事項

選單項目的 isAllow 屬性用於控制項目的顯示權限
子選單項目的路由資訊必須包含 name 屬性
側邊欄的折疊狀態會保存在 <body> 的 class 中
需在 <body> 的 class 加上 sidebar-dark Double-column
InkSidebarMenu 組件使用 Vue Router 作為路由管理工具，請確保您的專案中已安裝此套件
當使用 tabSwitchItems 時，需要同時提供 currentTabSwitchItemId 屬性

組件關係

InkSidebar
├──slot
│  └── InkSidebarSimpleHide (折疊時隱藏內容)
└── InkSidebarMenu (選單列表，已包含在容器內)

使用說明

InkSidebarSimpleHide 用於包裝需要在側邊欄折疊時隱藏的內容
可以通過 as 屬性來自定義渲染的標籤或組件
預設使用 span 標籤渲染
支援插槽內容

組件使用說明

InkButton

InkButton 提供了多種樣式和尺寸的按鈕。

基本連結按鈕

<div class="tw-flex tw-gap-1">
  <InkButton as="router-link" to="/" variant="base" theme="link">router-link</InkButton>
  <InkButton variant="base" theme="link">tw-btn-link</InkButton>
  <InkButton as="a" href="#" variant="base" theme="link">tw-btn-link</InkButton>
</div>

帶圖標的按鈕 (36px)

<div class="tw-flex tw-gap-1">
  <InkButton variant="txt" theme="transparent">
    <i class="far fa-sliders-h"></i>tw-btn-icon & txt
  </InkButton>
  <InkButton variant="txt" theme="gray">
    <i class="far fa-sliders-h"></i>tw-btn-gray
  </InkButton>
  <InkButton variant="txt" theme="primary">
    <i class="far fa-sliders-h"></i>tw-btn-primary
  </InkButton>
</div>

中等尺寸按鈕 (32px)

<div class="tw-flex tw-gap-1">
  <InkButton variant="txt" size="md" theme="transparent">
    <i class="far fa-sliders-h"></i>tw-btn-icon & txt
  </InkButton>
  <InkButton variant="txt" size="md" theme="primary">
    <i class="far fa-sliders-h"></i>tw-btn-primary
  </InkButton>
</div>

小尺寸按鈕 (24px)

<div class="tw-flex tw-gap-1">
  <InkButton variant="icon" size="xs" theme="transparent">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton variant="icon" size="xs" theme="primary">
    <i class="far fa-sliders-h"></i>
  </InkButton>
</div>

圖標按鈕 (36px)

<div class="tw-flex tw-gap-1">
  <InkButton as="router-link" to="/" variant="icon" theme="transparent">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton variant="icon" theme="transparent">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton variant="icon" theme="gray">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton variant="icon" theme="info">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton variant="icon" theme="primary">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton variant="icon" theme="outline-gray">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton as="a" href="#" variant="icon" theme="primary">
    <i class="far fa-sliders-h"></i>
  </InkButton>
</div>

中等尺寸圖標按鈕 (32px)

<div class="tw-flex tw-gap-1">
  <InkButton as="router-link" to="/" variant="icon" size="md" theme="transparent">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton variant="icon" size="md" theme="transparent">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton variant="icon" size="md" theme="gray">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton variant="icon" size="md" theme="info">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton variant="icon" size="md" theme="primary">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton variant="icon" size="md" theme="outline-gray">
    <i class="far fa-sliders-h"></i>
  </InkButton>
  <InkButton as="a" href="#" variant="icon" size="md" theme="primary">
    <i class="far fa-sliders-h"></i>
  </InkButton>
</div>

禁用狀態

<div class="tw-flex tw-gap-1">
  <InkButton variant="txt" disabled theme="transparent">
    <i class="far fa-sliders-h"></i>disabled
  </InkButton>
  <InkButton variant="txt" disabled theme="primary">
    <i class="far fa-sliders-h"></i>disabled
  </InkButton>
</div>

載入狀態

<div class="tw-flex tw-gap-1">
  <InkButton :disabled="testLoading" :loading="testLoading" variant="txt" theme="primary">
    <i class="far fa-sliders-h"></i>loading
  </InkButton>
</div>

InkButton 屬性說明

| 屬性名稱 | 類型 | 預設值 | 可選值 | 說明 | |---------|------|--------|--------|------| | as | string | 'button' | 'a' | 'button' | 'router-link' | 指定按鈕渲染的標籤類型。當需要連結功能時，可設為 'a' 或 'router-link' | | type | string | 'button' | 'button' | 'submit' | 'reset' | 當 as="button" 時，指定按鈕的類型 | | size | string | - | 'md' | 'xs' | 'xxs' | 按鈕尺寸。'md' 為中等尺寸(32px)，'xs' 為小尺寸(24px)，不指定則為預設尺寸(36px) | | variant | string | 'base' | 'base' | 'txt' | 'icon' | 按鈕變體。'base' 為基礎按鈕，'txt' 為文字按鈕，'icon' 為圖標按鈕 | | theme | string | 'transparent' | 'primary' | 'info' | 'gray' | 'outline-gray' | 'link' | 'transparent' | 按鈕主題樣式 | | disabled | boolean | false | true | false | 是否禁用按鈕。當為 true 時，按鈕無法點擊且會套用禁用樣式 | | loading | boolean | false | true | false | 是否顯示載入狀態。當為 true 時，會顯示載入動畫並隱藏按鈕內容 |

InkMenu

InkMenu 是基於 @headlessui/vue 的 Menu 組件封裝，提供了一個完整的下拉選單解決方案。

基本用法

<InkMenu v-slot="{open, close}">
  <InkMenuButton>
    <InkButton variant="txt" theme="transparent">
      <i class="far fa-grip-horizontal tw-text-base tw-text-gray-700"></i>
      {{ $t('navbar.apps.service') }}
    </InkButton>
  </InkMenuButton>
  <InkMenuItems>
    <InkMenuItemsWrapper>
      <InkMenuItem>
        <router-link :to="{ name: 'article-delivery-overview' }">
          <div class="content">
            <p class="tw-font-semibold tw-text-sm">test</p>
            <p class="sub-text tw-text-mute tw-text-xs">
              {{ $t(`navbar.apps.dashboard.description`) }}
            </p>
          </div>
        </router-link>
      </InkMenuItem>
    </InkMenuItemsWrapper>
  </InkMenuItems>
</InkMenu>

進階用法

<InkMenu v-slot="{open, close}">
  <InkMenuButton>
    <InkButton variant="txt" theme="transparent">
      <i class="far fa-grip-horizontal tw-text-base tw-text-gray-700"></i>
      {{ $t('navbar.apps.service') }}
    </InkButton>
  </InkMenuButton>
  <InkMenuItems>
    <InkMenuItemsWrapper>
      <InkMenuItem 
        as="div" 
        class="test" 
        v-slot="{active}" 
        href="https://www.inkmaginecms.com/dashboard"
        target="_blank" 
        @mouseenter="console.log('mouseenter')"
      >
        <div class="content">
          {{ active }}
          <p class="tw-font-semibold tw-text-sm">{{ $t('navbar.apps.dashboard.label') }}</p>
          <p class="sub-text tw-text-mute tw-text-xs">
            {{ $t(`navbar.apps.dashboard.description`) }}
          </p>
        </div>
      </InkMenuItem>
    </InkMenuItemsWrapper>
  </InkMenuItems>
</InkMenu>

多個選單項目容器

<InkMenu>
  <!-- 第一個選單按鈕 -->
  <VTooltip>
    <InkMenuButton :disabled="isLock" variant="icon" theme="transparent" @click="toggleMoreList" ref="moreListBtn">
      <InkButton>
        <i class="far fa-ellipsis-v fa-fw tw-text-base"></i>
      </InkButton>
    </InkMenuButton>
    <template #popper>
      more
    </template>
  </VTooltip>

  <!-- 第一個選單項目容器 -->
  <InkMenuItems :static="true" :unmount="false" class="tw-translate-y-4" v-show="!isRevisionList && isMoreList">
    <InkMenuItemsWrapper>
      <InkMenuItem :disabled="isLock" @click.prevent="openCopyArticle(); hideMoreList();" type="button" as="button">
        <i class="far fa-copy fa-fw tw-text-base icon"></i>
        {{ trans('article.copy_article.title') }}
      </InkMenuItem>
      <InkMenuItem as="button" type="button" @click="toggleReversionList" :disabled="isLock">
        <i class="far fa-history fa-fw tw-text-base icon"></i>
        {{ trans('article.revisions.title') }}
      </InkMenuItem>
    </InkMenuItemsWrapper>
  </InkMenuItems>

  <!-- 第二個選單項目容器 -->
  <InkMenuItems class="js-revision-list tw-translate-y-4 tw-overflow-hidden tw-py-0" :static="true" :unmount="false">
    <!-- 標題欄 -->
    <div class="tw-flex tw-items-center tw-relative tw-px-3 tw-py-2.5 tw-text-base tw-font-semibold tw-text-gray-900 after:tw-absolute after:tw-inset-x-0 after:tw-bottom-0 after:tw-h-[1px] after:tw-bg-gray-300 after:tw-content-['']">
      <InkButton variant="icon" theme="transparent" class="tw-mr-6" @click="$emit('hideReversionListEmit')">
        <i class="far fa-chevron-left fa-fw"></i>
      </InkButton>
      {{ trans('article.revisions.title') }}
    </div>

    <!-- 選單項目列表 -->
    <InkMenuItemsWrapper class="tw-max-h-[236px] tw-overflow-auto tw-py-2.5">
      <InkMenuItem v-slot="{ active }" v-for="item in dropdownList" :key="item.id">
        <a href :class="[{ 'tw-bg-primary-50': active }]" @click.prevent="onItemClick(item.id)">
          <div>
            <p class="tw-text-base tw-text-gray-900">{{ item.modifier }}</p>
            <p class="tw-text-xs tw-text-gray-700">{{ item.created }}</p>
            <p class="tw-text-xs tw-text-gray-700">{{ item.status }}</p>
          </div>
        </a>
      </InkMenuItem>

      <!-- 載入狀態 -->
      <div v-if="isLoading || dropdownList.length === 0" class="tw-flex tw-h-12 tw-items-center tw-justify-center tw-pt-2">
        <span v-if="isLoading" class="spinner-border spinner-border-sm" role="status"></span>
        <p v-else class="tw-text-gray-900">{{ trans('datatable.no_data') }}</p>
      </div>

      <!-- 無限滾動觸發器 -->
      <div v-if="targetIsVisible" ref="target"></div>
    </InkMenuItemsWrapper>
  </InkMenuItems>
</InkMenu>

InkMenu 相關組件說明

| 組件名稱 | @headlessui/vue 組件名稱 | 說明 | 屬性 | 預設值 | 可選值 | |---------|-------------------------|------|------|--------|--------| | InkMenu | Menu | 選單容器，管理選單的狀態和行為 | as | 'div' | string | Component | | InkMenuButton | MenuButton | 觸發按鈕，控制選單的開啟/關閉。 as 是 template 時 props 還是要從 InkMenuButton 往下傳遞。 | as | 'template' | string | Component | | InkMenuItems | MenuItems | 選單項目容器，包含所有選單項目 | - | - | - | | InkMenuItemsWrapper | - | 選單項目包裝器，用於自定義選單項目的樣式 | - | - | - | | InkMenuItem | MenuItem | 選單項目，可以是連結、按鈕或其他元素。 as 是 template 時，子層不能只放字串 | as | 'template' | string |

組件關係

InkMenu
├── InkMenuButton (觸發按鈕)
└── InkMenuItems (選單項目容器)
    ├── 其他自定義內容（可選）
    └── InkMenuItemsWrapper (選單項目包裝器)
        └── InkMenuItem (選單項目)

使用說明

InkMenu 提供 v-slot="{open, close}" 用於控制選單的開啟和關閉
InkMenuItem 提供 v-slot="{active}" 用於獲取當前項目的激活狀態
所有組件都支援 v-bind="restAttrs" 來傳遞額外的屬性
可以通過 as 屬性來自定義渲染的標籤或組件
v-slot 提供的屬性（如 open、close、active）都是基於 @headlessui/vue 的 Menu 組件

事件

InkMenuButton 支援所有標準的 DOM 事件
InkMenuItem 支援所有標準的 DOM 事件
選單項目可以通過 @click、@mouseenter 等事件來處理互動

樣式

所有組件都預設套用了相應的樣式類
可以通過 class 屬性來自定義樣式
支援 Tailwind CSS 的樣式類

InkDisclosure

InkDisclosure 是基於 @headlessui/vue 的 Disclosure 組件封裝，提供了一個可展開/收合的內容區塊解決方案。

基本用法

<InkDisclosure v-slot="{ open }" :defaultOpen="true">
  <InkDisclosureButton>
    標題
  </InkDisclosureButton>
  <InkDisclosurePanel>
    展開的內容
  </InkDisclosurePanel>
</InkDisclosure>

進階用法 - 群組展開

<InkDisclosure 
  v-for="(item, index) in group" 
  v-slot="{ open }" 
  :defaultOpen="defaultOpen[index]"
>
  <InkDisclosureButton @click="onOpen(index)">
    {{ item.name }}
  </InkDisclosureButton>
  <div v-show="open">
    <InkDisclosurePanel static :unmount="false">
      <DynamicComponent 
        v-for="field in item.field" 
        :key="field.id" 
        :field="field"
        :value="fieldValue.find(item => item.id === field.id)?.value" 
      />
    </InkDisclosurePanel>
  </div>
</InkDisclosure>

InkDisclosure 相關組件說明

| 組件名稱 | @headlessui/vue 組件名稱 | 說明 | 屬性 | 預設值 | 可選值 | |---------|-------------------------|------|------|--------|--------| | InkDisclosure | Disclosure | 展開/收合容器，管理內容的展開狀態 | - | - | - | | InkDisclosureButton | DisclosureButton | 觸發按鈕，控制內容的展開/收合 | astype | 'button''button' | stringstring | | InkDisclosurePanel | DisclosurePanel | 可展開/收合的內容區塊 | - | - | - |

組件關係

InkDisclosure (展開/收合容器)
├── InkDisclosureButton (觸發按鈕)
└── InkDisclosurePanel (內容區塊)

使用說明

InkDisclosure 提供 v-slot="{ open }" 用於獲取當前的展開狀態
defaultOpen 屬性可以設定預設是否展開
InkDisclosureButton 預設包含展開/收合的箭頭圖標

樣式

按鈕預設使用灰色主題 (tw-disclosure-button-gray)
箭頭圖標會根據展開狀態自動旋轉
支援 Tailwind CSS 的樣式類

vInkTooltip

vInkTooltip 是基於 floating-vue 的指令封裝，提供簡易的提示訊息功能。

基本用法

<span v-inkTooltip.right="'test'">test</span>

功能說明

支援多種位置設定（如 .right、.left、.top、.bottom 等）
可自訂提示內容（支援字串或 HTML）
適用於任何需要提示說明的場景
更多詳細屬性與用法，請參考 floating-vue 官方 API 文件，以獲得完整的組件參數說明。

注意事項

需安裝 floating-vue 及其樣式（已於組件內自動引入）
建議用於簡單的文字提示場景
如需更複雜的提示功能，請使用 InkVTooltip 組件

組件關係

vInkTooltip (指令)
└── Tooltip (floating-vue)

InkVTooltip

InkVTooltip 是基於 floating-vue 的 Tooltip 組件封裝，提供簡易的提示訊息功能，支援多種觸發方式（hover、focus、click）。

基本用法

<InkVTooltip>
  <button type="button"><i class="fa-regular fa-circle-info"></i></button>
  <template #popper>
    {{ tipContent }}
  </template>
</InkVTooltip>

禁用狀態

<InkVTooltip :disabled="Boolean(list.deletable)">
  <InkButton
    size="xs"
    variant="icon"
    theme="transparent"
    :disabled="!Boolean(list.deletable) || currentConsoleUserPermission.view"
    @click="handleDelete(list.id, list.article.title)"
  >
    <i class="far fa-trash"></i>
  </InkButton>
  <template #popper>
    {{ $t('enabledCannotDeleted') }}
  </template>
</InkVTooltip>

屬性說明

| 屬性名稱 | 類型 | 預設值 | 說明 | |------------|---------|----------|----------------------------| | disabled | Boolean | false | 是否停用 Tooltip 顯示 |

更多詳細屬性與用法，請參考 floating-vue 官方 API 文件，以獲得完整的組件參數說明。

插槽說明

| 插槽名稱 | 說明 | |------------|----------------------------| | default | 觸發 Tooltip 的內容 | | popper | Tooltip 彈出時顯示的內容 |

功能說明

支援 hover、focus、click 觸發（預設同時啟用）
可自訂提示內容（支援 slot）
可透過 disabled 屬性停用提示
彈出位置預設為下方（bottom）

組件關係

InkVTooltip
└── Tooltip (floating-vue)
    ├── slot (觸發內容)
    └── slot name="popper" (提示內容)

注意事項

需安裝 floating-vue 及其樣式（已於組件內自動引入）
適用於任何需要提示說明的場景

InkBadge

InkBadge 是一個輕量級的標籤組件，用於顯示狀態、分類或其他簡短資訊。

基本用法

<InkBadge>string</InkBadge>
<InkBadge as="button">string</InkBadge>

屬性說明

| 屬性名稱 | 類型 | 預設值 | 可選值 | 說明 | |---------|------|--------|--------|------| | as | string | 'span' | 'span' | 'button' | 指定標籤渲染的標籤類型 | | type | string | - | 'button' | 當 as="button" 時，指定按鈕的類型 | | theme | string | 'info' | 'info' | 標籤主題樣式 | | disabled | boolean | false | true | false | 是否禁用標籤。當為 true 時，標籤會套用禁用樣式 |

功能說明

支援作為 span 或 button 元素渲染
提供 info 主題樣式
支援禁用狀態
可透過插槽自定義內容

樣式

預設使用 info 主題 (tw-badge tw-badge-info)
禁用狀態會套用 tw-disabled 樣式類
支援 Tailwind CSS 的樣式類

InkSpinner

InkSpinner 是一個載入動畫組件，用於表示正在載入或處理中的狀態。

基本用法

<InkSpinner/>

屬性說明

| 屬性名稱 | 類型 | 預設值 | 可選值 | 說明 | |---------|------|--------|--------|------| | size | string | - | 'md' | 載入動畫的尺寸 | | theme | string | 'primary' | 'primary' | 'gray' | 載入動畫的主題顏色 |

功能說明

提供中等尺寸的載入動畫
支援灰色主題
適用於按鈕、頁面或組件的載入狀態

樣式

預設使用 tw-spinner-grow 作為基礎樣式
支援 tw-spinner-md 尺寸樣式
支援 tw-spinner-grow-gray 主題樣式
支援 Tailwind CSS 的樣式類

使用場景

按鈕載入狀態
頁面內容載入
表單提交處理
資料請求等待

Font

Inkmagine GUI 提供了完整的字體系統，支援多語言字體設定和響應式字體大小。

字體家族設定

Inkmagine GUI 根據語言自動設定對應的字體家族：

繁體中文 (zh-tw)

[lang="zh-tw"] {
  font-family: "Noto Sans TC", "Pingfang TC", "Microsoft JhengHei", "Heiti TC", "Microsoft YaHei", ui-sans-serif, system-ui, -apple-system, "sans-serif";
}

日文 (ja-jp)

[lang="ja-jp"] {
  font-family: "Noto Sans JP", "Microsoft JhengHei", ui-sans-serif, system-ui, -apple-system, "sans-serif";
}

英文 (en-us)

[lang="en-us"] {
  font-family: "Helvetica Neue", system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans", "Liberation Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
}

字體大小系統

Inkmagine GUI 使用 Tailwind CSS 的字體大小系統，並提供響應式字體大小：

字體大小對應的 CSS 變數

.tw-text-size-xs     /* 12px */
.tw-text-size-sm     /* 14px */
.tw-text-size-base   /* 16px */
.tw-text-size-lg     /* 18px */
.tw-text-size-xl     /* 20px */
.tw-text-size-2xl    /* 24px */
.tw-text-size-3xl    /* 30px */
.tw-text-size-4xl    /* 36px */
.tw-text-size-5xl    /* 48px */
.tw-text-size-6xl    /* 64px */

響應式字體大小對應的 CSS 變數

.tw-text-size-xlmix     /* xl 在桌面，lg 在手機 */
.tw-text-size-2xlmix    /* 2xl 在桌面，xl 在手機 */
.tw-text-size-3xlmix    /* 3xl 在桌面，2xl 在手機 */

基本字體大小(帶有lineHeight, letterSpacing, fontWeight)

.tw-text-xs     /* 12px - 小字 */
.tw-text-sm     /* 14px - 較小字 */
.tw-text-base   /* 16px - 基礎字體 */
.tw-text-lg     /* 18px - 較大字 */
.tw-text-xl     /* 20px - 大字 */
.tw-text-2xl    /* 24px - 更大字 */
.tw-text-3xl    /* 30px - 標題字 */
.tw-text-4xl    /* 36px - 大標題 */
.tw-text-5xl    /* 48px - 超大標題 */
.tw-text-6xl    /* 64px - 最大標題 */

響應式字體大小 (Mix)(帶有lineHeight, letterSpacing, fontWeight)

.tw-text-xlmix     /* xl 在桌面，lg 在手機 */
.tw-text-2xlmix    /* 2xl 在桌面，xl 在手機 */
.tw-text-3xlmix    /* 3xl 在桌面，2xl 在手機 */

字體權重和行高

字體權重

xs, sm, base: font-weight: 400 (正常)
lg, xl, 2xl, 3xl, 4xl, 5xl, 6xl: font-weight: 600 (半粗體)

行高設定

xs, sm: line-height: 1.4
base: line-height: 1.375
lg, xl, 2xl, 4xl, 5xl, 6xl: line-height: 1.25
3xl: line-height: 1.3

字間距

所有字體大小都設定 letter-spacing: 0.02em

特殊字體

Font Awesome 圖標字體

.tw-font-awesome  /* Font Awesome 6 Pro, Font Awesome 7 Pro 字體 */

使用範例

基本使用

<template>
  <!-- 基本字體大小 -->
  <h1 class="tw-text-3xl">主標題</h1>
  <h2 class="tw-text-2xl">副標題</h2>
  <p class="tw-text-base">正文內容</p>
  <small class="tw-text-sm">小字說明</small>
  
  <!-- 響應式字體大小 -->
  <h1 class="tw-text-3xlmix">響應式主標題</h1>
  <h2 class="tw-text-2xlmix">響應式副標題</h2>
  
  <!-- 使用 CSS 變數 -->
  <div class="tw-text-size-lg">使用 CSS 變數的字體大小</div>
</template>

在 SCSS 中使用

.my-component {
  // 使用 Tailwind 類別
  @apply tw-text-lg tw-font-semibold;
  
  // 或使用 CSS 變數
  font-size: theme('fontSize.size-lg');
  font-weight: theme('fontWeight.600');
  line-height: theme('lineHeight.1.25');
  letter-spacing: theme('letterSpacing.0.02em');
}

響應式斷點

字體響應式系統使用以下斷點：

md: 最大寬度 576px (手機)
tl: 最大寬度 992px (平板)
lg: 最大寬度 1024px (小桌面)
xl: 最大寬度 1200px (大桌面)

最佳實踐

優先使用響應式字體大小：使用 xlmix、2xlmix、3xlmix 來確保在不同裝置上的可讀性
保持字體層次：使用不同的字體大小來建立清楚的視覺層次
考慮行高：較大的字體使用較小的行高，較小的字體使用較大的行高
語言適配：確保在不同語言環境下字體都能正確顯示

Colors

Inkmagine GUI 提供了完整的顏色系統，包含主色調、輔助色調和語意化顏色，支援多種色階變化。

主色調 (Primary)

主色調採用藍紫色系，提供 9 個色階：

.tw-text-primary-50    /* #E6ECFE - 最淺藍紫 */
.tw-text-primary-100   /* #D5DFFE - 淺藍紫 */
.tw-text-primary-200   /* #B9CCFE - 較淺藍紫 */
.tw-text-primary-300   /* #8FAFFF - 中淺藍紫 */
.tw-text-primary-400   /* #527DFF - 中藍紫 */
.tw-text-primary-500   /* #4C3FFF - 主藍紫 */
.tw-text-primary-600   /* #3A3AF8 - 深藍紫 */
.tw-text-primary-700   /* #0E33EF - 較深藍紫 */
.tw-text-primary-800   /* #0F00E2 - 深藍紫 */
.tw-text-primary-900   /* #001ECC - 最深藍紫 */

使用範例：

<template>
  <button class="tw-bg-primary-500 tw-text-white">主要按鈕</button>
  <div class="tw-bg-primary-50 tw-text-primary-900">淺色背景</div>
</template>

輔助色調 (Secondary)

輔助色調採用黃色系，提供 9 個色階：

.tw-text-secondary-50    /* #FFFDE5 - 最淺黃 */
.tw-text-secondary-100   /* #FFF8BF - 淺黃 */
.tw-text-secondary-200   /* #FFF394 - 較淺黃 */
.tw-text-secondary-300   /* #FFEF67 - 中淺黃 */
.tw-text-secondary-400   /* #FEEA3F - 中黃 */
.tw-text-secondary-500   /* #FCE400 - 主黃 */
.tw-text-secondary-600   /* #FFD600 - 深黃 */
.tw-text-secondary-700   /* #FEBC00 - 較深黃 */
.tw-text-secondary-800   /* #FEA200 - 深黃 */
.tw-text-secondary-900   /* #FC7600 - 最深黃 */

使用範例：

<template>
  <div class="tw-bg-secondary-500 tw-text-white">警告提示</div>
  <span class="tw-text-secondary-700">高亮文字</span>
</template>

灰色系 (Gray)

灰色系提供 9 個色階，用於文字、背景和邊框：

.tw-text-gray-50     /* #FAFAFC - 最淺灰 */
.tw-text-gray-100    /* #F3F3F6 - 淺灰 */
.tw-text-gray-200    /* #EBEBF0 - 較淺灰 */
.tw-text-gray-300    /* #DDDFE8 - 中淺灰 */
.tw-text-gray-400    /* #8F90A6 - 中灰 */
.tw-text-gray-500    /* #7C7D97 - 主灰 */
.tw-text-gray-600    /* #676A88 - 深灰 */
.tw-text-gray-700    /* #555770 - 較深灰 */
.tw-text-gray-800    /* #353650 - 深灰 */
.tw-text-gray-900    /* #28293D - 最深灰 */

使用範例：

<template>
  <p class="tw-text-gray-900">主要文字</p>
  <p class="tw-text-gray-600">次要文字</p>
  <div class="tw-bg-gray-100 tw-border-gray-300">淺色卡片</div>
</template>

灰色系以命名的顏色

tw-text-gray /* #555770 - 較深灰 */

語意化顏色

成功色 (Success)

.tw-text-success-50     /* #E7F7EE - 淺綠背景 */
.tw-text-success-400    /* #54E4B7 - 成功圖標 */
.tw-text-success-500    /* #00A65E - 成功文字 */

危險色 (Danger)

.tw-text-danger-50      /* #FFECF1 - 淺紅背景 */
.tw-text-danger-400     /* #F7193E - 危險圖標 */
.tw-text-danger-500     /* #D8002F - 危險文字 */

警告色 (Warning)

.tw-text-warning-50    /* #FFFDE5 - 淺黃背景 */
.tw-text-warning-400    /* #FFD600 - 警告圖標 */
.tw-text-warning-500    /* #E7B800 - 警告文字 */

資訊色 (Info)

.tw-text-info-50       /* #E6ECFE - 淺藍背景 */
.tw-text-info-400      /* #527DFF - 資訊圖標 */
.tw-text-info-500      /* #4C3FFF - 資訊文字 */

紙張色 (Paper)

.tw-text-paper-500     /* #F9F4ED - 紙張背景色 */

無障礙設計

顏色對比度

確保文字和背景的對比度符合 WCAG 2.1 AA 標準
最小對比度比例：4.5:1 (正常文字)，3:1 (大字體)

色盲友善

不要僅依賴顏色來傳達資訊
結合圖標、文字或形狀來增強可讀性

input 類元件使用說明

表單驗證方法

Inkmagine GUI 使用 vee-validate 作為表單驗證框架，並透過 useDefineRule 提供自定義驗證規則。

Assign value to input

詳情請見 vee-validate 的 useForm

const { handleSubmit, handleReset, resetForm } = useForm({
  initialValues:{
    key:value[]
  }
});

const { handleSubmit, setValues, setFieldValue } = useForm();
// 取得 data 後 (一次 set 多 field)
setValues( { key:value[] })
// 或是 (一次 set 單 field)
setFieldValue('key', ['value'])

key 使用 field.id (field 物件結構)，確保每個欄位都有唯一識別符，便於表單資料的對應和管理
value 統一使用 array，讓單欄位(field)可以儲存多筆資料

支援的驗證規則

| 規則名稱 | 說明 | 參數 | |---------|------|------| | required | 必填驗證 | 無 | | wordLimit | 文字長度限制 | [min, max] | | itemLimit | 項目數量限制 | [min, max] | | url | URL 格式驗證 | 無 | | datetimeRestrict | 日期時間限制 | [restrict, timezone, format] | | datetimerngStartLimit | 日期範圍開始時間限制 | [endValue, minLength, maxLength, timezone, format] | | datetimerngEndLimit | 日期範圍結束時間限制 | [startValue, minLength, maxLength, timezone, format] |

InkField 動態欄位元件

InkField 是一個動態欄位元件，根據欄位類型自動渲染對應的輸入元件，並提供多項目輸入管理功能。

基本用法

<InkField
  :field="{
    id: 'title',
    type: 'text',
    name: '標題',
    placeholder: '請輸入標題',
    limit: [10, 100],
    max: 3,
    description: '請輸入文章標題',
    tip: '標題將顯示在文章列表'
  }"
  :required="true"
  :disabled="false"
  :inputBind="{
    // 根據欄位類型提供對應的 inputBind
  }"
  :inputOn="{
    // 事件處理函數
  }"
  @inkChanged="handleChange"
/>

屬性說明

| 屬性名稱 | 類型 | 必填 | 預設值 | 說明 | |---------|------|------|--------|------| | field | FieldDataSharp | 是 | - | 欄位設定物件，包含所有欄位相關設定 | | required | boolean | 否 | undefined | 是否必填 | | disabled | boolean | 否 | undefined | 是否禁用 | | inputBind | Record<string, any> | 否 | undefined | 輸入元件綁定屬性 | | inputOn | Record<string, any> | 否 | undefined | 事件處理函數 |

field 物件結構

{
  id: 'fieldId',           // 欄位 ID（必填）
  type: 'text',            // 欄位類型（必填）
  name: '欄位名稱',        // 顯示名稱（可選）
  require: true,           // 是否必填（可選）
  slug: 'field-slug',      // 欄位 slug（可選）
  description: '說明文字',  // 欄位說明（可選）
  position: 'left',        // 位置：'left' | 'center' | 'right'（可選）
  tip: '提示文字',         // 提示說明（可選）
  placeholder: '佔位符',   // 輸入提示（可選）
  min: 1,                  // 最小數量（可選，0 為無限制）
  max: 5,                  // 最大數量（可選，0 為無限制）
  limit: [10, 100],        // 限制條件（可選）
  default: ['預設值'],     // 預設值（可選）
  ai: ['AI 提示'],         // AI 相關設定（可選）
  // 根據 type 不同，會有額外的特定屬性
}

物件詳細資訊參考 https://github.com/tnlmedia/cabinet/blob/prod/resources/docs/internal/fields/type.md https://github.com/tnlmedia/cabinet/blob/prod/resources/docs/internal/articles/structure.md

支援的欄位類型

| 類型 | 對應元件 | 說明 | |------|----------|------| | text | InkText | 文字輸入 | | url | InkUrl | URL 輸入 | | textarea | InkTextarea | 多行文字輸入 | | select | InkSelect | 下拉選單 | | checkbox | InkCheckbox | 複選框 | | radio | InkRadio | 單選框 | | switch | InkSwitch | 開關 | | datetime | InkDatetime | 日期時間選擇器 | | date | InkDatetime | 日期選擇器 | | datetimerng | InkDatetimerng | 日期時間範圍選擇器 | | daterng | InkDatetimerng | 日期範圍選擇器 | | hashtag | InkHashtag | 標籤輸入 |

單一欄位類型

以下欄位類型預設為單一輸入，不支援多項目：

select
checkbox
radio
switch
datetime
date
datetimerng
daterng
hashtag

多項目欄位類型

以下欄位類型支援多項目輸入：

text
url
textarea

功能特色

動態元件渲染：根據 field.type 自動選擇對應的輸入元件
多項目管理：支援動態新增/刪除輸入項目
統一驗證：整合 vee-validate 提供統一的表單驗證
靈活配置：支援豐富的欄位配置選項
事件處理：提供 inkChanged 事件處理值變更
響應式設計：根據欄位類型自動調整佈局

事件說明

| 事件名稱 | 參數 | 說明 | |---------|------|------| | inkChanged | (value: any) | 當欄位值發生變更時觸發 |

使用範例

多項目文字輸入

<InkField
  :field="{
    id: 'keywords',
    type: 'text',
    name: '關鍵字',
    placeholder: '請輸入關鍵字',
    max: 5,
    limit: [1, 20]
  }"
  :required="true"
/>

單一選擇器

<InkField
  :field="{
    id: 'category',
    type: 'select',
    name: '分類',
    placeholder: '請選擇分類'
  }"
  :inputBind="{
    options: [
      { key: 1, name: '分類一' },
      { key: 2, name: '分類二' }
    ]
  }"
  :required="true"
/>

日期時間選擇

<InkField
  :field="{
    id: 'publishTime',
    type: 'datetime',
    name: '發布時間',
    placeholder: '請選擇發布時間'
  }"
  :inputBind="{
    timezone: 'Asia/Taipei',
    format: 'YYYY/MM/DD HH:mm',
    restrict: {
      restrictType: 'FUTURE',
      shiftSecond: 0
    }
  }"
  :required="true"
/>

InkField 與單獨使用元件的差異

Inkmagine GUI 提供了兩種使用 input 元件的方式：透過 InkField 動態欄位元件或直接使用個別元件。以下是兩種方式的詳細差異說明：

使用 InkField 的優勢

1. 統一的欄位管理

<!-- 使用 InkField - 推薦方式 -->
<InkField
  :field="{
    id: 'title',
    type: 'text',
    name: '標題',
    placeholder: '請輸入標題',
    limit: [10, 100],
    max: 3,
    description: '請輸入文章標題'
  }"
  :required="true"
  :disabled="false"
  @inkChanged="handleChange"
/>

2. 自動多項目管理

顯示欄位標題
自動處理多項目輸入的新增/刪除
自動管理 valueIndex 和 inputTotal
自動處理表單驗證陣列
自動顯示新增按鈕和刪除按鈕

3. 內建的 InkFieldMessage 支援

4. 簡化的配置

只需要設定 field 物件，自動選擇對應元件
統一的屬性介面，減少重複配置
自動處理元件間的依賴關係

5. 更好的維護性

欄位配置集中管理
統一的驗證規則
一致的錯誤處理

直接使用個別元件的場景

1. 需要高度自定義

<!-- 直接使用 InkText -->
<InkText
  :field="{
    id: 'customTitle',
    type: 'text',
    placeholder: '自定義標題'
  }"
  :valueIndex="0"
  :inputTotal="1"
  :required="true"
  :disabled="false"
  @removeInputItemFn="handleRemove"
/>

2. 複雜的互動邏輯

需要自定義事件處理
需要特殊的驗證邏輯
需要與其他元件深度整合

3. 效能考量

只需要單一輸入元件
避免不必要的動態載入開銷

動態新增/刪除輸入項目的差異

使用 InkField（自動處理）：

<InkField
  :field="{
    id: 'keywords',
    type: 'text',
    name: '關鍵字',
    max: 5  // 最多 5 個項目
  }"
/>
<!-- 自動顯示新增按鈕，當項目數量 < max 時 -->
<!-- 自動顯示刪除按鈕，當項目數量 > 1 時 -->
<!-- 自動管理 valueIndex 和 inputTotal -->

InkFieldMessage

InkFieldMessage 是 InkField 內建的欄位說明元件，用於顯示欄位的詳細說明文字。
可單獨使用

基本用法：

<InkFieldMessage :descriptionText="'請輸入有效的電子郵件地址'" />

屬性說明： | 屬性名稱 | 類型 | 預設值 | 說明 | |---------|------|--------|------| | descriptionText | string | '' | 欄位說明文字，支援 HTML 格式 |

功能特色：

支援 HTML 格式的說明文字
自動換行和斷字處理
統一的樣式設計
與 InkField 完美整合

使用場景：

欄位使用說明
格式要求說明
注意事項提醒
範例文字展示

選擇建議

| 使用場景 | 推薦方式 | 原因 | |---------|----------|------| | 表單欄位管理 | InkField | 統一的欄位管理，簡化配置 | | 多項目輸入 | InkField | 自動處理多項目邏輯 | | 動態表單 | InkField | 根據配置自動渲染元件 | | 需要欄位說明 | InkField | 內建 InkFieldMessage 支援 | | 單一輸入元件 | 直接使用對應的 input 元件 | 減少不必要的複雜度 |

InkErrorMessage

InkErrorMessage 是用於顯示表單驗證錯誤訊息的元件，通常與其他 input 元件配合使用。

基本用法

<InkErrorMessage v-if="errorMessage" :errorText="errorMessage" />

屬性說明

| 屬性名稱 | 類型 | 必填 | 預設值 | 說明 | |---------|------|------|--------|------| | errorText | string | 否 | '' | 錯誤訊息文字 |

功能特色

統一的錯誤訊息樣式
自動換行和斷字處理
支援條件渲染（通常與 v-if 配合使用）
與 vee-validate 完美整合

使用場景

表單驗證錯誤顯示
必填欄位提示
格式錯誤提示
自定義錯誤訊息

樣式說明

使用 tw-error-message 類別
預設為紅色錯誤文字樣式
支援自動換行（tw-break-all）
區塊級元素（tw-block）

InkText

InkText 提供基本的文字輸入功能，支援驗證和字數限制。通常透過 InkField 元件使用。

基本用法

<InkText
  :field="{
    id: 'title',
    type: 'text',
    placeholder: '請輸入標題',
    limit: [10, 100],
    prefix: '標題：',
    suffix: '字'
  }"
  :required="true"
  :disabled="false"
  @removeInputItemFn="handleRemove"
/>

屬性說明

| 屬性名稱 | 類型 | 必填 | 預設值 | 說明 | |---------|------|------|--------|------| | field | TextSharp | 是 | - | 欄位設定物件 | | required | boolean | 否 | false | 是否必填 | | disabled | boolean | 否 | false | 是否禁用 | | valueIndex | number | 否 | 0 | 值索引（多項目時使用） | | inputTotal | number | 否 | 0 | 輸入項目總數 | | inputBind | object | 否 | {} | 額外的輸入綁定屬性 |

field 物件結構（TextSharp）

請見 InkField 的 field 物件結構

功能特色

支援單行文字輸入
支援字數限制驗證
支援前綴和後綴文字
支援多項目輸入（透過 InkField）
整合 vee-validate 驗證

驗證規則

required: 必填驗證
wordLimit: 字數限制驗證（使用 field.limit 設定）

InkUrl

InkUrl 提供 URL 格式的輸入功能，自動驗證 URL 格式。通常透過 InkField 元件使用。

基本用法

<InkUrl
  :field="{
    id: 'website',
    type: 'url',
    name: '網站網址',
    placeholder: '請輸入網站網址',
    prefix: 'https://'
  }"
  :required="true"
  :disabled="false"
  @removeInputItemFn="handleRemove"
/>

屬性說明

請見 InkText 的屬性說明
與 InkText 相同，但 field.type 必須為 'url'

field 物件結構（UrlSharp）

請見 InkField 的 field 物件結構

功能特色

支援 URL 格式輸入
自動驗證 URL 格式
支援多項目輸入（透過 InkField）
整合 vee-validate 驗證

驗證規則

required: 必填驗證
url: URL 格式驗證（必須以 http:// 或 https:// 開頭）

InkTextarea

InkTextarea 提供多行文字輸入功能，支援字數統計和驗證。通常透過 InkField 元件使用。

基本用法

<InkTextarea
  :field="{
    id: 'content',
    type: 'textarea',
    name: '內容',
    placeholder: '請輸入內容',
    limit: [10, 1000],
    description: '請詳細描述內容'
  }"
  :required="true"
  :disabled="false"
  @removeInputItemFn="handleRemove"
/>

屬性說明

請見 InkText 的屬性說明
與 InkText 相同，但 field.type 必須為 'textarea'

field 物件結構（TextareaSharp）

請見 InkField 的 field 物件結構

功能特色

支援多行文字輸入
自動顯示字數統計
支援字數限制驗證
預設 5 行高度
支援多項目輸入（透過 InkField）
整合 vee-validate 驗證

驗證規則

required: 必填驗證
wordLimit: 字數限制驗證（使用 field.limit 設定）

InkSelect

InkSelect 是基於 Vue Select 的組件封裝。
InkSelect 提供下拉選單功能，支援搜尋、無限滾動和階層選項。通常透過 InkField 元件使用。

基本用法

<InkSelect
  :field="{
    id: 'category',
    type: 'select',
    name: '分類',
    placeholder: '請選擇分類',
    options: [
      { key: 1, name: '分類一' },
      { key: 2, name: '分類二' }
    ],
    total: 2,
    choosable: [1],
    hierarchy: true
  }"
  :inputBind="{
    options: [
      { key: 1, name: '分類一', depth: 0 },
      { key: 2, name: '分類二', depth: 1 }
    ],
    label: 'name',
    valueKey: 'key',
    hasNextPage: false,
    infiniteFn: () => {},
    activeStyle: true
  }"
  :required="true"
  :disabled="false"
  :valueIndex="0"
  :inputTotal="1"
  @removeInputItemFn="handleRemove"
/>

屬性說明

請見 InkText 的屬性說明
與 InkText 相同，但 field.type 必須為 'select'

field 物件結構（SelectSharp）

請見 InkField 的 field 物件結構

inputBind 物件結構（SelectInputBind）

以下皆為非必填項目

InkSelect 與 InkHashtag 通用項目

| 屬性名稱 | 類型 | 屬性來自套件 | 預設值 | 說明 | | ------- | -- | ----------- | ----- | --- | | label | string | 是 | 'name' | 顯示標籤欄位（選項字串用的 key）| | activeStyle | boolean | 否 | false | 是否啟用活躍樣式，通常在 filter 功能時啟用 | | autoscroll | boolean | 是 | false | 請見第三方套件 props 說明 |

InkSelect 項目

| 屬性名稱 | 類型 | 屬性來自套件 | 預設值 | 說明 | | ------- | -- | ----------- | ----- | --- | | options | SelectOptions[] string[] number[] | 是 | [] | 選項陣列 | | hasNextPage | boolean | 否 | false | 是否有下一頁（用於無限滾動功能） | | optionDivider | number[] | 否 | [] | 選項分隔線，最多可填入 [0,1,2] | | openFn | () => void | 否 | undefined | 開啟事件函數，在 Vue Select 的 onOpen 觸發 | | closeFn | () => void | 否 | undefined | 關閉事件函數，在 Vue Select 的 onClose 觸發 | | infiniteFn | () => void | 否 | undefined | 無限滾動函數 | | reduce | (option: UnKnownOptions) => SelectReduceReturn | 是 | (option) => option.key | 請見第三方套件 props 說明 | | searchable | boolean | 是 | false | 請見第三方套件 props 說明 | | selectable | (option: UnKnownOptions) => boolean | 是 | (option) => !option.disabled | 選擇條件函數，讀取 option.disabled 的值。請見第三方套件 props 說明 | | clearable | boolean | 是 | required ? false : !disabled| 當該欄位為避填項目，不可清除欄位值。欄位的 disabled 為 true 時也不可清除欄位值 | | filterable | boolean | 是 | false | 請見第三方套件 props 說明 | | inputId | string | 是 | 使用field.id 與欄位 value 的 index 組合而成，例如：fieldId[0],fieldId[1] | 請見第三方套件 props 說明 |

{
  options: [],              
  label: 'name',            
  hasNextPage: false,       
  activeStyle: false,       
  optionDivider: [],        
  openFn: () => {},         
  closeFn: () => {},        
  infiniteFn: () => {},     
  reduce: (item) => item.key,  
  filterable: false,        
  autoscroll: false,        
  searchable: false,        
  selectable: (option) => !option.disabled
}

options 物件結構（SelectOptions）

物件結構（SelectOptions）

{
  key: 'value',             // 選項值（必填），用於識別選項的唯一值
  name: '顯示名稱',         // 顯示名稱（必填），在選單中顯示的文字
  disabled: false,          // 是否禁用（可選），預設為 false
  depth: 0,                // 階層深度（可選），用於顯示階層結構，0 為最上層，每增加 1 代表下一層
  own: false,               // 是否為自有選項（可選），用於特殊標記
  status: true,             // 選項狀態（可選），預設為 true
  children: [],             // 子選項陣列（可選），用於階層結構
  total: 0,                 // 子選項總數（可選），用於顯示子項目數量
  [key: string]: unknown    // 其他自定義屬性（可選），可根據需求添加任意屬性
}

key key 可更改，但 inputBind.reduce 需一起修改
name Key 可更改，但 inputBind.label 需一起修改

Array of strings or Array of numbers 結構

如果 options value 是 string[] or number[]，需調整 reduce 為 reduce: (option) => option

階層結構範例：

options: [
  {
    key: 1,
    name: '分類一',
    depth: 0,
    children: [
      {
        key: 11,
        name: '子分類一',
        depth: 1
      }
    ]
  },
  {
    key: 2,
    name: '分類二',
    depth: 0,
    disabled: true
  }
]

功能特色

vue-select Props 提供的 clearable，若欄位 required、disabled 為 true，clearable 預設會是 false
支援搜尋功能
支援無限滾動載入
支援階層選項（透過 depth 屬性）
支援自定義圖標
支援選項分隔線
支援選項禁用狀態
支援值轉換函數
整合 vee-validate 驗證

驗證規則

required: 必填驗證

InkCheckbox

InkCheckbox 提供複選框功能，支援多選和無限滾動。通常透過 InkField 元件使用。

基本用法

<InkCheckbox
  :field="{
    id: 'tags',
    type: 'checkbox',
    name: '標籤',
    options: [
      { key: 1, name: '標籤一' },
      { key: 2, name: '標籤二' }
    ],
    total: 2,
    choosable: [1, 2],
    hierarchy: true
  }"
  :inputBind="{
    options: [
      { key: 1, name: '標籤一', depth: 0 },
      { key: 2, name: '標籤二', depth: 1, disabled: false }
    ],
    label: 'name',
    valueKey: 'key',
    hasNextPage: false,
    infiniteFn: () => {}
  }"
  :required="true"
  :disabled="false"
  :valueIndex="0"
  :inputTotal="1"
  @removeInputItemFn="handleRemove"
/>

屬性說明

請見 InkText 的屬性說明
與 InkText 相同，但 field.type 必須為 'checkbox'

field 物件結構（CheckBoxSharp）

請見 InkField 的 field 物件結構

inputBind 物件結構（CheckBoxInputBind）

{
  options: [],              // 選項陣列
  label: 'name',            // 顯示標籤欄位，選項字串使用的 key
  valueKey: 'key',          // 值欄位，選項 value 使用的 key
  hasNextPage: false,       // 是否有下一頁（可選）
  infiniteFn: () => {}      // 無限滾動函數（可選）
}

options 物件結構（CheckBoxOptions）

請見 InkSelect 的 options 物件結構
key key 與 inputBind.valueKey 相同即可
name Key 與 inputBind.label 相同即可
description 可放 description 相關文字，使用 v-html 方式渲染

自定義項目排列樣式

有提供以下兩個 css variable 做樣式客製化排列

.form-checks,
.form-radios{
  --checkRadioWidth:auto;
  --checkRadioFlexDirection:row;
}

功能特色

支援多選功能
支援無限滾動載入
支援階層選項（透過 depth 屬性）
支援禁用個別選項
支援自定義標籤和值欄位
整合 vee-validate 驗證

驗證規則

required: 必填驗證

InkRadio

InkRadio 提供單選框功能，支援無限滾動。通常透過 InkField 元件使用。

基本用法

<InkRadio
  :field="{
    id: 'gender',
    type: 'radio',
    name: '性別',
    options: [
      { key: 'male', name: '男性' },
      { key: 'female', name: '女性' }
    ],
    total: 2
  }"
  :inputBind="{
    options: [
      { key: 'male', name: '男性' },
      { key: 'female', name: '女性', disabled: false }
    ],
    label: 'name',
    valueKey: 'key',
    hasNextPage: false,
    infiniteFn: () => {}
  }"
  :required="true"
  :disabled="false"
  :valueIndex="0"
  :inputTotal="1"
  @removeInputItemFn="handleRemove"
/>

屬性說明

請見 InkText 的屬性說明
與 InkText 相同，但 field.type 必須為 'radio'

field 物件結構（RadioSharp）

請見 InkField 的 field 物件結構

inputBind 物件結構（RadioInputBind）

請見 InkCheckbox 的 inputBind 物件結構（CheckBoxInputBind）

options 物件結構（RadioOptions）

請見 InkCheckbox 的 options 物件結構 注意： Radio 選項不支援 depth、children 和 total 屬性，因為單選框不支援階層結構。

功能特色

支援單選功能
支援無限滾動載入
支援禁用個別選項
支援自定義標籤和值欄位
整合 vee-validate 驗證

驗證規則

required: 必填驗證

InkSwitch

InkSwitch 提供開關切換功能。通常透過 InkField 元件使用。

基本用法

<InkSwitch
  :field="{
    id: 'notification',
    type: 'switch',
    name: '通知設定',
    description: '是否啟用通知功能'
  }"
  :required="true"
  :disabled="false"
  @removeInputItemFn="handleRemove"
  @inkChanged="handleChange"
/>

屬性說明

請見 InkText 的屬性說明
與 InkText 相同，但 field.type 必須為 'switch'

field 物件結構（SwitchSharp）

請見 InkField 的 field 物件結構

功能特色

提供開關切換功能
支援 inkChanged 事件，當觸發 click 會觸發該事件
自動處理布林值轉換
整合 vee-validate 驗證

驗證規則

required: 必填驗證

InkElConfigProvider

InkElConfigProvider 為 Element Plus 提供的配置。

基本用法

<InkElConfigProvider>
  <InkDatetime />
  <InkDatetimerng />
</InkElConfigProvider>

功能說明

自動根據 Inkmagine GUI 的語言設定配置 Element Plus
支援 zh-tw、en-us、ja-jp 三種語言
用於 InkDatetime 和 InkDatetimerng 組件

InkDatetime

InkDatetime 提供日期和時間選擇功能，基於 Element Plus 的 DatePicker。通常透過 InkField 元件使用。

基本用法

<InkDatetime
  :field="{
    id: 'publishTime',
    type: 'datetime',
    name: '發布時間',
    placeholder: '請選擇發布時間',
    description: '選擇文章發布的時間'
  }"
  :inputBind="{
    type: 'datetime',
    format: 'YYYY/MM/DD HH:mm',
    timezone: 'Asia/Taipei',
    restrict: {
      restrictType: 'FUTURE',
      shiftSecond: 0
    },
    isClearable: true,
    popperClass: 'custom-popper'
  }"
  :required="true"
  :disabled="false"
  @removeInputItemFn="handleRemove"
  @inkChanged="handleChange"
/>

屬性說明

請見 InkText 的屬性說明
與 InkText 相同，但 field.type 必須為 'datetime' | 'date'

field 物件結構（DatetimeSharp）

請見 InkField 的 field 物件結構

inputBind 物件結構（DatetimePickerInputBind）

{
  timezone: 'Asia/Taipei',  // 時區（必填）
  type: 'datetime',         // 類型：'year' | 'month' | 'date' | 'datetime' | 'week'（可選）與 field.type 同步
  format: 'YYYY/MM/DD HH:mm', // 顯示格式（可選）
  isClearable: true,       // 是否可清除（可選）
  restrict: {              // 時間限制（可選）
    restrictType: 'unlimited', // 'past' | 'future' | 'unlimited'，default is 'unlimited'
    shiftSecond: 0          // 時間偏移（秒）
  },
  clearable: false,         // 清除按鈕（可選）
  teleported: true         // 是否傳送到 body（可選）
}

功能特色

支援 inkChanged 事件，當 useField value change 時觸發
支援日期和日期時間選擇
支援時區設定
支援時間限制（過去、未來、無限制）
支援清除功能
支援自定義格式
支援 "現在" 按鈕快速設定
整合 vee-validate 驗證

驗證規則

required: 必填驗證
datetimeRestrict: 日期時間限制驗證

InkDatetimerng

InkDatetimerng 提供日期時間範圍選擇功能。通常透過 InkField 元件使用。

基本用法

<InkDatetimerng
  :field="{
    id: 'publishRange',
    type: 'datetimerng',
    name: '發布時間範圍',
    limit: [1640995200, 1672531200],  // 最小和最大時間戳
    description: '選擇文章發布的時間範圍'
  }"
  :inputBind="{
    type: 'datetime',
    format: 'YYYY/MM/DD HH:mm',
    timezone: 'Asia/Taipei',
    isClearable: true,
    activeStyle: true,
    popperClass: 'custom-popper'
  }"
  :required="true"
  :disabled="false"
  @removeInputItemFn="handleRemove"
  @inkChanged="handleChange"
/>

屬性說明

請見 InkText 的屬性說明
與 InkText 相同，但 field.type 必須為 'datetimerng' | 'daterng'

field 物件結構（DatetimerngSharp）

請見 InkField 的 field 物件結構

inputBind 物件結構（DatetimerngInputBind）

{
  timezone: 'Asia/Taipei',  // 時區（必填）
  type: 'datetime',         // 類型：'year' | 'month' | 'date' | 'datetime' | 'week'（可選），對應 field.type 預設是 'datetime'
  format: 'YYYY/MM/DD HH:mm', // 顯示格式（可選）
  isClearable: true,       // 是否可清除（可選）
  activeStyle: false,       // 是否啟用活躍樣式（可選）
  clearable: false,         // 清除按鈕（可選）
  teleported: true         // 是否傳送到 body（可選）
}

功能特色

支援 inkChanged 事件，當 useField value change 時觸發
如果 field.type 為 'daterng'，結束時間會設定為當日的 23:59:59
支援日期範圍和日期時間範圍選擇
支援時區設定
支援時間範圍限制
支援清除功能
支援自定義格式
支援 "現在" 按鈕快速設定
自動處理開始時間和結束時間的關聯驗證
整合 vee-validate 驗證

驗證規則

required: 必填驗證
datetimerngStartLimit: 開始時間限制驗證
datetimerngEndLimit: 結束時間限制驗證

InkHashtag

InkHashtag 是基於 Vue Select 的組件封裝。
InkHashtag 提供標籤輸入功能，支援創建新標籤和選擇現有標籤。通常透過 InkField 元件使用。

基本用法

<InkHashtag
  :field="{
    id: 'tags',
    type: 'hashtag',
    name: '標籤',
    placeholder: '請輸入標籤',
    limit: [1, 10],
    description: '請選擇或創建相關標籤'
  }"
  :inputBind="{
    options: [
      { key: 1, name: '標籤一' },
      { key: 2, name: '標籤二' }
    ],
    label: 'name',
    valueKey: 'key',
    activeStyle: true,
    noDrop: false,
    loading: false
  }"
  :required="true"
  :disabled="false"
  @removeInputItemFn="handleRemove"
/>

屬性說明

請見 InkText 的屬性說明
與 InkText 相同，但 field.type 必須為 'hashtag'

field 物件結構（HashtagSharp）

請見 InkField 的 field 物件結構

inputBind 物件結構（HashtagInputBind）

請查看 InkSelect 的 InkSelect 與 InkHashtag 通用項目

InkHashtag 項目

| 屬性名稱 | 類型 | 屬性來自套件 | 預設值 | 說明 | | ------- | -- | ----------- | ----- | --- | | options | HashtagOptions[] | 是 | [] | 選項陣列 | | clearable | boolean | 是 | tue | 有利用第三方套件 slots #selected-option 修改以選項目的 html 結構，達到是否顯示清除按鈕 | | searchable | boolean | 是 | true | 請見第三方套件 props 說明 | | inputId | string | 是 | 使用 field.id，例如：fieldId | 請見第三方套件 props 說明 | | taggable | boolean | 是 | 使用 field.limit，!field.limit | 是否可透過 searchInput 增加沒有的選項，若 field.limit 為 false，則可增加沒有的選項| | filterable | boolean | 是 | 使用 field.limit，field.limit | 請見第三方套件 props 說明 | | multiple | boolean | 是，且不可改 | true | 多選欄位 |

該元件是否顯示清除按鈕，是透過 disabled，如果 value 為 true，則不顯示清除按鈕

{
  options: [],
  label: 'name',
  activeStyle: false,
  clearable: true,
  searchable: true,
  autoscroll: false,
}

options 物件結構（HashtagOptions）

- 請見 InkSelect 的 options 物件結構
**注意：** Hashtag 選項不支援 `disabled`、`depth`、`children` 和 `total` 屬性，因為標籤功能主要用於選擇和創建，不需要階層結構或禁用狀態。

#### 功能特色
- 支援創建新標籤
- 支援選擇現有標籤
- 支援多選功能
- 支援標籤數量限制
- 支援禁用狀態
- 支援自定義標籤格式
- 支援搜尋功能
- 支援載入狀態
- 整合 vee-validate 驗證

#### 驗證規則
- `required`: 必填驗證
- `itemLimit`: 標籤數量限制驗證（使用 `field.limit` 設定）

#### 使用場景
- 文章標籤
- 產品分類
- 用戶興趣標籤
- 搜尋關鍵字

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Inkmagine GUI 工具

安裝需求

安裝

可用樣式使用說明

tailwind config

全域設定說明

vue-i18n language

支援的語言

How to import component

容器使用說明

InkNavbar

基本用法

屬性說明

功能說明

注意事項

InkSidebar

基本用法

進階用法（使用插槽）

屬性說明

事件說明

選單結構範例

功能說明

注意事項

相關組件說明

組件關係

使用說明

組件使用說明

InkButton

基本連結按鈕

帶圖標的按鈕 (36px)

中等尺寸按鈕 (32px)

小尺寸按鈕 (24px)

圖標按鈕 (36px)

中等尺寸圖標按鈕 (32px)

禁用狀態

載入狀態

InkButton 屬性說明

InkMenu

基本用法

進階用法

多個選單項目容器

InkMenu 相關組件說明

組件關係

使用說明

事件

樣式

InkDisclosure

基本用法

進階用法 - 群組展開

InkDisclosure 相關組件說明

組件關係

使用說明

樣式

vInkTooltip

基本用法

功能說明

注意事項

組件關係

InkVTooltip

基本用法

禁用狀態

屬性說明

插槽說明

功能說明

組件關係

注意事項

InkBadge

基本用法

屬性說明

功能說明

樣式

InkSpinner

基本用法

屬性說明