跳到主要内容

入门

一分钟内即可在浏览器渲染三维内容，无需安装或构建。可以直接从 CDN 加载 PlayCanvas Web Components，也可以在集成现有项目时安装 npm 包。

创建项目模板

Vite 和 TypeScript 项目可使用 create-playcanvas，选择 Web Components 格式：

npm create playcanvas@latest my-app -- -f web-components

生成的项目包含可运行模板和供兼容 AI 编程助手使用的 PlayCanvas Skills。手动集成时使用以下 CDN 或 npm 方式。

安装​

两种加载方式如下。不确定时可先用 CDN，之后切换到 npm 无需修改场景标记：

  • CDN，无需安装：不需要下载文件或配置工具，是最快的入门方式。固定版本后也适合生产环境。
  • npm：适合已有 package.json、开发服务器或打包器的项目。引擎与组件和其他依赖一起管理版本，并通过自己的基础设施提供。

除非使用打包器构建页面，HTML 需要 import map，让组件找到外部依赖 PlayCanvas 引擎。映射还列出 @playcanvas/web-components 本身，标签不需要这一项，但以后编写 JavaScript 时可按包名导入 API，详见代码访问。

从 jsDelivr 等 CDN 加载引擎和组件，使用压缩构建 pwc.min.mjs，其大小不到 pwc.mjs 的三分之一：

<script type="importmap">
    {
        "imports": {
            "playcanvas": "https://cdn.jsdelivr.net/npm/playcanvas@latest/build/playcanvas.mjs",
            "@playcanvas/web-components": "https://cdn.jsdelivr.net/npm/@playcanvas/web-components@latest/dist/pwc.min.mjs"
        }
    }
</script>

随后导入 Web Components：

<script type="module" src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@latest/dist/pwc.min.mjs"></script>
版本管理

示例为方便采用 @latest。生产部署应固定版本，例如 [email protected] 和 @playcanvas/[email protected]，确保构建一致。选择兼容组合：组件各版本支持的引擎范围在 package.json 的 playcanvas peer dependency 中声明。

库 URL 同时出现在 import map 与 <script> 中，两者必须固定为相同版本。URL 不同时，浏览器视为不同模块；自己的代码通过映射导入后会加载第二份副本，因标签已被第一份注册而失败。

最新稳定版本详见 PlayCanvas 引擎发布记录与 Web Components 发布记录。

第一个页面​

以下完整页面渲染一个受光照的球体，相当于三维版本的 hello world。采用 CDN，无需安装：

index.html
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>My PlayCanvas Web Components App</title>
        <script type="importmap">
            {
                "imports": {
                    "playcanvas": "https://cdn.jsdelivr.net/npm/playcanvas@latest/build/playcanvas.mjs",
                    "@playcanvas/web-components": "https://cdn.jsdelivr.net/npm/@playcanvas/web-components@latest/dist/pwc.min.mjs"
                }
            }
        </script>
        <script type="module" src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@latest/dist/pwc.min.mjs"></script>
        <style>
            body {
                margin: 0;
                overflow: hidden;
            }
            pc-app {
                width: 100%;
                height: 100vh;  /* fallback for browsers without dynamic viewport units */
                height: 100dvh;
            }
        </style>
    </head>
    <body>
        <pc-app>
            <pc-scene>
                <pc-entity name="camera" position="0 0 3">
                    <pc-camera></pc-camera>
                </pc-entity>
                <pc-entity name="light" rotation="45 45 0">
                    <pc-light></pc-light>
                </pc-entity>
                <pc-entity name="ball">
                    <pc-render type="sphere"></pc-render>
                </pc-entity>
            </pc-scene>
        </pc-app>
    </body>
</html>

<style> 中有一条重要规则：<pc-app> 像 <video> 一样由 CSS 控制尺寸，默认仅 300×150 像素。示例 pc-app 规则使其填满视口；也可按普通网页布局自行设置，详见尺寸。

保存为 index.html，在浏览器打开。全部依赖来自 CDN，可以直接从磁盘打开，无需 Web 服务器。你应看到与下方实时预览相同的受光球体，编辑标记会重新运行预览：

实时示例
<pc-app>
    <pc-scene>
        <pc-entity name="camera" position="0 0 3">
            <pc-camera></pc-camera>
        </pc-entity>
        <pc-entity name="light" rotation="45 45 0">
            <pc-light></pc-light>
        </pc-entity>
        <pc-entity name="ball">
            <pc-render type="sphere"></pc-render>
        </pc-entity>
    </pc-scene>
</pc-app>
备注

通过 npm 安装时，将 import map 和 <script> 改为上方 npm 选项卡中的 /node_modules/... 路径；使用打包器则删除两者，在入口脚本导入包。

编辑器支持​

包包含 Custom Elements Manifest，供编辑器补全标签、属性及合法值，并提供悬停文档。编辑器从 node_modules 读取，即使页面使用 CDN，也应安装 npm 包以获得支持。

VS Code：在工作区 .vscode/settings.json 添加：

{
  "html.customData": [
    "./node_modules/@playcanvas/web-components/dist/vscode.html-custom-data.json"
  ]
}

JetBrains IDE，例如 WebStorm 和 IntelliJ IDEA：无需配置，自动发现包内 web-types.json。

其他工具：清单位于 @playcanvas/web-components/dist/custom-elements.json，并由包的 customElements 字段声明，供 lit-analyzer、Storybook 等发现。

后续步骤​

  • 阅读构建场景，逐步加入摄像机、网格、灯光、材质、阴影和地面。
  • 浏览标签参考，了解全部可声明元素。
  • 体验示例，了解组件能力。