环境提供器

将组件的 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。

安装与初始化

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 编写，不属于上游原始示例。

// 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<string>();
  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 <Stack gap="4" width="100%" maxW="sm">
    <Text fontWeight="semibold">{expected.nodeType === 9 ? "Document" : "ShadowRoot"}</Text>
    <Text fontSize="sm">{zh ? "拖动或用方向键调整原生滑块，检查该组件使用的文档环境。" : "Drag or use arrow keys on the native slider, then check its document environment."}</Text>
    <Slider.Root value={value} onValueChange={event => setValue(event.value)}>
      <Slider.Label>{zh ? "环境内滑块" : "Slider in this environment"}</Slider.Label>
      <Slider.ValueText />
      <Slider.Control><Slider.Track><Slider.Range /></Slider.Track><Slider.Thumbs /></Slider.Control>
    </Slider.Root>
    <Button onClick={inspect}>{zh ? "检查环境" : "Check environment"}</Button>
    <Text role="status" fontFamily="mono" fontSize="xs" overflowWrap="anywhere">{checked ?? (zh ? "等待检查" : "Not checked yet")}</Text>
  </Stack>;
}

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 <CacheProvider value={cache}><ChakraProvider value={defaultSystem}>
    <EnvironmentProvider value={() => root}>
      <Box className={`chakra-theme ${dark ? "dark" : "light"}`} bg="bg" color="fg" p="5" minH="300px">
        <EnvironmentControls expected={root}/>
      </Box>
    </EnvironmentProvider>
  </ChakraProvider></CacheProvider>;
}

function FrameEnvironment() {
  const { document } = useFrame();
  return document?.head ? <ScopedEnvironment root={document} styleContainer={document.head}/> : null;
}

export function EnvironmentProviderIframe() {
  return <Frame title={zh ? "原生环境：嵌套 iframe" : "Native environment: nested iframe"} style={{ width: "100%", height: 340, border: "1px solid #8886", borderRadius: 12 }} initialContent={`<!doctype html><html lang="${zh ? "zh-CN" : "en"}" class="${dark ? "dark" : "light"}"><head><style>body{margin:0}html{color-scheme:${dark ? "dark" : "light"}}</style></head><body><div></div></body></html>`}><FrameEnvironment/></Frame>;
}

export function EnvironmentProviderShadow() {
  const [root, setRoot] = useState<ShadowRoot | null>(null);
  const host = useCallback((node: HTMLDivElement | null) => {
    if (node) setRoot(node.shadowRoot ?? node.attachShadow({ mode: "open" }));
  }, []);
  return <div ref={host} data-native-shadow-environment style={{ width: "100%", border: "1px solid #8886", borderRadius: 12, overflow: "hidden" }}>
    {root && createPortal(<ScopedEnvironment root={root} styleContainer={root}/>, root)}
  </div>;
}

export function EnvironmentProviderContext() {
  return <EnvironmentProvider value={() => document}><EnvironmentControls expected={document}/></EnvironmentProvider>;
}

全部示例与复现要求

示例名称用于选择演示，不是组件通用 variant 属性。复制所选示例全部 sourceFiles；compositions 别名表示本地文件，不是 npm 包。保留相对导入或映射到宿主真实目录。React peer 单独检查；编辑器示例保留一致的固定 Tiptap 扩展版本。

iframe 环境

environment-provider-iframe · 命名导出 EnvironmentProviderIframe · JGuang 原生组合

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 原生组合

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 原生组合

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 付费内容。