@aithe/aithe-ui 26.2.2

package/docs/framework-integration.md

@@ -0,0 +1,422 @@
+# 框架集成 / Framework Integration
+
+Aithe UI 基于 Web Components 标准（Custom Elements + Shadow DOM），可在任何前端框架中使用。本文档介绍在主流框架中的集成方式和注意事项。
+
+---
+
+## 通用原则
+
+### Web Components 的框架无关性
+
+Web Components 是浏览器原生标准，不依赖任何框架。Aithe UI 组件注册后即可像原生 HTML 元素一样使用：
+
+```html
+<aithe-button type="primary">Click</aithe-button>
+```
+
+### 需要注意的差异
+
+| 特性             | 说明                                                                                    |
+| ---------------- | --------------------------------------------------------------------------------------- |
+| **属性 vs 属性** | HTML 属性（attribute）只能传字符串；复杂类型（对象/数组）需通过 JS 属性（property）设置 |
+| **事件监听**     | 自定义事件（`aithe-*`）默认 composed + bubbles，可穿透 Shadow DOM                       |
+| **样式封装**     | Shadow DOM 隔离内部样式，外部 CSS 无法直接选择内部元素；使用 CSS 变量覆盖               |
+| **双向绑定**     | Web Components 不原生支持双向绑定，需手动监听事件并更新值                               |
+
+---
+
+## React
+
+### 基本使用
+
+```tsx
+import 'aithe-ui';
+import { setAitheTheme } from 'aithe-ui';
+
+function App() {
+  return (
+    <div>
+      <aithe-button type="primary" onClick={() => alert('clicked')}>
+        Click Me
+      </aithe-button>
+    </div>
+  );
+}
+```
+
+### 传递复杂属性
+
+React 对 Web Components 的属性传递有限制：HTML 属性只能传字符串。对于对象/数组属性，需使用 `ref`：
+
+```tsx
+function SelectExample() {
+  const selectRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    if (selectRef.current) {
+      selectRef.current.options = [
+        { label: 'Option A', id: 'a' },
+        { label: 'Option B', id: 'b' },
+      ];
+    }
+  }, []);
+
+  return <aithe-select ref={selectRef}></aithe-select>;
+}
+```
+
+### 监听自定义事件
+
+React 不原生支持自定义事件监听，需使用 `ref` + `addEventListener`：
+
+```tsx
+function ThemeExample() {
+  const pickerRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    const el = pickerRef.current;
+    if (!el) return;
+
+    const handler = (e: Event) => {
+      console.log('Theme changed:', (e as CustomEvent).detail.theme);
+    };
+    el.addEventListener('aithe-theme-change', handler);
+    return () => el.removeEventListener('aithe-theme-change', handler);
+  }, []);
+
+  return <aithe-theme-picker ref={pickerRef}></aithe-theme-picker>;
+}
+```
+
+### 推荐封装模式
+
+为常用组件创建 React 包装器，简化 API：
+
+```tsx
+// AitheButtonReact.tsx
+import 'aithe-ui';
+
+interface AitheButtonProps {
+  type?: 'primary' | 'default' | 'dashed' | 'text' | 'link';
+  size?: 'small' | 'medium' | 'large';
+  disabled?: boolean;
+  loading?: boolean;
+  danger?: boolean;
+  block?: boolean;
+  onClick?: () => void;
+  children: React.ReactNode;
+}
+
+export function AitheButton({
+  type = 'default',
+  size = 'medium',
+  disabled,
+  loading,
+  danger,
+  block,
+  onClick,
+  children,
+}: AitheButtonProps) {
+  const ref = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || !onClick) return;
+    const handler = () => onClick();
+    el.addEventListener('aithe-click', handler);
+    return () => el.removeEventListener('aithe-click', handler);
+  }, [onClick]);
+
+  return (
+    <aithe-button
+      ref={ref}
+      type={type}
+      size={size}
+      disabled={disabled || undefined}
+      loading={loading || undefined}
+      danger={danger || undefined}
+      block={block || undefined}
+    >
+      {children}
+    </aithe-button>
+  );
+}
+```
+
+---
+
+## Vue
+
+### 基本使用
+
+Vue 3 对 Web Components 有良好的原生支持：
+
+```vue
+<template>
+  <aithe-button type="primary" @click="handleClick">Click Me</aithe-button>
+</template>
+
+<script setup>
+import 'aithe-ui';
+
+function handleClick() {
+  console.log('clicked');
+}
+</script>
+```
+
+### 配置 Vue 识别自定义元素
+
+在 `vite.config.ts` 或 Vue 配置中声明 `aithe-` 前缀的元素为自定义元素：
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+
+export default defineConfig({
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: (tag) => tag.startsWith('aithe-'),
+        },
+      },
+    }),
+  ],
+});
+```
+
+### 传递复杂属性
+
+Vue 3 使用 `v-bind` 的 `.prop` 修饰符或 `:` 前缀传递 DOM 属性：
+
+```vue
+<template>
+  <!-- 使用 v-bind:prop 语法 -->
+  <aithe-select :options.prop="options" @aithe-change="handleChange"></aithe-select>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import 'aithe-ui';
+
+const options = ref([
+  { label: 'Option A', id: 'a' },
+  { label: 'Option B', id: 'b' },
+]);
+
+function handleChange(e) {
+  console.log('Selected:', e.detail);
+}
+</script>
+```
+
+### v-model 集成
+
+通过计算属性实现类似 `v-model` 的双向绑定：
+
+```vue
+<template>
+  <aithe-input :value="inputValue" @aithe-input="handleInput"></aithe-input>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import 'aithe-ui';
+
+const inputValue = ref('');
+
+function handleInput(e) {
+  inputValue.value = e.detail.value;
+}
+</script>
+```
+
+---
+
+## Angular
+
+### 基本使用
+
+在 `angular.json` 或组件中导入 Aithe UI：
+
+```ts
+// 在 main.ts 或组件中
+import 'aithe-ui';
+```
+
+### 配置自定义元素
+
+Angular 默认不识别非标准 HTML 标签，需在模块中配置：
+
+```ts
+// app.module.ts
+import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
+
+@NgModule({
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class AppModule {}
+```
+
+### 传递复杂属性
+
+Angular 通过 `[prop]` 绑定 DOM 属性：
+
+```html
+<aithe-select [options]="options"></aithe-select>
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  template: `
+    <aithe-select [options]="options"></aithe-select>
+  `,
+})
+export class ExampleComponent {
+  options = [
+    { label: 'Option A', id: 'a' },
+    { label: 'Option B', id: 'b' },
+  ];
+}
+```
+
+### 监听自定义事件
+
+使用 `@HostListener` 或 `(event)` 绑定：
+
+```html
+<aithe-theme-picker (aithe-theme-change)="onThemeChange($event)"></aithe-theme-picker>
+```
+
+```ts
+onThemeChange(event: CustomEvent) {
+  console.log('Theme:', event.detail.theme);
+}
+```
+
+---
+
+## Svelte
+
+### 基本使用
+
+Svelte 对 Web Components 支持良好：
+
+```svelte
+<script>
+import 'aithe-ui';
+</script>
+
+<aithe-button type="primary" on:aithe-click={handleClick}>
+  Click Me
+</aithe-button>
+```
+
+### 传递复杂属性
+
+Svelte 使用 `propname={value}` 语法传递属性：
+
+```svelte
+<script>
+import 'aithe-ui';
+
+const options = [
+  { label: 'Option A', id: 'a' },
+  { label: 'Option B', id: 'b' },
+];
+</script>
+
+<aithe-select options={options}></aithe-select>
+```
+
+### 监听事件
+
+```svelte
+<script>
+import 'aithe-ui';
+
+function handleChange(e) {
+  console.log('Selected:', e.detail);
+}
+</script>
+
+<aithe-select
+  options={options}
+  on:aithe-change={handleChange}
+></aithe-select>
+```
+
+---
+
+## 原生 JavaScript / 无框架
+
+### 基本使用
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <script type="module">
+      import 'aithe-ui';
+      import { setAitheTheme, setAitheLocale } from 'aithe-ui';
+
+      setAitheTheme('light');
+      setAitheLocale('en-US');
+    </script>
+  </head>
+  <body>
+    <aithe-button type="primary" id="myBtn">Click Me</aithe-button>
+
+    <script type="module">
+      const btn = document.getElementById('myBtn');
+      btn.addEventListener('aithe-click', (e) => {
+        console.log('Clicked!', e.detail);
+      });
+    </script>
+  </body>
+</html>
+```
+
+### 动态设置属性
+
+```js
+const select = document.querySelector('aithe-select');
+select.options = [
+  { label: 'Option A', id: 'a' },
+  { label: 'Option B', id: 'b' },
+];
+
+select.addEventListener('aithe-change', (e) => {
+  console.log('Selected:', e.detail);
+});
+```
+
+---
+
+## SSR 注意事项
+
+Aithe UI 组件依赖 DOM API（`document`、`window`），在 SSR 环境中需注意：
+
+1. **条件导入**：仅在客户端导入 Aithe UI
+2. **延迟初始化**：在 `onMounted` / `useEffect` / `afterViewInit` 中调用 `initializeAitheUI()`
+3. **主题注入**：`registerAitheTheme()` 内部检查 `typeof document`，SSR 时自动跳过
+
+```ts
+// Next.js / Nuxt 等框架中
+if (typeof window !== 'undefined') {
+  import('aithe-ui');
+}
+```
+
+---
+
+## 下一步
+
+- [快速上手](quickstart.md) — 安装和基本使用
+- [使用指南](guide.md) — 组件通用 API
+- [主题系统](theming.md) — 22 种内置主题
+- [国际化](i18n.md) — 多语言支持
+- [API 参考](api/summary.md) — 全部组件详细 API