Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
See #121
  • Loading branch information
mantou132 committed Apr 17, 2024
1 parent 4984a06 commit 29ef6c1
Show file tree
Hide file tree
Showing 2 changed files with 142 additions and 4 deletions.
73 changes: 71 additions & 2 deletions packages/duoyun-ui/docs/en/01-guide/60-integrate.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,81 @@ However, there is no [type hint](https://code.visualstudio.com/docs/editor/intel
## React

> [!NOTE]
> Only the experimental version of React supports custom elements. Use `npm install react@experimental react-dom@experimental` to install the experimental version of React.
> Only the React 19 supports custom elements. Use `npm install react@canary react-dom@canary` to install the React 19.
Use DuoyunUI like any other React component library:

<gbp-raw range="import DyCard,<DyCard-</DyCard>" src="https://raw.githubusercontent.com/mantou132/nextjs-learn/main/pages/ce-test.tsx"></gbp-raw>

### Use React Component in `<dy-route>`

`<dy-route>` only supports rendering `TemplateResult`:

```ts
const routes = {
about: {
pattern: '/about',
title: `About`,
getContent(_, ele) {
return html`<p-about></p-about>`;
},
},
} satisfies RoutesObject;
```

To render the React component, need to manually mount it onto the `<dy-route>`:

```ts
function renderReactNode(ele: any, node: ReactNode) {
ele.react?.unmount();
ele.react = createRoot(ele);
ele.react.render(node);
}

const routes = {
about: {
pattern: '/about',
title: `About`,
getContent(_, ele) {
renderReactNode(ele, <About />);
},
},
} satisfies RoutesObject;
```

### Using the React component as Property

Some elements support custom rendering content, such as the `header` of `<dy-card>`:

```ts
function Page() {
return <DyCard header={html`<div>No.</div>`}></DyCard>;
}
```

If want to render the React component, need to first mount it to the `HTMLElement`, which can be achieved through custom Hooks:

```tsx
function useReactNode(node: ReactNode) {
const ref = useRef<{ root: Root; container: HTMLElement }>();
useEffect(() => () => ref.current?.root.unmount(), []);
if (ref.current) {
ref.current.root.render(node);
return ref.current.container;
}
const container = document.createElement('div');
container.style.display = 'contents';
const root = createRoot(container);
ref.current = { root, container };
root.render(node);
return container;
}

function Page() {
return <DyCard header={useReactNode(<>No</>)}></DyCard>;
}
```

## Vue

DuoyunUI also exports Vue components, which are used the same as React. The only difference is that the path is changed from `react` to `vue`,
Expand All @@ -33,7 +102,7 @@ In the Vue project, it also supports directly writing custom elements, but [dist

DuoyunUI does not re-export as a Svelte component, and you can use the custom element directly:

<gbp-raw codelang="html" range="2-9,46-57" src="https://raw.githubusercontent.com/mantou132/sveltekit-learn/main/src/routes/ce-test/+page.svelte"></gbp-raw>
<gbp-raw codelang="html" range="2-9,44-55" src="https://raw.githubusercontent.com/mantou132/sveltekit-learn/main/src/routes/ce-test/+page.svelte"></gbp-raw>

> [!NOTE]
> Use the `Sveltekit`, please make sure the `Svelte` is installed as a `dependencies` instead of `DevDependenCies`, otherwise the type cannot be import successfully;
Expand Down
73 changes: 71 additions & 2 deletions packages/duoyun-ui/docs/zh/01-guide/60-integrate.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,81 @@
## React

> [!NOTE]
> React 的实验版才支持自定义元素,使用 `npm install react@experimental react-dom@experimental` 安装 React 实验版
> React 19 才支持自定义元素,当前使用 `npm install react@canary react-dom@canary` 安装 React 19
跟使用其他 React 组件库一样使用 DuoyunUI:

<gbp-raw range="import DyCard,<DyCard-</DyCard>" src="https://raw.githubusercontent.com/mantou132/nextjs-learn/main/pages/ce-test.tsx"></gbp-raw>

### `<dy-route>` 中使用 React 组件

`<dy-route>` 只支持渲染 `TemplateResult`

```ts
const routes = {
about: {
pattern: '/about',
title: `About`,
getContent(_, ele) {
return html`<p-about></p-about>`;
},
},
} satisfies RoutesObject;
```

要渲染 React 组件需要手动挂载到 `<dy-route>` 上:

```ts
function renderReactNode(ele: any, node: ReactNode) {
ele.react?.unmount();
ele.react = createRoot(ele);
ele.react.render(node);
}

const routes = {
about: {
pattern: '/about',
title: `About`,
getContent(_, ele) {
renderReactNode(ele, <About />);
},
},
} satisfies RoutesObject;
```

### 在 Property 上使用 React 组件

一些元素支持自定义渲染内容,例如 `<dy-card>``header`

```ts
function Page() {
return <DyCard header={html`<div>No.</div>`}></DyCard>;
}
```

如果要渲染 React 组件,则需要先渲染到 `HTMLElement` 上,可以通过自定义 Hooks 实现:

```tsx
function useReactNode(node: ReactNode) {
const ref = useRef<{ root: Root; container: HTMLElement }>();
useEffect(() => () => ref.current?.root.unmount(), []);
if (ref.current) {
ref.current.root.render(node);
return ref.current.container;
}
const container = document.createElement('div');
container.style.display = 'contents';
const root = createRoot(container);
ref.current = { root, container };
root.render(node);
return container;
}

function Page() {
return <DyCard header={useReactNode(<>No</>)}></DyCard>;
}
```

## Vue

DuoyunUI 也导出了 Vue 组件,使用和 React 一样,唯一的区别是路径将 `react` 改成 `vue`
Expand All @@ -33,7 +102,7 @@ DuoyunUI 也导出了 Vue 组件,使用和 React 一样,唯一的区别是

DuoyunUI 没有重导出为 Svelte 组件,直接使用自定义元素即可:

<gbp-raw codelang="html" range="2-9,46-57" src="https://raw.githubusercontent.com/mantou132/sveltekit-learn/main/src/routes/ce-test/+page.svelte"></gbp-raw>
<gbp-raw codelang="html" range="2-9,44-55" src="https://raw.githubusercontent.com/mantou132/sveltekit-learn/main/src/routes/ce-test/+page.svelte"></gbp-raw>

> [!NOTE]
> 使用 `SvelteKit` 请确保 `svelte` 安装成 `dependencies` 而非 `devDependencies`,否则类型不能成功导入;
Expand Down

0 comments on commit 29ef6c1

Please sign in to comment.