全局配置

三个适配器都由同一个配置对象驱动，该对象由 @thl-ui/core 中的 createThl() 创建。你可以将它传给 ThlProvider（React）、app.use(ThlUI, …)（Vue）或 provideThlUI(…)（Angular）。

选项

选项	类型	默认值	说明
prefix	string	'thl'	CSS 类名和自定义属性前缀（.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 会将所有圆角 token 设为 0
zIndex	number	1000	浮层基准值：dropdown = base，modal = base + 50，toast = base + 80
locale	string	'en'	当前语言
fallbackLocale	string	'en'	缺少某个 key 时使用
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（key 为 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() 的界面而已。

组件默认值

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 };
  }
}

共享同一个实例

自行创建实例，即可与非 UI 代码（store、service、微前端）共享：

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

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

<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（store）和 i18n。