From e2fd72224321e1bd6284f93c3afa67f506a4f676 Mon Sep 17 00:00:00 2001
From: Uyarn <uyarnchen@gmail.com>
Date: Tue, 27 Oct 2026 12:39:32 +0800
Subject: [PATCH 1/4] fix: fix doc badge display result

---
 .../src/components/td-doc-badge/index.ts      | 26 ++++++++++++++++---
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/packages/site-components/src/components/td-doc-badge/index.ts b/packages/site-components/src/components/td-doc-badge/index.ts
index a1d19664f..e3b6fb66e 100644
--- a/packages/site-components/src/components/td-doc-badge/index.ts
+++ b/packages/site-components/src/components/td-doc-badge/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define, type Descriptor } from 'hybrids';
 import style from './style.less?inline';
 
 interface BadgeHost {
@@ -7,6 +7,24 @@ interface BadgeHost {
   color: string;
 }
 
+function attribute(defaultValue: string): Descriptor<BadgeHost, string> {
+  return {
+    value: (_host, value) => value ?? defaultValue,
+    connect: (host, key) => {
+      const attributeName = key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+      const syncAttribute = () => {
+        host[key] = host.getAttribute(attributeName) ?? defaultValue;
+      };
+      const observer = new MutationObserver(syncAttribute);
+
+      if (host.hasAttribute(attributeName)) syncAttribute();
+      observer.observe(host, { attributes: true, attributeFilter: [attributeName] });
+
+      return () => observer.disconnect();
+    },
+  };
+}
+
 function getColor(message: string): string {
   const percentage = parseFloat(message);
   if (percentage >= 90) {
@@ -20,9 +38,9 @@ function getColor(message: string): string {
 
 export default define<BadgeHost>({
   tag: 'td-doc-badge',
-  label: 'coverage',
-  message: '0%',
-  color: '',
+  label: attribute('coverage'),
+  message: attribute('0%'),
+  color: attribute(''),
   render: (host) => {
     const { label, message, color: defaultColor } = host;
     let color = defaultColor;

From 0e48fc393723652b5eb784207241832917d7614b Mon Sep 17 00:00:00 2001
From: Uyarn <uyarnchen@gmail.com>
Date: Tue, 27 Oct 2026 13:24:26 +0800
Subject: [PATCH 2/4] fix: fix component attribute configuration

---
 .../src/__tests__/attribute.spec.ts           | 55 ++++++++++++++++
 .../src/__tests__/td-doc-badge.spec.ts        | 51 +++++++++++++++
 .../src/__tests__/td-doc-content.spec.ts      |  5 +-
 .../src/__tests__/td-doc-header.spec.ts       |  4 ++
 .../src/__tests__/td-doc-popup.spec.ts        |  5 +-
 .../src/__tests__/td-select.spec.ts           | 64 +++++++++++++++++++
 .../src/components/td-avatar/index.ts         |  9 +--
 .../src/components/td-doc-aside/index.ts      |  4 +-
 .../src/components/td-doc-badge/index.ts      | 21 +-----
 .../src/components/td-doc-content/index.ts    |  6 +-
 .../src/components/td-doc-copy/index.ts       |  3 +-
 .../src/components/td-doc-footer/index.ts     |  4 +-
 .../src/components/td-doc-header/index.ts     | 21 ++----
 .../src/components/td-doc-layout/index.ts     |  3 +-
 .../src/components/td-doc-popup/index.ts      | 14 ++--
 .../src/components/td-doc-tabs/index.ts       |  6 +-
 .../src/components/td-header/index.ts         | 18 +++---
 .../td-header/td-collapse-menu/index.ts       | 10 +--
 .../src/components/td-logo/index.ts           |  2 +-
 .../src/components/td-select/index.ts         |  9 +--
 .../src/components/td-switch/index.ts         |  5 +-
 .../src/components/td-tooltip/index.ts        |  7 +-
 packages/site-components/src/utils/index.ts   | 32 ++++++++++
 23 files changed, 275 insertions(+), 83 deletions(-)
 create mode 100644 packages/site-components/src/__tests__/attribute.spec.ts
 create mode 100644 packages/site-components/src/__tests__/td-doc-badge.spec.ts
 create mode 100644 packages/site-components/src/__tests__/td-select.spec.ts

diff --git a/packages/site-components/src/__tests__/attribute.spec.ts b/packages/site-components/src/__tests__/attribute.spec.ts
new file mode 100644
index 000000000..9569f9a21
--- /dev/null
+++ b/packages/site-components/src/__tests__/attribute.spec.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { attribute, parseBoolean } from '../utils';
+
+interface AttributeHost extends HTMLElement {
+  enabled: boolean;
+}
+
+type ConnectedHost = AttributeHost & { __property_key__: boolean };
+
+describe('attribute descriptor', () => {
+  it('reads attributes added after element creation and observes updates', async () => {
+    const host = document.createElement('div') as unknown as ConnectedHost;
+    host.enabled = false;
+    host.setAttribute('enabled', '');
+
+    const descriptor = attribute(false, (value) => parseBoolean(value, false));
+    const cleanup = descriptor.connect?.(host, 'enabled' as '__property_key__', vi.fn());
+
+    expect(host.enabled).toBe(true);
+
+    host.setAttribute('enabled', 'false');
+    await new Promise((resolve) => setTimeout(resolve));
+    expect(host.enabled).toBe(false);
+
+    cleanup?.();
+  });
+
+  it('preserves properties when the attribute is absent', () => {
+    const host = document.createElement('div') as unknown as ConnectedHost;
+    host.enabled = true;
+
+    const descriptor = attribute(false, (value) => parseBoolean(value, false));
+    const cleanup = descriptor.connect?.(host, 'enabled' as '__property_key__', vi.fn());
+
+    expect(host.enabled).toBe(true);
+
+    cleanup?.();
+  });
+
+  it('composes an existing connect lifecycle', () => {
+    const host = document.createElement('div') as unknown as ConnectedHost;
+    host.enabled = false;
+    const lifecycleCleanup = vi.fn();
+    const connect = vi.fn(() => lifecycleCleanup);
+
+    const descriptor = attribute<boolean, AttributeHost>(false, undefined, { connect });
+    const cleanup = descriptor.connect?.(host, 'enabled' as '__property_key__', vi.fn());
+
+    expect(connect).toHaveBeenCalledOnce();
+
+    cleanup?.();
+    expect(lifecycleCleanup).toHaveBeenCalledOnce();
+  });
+});
diff --git a/packages/site-components/src/__tests__/td-doc-badge.spec.ts b/packages/site-components/src/__tests__/td-doc-badge.spec.ts
new file mode 100644
index 000000000..7db9fe04f
--- /dev/null
+++ b/packages/site-components/src/__tests__/td-doc-badge.spec.ts
@@ -0,0 +1,51 @@
+import { afterEach, describe, expect, it } from 'vitest';
+
+import '../components/td-doc-badge';
+
+async function waitForRender(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve));
+}
+
+describe('td-doc-badge', () => {
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('reads attributes set after element creation', async () => {
+    const badge = document.createElement('td-doc-badge');
+    badge.setAttribute('label', 'statements');
+    badge.setAttribute('message', '87.5%');
+    document.body.appendChild(badge);
+
+    await waitForRender();
+
+    expect(badge.shadowRoot?.querySelector('img')?.getAttribute('src')).toBe(
+      'https://img.shields.io/badge/statements-87.5%25-yellow',
+    );
+  });
+
+  it('updates when an attribute changes', async () => {
+    const badge = document.createElement('td-doc-badge');
+    document.body.appendChild(badge);
+    await waitForRender();
+
+    badge.setAttribute('message', '95%');
+    await waitForRender();
+
+    expect(badge.shadowRoot?.querySelector('img')?.getAttribute('src')).toBe(
+      'https://img.shields.io/badge/coverage-95%25-brightgreen',
+    );
+  });
+
+  it('preserves properties set before connection', async () => {
+    const badge = document.createElement('td-doc-badge') as HTMLElement & { message: string };
+    badge.message = '72%';
+    document.body.appendChild(badge);
+
+    await waitForRender();
+
+    expect(badge.shadowRoot?.querySelector('img')?.getAttribute('src')).toBe(
+      'https://img.shields.io/badge/coverage-72%25-yellow',
+    );
+  });
+});
diff --git a/packages/site-components/src/__tests__/td-doc-content.spec.ts b/packages/site-components/src/__tests__/td-doc-content.spec.ts
index 920b824ee..826a963f9 100644
--- a/packages/site-components/src/__tests__/td-doc-content.spec.ts
+++ b/packages/site-components/src/__tests__/td-doc-content.spec.ts
@@ -37,7 +37,10 @@ vi.mock('hybrids', () => ({
   html: mockHtml,
 }));
 
-vi.mock('@utils', () => ({ mobileBodyStyle: {} }));
+vi.mock('@utils', () => ({
+  attribute: vi.fn((value: unknown) => ({ value })),
+  mobileBodyStyle: {},
+}));
 vi.mock('../components/td-doc-content/style.less?inline', () => ({ default: '' }));
 
 describe('td-doc-content anchor scroll', () => {
diff --git a/packages/site-components/src/__tests__/td-doc-header.spec.ts b/packages/site-components/src/__tests__/td-doc-header.spec.ts
index efd9a7f55..07108c722 100644
--- a/packages/site-components/src/__tests__/td-doc-header.spec.ts
+++ b/packages/site-components/src/__tests__/td-doc-header.spec.ts
@@ -20,6 +20,10 @@ vi.mock('@config/locale', () => ({ getLocale: vi.fn(() => ({})) }));
 vi.mock('@config/spline', () => ({}));
 vi.mock('@images/history.svg?raw', () => ({ default: '' }));
 vi.mock('@utils', () => ({
+  attribute: vi.fn((value: unknown, _parse?: unknown, descriptor: Record<string, unknown> = {}) => ({
+    value,
+    ...descriptor,
+  })),
   isComponentPage: vi.fn(),
   isGlobalConfigPage: vi.fn(),
   mobileBodyStyle: {},
diff --git a/packages/site-components/src/__tests__/td-doc-popup.spec.ts b/packages/site-components/src/__tests__/td-doc-popup.spec.ts
index ca5eeeef5..5c50e5e79 100644
--- a/packages/site-components/src/__tests__/td-doc-popup.spec.ts
+++ b/packages/site-components/src/__tests__/td-doc-popup.spec.ts
@@ -28,7 +28,10 @@ vi.mock('hybrids', () => ({
 }));
 
 vi.mock('@popperjs/core', () => ({ createPopper: mockCreatePopper }));
-vi.mock('@utils', () => ({ parseBoolean: vi.fn((value: unknown) => Boolean(value)) }));
+vi.mock('@utils', () => ({
+  attribute: vi.fn((value: unknown) => ({ value })),
+  parseBoolean: vi.fn((value: unknown) => Boolean(value)),
+}));
 vi.mock('../components/td-doc-popup/style.less?inline', () => ({ default: '' }));
 
 interface PortalContainerMock {
diff --git a/packages/site-components/src/__tests__/td-select.spec.ts b/packages/site-components/src/__tests__/td-select.spec.ts
new file mode 100644
index 000000000..1ffe4a865
--- /dev/null
+++ b/packages/site-components/src/__tests__/td-select.spec.ts
@@ -0,0 +1,64 @@
+import { afterEach, describe, expect, it } from 'vitest';
+
+import '../components/td-select';
+
+interface SelectElement extends HTMLElement {
+  borderless: boolean;
+  value: string | number;
+  options: Array<{ label: string; value: string | number }>;
+}
+
+async function waitForRender(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve));
+}
+
+describe('td-select', () => {
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('reads attributes set after element creation', async () => {
+    const select = document.createElement('td-select') as SelectElement;
+    select.options = [
+      { label: 'One', value: '1' },
+      { label: 'Two', value: '2' },
+    ];
+    select.setAttribute('value', '2');
+    select.setAttribute('borderless', '');
+    document.body.appendChild(select);
+
+    await waitForRender();
+
+    expect(select.shadowRoot?.querySelector('input')?.value).toBe('Two');
+    expect(select.shadowRoot?.querySelector('.TDesign-select-input')?.classList).toContain(
+      'TDesign-select-input--borderless',
+    );
+  });
+
+  it('updates when the value attribute changes', async () => {
+    const select = document.createElement('td-select') as SelectElement;
+    select.options = [
+      { label: 'One', value: '1' },
+      { label: 'Two', value: '2' },
+    ];
+    document.body.appendChild(select);
+    await waitForRender();
+
+    select.setAttribute('value', '1');
+    await waitForRender();
+
+    expect(select.shadowRoot?.querySelector('input')?.value).toBe('One');
+  });
+
+  it('preserves properties set before connection', async () => {
+    const select = document.createElement('td-select') as SelectElement;
+    select.options = [{ label: 'Two', value: 2 }];
+    select.value = 2;
+    document.body.appendChild(select);
+
+    await waitForRender();
+
+    expect(select.value).toBe(2);
+    expect(select.shadowRoot?.querySelector('input')?.value).toBe('Two');
+  });
+});
diff --git a/packages/site-components/src/components/td-avatar/index.ts b/packages/site-components/src/components/td-avatar/index.ts
index 91ba41a1e..1ee0e829a 100644
--- a/packages/site-components/src/components/td-avatar/index.ts
+++ b/packages/site-components/src/components/td-avatar/index.ts
@@ -1,4 +1,5 @@
 import { html, define } from 'hybrids';
+import { attribute } from '@utils';
 import style from './style.less?inline';
 
 interface AvatarProps {
@@ -10,10 +11,10 @@ interface AvatarProps {
 
 export default define<AvatarProps>({
   tag: 'td-avatar',
-  content: '',
-  username: '',
-  src: '',
-  href: '',
+  content: attribute(''),
+  username: attribute(''),
+  src: attribute(''),
+  href: attribute(''),
   render: ({ content, username, src, href }) => {
     const defaultSrc = `https://avatars.githubusercontent.com/${username}`;
     const defaultHref = `https://github.com/${username}`;
diff --git a/packages/site-components/src/components/td-doc-aside/index.ts b/packages/site-components/src/components/td-doc-aside/index.ts
index b6ab615b6..061345e65 100644
--- a/packages/site-components/src/components/td-doc-aside/index.ts
+++ b/packages/site-components/src/components/td-doc-aside/index.ts
@@ -1,7 +1,7 @@
 import { html, dispatch, define, type Component } from 'hybrids';
 import menuFoldIcon from '@images/menu-fold.svg?raw';
 import menuUnfoldIcon from '@images/menu-unfold.svg?raw';
-import { patchShadowDomIntoDom } from '@utils';
+import { attribute, patchShadowDomIntoDom } from '@utils';
 import style from './style.less?inline';
 
 const replaceStateEvent = new CustomEvent('replaceState');
@@ -130,7 +130,7 @@ const asideComponent = {
   routerList: {
     value: (_host: AsideHost & HTMLElement, v?: NavItem[]) => v || [],
   },
-  title: '',
+  title: attribute(''),
   patchDom: {
     value: (_host: AsideHost & HTMLElement, v?: boolean) => v || false,
     connect: patchShadowDomIntoDom,
diff --git a/packages/site-components/src/components/td-doc-badge/index.ts b/packages/site-components/src/components/td-doc-badge/index.ts
index e3b6fb66e..203add76c 100644
--- a/packages/site-components/src/components/td-doc-badge/index.ts
+++ b/packages/site-components/src/components/td-doc-badge/index.ts
@@ -1,4 +1,5 @@
-import { html, define, type Descriptor } from 'hybrids';
+import { html, define } from 'hybrids';
+import { attribute } from '@utils';
 import style from './style.less?inline';
 
 interface BadgeHost {
@@ -7,24 +8,6 @@ interface BadgeHost {
   color: string;
 }
 
-function attribute(defaultValue: string): Descriptor<BadgeHost, string> {
-  return {
-    value: (_host, value) => value ?? defaultValue,
-    connect: (host, key) => {
-      const attributeName = key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
-      const syncAttribute = () => {
-        host[key] = host.getAttribute(attributeName) ?? defaultValue;
-      };
-      const observer = new MutationObserver(syncAttribute);
-
-      if (host.hasAttribute(attributeName)) syncAttribute();
-      observer.observe(host, { attributes: true, attributeFilter: [attributeName] });
-
-      return () => observer.disconnect();
-    },
-  };
-}
-
 function getColor(message: string): string {
   const percentage = parseFloat(message);
   if (percentage >= 90) {
diff --git a/packages/site-components/src/components/td-doc-content/index.ts b/packages/site-components/src/components/td-doc-content/index.ts
index 1f5c0a782..adf8650bb 100644
--- a/packages/site-components/src/components/td-doc-content/index.ts
+++ b/packages/site-components/src/components/td-doc-content/index.ts
@@ -1,5 +1,5 @@
 import { html, define } from 'hybrids';
-import { mobileBodyStyle } from '@utils';
+import { attribute, mobileBodyStyle } from '@utils';
 import style from './style.less?inline';
 
 const FIXED_HEADER_TOP = 228;
@@ -50,8 +50,8 @@ function anchorHighlight(): void {
 
 export default define<ContentHost>({
   tag: 'td-doc-content',
-  platform: 'web',
-  pageStatus: 'show',
+  platform: attribute('web'),
+  pageStatus: attribute('show'),
   mobileBodyStyle,
   fixedAnchor: {
     value: (_host, v) => v || undefined,
diff --git a/packages/site-components/src/components/td-doc-copy/index.ts b/packages/site-components/src/components/td-doc-copy/index.ts
index c664a9a36..97c6a9169 100644
--- a/packages/site-components/src/components/td-doc-copy/index.ts
+++ b/packages/site-components/src/components/td-doc-copy/index.ts
@@ -1,4 +1,5 @@
 import { html, dispatch, define } from 'hybrids';
+import { attribute } from '@utils';
 import style from './style.less?inline';
 import copyIcon from '@images/copy.svg?raw';
 
@@ -41,7 +42,7 @@ function handleCopy(host: CopyHost & HTMLElement): void {
 
 export default define<CopyHost>({
   tag: 'td-doc-copy',
-  code: '',
+  code: attribute(''),
   render: () =>
     html`
       <td-tooltip duration="800">
diff --git a/packages/site-components/src/components/td-doc-footer/index.ts b/packages/site-components/src/components/td-doc-footer/index.ts
index 09af565ea..543e31427 100644
--- a/packages/site-components/src/components/td-doc-footer/index.ts
+++ b/packages/site-components/src/components/td-doc-footer/index.ts
@@ -1,7 +1,7 @@
 import { html, define } from 'hybrids';
 import { getFooterConfig } from '@config/footer';
 import { getLocale } from '@config/locale';
-import { patchShadowDomIntoDom, mobileBodyStyle } from '@utils';
+import { attribute, patchShadowDomIntoDom, mobileBodyStyle } from '@utils';
 import { fetchEcosystemConfig, getEcosystemLinkTarget } from '@config/ecosystem';
 import type { FooterGroup } from '@config/types';
 import tencentCloudIcon from '@images/tencentcloud-logo.svg?raw';
@@ -60,8 +60,8 @@ interface FooterHost {
 
 export default define<FooterHost>({
   tag: 'td-doc-footer',
+  platform: attribute('web'),
   mobileBodyStyle,
-  platform: 'web',
   displayQrCode: '',
   footerLinks: {
     value: (_host, value) => value || getFooterConfig(),
diff --git a/packages/site-components/src/components/td-doc-header/index.ts b/packages/site-components/src/components/td-doc-header/index.ts
index 098c8d320..dd3123ce5 100644
--- a/packages/site-components/src/components/td-doc-header/index.ts
+++ b/packages/site-components/src/components/td-doc-header/index.ts
@@ -1,7 +1,7 @@
 import { getLocale } from '@config/locale';
 import splineConfig from '@config/spline';
 import historyIcon from '@images/history.svg?raw';
-import { isComponentPage, isGlobalConfigPage, mobileBodyStyle, parseBoolean, watchHtmlMode } from '@utils';
+import { attribute, isComponentPage, isGlobalConfigPage, mobileBodyStyle, parseBoolean, watchHtmlMode } from '@utils';
 import { define, html } from 'hybrids';
 import style from './style.less?inline';
 
@@ -87,8 +87,7 @@ function iframeOnload(host: HeaderHost & HTMLElement): void {
 
 export default define<HeaderHost>({
   tag: 'td-doc-header',
-  spline: {
-    value: (_host, v) => v || '',
+  spline: attribute<string, HeaderHost>('', undefined, {
     connect: (host) => {
       const observer = watchHtmlMode((themeMode) => handleModeChange(themeMode, host));
 
@@ -101,14 +100,10 @@ export default define<HeaderHost>({
         handleModeChange(themeMode, host);
       }, 600);
     },
-  },
-  platform: 'web',
-  changelog: {
-    value: (_host, v) => parseBoolean(v, true),
-  },
-  changelogEn: {
-    value: (_host, v) => parseBoolean(v, true),
-  },
+  }),
+  platform: attribute('web'),
+  changelog: attribute(true, (value) => parseBoolean(value, true)),
+  changelogEn: attribute(true, (value) => parseBoolean(value, true)),
   mobileBodyStyle,
   shouldShowPopup: {
     value: (_host, v) => v || false,
@@ -232,9 +227,7 @@ export default define<HeaderHost>({
       };
     },
   },
-  showIssue: {
-    value: (_host, v) => parseBoolean(v, true),
-  },
+  showIssue: attribute(true, (value) => parseBoolean(value, true)),
 
   render: (host) => {
     const { changelog, changelogEn, docInfo, spline, showIssue } = host;
diff --git a/packages/site-components/src/components/td-doc-layout/index.ts b/packages/site-components/src/components/td-doc-layout/index.ts
index 1c0dd2a6b..e33392378 100644
--- a/packages/site-components/src/components/td-doc-layout/index.ts
+++ b/packages/site-components/src/components/td-doc-layout/index.ts
@@ -1,5 +1,6 @@
 import { html, define } from 'hybrids';
 import NProgress from 'nprogress';
+import { attribute } from '@utils';
 import style from './style.less?inline';
 
 interface DocLayoutProps {
@@ -26,7 +27,7 @@ export default define<DocLayoutProps>({
       return () => window.removeEventListener('load', onLoad);
     },
   },
-  direction: 'row', // row column
+  direction: attribute('row'), // row column
   render: ({ direction }) =>
     html`
       <div class="TDesign-page-doc">
diff --git a/packages/site-components/src/components/td-doc-popup/index.ts b/packages/site-components/src/components/td-doc-popup/index.ts
index 4bbf28b1e..1ba9a3420 100644
--- a/packages/site-components/src/components/td-doc-popup/index.ts
+++ b/packages/site-components/src/components/td-doc-popup/index.ts
@@ -1,6 +1,6 @@
 import { html, define, dispatch } from 'hybrids';
 import { createPopper, type Instance, type Placement } from '@popperjs/core';
-import { parseBoolean } from '@utils';
+import { attribute, parseBoolean } from '@utils';
 import style from './style.less?inline';
 
 interface PortalElement extends HTMLElement {
@@ -49,16 +49,14 @@ function handleClick(host: DocPopupHost): void {
 export default define<DocPopupProps>({
   tag: 'td-doc-popup',
   reference: ({ render }) => render().querySelector<HTMLElement>('.TDesign-doc-popup') as HTMLElement,
-  portalClass: '',
-  portalStyle: '',
-  placement: 'bottom-end',
-  triggerType: 'hover',
+  portalClass: attribute(''),
+  portalStyle: attribute(''),
+  placement: attribute<Placement>('bottom-end'),
+  triggerType: attribute<DocPopupProps['triggerType']>('hover'),
   portals: null,
   portal: null,
   popper: null,
-  equalWidth: {
-    value: (_host, v) => parseBoolean(v, false),
-  },
+  equalWidth: attribute(false, (value) => parseBoolean(value, false)),
   visible: {
     value: (host, v) => v || false,
     connect: (host) => {
diff --git a/packages/site-components/src/components/td-doc-tabs/index.ts b/packages/site-components/src/components/td-doc-tabs/index.ts
index 328912282..df1533034 100644
--- a/packages/site-components/src/components/td-doc-tabs/index.ts
+++ b/packages/site-components/src/components/td-doc-tabs/index.ts
@@ -1,5 +1,5 @@
 import { html, dispatch, define } from 'hybrids';
-import { isEn } from '@utils';
+import { attribute, isEn, parseBoolean } from '@utils';
 import style from './style.less?inline';
 
 interface TabItem {
@@ -53,9 +53,9 @@ const defaultTabs = [
 
 export default define<DocTabsProps>({
   tag: 'td-doc-tabs',
-  tab: 'demo',
+  tab: attribute('demo'),
   // 记录每个 tab 滚动条并自动滚动
-  autoScroll: true,
+  autoScroll: attribute(true, (value) => parseBoolean(value, true)),
   // 记录每个 tab 的滚动距离
   tabScrollMap: {
     value: (host, v) => {
diff --git a/packages/site-components/src/components/td-header/index.ts b/packages/site-components/src/components/td-header/index.ts
index 60b3d91ea..f09cc66d5 100644
--- a/packages/site-components/src/components/td-header/index.ts
+++ b/packages/site-components/src/components/td-header/index.ts
@@ -4,7 +4,7 @@ import closeIcon from '@images/close.svg?raw';
 import fakeArrowIcon from '@images/fake-arrow.svg?raw';
 import githubIcon from '@images/github.svg?raw';
 import translateIcon from '@images/translate.svg?raw';
-import { isEn } from '@utils';
+import { attribute, isEn, parseBoolean } from '@utils';
 import portalStyle from './portal.less?inline';
 import style from './style.less?inline';
 
@@ -133,7 +133,7 @@ function renderNotice(host: HeaderHost) {
 
 function renderLinksPopup(host: HeaderHost, trigger: UpdateFunctionWithMethods<unknown>) {
   return html`
-    <td-doc-popup placement="bottom" portalStyle="${portalStyle}">
+    <td-doc-popup placement="bottom" portal-style="${portalStyle}">
       ${trigger}
       <div slot="content" class="TDesign-base-components-links">
         <div class="TDesign-base-components-links__web">
@@ -255,10 +255,10 @@ function renderLinks(host: HeaderHost, items: HeaderNavItem[], platform: string,
 
 export default define<HeaderProps>({
   tag: 'td-header',
-  platform: 'web',
-  framework: 'vue',
-  disabledTheme: false,
-  disabledLocale: false,
+  platform: attribute('web'),
+  framework: attribute('vue'),
+  disabledTheme: attribute(false, (value) => parseBoolean(value, false)),
+  disabledLocale: attribute(false, (value) => parseBoolean(value, false)),
   notice: {
     value: (_host, v) => v || {},
     connect: (host) => {
@@ -316,11 +316,11 @@ export default define<HeaderProps>({
             ${collapseMenu
               ? html`
                   <td-collapse-menu
-                    disabledTheme="${disabledTheme}"
+                    disabled-theme="${disabledTheme}"
                     platform="${platform}"
                     framework="${framework}"
-                    headerList="${headerList}"
-                    baseComponentsLinks="${baseComponentsLinks}"
+                    header-list="${headerList}"
+                    base-components-links="${baseComponentsLinks}"
                   >
                   </td-collapse-menu>
                 `
diff --git a/packages/site-components/src/components/td-header/td-collapse-menu/index.ts b/packages/site-components/src/components/td-header/td-collapse-menu/index.ts
index a5ef78df2..3fcc89518 100644
--- a/packages/site-components/src/components/td-header/td-collapse-menu/index.ts
+++ b/packages/site-components/src/components/td-header/td-collapse-menu/index.ts
@@ -2,7 +2,7 @@ import { html, define } from 'hybrids';
 import style from './style.less?inline';
 import portalStyle from './portal.less?inline';
 import bulletpointIcon from '@images/bulletpoint.svg?raw';
-import { isIntranet } from '@utils/index';
+import { attribute, isIntranet, parseBoolean } from '@utils/index';
 import { gitPath, renderTag, handleLinkClick, type BaseComponentsLinks, type HeaderNavItem } from '../index';
 
 interface CollapseMenuProps {
@@ -79,13 +79,13 @@ export default define<CollapseMenuProps>({
   baseComponentsLinks: {
     value: (_host, value) => value || [],
   },
-  platform: 'web',
-  framework: 'vue',
-  disabledTheme: false,
+  platform: attribute('web'),
+  framework: attribute('vue'),
+  disabledTheme: attribute(false, (value) => parseBoolean(value, false)),
   render: (host) =>
     html`
       <div class="TDesign-collapse-menu">
-        <td-doc-popup portalStyle="${portalStyle}" trigger-type="click">
+        <td-doc-popup portal-style="${portalStyle}" trigger-type="click">
           <div class="collapse-icon" innerHTML="${bulletpointIcon}"></div>
           <div slot="content" class="TDesign-collapse-menu__list">
             ${renderLinks(host)} ${host.disabledTheme ? html`` : html`<td-theme-tabs></td-theme-tabs>`}
diff --git a/packages/site-components/src/components/td-logo/index.ts b/packages/site-components/src/components/td-logo/index.ts
index 82965e0f5..9a3c800f6 100644
--- a/packages/site-components/src/components/td-logo/index.ts
+++ b/packages/site-components/src/components/td-logo/index.ts
@@ -67,7 +67,7 @@ export default define<LogoProps>({
     </style>
 
     <div class="TDesign-header-logo">
-      <td-doc-popup portalStyle="${portalStyle}" placement="bottom-start">
+      <td-doc-popup portal-style="${portalStyle}" placement="bottom-start">
         <div class="TDesign-header-logo__menu" innerHTML=${menuApplicationIcon}></div>
         <div slot="content" class="TDesign-header-logo__content">${renderMenu(menuList)}</div>
       </td-doc-popup>
diff --git a/packages/site-components/src/components/td-select/index.ts b/packages/site-components/src/components/td-select/index.ts
index decfac69c..9234ac4cd 100644
--- a/packages/site-components/src/components/td-select/index.ts
+++ b/packages/site-components/src/components/td-select/index.ts
@@ -1,4 +1,5 @@
 import { html, define, dispatch } from 'hybrids';
+import { attribute, parseBoolean } from '@utils';
 import style from './style.less?inline';
 import portalStyle from './portal.less?inline';
 import fakeArrowIcon from '@images/fake-arrow.svg?raw';
@@ -51,9 +52,9 @@ function renderOptions(host: SelectHost) {
 
 export default define<SelectProps>({
   tag: 'td-select',
-  borderless: false,
-  value: '',
-  visible: false,
+  borderless: attribute(false, (value) => parseBoolean(value, false)),
+  value: attribute<SelectValue>(''),
+  visible: attribute(false, (value) => parseBoolean(value, false)),
   options: {
     value: (host, v) => v || [],
   },
@@ -75,7 +76,7 @@ export default define<SelectProps>({
         placement="bottom-start"
         trigger-type="click"
         portal-class="td-select-portal"
-        portalStyle="${portalStyle}"
+        portal-style="${portalStyle}"
         onvisible-change="${(host: SelectHost, event: VisibleChangeEvent) => (host.visible = event.detail.visible)}"
       >
         <div class="${selectInputClass}">
diff --git a/packages/site-components/src/components/td-switch/index.ts b/packages/site-components/src/components/td-switch/index.ts
index d730b40fc..abc7d6de1 100644
--- a/packages/site-components/src/components/td-switch/index.ts
+++ b/packages/site-components/src/components/td-switch/index.ts
@@ -1,4 +1,5 @@
 import { html, define, dispatch } from 'hybrids';
+import { attribute, parseBoolean } from '@utils';
 import style from './style.less?inline';
 
 type SwitchSize = 'small' | 'medium' | 'large';
@@ -15,8 +16,8 @@ function handleChange(host: SwitchProps & HTMLElement) {
 
 export default define<SwitchProps>({
   tag: 'td-switch',
-  value: false,
-  size: 'medium',
+  value: attribute(false, (value) => parseBoolean(value, false)),
+  size: attribute<SwitchSize>('medium'),
   render: (host) => {
     const { value, size } = host;
 
diff --git a/packages/site-components/src/components/td-tooltip/index.ts b/packages/site-components/src/components/td-tooltip/index.ts
index a37196f68..a72cd9cd6 100644
--- a/packages/site-components/src/components/td-tooltip/index.ts
+++ b/packages/site-components/src/components/td-tooltip/index.ts
@@ -1,4 +1,5 @@
 import { html, define } from 'hybrids';
+import { attribute } from '@utils';
 import style from './style.less?inline';
 
 type TooltipTrigger = 'click' | 'hover';
@@ -33,10 +34,10 @@ function handleLeave(host: TooltipHost) {
 
 export default define<TooltipProps>({
   tag: 'td-tooltip',
-  placement: 'top',
+  placement: attribute('top'),
   showTip: false,
-  duration: 1800,
-  triggerType: 'click',
+  duration: attribute(1800, Number),
+  triggerType: attribute<TooltipTrigger>('click'),
   render: (host) => {
     const { showTip, placement } = host;
 
diff --git a/packages/site-components/src/utils/index.ts b/packages/site-components/src/utils/index.ts
index 96aeeb612..08865eafb 100644
--- a/packages/site-components/src/utils/index.ts
+++ b/packages/site-components/src/utils/index.ts
@@ -1,3 +1,35 @@
+import type { Descriptor } from 'hybrids';
+
+export function attribute<T, H extends object = object>(
+  defaultValue: T,
+  parse: (value: string) => T = (value) => value as T,
+  descriptor: Omit<Descriptor<H, T>, 'value'> = {},
+): Descriptor<H, T> {
+  const { connect, ...options } = descriptor;
+
+  return {
+    ...options,
+    value: (_host, value) => value ?? defaultValue,
+    connect: (host, key, invalidate) => {
+      const attributeName = key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+      const syncAttribute = () => {
+        const value = host.getAttribute(attributeName);
+        host[key] = value === null ? defaultValue : parse(value);
+      };
+      const observer = new MutationObserver(syncAttribute);
+
+      if (host.hasAttribute(attributeName)) syncAttribute();
+      observer.observe(host, { attributes: true, attributeFilter: [attributeName] });
+      const disconnect = connect?.(host, key, invalidate);
+
+      return () => {
+        observer.disconnect();
+        disconnect?.();
+      };
+    },
+  };
+}
+
 /**
  * @function debounce 防抖
  * @param func, delay

From 4bbee9b0bd6441aa602a177b974d9848e5f4eba1 Mon Sep 17 00:00:00 2001
From: Uyarn <uyarnchen@gmail.com>
Date: Tue, 27 Oct 2026 14:01:48 +0800
Subject: [PATCH 3/4] chore: fix component attribute configuration

---
 .../src/__tests__/react-attributes.spec.ts    | 45 +++++++++++++++++++
 .../src/__tests__/td-doc-content.spec.ts      |  5 +--
 .../src/components/td-avatar/index.ts         |  9 ++--
 .../src/components/td-code/index.ts           |  3 +-
 .../src/components/td-contributors/index.ts   |  7 +--
 .../src/components/td-doc-content/index.ts    |  6 +--
 .../src/components/td-doc-copy/index.ts       |  3 +-
 .../src/components/td-doc-demo/index.ts       | 21 +++++++--
 .../src/components/td-doc-header/index.ts     | 12 +++--
 .../src/components/td-doc-history/index.ts    |  3 +-
 .../src/components/td-doc-layout/index.ts     |  3 +-
 .../src/components/td-doc-tabs/index.ts       |  4 +-
 .../src/components/td-header/index.ts         | 10 ++---
 .../td-header/td-collapse-menu/index.ts       |  8 ++--
 .../src/components/td-select/index.ts         |  2 +-
 15 files changed, 102 insertions(+), 39 deletions(-)
 create mode 100644 packages/site-components/src/__tests__/react-attributes.spec.ts

diff --git a/packages/site-components/src/__tests__/react-attributes.spec.ts b/packages/site-components/src/__tests__/react-attributes.spec.ts
new file mode 100644
index 000000000..8e7a67547
--- /dev/null
+++ b/packages/site-components/src/__tests__/react-attributes.spec.ts
@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, it } from 'vitest';
+
+import '../components/td-code';
+import '../components/td-doc-copy';
+import '../components/td-doc-demo';
+
+async function waitForRender(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve));
+}
+
+describe('React attribute integration', () => {
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('renders td-code created through innerHTML', async () => {
+    const container = document.createElement('div');
+    container.innerHTML = '<td-code text="Button"></td-code>';
+    document.body.appendChild(container);
+
+    await waitForRender();
+
+    const code = container.querySelector('td-code');
+    expect(code?.shadowRoot?.textContent).toContain('Button');
+  });
+
+  it('renders td-doc-demo code from React-style data attributes', async () => {
+    const demo = document.createElement('td-doc-demo');
+    demo.setAttribute('languages', 'TypeScript,JavaScript');
+    demo.setAttribute('data-TypeScript', 'const value: string = "TS";');
+    demo.setAttribute('data-JavaScript', 'const value = "JS";');
+    document.body.appendChild(demo);
+
+    await waitForRender();
+
+    const tabs = Array.from(demo.shadowRoot?.querySelectorAll('.TDesign-doc-demo-tabs__item') ?? []);
+    expect(tabs.map((tab) => tab.textContent?.trim())).toEqual(['TypeScript', 'JavaScript']);
+    expect(demo.shadowRoot?.querySelector('code')?.textContent).toContain('const value: string = "TS";');
+
+    demo.setAttribute('data-TypeScript', 'const updated: string = "TS";');
+    await waitForRender();
+
+    expect(demo.shadowRoot?.querySelector('code')?.textContent).toContain('const updated: string = "TS";');
+  });
+});
diff --git a/packages/site-components/src/__tests__/td-doc-content.spec.ts b/packages/site-components/src/__tests__/td-doc-content.spec.ts
index 826a963f9..920b824ee 100644
--- a/packages/site-components/src/__tests__/td-doc-content.spec.ts
+++ b/packages/site-components/src/__tests__/td-doc-content.spec.ts
@@ -37,10 +37,7 @@ vi.mock('hybrids', () => ({
   html: mockHtml,
 }));
 
-vi.mock('@utils', () => ({
-  attribute: vi.fn((value: unknown) => ({ value })),
-  mobileBodyStyle: {},
-}));
+vi.mock('@utils', () => ({ mobileBodyStyle: {} }));
 vi.mock('../components/td-doc-content/style.less?inline', () => ({ default: '' }));
 
 describe('td-doc-content anchor scroll', () => {
diff --git a/packages/site-components/src/components/td-avatar/index.ts b/packages/site-components/src/components/td-avatar/index.ts
index 1ee0e829a..91ba41a1e 100644
--- a/packages/site-components/src/components/td-avatar/index.ts
+++ b/packages/site-components/src/components/td-avatar/index.ts
@@ -1,5 +1,4 @@
 import { html, define } from 'hybrids';
-import { attribute } from '@utils';
 import style from './style.less?inline';
 
 interface AvatarProps {
@@ -11,10 +10,10 @@ interface AvatarProps {
 
 export default define<AvatarProps>({
   tag: 'td-avatar',
-  content: attribute(''),
-  username: attribute(''),
-  src: attribute(''),
-  href: attribute(''),
+  content: '',
+  username: '',
+  src: '',
+  href: '',
   render: ({ content, username, src, href }) => {
     const defaultSrc = `https://avatars.githubusercontent.com/${username}`;
     const defaultHref = `https://github.com/${username}`;
diff --git a/packages/site-components/src/components/td-code/index.ts b/packages/site-components/src/components/td-code/index.ts
index be58510b9..0195d36ad 100644
--- a/packages/site-components/src/components/td-code/index.ts
+++ b/packages/site-components/src/components/td-code/index.ts
@@ -1,4 +1,5 @@
 import { define, html } from 'hybrids';
+import { attribute } from '@utils';
 import style from './style.less?inline';
 
 interface CodeProps {
@@ -7,6 +8,6 @@ interface CodeProps {
 
 export default define<CodeProps>({
   tag: 'td-code',
-  text: '',
+  text: attribute(''),
   render: ({ text }) => html`<code class="TDesign-code">${text}</code>`.css`${style}`,
 });
diff --git a/packages/site-components/src/components/td-contributors/index.ts b/packages/site-components/src/components/td-contributors/index.ts
index bfe85bb66..11898d0a5 100644
--- a/packages/site-components/src/components/td-contributors/index.ts
+++ b/packages/site-components/src/components/td-contributors/index.ts
@@ -1,4 +1,5 @@
 import { html, define } from 'hybrids';
+import { attribute } from '@utils';
 import style from './style.less?inline';
 
 const apiUrl = import.meta.env.VITE_CONTRIBUTORS_API_URL;
@@ -90,9 +91,9 @@ function getContributors(
 
 export default define<ContributorsProps>({
   tag: 'td-contributors',
-  platform: '',
-  framework: '',
-  componentName: '',
+  platform: attribute(''),
+  framework: attribute(''),
+  componentName: attribute(''),
   contributorsData: {
     value: (host, v) => v || {},
     connect: (host, key, invalidate) => {
diff --git a/packages/site-components/src/components/td-doc-content/index.ts b/packages/site-components/src/components/td-doc-content/index.ts
index 28bc4a7cf..667f3c5ca 100644
--- a/packages/site-components/src/components/td-doc-content/index.ts
+++ b/packages/site-components/src/components/td-doc-content/index.ts
@@ -1,5 +1,5 @@
 import { html, define } from 'hybrids';
-import { attribute, mobileBodyStyle } from '@utils';
+import { mobileBodyStyle } from '@utils';
 import style from './style.less?inline';
 
 const FIXED_HEADER_TOP = 228;
@@ -52,8 +52,8 @@ function anchorHighlight(): void {
 
 export default define<ContentHost>({
   tag: 'td-doc-content',
-  platform: attribute('web'),
-  pageStatus: attribute('show'),
+  platform: 'web',
+  pageStatus: 'show',
   mobileBodyStyle,
   fixedAnchor: {
     value: (_host, v) => v || undefined,
diff --git a/packages/site-components/src/components/td-doc-copy/index.ts b/packages/site-components/src/components/td-doc-copy/index.ts
index 97c6a9169..c664a9a36 100644
--- a/packages/site-components/src/components/td-doc-copy/index.ts
+++ b/packages/site-components/src/components/td-doc-copy/index.ts
@@ -1,5 +1,4 @@
 import { html, dispatch, define } from 'hybrids';
-import { attribute } from '@utils';
 import style from './style.less?inline';
 import copyIcon from '@images/copy.svg?raw';
 
@@ -42,7 +41,7 @@ function handleCopy(host: CopyHost & HTMLElement): void {
 
 export default define<CopyHost>({
   tag: 'td-doc-copy',
-  code: attribute(''),
+  code: '',
   render: () =>
     html`
       <td-tooltip duration="800">
diff --git a/packages/site-components/src/components/td-doc-demo/index.ts b/packages/site-components/src/components/td-doc-demo/index.ts
index 59dcc1f2e..8c1876731 100644
--- a/packages/site-components/src/components/td-doc-demo/index.ts
+++ b/packages/site-components/src/components/td-doc-demo/index.ts
@@ -1,6 +1,6 @@
 import { html, define, dispatch } from 'hybrids';
 import Prism from 'prismjs';
-import { parseBoolean } from '@utils';
+import { attribute, parseBoolean } from '@utils';
 import style from './style.less?inline';
 import codeIcon from '@images/code.svg?raw';
 import 'prismjs/components/prism-markup.js';
@@ -21,6 +21,7 @@ interface DemoHost {
   mode: string;
   currentLangIndex: number;
   languages: string | undefined;
+  _dataVersion: number;
   theme: string;
   activeStyleMap: Record<string, TabStyle> | null | undefined;
 }
@@ -38,7 +39,20 @@ export default define<DemoHost>({
   },
   mode: 'auto', // auto open
   currentLangIndex: 0,
-  languages: undefined, // multiple languages display
+  languages: attribute<string | undefined>(undefined), // multiple languages display
+  _dataVersion: {
+    value: (_host, value) => value || 0,
+    connect: (host) => {
+      const observer = new MutationObserver((mutations) => {
+        if (mutations.some(({ attributeName }) => attributeName?.startsWith('data-'))) {
+          host._dataVersion += 1;
+        }
+      });
+      observer.observe(host, { attributes: true });
+
+      return () => observer.disconnect();
+    },
+  },
   theme: {
     value: (_host, v) => v || localStorage.getItem('--tdesign-theme') || 'light',
     connect(host, key, invalidate) {
@@ -90,7 +104,8 @@ export default define<DemoHost>({
     },
   },
   render: (host) => {
-    let { code, language, showCode, mode, theme, currentLangIndex, languages, activeStyleMap } = host;
+    let { code, language, showCode, mode, theme, currentLangIndex, languages, _dataVersion, activeStyleMap } = host;
+    void _dataVersion;
     const languageArr = typeof languages === 'string' ? languages.split(',') : [];
 
     const tabsDisplay =
diff --git a/packages/site-components/src/components/td-doc-header/index.ts b/packages/site-components/src/components/td-doc-header/index.ts
index dd3123ce5..a4855808f 100644
--- a/packages/site-components/src/components/td-doc-header/index.ts
+++ b/packages/site-components/src/components/td-doc-header/index.ts
@@ -102,8 +102,12 @@ export default define<HeaderHost>({
     },
   }),
   platform: attribute('web'),
-  changelog: attribute(true, (value) => parseBoolean(value, true)),
-  changelogEn: attribute(true, (value) => parseBoolean(value, true)),
+  changelog: {
+    value: (_host, v) => parseBoolean(v, true),
+  },
+  changelogEn: {
+    value: (_host, v) => parseBoolean(v, true),
+  },
   mobileBodyStyle,
   shouldShowPopup: {
     value: (_host, v) => v || false,
@@ -227,7 +231,9 @@ export default define<HeaderHost>({
       };
     },
   },
-  showIssue: attribute(true, (value) => parseBoolean(value, true)),
+  showIssue: {
+    value: (_host, v) => parseBoolean(v, true),
+  },
 
   render: (host) => {
     const { changelog, changelogEn, docInfo, spline, showIssue } = host;
diff --git a/packages/site-components/src/components/td-doc-history/index.ts b/packages/site-components/src/components/td-doc-history/index.ts
index 2dbe700bf..2d88cf251 100644
--- a/packages/site-components/src/components/td-doc-history/index.ts
+++ b/packages/site-components/src/components/td-doc-history/index.ts
@@ -1,4 +1,5 @@
 import { html, define } from 'hybrids';
+import { attribute } from '@utils';
 import style from './style.less?inline';
 import historyIcon from '@images/history.svg?raw';
 
@@ -18,7 +19,7 @@ function transformTime(time: string): string {
 
 export default define<HistoryHost>({
   tag: 'td-doc-history',
-  time: '',
+  time: attribute(''),
   content: '',
   render: ({ time, content }) => {
     return html`
diff --git a/packages/site-components/src/components/td-doc-layout/index.ts b/packages/site-components/src/components/td-doc-layout/index.ts
index e33392378..1c0dd2a6b 100644
--- a/packages/site-components/src/components/td-doc-layout/index.ts
+++ b/packages/site-components/src/components/td-doc-layout/index.ts
@@ -1,6 +1,5 @@
 import { html, define } from 'hybrids';
 import NProgress from 'nprogress';
-import { attribute } from '@utils';
 import style from './style.less?inline';
 
 interface DocLayoutProps {
@@ -27,7 +26,7 @@ export default define<DocLayoutProps>({
       return () => window.removeEventListener('load', onLoad);
     },
   },
-  direction: attribute('row'), // row column
+  direction: 'row', // row column
   render: ({ direction }) =>
     html`
       <div class="TDesign-page-doc">
diff --git a/packages/site-components/src/components/td-doc-tabs/index.ts b/packages/site-components/src/components/td-doc-tabs/index.ts
index df1533034..9a610e027 100644
--- a/packages/site-components/src/components/td-doc-tabs/index.ts
+++ b/packages/site-components/src/components/td-doc-tabs/index.ts
@@ -1,5 +1,5 @@
 import { html, dispatch, define } from 'hybrids';
-import { attribute, isEn, parseBoolean } from '@utils';
+import { attribute, isEn } from '@utils';
 import style from './style.less?inline';
 
 interface TabItem {
@@ -55,7 +55,7 @@ export default define<DocTabsProps>({
   tag: 'td-doc-tabs',
   tab: attribute('demo'),
   // 记录每个 tab 滚动条并自动滚动
-  autoScroll: attribute(true, (value) => parseBoolean(value, true)),
+  autoScroll: true,
   // 记录每个 tab 的滚动距离
   tabScrollMap: {
     value: (host, v) => {
diff --git a/packages/site-components/src/components/td-header/index.ts b/packages/site-components/src/components/td-header/index.ts
index f09cc66d5..72e24ba01 100644
--- a/packages/site-components/src/components/td-header/index.ts
+++ b/packages/site-components/src/components/td-header/index.ts
@@ -4,7 +4,7 @@ import closeIcon from '@images/close.svg?raw';
 import fakeArrowIcon from '@images/fake-arrow.svg?raw';
 import githubIcon from '@images/github.svg?raw';
 import translateIcon from '@images/translate.svg?raw';
-import { attribute, isEn, parseBoolean } from '@utils';
+import { isEn } from '@utils';
 import portalStyle from './portal.less?inline';
 import style from './style.less?inline';
 
@@ -255,10 +255,10 @@ function renderLinks(host: HeaderHost, items: HeaderNavItem[], platform: string,
 
 export default define<HeaderProps>({
   tag: 'td-header',
-  platform: attribute('web'),
-  framework: attribute('vue'),
-  disabledTheme: attribute(false, (value) => parseBoolean(value, false)),
-  disabledLocale: attribute(false, (value) => parseBoolean(value, false)),
+  platform: 'web',
+  framework: 'vue',
+  disabledTheme: false,
+  disabledLocale: false,
   notice: {
     value: (_host, v) => v || {},
     connect: (host) => {
diff --git a/packages/site-components/src/components/td-header/td-collapse-menu/index.ts b/packages/site-components/src/components/td-header/td-collapse-menu/index.ts
index 3fcc89518..d827fda85 100644
--- a/packages/site-components/src/components/td-header/td-collapse-menu/index.ts
+++ b/packages/site-components/src/components/td-header/td-collapse-menu/index.ts
@@ -2,7 +2,7 @@ import { html, define } from 'hybrids';
 import style from './style.less?inline';
 import portalStyle from './portal.less?inline';
 import bulletpointIcon from '@images/bulletpoint.svg?raw';
-import { attribute, isIntranet, parseBoolean } from '@utils/index';
+import { isIntranet } from '@utils/index';
 import { gitPath, renderTag, handleLinkClick, type BaseComponentsLinks, type HeaderNavItem } from '../index';
 
 interface CollapseMenuProps {
@@ -79,9 +79,9 @@ export default define<CollapseMenuProps>({
   baseComponentsLinks: {
     value: (_host, value) => value || [],
   },
-  platform: attribute('web'),
-  framework: attribute('vue'),
-  disabledTheme: attribute(false, (value) => parseBoolean(value, false)),
+  platform: 'web',
+  framework: 'vue',
+  disabledTheme: false,
   render: (host) =>
     html`
       <div class="TDesign-collapse-menu">
diff --git a/packages/site-components/src/components/td-select/index.ts b/packages/site-components/src/components/td-select/index.ts
index 9234ac4cd..f6c655f1f 100644
--- a/packages/site-components/src/components/td-select/index.ts
+++ b/packages/site-components/src/components/td-select/index.ts
@@ -54,7 +54,7 @@ export default define<SelectProps>({
   tag: 'td-select',
   borderless: attribute(false, (value) => parseBoolean(value, false)),
   value: attribute<SelectValue>(''),
-  visible: attribute(false, (value) => parseBoolean(value, false)),
+  visible: false,
   options: {
     value: (host, v) => v || [],
   },

From 3ce623b07fdbf62b5641bd1841b04b6b71e84a2a Mon Sep 17 00:00:00 2001
From: Uyarn <uyarnchen@gmail.com>
Date: Tue, 27 Oct 2026 14:11:27 +0800
Subject: [PATCH 4/4] chore: define compatiable define func

---
 .../src/__tests__/attribute.spec.ts           |  55 ---------
 .../src/__tests__/td-doc-header.spec.ts       |   4 -
 .../src/__tests__/td-doc-popup.spec.ts        |   1 -
 .../src/components/td-aegis/index.ts          |   2 +-
 .../src/components/td-ai-button/index.ts      |   2 +-
 .../src/components/td-avatar/index.ts         |   2 +-
 .../src/components/td-backtop/index.ts        |   2 +-
 .../src/components/td-code-block/index.ts     |   2 +-
 .../src/components/td-code/index.ts           |   5 +-
 .../src/components/td-contributors/index.ts   |   9 +-
 .../src/components/td-doc-aside/index.ts      |   6 +-
 .../src/components/td-doc-badge/index.ts      |  26 +---
 .../src/components/td-doc-changelog/index.ts  |   2 +-
 .../src/components/td-doc-content/index.ts    |   2 +-
 .../src/components/td-doc-copy/index.ts       |   2 +-
 .../src/components/td-doc-demo/index.ts       |  23 +---
 .../src/components/td-doc-empty/index.ts      |   2 +-
 .../src/components/td-doc-footer/index.ts     |   2 +-
 .../src/components/td-doc-header/index.ts     |  11 +-
 .../td-doc-header/td-doc-issue/index.ts       |   2 +-
 .../src/components/td-doc-history/index.ts    |   5 +-
 .../src/components/td-doc-layout/index.ts     |   2 +-
 .../src/components/td-doc-phone/index.ts      |   2 +-
 .../src/components/td-doc-popup/index.ts      |  16 +--
 .../src/components/td-doc-search/index.ts     |   2 +-
 .../src/components/td-doc-search/views.ts     |   2 +-
 .../src/components/td-doc-tabs/index.ts       |   6 +-
 .../src/components/td-doc-usage/index.ts      |   2 +-
 .../src/components/td-header/index.ts         |   2 +-
 .../td-header/td-collapse-menu/index.ts       |   2 +-
 .../src/components/td-logo/index.ts           |   2 +-
 .../src/components/td-message/index.ts        |   2 +-
 .../src/components/td-portal/index.ts         |   2 +-
 .../src/components/td-select/index.ts         |  12 +-
 .../src/components/td-stats/index.ts          |   2 +-
 .../src/components/td-switch/index.ts         |   7 +-
 .../src/components/td-theme-tabs/index.ts     |   2 +-
 .../src/components/td-tooltip/index.ts        |   9 +-
 packages/site-components/src/utils/hybrids.ts | 111 ++++++++++++++++++
 packages/site-components/src/utils/index.ts   |  32 -----
 40 files changed, 186 insertions(+), 198 deletions(-)
 delete mode 100644 packages/site-components/src/__tests__/attribute.spec.ts
 create mode 100644 packages/site-components/src/utils/hybrids.ts

diff --git a/packages/site-components/src/__tests__/attribute.spec.ts b/packages/site-components/src/__tests__/attribute.spec.ts
deleted file mode 100644
index 9569f9a21..000000000
--- a/packages/site-components/src/__tests__/attribute.spec.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-
-import { attribute, parseBoolean } from '../utils';
-
-interface AttributeHost extends HTMLElement {
-  enabled: boolean;
-}
-
-type ConnectedHost = AttributeHost & { __property_key__: boolean };
-
-describe('attribute descriptor', () => {
-  it('reads attributes added after element creation and observes updates', async () => {
-    const host = document.createElement('div') as unknown as ConnectedHost;
-    host.enabled = false;
-    host.setAttribute('enabled', '');
-
-    const descriptor = attribute(false, (value) => parseBoolean(value, false));
-    const cleanup = descriptor.connect?.(host, 'enabled' as '__property_key__', vi.fn());
-
-    expect(host.enabled).toBe(true);
-
-    host.setAttribute('enabled', 'false');
-    await new Promise((resolve) => setTimeout(resolve));
-    expect(host.enabled).toBe(false);
-
-    cleanup?.();
-  });
-
-  it('preserves properties when the attribute is absent', () => {
-    const host = document.createElement('div') as unknown as ConnectedHost;
-    host.enabled = true;
-
-    const descriptor = attribute(false, (value) => parseBoolean(value, false));
-    const cleanup = descriptor.connect?.(host, 'enabled' as '__property_key__', vi.fn());
-
-    expect(host.enabled).toBe(true);
-
-    cleanup?.();
-  });
-
-  it('composes an existing connect lifecycle', () => {
-    const host = document.createElement('div') as unknown as ConnectedHost;
-    host.enabled = false;
-    const lifecycleCleanup = vi.fn();
-    const connect = vi.fn(() => lifecycleCleanup);
-
-    const descriptor = attribute<boolean, AttributeHost>(false, undefined, { connect });
-    const cleanup = descriptor.connect?.(host, 'enabled' as '__property_key__', vi.fn());
-
-    expect(connect).toHaveBeenCalledOnce();
-
-    cleanup?.();
-    expect(lifecycleCleanup).toHaveBeenCalledOnce();
-  });
-});
diff --git a/packages/site-components/src/__tests__/td-doc-header.spec.ts b/packages/site-components/src/__tests__/td-doc-header.spec.ts
index 07108c722..efd9a7f55 100644
--- a/packages/site-components/src/__tests__/td-doc-header.spec.ts
+++ b/packages/site-components/src/__tests__/td-doc-header.spec.ts
@@ -20,10 +20,6 @@ vi.mock('@config/locale', () => ({ getLocale: vi.fn(() => ({})) }));
 vi.mock('@config/spline', () => ({}));
 vi.mock('@images/history.svg?raw', () => ({ default: '' }));
 vi.mock('@utils', () => ({
-  attribute: vi.fn((value: unknown, _parse?: unknown, descriptor: Record<string, unknown> = {}) => ({
-    value,
-    ...descriptor,
-  })),
   isComponentPage: vi.fn(),
   isGlobalConfigPage: vi.fn(),
   mobileBodyStyle: {},
diff --git a/packages/site-components/src/__tests__/td-doc-popup.spec.ts b/packages/site-components/src/__tests__/td-doc-popup.spec.ts
index 5c50e5e79..1520562f2 100644
--- a/packages/site-components/src/__tests__/td-doc-popup.spec.ts
+++ b/packages/site-components/src/__tests__/td-doc-popup.spec.ts
@@ -29,7 +29,6 @@ vi.mock('hybrids', () => ({
 
 vi.mock('@popperjs/core', () => ({ createPopper: mockCreatePopper }));
 vi.mock('@utils', () => ({
-  attribute: vi.fn((value: unknown) => ({ value })),
   parseBoolean: vi.fn((value: unknown) => Boolean(value)),
 }));
 vi.mock('../components/td-doc-popup/style.less?inline', () => ({ default: '' }));
diff --git a/packages/site-components/src/components/td-aegis/index.ts b/packages/site-components/src/components/td-aegis/index.ts
index 40d2998b0..9719dcef9 100644
--- a/packages/site-components/src/components/td-aegis/index.ts
+++ b/packages/site-components/src/components/td-aegis/index.ts
@@ -1,5 +1,5 @@
 /* global Aegis */
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 
 interface AegisProps {
   aegisId: string;
diff --git a/packages/site-components/src/components/td-ai-button/index.ts b/packages/site-components/src/components/td-ai-button/index.ts
index d0689b310..ccd03ca94 100644
--- a/packages/site-components/src/components/td-ai-button/index.ts
+++ b/packages/site-components/src/components/td-ai-button/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import { createAISearchSDK } from './utils';
 import style from './style.less?inline';
 
diff --git a/packages/site-components/src/components/td-avatar/index.ts b/packages/site-components/src/components/td-avatar/index.ts
index 91ba41a1e..a748690f9 100644
--- a/packages/site-components/src/components/td-avatar/index.ts
+++ b/packages/site-components/src/components/td-avatar/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import style from './style.less?inline';
 
 interface AvatarProps {
diff --git a/packages/site-components/src/components/td-backtop/index.ts b/packages/site-components/src/components/td-backtop/index.ts
index 8b04b8a24..3fc4f64cf 100644
--- a/packages/site-components/src/components/td-backtop/index.ts
+++ b/packages/site-components/src/components/td-backtop/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import style from './style.less?inline';
 import backTopIcon from '@images/backtop.svg?raw';
 
diff --git a/packages/site-components/src/components/td-code-block/index.ts b/packages/site-components/src/components/td-code-block/index.ts
index 36687ad07..eb97c3e56 100644
--- a/packages/site-components/src/components/td-code-block/index.ts
+++ b/packages/site-components/src/components/td-code-block/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import style from './style.less?inline';
 import Prism from 'prismjs';
 
diff --git a/packages/site-components/src/components/td-code/index.ts b/packages/site-components/src/components/td-code/index.ts
index 0195d36ad..03852d159 100644
--- a/packages/site-components/src/components/td-code/index.ts
+++ b/packages/site-components/src/components/td-code/index.ts
@@ -1,5 +1,4 @@
-import { define, html } from 'hybrids';
-import { attribute } from '@utils';
+import { define, html } from '@utils/hybrids';
 import style from './style.less?inline';
 
 interface CodeProps {
@@ -8,6 +7,6 @@ interface CodeProps {
 
 export default define<CodeProps>({
   tag: 'td-code',
-  text: attribute(''),
+  text: '',
   render: ({ text }) => html`<code class="TDesign-code">${text}</code>`.css`${style}`,
 });
diff --git a/packages/site-components/src/components/td-contributors/index.ts b/packages/site-components/src/components/td-contributors/index.ts
index 11898d0a5..83ddaab2b 100644
--- a/packages/site-components/src/components/td-contributors/index.ts
+++ b/packages/site-components/src/components/td-contributors/index.ts
@@ -1,5 +1,4 @@
-import { html, define } from 'hybrids';
-import { attribute } from '@utils';
+import { html, define } from '@utils/hybrids';
 import style from './style.less?inline';
 
 const apiUrl = import.meta.env.VITE_CONTRIBUTORS_API_URL;
@@ -91,9 +90,9 @@ function getContributors(
 
 export default define<ContributorsProps>({
   tag: 'td-contributors',
-  platform: attribute(''),
-  framework: attribute(''),
-  componentName: attribute(''),
+  platform: '',
+  framework: '',
+  componentName: '',
   contributorsData: {
     value: (host, v) => v || {},
     connect: (host, key, invalidate) => {
diff --git a/packages/site-components/src/components/td-doc-aside/index.ts b/packages/site-components/src/components/td-doc-aside/index.ts
index 061345e65..501e6f290 100644
--- a/packages/site-components/src/components/td-doc-aside/index.ts
+++ b/packages/site-components/src/components/td-doc-aside/index.ts
@@ -1,7 +1,7 @@
-import { html, dispatch, define, type Component } from 'hybrids';
+import { html, dispatch, define, type Component } from '@utils/hybrids';
 import menuFoldIcon from '@images/menu-fold.svg?raw';
 import menuUnfoldIcon from '@images/menu-unfold.svg?raw';
-import { attribute, patchShadowDomIntoDom } from '@utils';
+import { patchShadowDomIntoDom } from '@utils';
 import style from './style.less?inline';
 
 const replaceStateEvent = new CustomEvent('replaceState');
@@ -130,7 +130,7 @@ const asideComponent = {
   routerList: {
     value: (_host: AsideHost & HTMLElement, v?: NavItem[]) => v || [],
   },
-  title: attribute(''),
+  title: '',
   patchDom: {
     value: (_host: AsideHost & HTMLElement, v?: boolean) => v || false,
     connect: patchShadowDomIntoDom,
diff --git a/packages/site-components/src/components/td-doc-badge/index.ts b/packages/site-components/src/components/td-doc-badge/index.ts
index e3b6fb66e..2e0069937 100644
--- a/packages/site-components/src/components/td-doc-badge/index.ts
+++ b/packages/site-components/src/components/td-doc-badge/index.ts
@@ -1,4 +1,4 @@
-import { html, define, type Descriptor } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import style from './style.less?inline';
 
 interface BadgeHost {
@@ -7,24 +7,6 @@ interface BadgeHost {
   color: string;
 }
 
-function attribute(defaultValue: string): Descriptor<BadgeHost, string> {
-  return {
-    value: (_host, value) => value ?? defaultValue,
-    connect: (host, key) => {
-      const attributeName = key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
-      const syncAttribute = () => {
-        host[key] = host.getAttribute(attributeName) ?? defaultValue;
-      };
-      const observer = new MutationObserver(syncAttribute);
-
-      if (host.hasAttribute(attributeName)) syncAttribute();
-      observer.observe(host, { attributes: true, attributeFilter: [attributeName] });
-
-      return () => observer.disconnect();
-    },
-  };
-}
-
 function getColor(message: string): string {
   const percentage = parseFloat(message);
   if (percentage >= 90) {
@@ -38,9 +20,9 @@ function getColor(message: string): string {
 
 export default define<BadgeHost>({
   tag: 'td-doc-badge',
-  label: attribute('coverage'),
-  message: attribute('0%'),
-  color: attribute(''),
+  label: 'coverage',
+  message: '0%',
+  color: '',
   render: (host) => {
     const { label, message, color: defaultColor } = host;
     let color = defaultColor;
diff --git a/packages/site-components/src/components/td-doc-changelog/index.ts b/packages/site-components/src/components/td-doc-changelog/index.ts
index 914765440..2038dd0af 100644
--- a/packages/site-components/src/components/td-doc-changelog/index.ts
+++ b/packages/site-components/src/components/td-doc-changelog/index.ts
@@ -1,4 +1,4 @@
-import { define, html } from 'hybrids';
+import { define, html } from '@utils/hybrids';
 import { getLocale } from '@config/locale';
 import closeIcon from '@images/close.svg?raw';
 import { convert2PascalCase, isComponentPage, isEn, isGlobalConfigPage, parseBoolean } from '@utils';
diff --git a/packages/site-components/src/components/td-doc-content/index.ts b/packages/site-components/src/components/td-doc-content/index.ts
index 667f3c5ca..8ffebb71e 100644
--- a/packages/site-components/src/components/td-doc-content/index.ts
+++ b/packages/site-components/src/components/td-doc-content/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import { mobileBodyStyle } from '@utils';
 import style from './style.less?inline';
 
diff --git a/packages/site-components/src/components/td-doc-copy/index.ts b/packages/site-components/src/components/td-doc-copy/index.ts
index c664a9a36..6e248f7f8 100644
--- a/packages/site-components/src/components/td-doc-copy/index.ts
+++ b/packages/site-components/src/components/td-doc-copy/index.ts
@@ -1,4 +1,4 @@
-import { html, dispatch, define } from 'hybrids';
+import { html, dispatch, define } from '@utils/hybrids';
 import style from './style.less?inline';
 import copyIcon from '@images/copy.svg?raw';
 
diff --git a/packages/site-components/src/components/td-doc-demo/index.ts b/packages/site-components/src/components/td-doc-demo/index.ts
index 8c1876731..335165ae7 100644
--- a/packages/site-components/src/components/td-doc-demo/index.ts
+++ b/packages/site-components/src/components/td-doc-demo/index.ts
@@ -1,6 +1,6 @@
-import { html, define, dispatch } from 'hybrids';
+import { html, define, dispatch } from '@utils/hybrids';
 import Prism from 'prismjs';
-import { attribute, parseBoolean } from '@utils';
+import { parseBoolean } from '@utils';
 import style from './style.less?inline';
 import codeIcon from '@images/code.svg?raw';
 import 'prismjs/components/prism-markup.js';
@@ -21,7 +21,6 @@ interface DemoHost {
   mode: string;
   currentLangIndex: number;
   languages: string | undefined;
-  _dataVersion: number;
   theme: string;
   activeStyleMap: Record<string, TabStyle> | null | undefined;
 }
@@ -39,20 +38,7 @@ export default define<DemoHost>({
   },
   mode: 'auto', // auto open
   currentLangIndex: 0,
-  languages: attribute<string | undefined>(undefined), // multiple languages display
-  _dataVersion: {
-    value: (_host, value) => value || 0,
-    connect: (host) => {
-      const observer = new MutationObserver((mutations) => {
-        if (mutations.some(({ attributeName }) => attributeName?.startsWith('data-'))) {
-          host._dataVersion += 1;
-        }
-      });
-      observer.observe(host, { attributes: true });
-
-      return () => observer.disconnect();
-    },
-  },
+  languages: undefined, // multiple languages display
   theme: {
     value: (_host, v) => v || localStorage.getItem('--tdesign-theme') || 'light',
     connect(host, key, invalidate) {
@@ -104,8 +90,7 @@ export default define<DemoHost>({
     },
   },
   render: (host) => {
-    let { code, language, showCode, mode, theme, currentLangIndex, languages, _dataVersion, activeStyleMap } = host;
-    void _dataVersion;
+    let { code, language, showCode, mode, theme, currentLangIndex, languages, activeStyleMap } = host;
     const languageArr = typeof languages === 'string' ? languages.split(',') : [];
 
     const tabsDisplay =
diff --git a/packages/site-components/src/components/td-doc-empty/index.ts b/packages/site-components/src/components/td-doc-empty/index.ts
index 964ec3c53..73f0f622e 100644
--- a/packages/site-components/src/components/td-doc-empty/index.ts
+++ b/packages/site-components/src/components/td-doc-empty/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import style from './style.less?inline';
 
 interface EmptyHost {
diff --git a/packages/site-components/src/components/td-doc-footer/index.ts b/packages/site-components/src/components/td-doc-footer/index.ts
index 40535156d..1b6eabdfd 100644
--- a/packages/site-components/src/components/td-doc-footer/index.ts
+++ b/packages/site-components/src/components/td-doc-footer/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import { getFooterConfig } from '@config/footer';
 import { getLocale } from '@config/locale';
 import { patchShadowDomIntoDom } from '@utils';
diff --git a/packages/site-components/src/components/td-doc-header/index.ts b/packages/site-components/src/components/td-doc-header/index.ts
index a4855808f..0dd0e2ac3 100644
--- a/packages/site-components/src/components/td-doc-header/index.ts
+++ b/packages/site-components/src/components/td-doc-header/index.ts
@@ -1,8 +1,8 @@
 import { getLocale } from '@config/locale';
 import splineConfig from '@config/spline';
 import historyIcon from '@images/history.svg?raw';
-import { attribute, isComponentPage, isGlobalConfigPage, mobileBodyStyle, parseBoolean, watchHtmlMode } from '@utils';
-import { define, html } from 'hybrids';
+import { isComponentPage, isGlobalConfigPage, mobileBodyStyle, parseBoolean, watchHtmlMode } from '@utils';
+import { define, html } from '@utils/hybrids';
 import style from './style.less?inline';
 
 interface DocInfo {
@@ -87,7 +87,8 @@ function iframeOnload(host: HeaderHost & HTMLElement): void {
 
 export default define<HeaderHost>({
   tag: 'td-doc-header',
-  spline: attribute<string, HeaderHost>('', undefined, {
+  spline: {
+    value: (_host, value) => value || '',
     connect: (host) => {
       const observer = watchHtmlMode((themeMode) => handleModeChange(themeMode, host));
 
@@ -100,8 +101,8 @@ export default define<HeaderHost>({
         handleModeChange(themeMode, host);
       }, 600);
     },
-  }),
-  platform: attribute('web'),
+  },
+  platform: 'web',
   changelog: {
     value: (_host, v) => parseBoolean(v, true),
   },
diff --git a/packages/site-components/src/components/td-doc-header/td-doc-issue/index.ts b/packages/site-components/src/components/td-doc-header/td-doc-issue/index.ts
index e2b0835cc..1786736d1 100644
--- a/packages/site-components/src/components/td-doc-header/td-doc-issue/index.ts
+++ b/packages/site-components/src/components/td-doc-header/td-doc-issue/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import style from './style.less?inline';
 import infoIcon from '@images/info.svg?raw';
 import checkIcon from '@images/check.svg?raw';
diff --git a/packages/site-components/src/components/td-doc-history/index.ts b/packages/site-components/src/components/td-doc-history/index.ts
index 2d88cf251..9cf25173f 100644
--- a/packages/site-components/src/components/td-doc-history/index.ts
+++ b/packages/site-components/src/components/td-doc-history/index.ts
@@ -1,5 +1,4 @@
-import { html, define } from 'hybrids';
-import { attribute } from '@utils';
+import { html, define } from '@utils/hybrids';
 import style from './style.less?inline';
 import historyIcon from '@images/history.svg?raw';
 
@@ -19,7 +18,7 @@ function transformTime(time: string): string {
 
 export default define<HistoryHost>({
   tag: 'td-doc-history',
-  time: attribute(''),
+  time: '',
   content: '',
   render: ({ time, content }) => {
     return html`
diff --git a/packages/site-components/src/components/td-doc-layout/index.ts b/packages/site-components/src/components/td-doc-layout/index.ts
index 1c0dd2a6b..9d6bba8fe 100644
--- a/packages/site-components/src/components/td-doc-layout/index.ts
+++ b/packages/site-components/src/components/td-doc-layout/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import NProgress from 'nprogress';
 import style from './style.less?inline';
 
diff --git a/packages/site-components/src/components/td-doc-phone/index.ts b/packages/site-components/src/components/td-doc-phone/index.ts
index acc9c64c5..9d9db4d7c 100644
--- a/packages/site-components/src/components/td-doc-phone/index.ts
+++ b/packages/site-components/src/components/td-doc-phone/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import QRCode from 'qrcode';
 import style from './style.less?inline';
 import qrcodeIcon from '@images/qrcode.svg?raw';
diff --git a/packages/site-components/src/components/td-doc-popup/index.ts b/packages/site-components/src/components/td-doc-popup/index.ts
index 1ba9a3420..ab2d5f9bc 100644
--- a/packages/site-components/src/components/td-doc-popup/index.ts
+++ b/packages/site-components/src/components/td-doc-popup/index.ts
@@ -1,6 +1,6 @@
-import { html, define, dispatch } from 'hybrids';
+import { html, define, dispatch } from '@utils/hybrids';
 import { createPopper, type Instance, type Placement } from '@popperjs/core';
-import { attribute, parseBoolean } from '@utils';
+import { parseBoolean } from '@utils';
 import style from './style.less?inline';
 
 interface PortalElement extends HTMLElement {
@@ -49,14 +49,16 @@ function handleClick(host: DocPopupHost): void {
 export default define<DocPopupProps>({
   tag: 'td-doc-popup',
   reference: ({ render }) => render().querySelector<HTMLElement>('.TDesign-doc-popup') as HTMLElement,
-  portalClass: attribute(''),
-  portalStyle: attribute(''),
-  placement: attribute<Placement>('bottom-end'),
-  triggerType: attribute<DocPopupProps['triggerType']>('hover'),
+  portalClass: '',
+  portalStyle: '',
+  placement: 'bottom-end',
+  triggerType: 'hover',
   portals: null,
   portal: null,
   popper: null,
-  equalWidth: attribute(false, (value) => parseBoolean(value, false)),
+  equalWidth: {
+    value: (_host, value) => parseBoolean(value, false),
+  },
   visible: {
     value: (host, v) => v || false,
     connect: (host) => {
diff --git a/packages/site-components/src/components/td-doc-search/index.ts b/packages/site-components/src/components/td-doc-search/index.ts
index c6d213f39..f8deec8f9 100644
--- a/packages/site-components/src/components/td-doc-search/index.ts
+++ b/packages/site-components/src/components/td-doc-search/index.ts
@@ -16,7 +16,7 @@
  *                  → views.js 根据最新 host 输出 html``
  */
 
-import { define, html, type Descriptor } from 'hybrids';
+import { define, html, type Descriptor } from '@utils/hybrids';
 
 import style from './style.less?inline';
 import {
diff --git a/packages/site-components/src/components/td-doc-search/views.ts b/packages/site-components/src/components/td-doc-search/views.ts
index ea462e944..7ee335cc6 100644
--- a/packages/site-components/src/components/td-doc-search/views.ts
+++ b/packages/site-components/src/components/td-doc-search/views.ts
@@ -21,7 +21,7 @@
  * }
  */
 
-import { html, type UpdateFunctionWithMethods } from 'hybrids';
+import { html, type UpdateFunctionWithMethods } from '@utils/hybrids';
 import SearchIcon from 'tdesign-icons-svg/src/search.svg?raw';
 import CloseIcon from 'tdesign-icons-svg/src/close.svg?raw';
 
diff --git a/packages/site-components/src/components/td-doc-tabs/index.ts b/packages/site-components/src/components/td-doc-tabs/index.ts
index 9a610e027..e1f39e029 100644
--- a/packages/site-components/src/components/td-doc-tabs/index.ts
+++ b/packages/site-components/src/components/td-doc-tabs/index.ts
@@ -1,5 +1,5 @@
-import { html, dispatch, define } from 'hybrids';
-import { attribute, isEn } from '@utils';
+import { html, dispatch, define } from '@utils/hybrids';
+import { isEn } from '@utils';
 import style from './style.less?inline';
 
 interface TabItem {
@@ -53,7 +53,7 @@ const defaultTabs = [
 
 export default define<DocTabsProps>({
   tag: 'td-doc-tabs',
-  tab: attribute('demo'),
+  tab: 'demo',
   // 记录每个 tab 滚动条并自动滚动
   autoScroll: true,
   // 记录每个 tab 的滚动距离
diff --git a/packages/site-components/src/components/td-doc-usage/index.ts b/packages/site-components/src/components/td-doc-usage/index.ts
index 2e31c3bec..5b6ff6a46 100644
--- a/packages/site-components/src/components/td-doc-usage/index.ts
+++ b/packages/site-components/src/components/td-doc-usage/index.ts
@@ -1,4 +1,4 @@
-import { html, define, dispatch } from 'hybrids';
+import { html, define, dispatch } from '@utils/hybrids';
 import { parseBoolean } from '@utils';
 import style from './style.less?inline';
 import tipsIcon from '@images/tips.svg?raw';
diff --git a/packages/site-components/src/components/td-header/index.ts b/packages/site-components/src/components/td-header/index.ts
index 72e24ba01..b14b08069 100644
--- a/packages/site-components/src/components/td-header/index.ts
+++ b/packages/site-components/src/components/td-header/index.ts
@@ -1,4 +1,4 @@
-import { define, html, type UpdateFunctionWithMethods } from 'hybrids';
+import { define, html, type UpdateFunctionWithMethods } from '@utils/hybrids';
 import { getHeaderConfig } from '@config/header';
 import closeIcon from '@images/close.svg?raw';
 import fakeArrowIcon from '@images/fake-arrow.svg?raw';
diff --git a/packages/site-components/src/components/td-header/td-collapse-menu/index.ts b/packages/site-components/src/components/td-header/td-collapse-menu/index.ts
index d827fda85..358f10e8f 100644
--- a/packages/site-components/src/components/td-header/td-collapse-menu/index.ts
+++ b/packages/site-components/src/components/td-header/td-collapse-menu/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import style from './style.less?inline';
 import portalStyle from './portal.less?inline';
 import bulletpointIcon from '@images/bulletpoint.svg?raw';
diff --git a/packages/site-components/src/components/td-logo/index.ts b/packages/site-components/src/components/td-logo/index.ts
index 9a3c800f6..0ec79b554 100644
--- a/packages/site-components/src/components/td-logo/index.ts
+++ b/packages/site-components/src/components/td-logo/index.ts
@@ -1,5 +1,5 @@
 /* eslint-disable prettier/prettier */
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import logoIcon from '@images/logo.svg?raw';
 import menuApplicationIcon from '@images/menu-application.svg?raw';
 import chevronRightIcon from '@images/chevron-right.svg?raw';
diff --git a/packages/site-components/src/components/td-message/index.ts b/packages/site-components/src/components/td-message/index.ts
index f1eaeade1..7fa1f275c 100644
--- a/packages/site-components/src/components/td-message/index.ts
+++ b/packages/site-components/src/components/td-message/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import InfoCircleFilled from 'tdesign-icons-svg/src/info-circle-filled.svg?raw';
 import ErrorCircleFilled from 'tdesign-icons-svg/src/error-circle-filled.svg?raw';
 import CheckCircleFilled from 'tdesign-icons-svg/src/check-circle-filled.svg?raw';
diff --git a/packages/site-components/src/components/td-portal/index.ts b/packages/site-components/src/components/td-portal/index.ts
index 0d65bb0a5..9e2d96aaa 100644
--- a/packages/site-components/src/components/td-portal/index.ts
+++ b/packages/site-components/src/components/td-portal/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import style from './style.less?inline';
 
 interface PortalProps {
diff --git a/packages/site-components/src/components/td-select/index.ts b/packages/site-components/src/components/td-select/index.ts
index f6c655f1f..f19d61732 100644
--- a/packages/site-components/src/components/td-select/index.ts
+++ b/packages/site-components/src/components/td-select/index.ts
@@ -1,5 +1,5 @@
-import { html, define, dispatch } from 'hybrids';
-import { attribute, parseBoolean } from '@utils';
+import { html, define, dispatch } from '@utils/hybrids';
+import { parseBoolean } from '@utils';
 import style from './style.less?inline';
 import portalStyle from './portal.less?inline';
 import fakeArrowIcon from '@images/fake-arrow.svg?raw';
@@ -52,8 +52,12 @@ function renderOptions(host: SelectHost) {
 
 export default define<SelectProps>({
   tag: 'td-select',
-  borderless: attribute(false, (value) => parseBoolean(value, false)),
-  value: attribute<SelectValue>(''),
+  borderless: {
+    value: (_host, value) => parseBoolean(value, false),
+  },
+  value: {
+    value: (_host, value) => value ?? '',
+  },
   visible: false,
   options: {
     value: (host, v) => v || [],
diff --git a/packages/site-components/src/components/td-stats/index.ts b/packages/site-components/src/components/td-stats/index.ts
index fa69134e6..369ae8fa3 100644
--- a/packages/site-components/src/components/td-stats/index.ts
+++ b/packages/site-components/src/components/td-stats/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 
 interface ScriptAttributes {
   src: string;
diff --git a/packages/site-components/src/components/td-switch/index.ts b/packages/site-components/src/components/td-switch/index.ts
index abc7d6de1..1a1890821 100644
--- a/packages/site-components/src/components/td-switch/index.ts
+++ b/packages/site-components/src/components/td-switch/index.ts
@@ -1,5 +1,4 @@
-import { html, define, dispatch } from 'hybrids';
-import { attribute, parseBoolean } from '@utils';
+import { html, define, dispatch } from '@utils/hybrids';
 import style from './style.less?inline';
 
 type SwitchSize = 'small' | 'medium' | 'large';
@@ -16,8 +15,8 @@ function handleChange(host: SwitchProps & HTMLElement) {
 
 export default define<SwitchProps>({
   tag: 'td-switch',
-  value: attribute(false, (value) => parseBoolean(value, false)),
-  size: attribute<SwitchSize>('medium'),
+  value: false,
+  size: 'medium',
   render: (host) => {
     const { value, size } = host;
 
diff --git a/packages/site-components/src/components/td-theme-tabs/index.ts b/packages/site-components/src/components/td-theme-tabs/index.ts
index 5f633685a..a922bc04a 100644
--- a/packages/site-components/src/components/td-theme-tabs/index.ts
+++ b/packages/site-components/src/components/td-theme-tabs/index.ts
@@ -1,4 +1,4 @@
-import { html, define } from 'hybrids';
+import { html, define } from '@utils/hybrids';
 import style from './style.less?inline';
 import moonIcon from '@images/moon.svg?raw';
 import sunIcon from '@images/sun.svg?raw';
diff --git a/packages/site-components/src/components/td-tooltip/index.ts b/packages/site-components/src/components/td-tooltip/index.ts
index a72cd9cd6..1488a205d 100644
--- a/packages/site-components/src/components/td-tooltip/index.ts
+++ b/packages/site-components/src/components/td-tooltip/index.ts
@@ -1,5 +1,4 @@
-import { html, define } from 'hybrids';
-import { attribute } from '@utils';
+import { html, define } from '@utils/hybrids';
 import style from './style.less?inline';
 
 type TooltipTrigger = 'click' | 'hover';
@@ -34,10 +33,10 @@ function handleLeave(host: TooltipHost) {
 
 export default define<TooltipProps>({
   tag: 'td-tooltip',
-  placement: attribute('top'),
+  placement: 'top',
   showTip: false,
-  duration: attribute(1800, Number),
-  triggerType: attribute<TooltipTrigger>('click'),
+  duration: 1800,
+  triggerType: 'click',
   render: (host) => {
     const { showTip, placement } = host;
 
diff --git a/packages/site-components/src/utils/hybrids.ts b/packages/site-components/src/utils/hybrids.ts
new file mode 100644
index 000000000..1b5cfc8bf
--- /dev/null
+++ b/packages/site-components/src/utils/hybrids.ts
@@ -0,0 +1,111 @@
+import { define as baseDefine, type Component } from 'hybrids';
+
+export * from 'hybrids';
+
+const ATTRIBUTE_VERSION = '__attributeVersion';
+
+interface AttributeSyncHost extends HTMLElement {
+  [ATTRIBUTE_VERSION]: number;
+  [key: string]: unknown;
+}
+
+interface PropertyConfig {
+  type: string;
+}
+
+function getWritableProperties(component: Component<unknown>): Map<string, PropertyConfig> {
+  const properties = new Map<string, PropertyConfig>();
+
+  Object.entries(component).forEach(([key, property]) => {
+    if (key === 'tag' || key === 'render') return;
+
+    if (typeof property !== 'object' || property === null) {
+      if (typeof property !== 'function') properties.set(key, { type: typeof property });
+      return;
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(property, 'value')) return;
+    const value = (property as { value: unknown }).value;
+    if (typeof value !== 'function' || value.length > 1) {
+      properties.set(key, { type: typeof value });
+    }
+  });
+
+  return properties;
+}
+
+function dashToCamelCase(value: string): string {
+  return value.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+function syncAttribute(host: AttributeSyncHost, attributeName: string, property: PropertyConfig): void {
+  const key = dashToCamelCase(attributeName);
+  const attributeValue = host.getAttribute(attributeName);
+
+  if (attributeValue === null) {
+    host[key] = undefined;
+  } else if (property.type === 'boolean') {
+    host[key] = true;
+  } else if (property.type === 'number') {
+    host[key] = Number(attributeValue);
+  } else {
+    host[key] = attributeValue;
+  }
+}
+
+function withAttributeSync<E>(component: Component<E>): Component<E> {
+  const properties = getWritableProperties(component as Component<unknown>);
+  const { tag, ...definition } = component;
+  const render = component.render;
+  const syncedRender =
+    typeof render === 'function'
+      ? (host: E & AttributeSyncHost) => {
+          void host[ATTRIBUTE_VERSION];
+          return render(host);
+        }
+      : render && {
+          ...render,
+          value: (host: E & AttributeSyncHost) => {
+            void host[ATTRIBUTE_VERSION];
+            return render.value(host);
+          },
+        };
+
+  return {
+    tag,
+    [ATTRIBUTE_VERSION]: {
+      value: 0,
+      connect: (host: AttributeSyncHost) => {
+        Array.from(host.attributes).forEach(({ name }) => {
+          const property = properties.get(dashToCamelCase(name));
+          if (property) syncAttribute(host, name, property);
+        });
+
+        const observer = new MutationObserver((mutations) => {
+          mutations.forEach(({ attributeName }) => {
+            if (!attributeName) return;
+            const property = properties.get(dashToCamelCase(attributeName));
+            if (property) {
+              syncAttribute(host, attributeName, property);
+            } else if (attributeName.startsWith('data-')) {
+              host[ATTRIBUTE_VERSION] += 1;
+            }
+          });
+        });
+        observer.observe(host, { attributes: true });
+
+        return () => observer.disconnect();
+      },
+    },
+    ...definition,
+    ...(syncedRender ? { render: syncedRender } : {}),
+  } as Component<E>;
+}
+
+export const define = Object.assign(
+  <E>(component: Component<E>): Component<E> => baseDefine(withAttributeSync(component)),
+  {
+    compile: baseDefine.compile,
+    from: baseDefine.from,
+  },
+);
diff --git a/packages/site-components/src/utils/index.ts b/packages/site-components/src/utils/index.ts
index 08865eafb..96aeeb612 100644
--- a/packages/site-components/src/utils/index.ts
+++ b/packages/site-components/src/utils/index.ts
@@ -1,35 +1,3 @@
-import type { Descriptor } from 'hybrids';
-
-export function attribute<T, H extends object = object>(
-  defaultValue: T,
-  parse: (value: string) => T = (value) => value as T,
-  descriptor: Omit<Descriptor<H, T>, 'value'> = {},
-): Descriptor<H, T> {
-  const { connect, ...options } = descriptor;
-
-  return {
-    ...options,
-    value: (_host, value) => value ?? defaultValue,
-    connect: (host, key, invalidate) => {
-      const attributeName = key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
-      const syncAttribute = () => {
-        const value = host.getAttribute(attributeName);
-        host[key] = value === null ? defaultValue : parse(value);
-      };
-      const observer = new MutationObserver(syncAttribute);
-
-      if (host.hasAttribute(attributeName)) syncAttribute();
-      observer.observe(host, { attributes: true, attributeFilter: [attributeName] });
-      const disconnect = connect?.(host, key, invalidate);
-
-      return () => {
-        observer.disconnect();
-        disconnect?.();
-      };
-    },
-  };
-}
-
 /**
  * @function debounce 防抖
  * @param func, delay