# 环境提供器 - 页面: https://jiguang132.com/zh/resources/chakra-ui/docs/environment-provider - 资源: Chakra UI (https://jiguang132.com/zh/resources/chakra-ui.md) - 全部指南: https://jiguang132.com/zh/resources/chakra-ui/docs.md 将组件的 DOM 根、文档与窗口解析到真实 iframe 或 ShadowRoot。它不自动迁移 Emotion 样式缓存；原生环境检查与样式容器配置见专属实用指南。 `EnvironmentProvider` 用于把原生组件的 DOM 查询、焦点和事件环境指向正确的 `Document` 或 `ShadowRoot`。它不会自动复制 iframe 外部的 CSS，也不是主题提供器。 ## 安装与基础配置 使用固定的 `@chakra-ui/react@3.37.0` 和 `@emotion/react@11.14.0`。iframe 示例额外使用 `react-frame-component@5.3.2`，iframe 与 Shadow DOM 的样式容器使用 `@emotion/cache@11.14.0`。 主题仍由原生 `ChakraProvider` 与 `defaultSystem` 提供。嵌套文档必须把 Emotion 的样式插入其 `head`；Shadow DOM 必须把样式插入该 ShadowRoot。示例中的 `.chakra-theme` 容器承接 Chakra CSS 变量，不能仅把外层 class 当作跨文档主题继承。 ## 三种实际用法 - **嵌套 iframe**：通过 `react-frame-component` 的 `useFrame()` 获取内部文档，等待 `document.head` 存在，再传入 `value={() => document}`。滑块和环境检查按钮都在内层 iframe 中运行。 - **Shadow DOM**：创建开放的 ShadowRoot，把内容通过 React Portal 挂入其中，再传入 `value={() => shadowRoot}`。Portal 只负责挂载位置，EnvironmentProvider 才负责原生组件的 DOM 查询上下文。 - **读取环境**：`useEnvironmentContext()` 提供 `getRootNode()`、`getDocument()`、`getWindow()`。不要 JSON 序列化完整 Document/Window；本例只比较对象身份并展示布尔结果，避免循环引用。 ## 参数与状态 `value` 是返回根节点的函数，不是组件颜色或字符串 ID。传入的是当前渲染环境，不要把 JGuang 官网的 document 传给独立预览中的组件。 滑块使用原生受控 `value` 与 `onValueChange`，初始值为 `[40]`。鼠标拖动或方向键应更新数值。“检查环境”检查 root、document、window 是否与当前容器匹配。检查结果不是安装成功状态。 iframe/Shadow 容器随着示例卸载一起销毁。不要在普通 effect 清理中手动清空仍在复用的 Emotion cache，否则 React StrictMode 的 effect 重放可能让样式消失。 ## 验证与限制 检查键盘左右方向键、可见焦点、深浅色和中英文。iframe 场景中，焦点应留在当前 iframe 的控件；Shadow 场景应查询 ShadowRoot 内部元素。 此示例没有申请麦克风、摄像头或其他权限。Electron 是上游列出的应用场景，但当前 JGuang 浏览器示例不声称已验证 Electron。原生 API 参考与上游内联文档保留在源码查看资料中。 ## 来源 这三个完整示例由 JGuang 根据固定版本的上游 EnvironmentProvider 内联指南组合，使用原生 Chakra、Emotion 和 React API，不是修改过的上游示例文件。原文及许可证保留在 vendor；本地组合来源与差异记录在 LOCAL_CHANGES.md。 ## 安装与初始化 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` 渲染前配置 ChakraProvider、defaultSystem 和 Emotion。保留宿主项目的 React 版本并检查 peer 兼容。官方 npm 安装提供组件包，不会复制以下示例源码。locale、next-themes 和框架专属 SSR 配置见资源安装指南；npm 安装之外还需单独复制所选示例源码。 ## 完整原生使用示例 这是固定版本的真实示例，不是通用 API 伪代码。复制完整源码依赖并保留命名导出；附加依赖逐例列在下方。 此组合明确由 JGuang 使用原生 API 编写，不属于上游原始示例。 ```tsx // Local runnable compositions of the upstream inline EnvironmentProvider guide. // Native provider, context, slider and Emotion APIs are not replaced or patched. import { useCallback, useMemo, useState } from "react"; import { createPortal } from "react-dom"; import createCache from "@emotion/cache"; import { CacheProvider } from "@emotion/react"; import Frame, { useFrame } from "react-frame-component"; import { Box, Button, ChakraProvider, EnvironmentProvider, Slider, Stack, Text, defaultSystem, useEnvironmentContext } from "@chakra-ui/react"; const params = new URLSearchParams(location.search); const zh = params.get("locale") === "zh"; const dark = params.get("theme") === "dark"; type NativeRoot = Document | ShadowRoot; function EnvironmentControls({ expected }: { expected: NativeRoot }) { const { getRootNode, getDocument, getWindow } = useEnvironmentContext(); const [value, setValue] = useState([40]); const [checked, setChecked] = useState(); function inspect() { const node = getRootNode(); const owner = expected.nodeType === 9 ? expected as Document : expected.ownerDocument; setChecked(JSON.stringify({ root: node === expected, document: owner !== null && getDocument() === owner, window: owner !== null && getWindow() === owner.defaultView })); } return {expected.nodeType === 9 ? "Document" : "ShadowRoot"} {zh ? "拖动或用方向键调整原生滑块，检查该组件使用的文档环境。" : "Drag or use arrow keys on the native slider, then check its document environment."} setValue(event.value)}> {zh ? "环境内滑块" : "Slider in this environment"} {checked ?? (zh ? "等待检查" : "Not checked yet")} ; } function ScopedEnvironment({ root, styleContainer }: { root: NativeRoot; styleContainer: HTMLElement | ShadowRoot }) { const cache = useMemo(() => createCache({ key: "jguang-chakra-environment", container: styleContainer }), [styleContainer]); // Both containers belong to this example's frame/shadow host and disappear // with it. Manually flushing a memoized cache in an effect cleanup would // erase styles during React StrictMode's setup/cleanup replay. return root}> ; } function FrameEnvironment() { const { document } = useFrame(); return document?.head ? : null; } export function EnvironmentProviderIframe() { return
`}>; } export function EnvironmentProviderShadow() { const [root, setRoot] = useState(null); const host = useCallback((node: HTMLDivElement | null) => { if (node) setRoot(node.shadowRoot ?? node.attachShadow({ mode: "open" })); }, []); return
{root && createPortal(, root)}
; } export function EnvironmentProviderContext() { return document}>; } ``` ## 全部示例与复现要求 示例名称用于选择演示，不是组件通用 variant 属性。复制所选示例全部 sourceFiles；compositions 别名表示本地文件，不是 npm 包。保留相对导入或映射到宿主真实目录。React peer 单独检查；编辑器示例保留一致的固定 Tiptap 扩展版本。 ### iframe 环境 `environment-provider-iframe` · 命名导出 `EnvironmentProviderIframe` · JGuang 原生组合 ```bash npm install @chakra-ui/react@3.37.0 @emotion/cache@11.14.0 @emotion/react@11.14.0 react-frame-component@5.3.2 ``` - `authored/examples/environment-provider.tsx` ### ShadowRoot 环境 `environment-provider-shadow` · 命名导出 `EnvironmentProviderShadow` · JGuang 原生组合 ```bash npm install @chakra-ui/react@3.37.0 @emotion/cache@11.14.0 @emotion/react@11.14.0 react-frame-component@5.3.2 ``` - `authored/examples/environment-provider.tsx` ### 原生环境上下文 `environment-provider-context` · 命名导出 `EnvironmentProviderContext` · JGuang 原生组合 ```bash npm install @chakra-ui/react@3.37.0 @emotion/cache@11.14.0 @emotion/react@11.14.0 react-frame-component@5.3.2 ``` - `authored/examples/environment-provider.tsx` ## 原生 API 与源码参考 源码查看器保留原始声明、import 与继承关系。Ark UI 事件契约、Chakra 样式属性和 recipe 类型仍以原生包为准；本指南不平铺或编造默认值。代码注释保留原文，不冒充正文翻译。 - `npm/@chakra-ui/react@3.37.0/dist/types/components/environment/index.d.ts` ## 状态与安装后检查 执行严格类型检查、目标项目生产构建和实际操作。检查名称／焦点／键盘、深浅色、窄屏、原生支持的空／加载／错误状态以及卸载清理。预览限制远程接口、上传与下载，业务服务需自行配置。复制命令或预览就绪不代表安装完成或后端成功。 ## 来源与许可边界 https://github.com/chakra-ui/chakra-ui/tree/2e7517745cff2fcde0b8012f136cf99611ff262a 本页是 JGuang 双语实用说明，不声称全文翻译上游 MDX。原始文档与示例字节保留在 vendor。保留仓库 MIT、compositions 的 ISC 元数据和独立依赖声明；原始许可元数据差异与缺失完整声明仍作为显式审查事项，不包含 Chakra Pro 付费内容。 --- JGuang 全部资源索引: https://jiguang132.com/llms.txt