グローバル設定

3 つのアダプターはすべて、@thl-ui/core の createThl() で作られる 1 つの設定オブジェクトで動作します。これを ThlProvider（React）、app.use(ThlUI, …)（Vue）、provideThlUI(…)（Angular）に渡します。

オプション

オプション	型	デフォルト	説明
prefix	string	'thl'	CSS クラスとカスタムプロパティの prefix（.thl-btn、--thl-theme）
theme	ThlSkin	'default'	12 種類のスキンのいずれか: default · green · yellow · red · purple · black と、それぞれの -dark（ダークなサイドバー）
colorMode	'light' | 'dark' | 'auto'	'light'	auto は prefers-color-scheme にリアルタイムで追従
layout	'vertical' | 'mini' | 'horizontal'	'vertical'	AppLayout のバリアント
fixedHeader	boolean	true	トップバーを固定
fixedSidebar	boolean	true	サイドバーを固定
size	'sm' | 'md' | 'lg'	'md'	基本フォントサイズとコントロールの高さ
radius	'sharp' | 'rounded'	'rounded'	sharp はすべての角丸トークンを 0 にします
zIndex	number	1000	オーバーレイの基準値: dropdown = base、modal = base + 50、toast = base + 80
locale	string	'en'	現在のロケール
fallbackLocale	string	'en'	キーが見つからないときに使用
locales	string[]	['en','vi','ja','zh']	言語切り替えに表示される一覧
messages	Record<locale, Messages>	{}	追加 / 上書きするメッセージ。組み込みのものとディープマージされます
loadLocale	(l) => Promise<Messages>	—	バンドルされていないロケールの遅延ローダー
components	Partial<ThlComponentDefaults>	下記参照	コンポーネントごとのデフォルト props
persist	boolean | { key }	false	theme / colorMode / locale / layout / fixed* / size / radius を localStorage（キー thl-ui-config）に保存
root	HTMLElement	<html>	data-thl-* 属性を受け取る要素
icons	IconRegistry	—	追加アイコンの登録（アダプターのオプション）

実行時に起きること

createThl() は設定をルート要素に data 属性として書き込みます。スタイルはすべてこれらの属性に反応するため、設定を変えてもコンポーネントが不必要に再レンダリングされることはありません。

<html lang="vi" dir="ltr"
      data-thl-theme="green-dark" data-thl-color-mode="dark" data-thl-layout="vertical"
      data-thl-size="md" data-thl-radius="rounded" data-thl-fixed-header data-thl-fixed-sidebar>

実行時に設定を変更する

Vue

<script setup lang="ts">
import { useThlConfig } from '@thl-ui/vue';
const { config, set } = useThlConfig();
</script>
<template>
  <ThlButton @click="set({ theme: 'purple', colorMode: 'dark' })">パープル · ダーク</ThlButton>
  <p>レイアウト: {{ config.layout }}</p>
</template>

React

import { useThlConfig, Button } from '@thl-ui/react';
const [config, set] = useThlConfig();
<Button onClick={() => set({ theme: 'purple', colorMode: 'dark' })}>パープル · ダーク</Button>

Angular

import { ThlConfigService } from '@thl-ui/angular';
readonly cfg = inject(ThlConfigService);
// テンプレート: {{ cfg.config().layout }}
toPurple() { this.cfg.set({ theme: 'purple', colorMode: 'dark' }); }

ライブ: グローバル設定を変更

<SettingsPanel>（AppLayout に内蔵）は、これと同じ set() 呼び出しのための UI にすぎません。

コンポーネントのデフォルト値

components はすべてのインスタンスに対するデフォルト props を設定します。明示的に指定した props が常に優先されます。

createThl({
  components: {
    Button: { rounded: true, size: 'sm' },
    Table: { pageSize: 25, pageSizes: [25, 50, 100], striped: true },
    Toast: { position: 'bottom-right', duration: 5000, max: 3 },
    Modal: { closeOnBackdrop: false, centered: true },
    Pagination: { maxPages: 5 },
    Sidebar: { breakpoint: 1024 },
  },
});

組み込みのデフォルト値:

{
  Toast: { position: 'top-right', duration: 3500, max: 5 },
  Table: { pageSize: 10, pageSizes: [10, 25, 50, 100], hover: true },
  Modal: { closeOnBackdrop: true, closeOnEsc: true },
  Pagination: { maxPages: 7 },
  Sidebar: { breakpoint: 1170 },
}

ThlComponentDefaults 型は declaration merging で拡張できます。

declare module '@thl-ui/core' {
  interface ThlComponentDefaults {
    MyWidget: { dense?: boolean };
  }
}

1 つのインスタンスを共有する

インスタンスを自分で作成すると、UI 以外のコード（ストア、サービス、マイクロフロントエンド）と共有できます。

import { createThl } from '@thl-ui/core';
export const thl = createThl({ locale: 'ja', persist: true });

thl.subscribe((c, prev) => { if (c.locale !== prev.locale) api.setLanguage(c.locale); });
thl.t('common.save');          // "保存"

<ThlProvider instance={thl}>…</ThlProvider>          // React
app.use(ThlUI, { instance: thl });                   // Vue
provideThlUI({ instance: thl });                      // Angular

ThlInstance の API: get()、set(patch)、subscribe(fn)、defaults(name, props)、t()、setLocale()、resolvedColorMode()、applyToDocument()、attach()、destroy()、さらに config（ストア）と i18n。