低代码前端后端【免费下载链接】plasmicVisual builder for React. Build apps, websites, and content. Integrate with your codebase.项目地址https://gitcode.com/gh_mirrors/pl/plasmic点击查看免费下载plasmicpkgs/graphql是 Plasmic 官方维护的包用于在 Plasmic Studio 的数据查询Data Queries与交互动作Mutations中直接执行 GraphQL 请求。通过本文你将掌握fetchGraphQL函数的完整参数语义、GET/POST 请求构造的底层原理、返回值结构以及如何在代码中通过registerGraphQL完成注册并与你自己的 React 代码库打通。包概览从 API 报告到真实源码本仓库中与本文直接相关的文档是 plasmicpkgs/graphql/api/index.api.md它是由 API Extractor 自动生成的公共 API 报告完整刻画了该包的对外接口面。结合 plasmicpkgs/graphql/src/index.ts 的实现我们可以得到一张完整的技术地图。从 plasmicpkgs/graphql/package.json 可知包名plasmicpkgs/graphql当前仓库版本0.0.48定位Custom functions for running GraphQL queries from Plasmic data queries.为 Plasmic 数据查询提供执行 GraphQL 查询的自定义函数模块格式同时提供 CJSdist/index.js、ESMdist/index.esm.js与类型声明dist/index.d.ts兼容各类打包器Peer 依赖plasmicapp/host 1.0.211注册机制、plasmicpkgs/fetch ^0.0.5底层 HTTP 执行器包对外只暴露两个公共 APIfetchGraphQL函数与registerGraphQL注册函数它们构成了执行与注册两个核心环节。FetchGraphQLOpts参数契约详解根据 index.api.md 中的接口定义fetchGraphQL接受一个名为opts的对象其类型为FetchGraphQLOpts字段类型必填说明urlstring是GraphQL 端点地址例如https://graphql.contentful.com/content/v1/spaces/spacemethodGET \| POST \| PUT \| DELETE是HTTP 方法Studio 面板中默认值为POSTheadersRecordstring, string否附加请求头如Authorization、Content-Type默认{}request{ query: string; variables?: object }是核心请求体query为 GraphQL 查询字符串variables为查询变量对象varOverridesRecordstring, any否变量覆盖层用于在运行时注入/覆盖variables中的同名变量从 源码实现 可以看到其硬性校验url、method、request三者缺一不可否则直接抛出Error(url, method, and request are required)。这一点与 Studio 注册元数据中url、request均标记为required: true完全对应。请求构造GET 与 POST/PUT/DELETE 的分支逻辑fetchGraphQL的核心在于按 HTTP 方法分两条路径构造请求源码 如下if (method GET) { // https://graphql.org/learn/serving-over-http/#get-request-and-parameters const urlWithQueryParams new URL(url); urlWithQueryParams.searchParams.set(query, request.query); urlWithQueryParams.searchParams.set( variables, JSON.stringify({ ...request.variables, ...varOverrides }) ); return fetch({ url: urlWithQueryParams.toString(), method: GET, headers }); } else { return fetch({ url, method, headers, body: { query: request.query, variables: { ...request.variables, ...varOverrides }, }, }); }两条路径的关键差异GET遵循 GraphQL over HTTP 规范代码注释明确引用了 graphql.org 的 GET 参数规范将query作为普通 URL 查询参数、variables作为JSON.stringify后的查询参数拼接到 URL 上不发送请求体。POST/PUT/DELETE将{ query, variables }作为 JSON 请求体发送。值得注意的合并逻辑{ ...request.variables, ...varOverrides }意味着varOverrides中声明的变量会覆盖request.variables中的同名变量。这正是Variable overrides字段的设计意图——在 Studio 面板中配置的静态变量可以被运行时传入的动态值如页面参数、用户上下文覆盖。返回值结构fetchGraphQL返回一个 Promiseresolve 值为{ statusCode: number; // HTTP 状态码 headers: { [k: string]: string }; // 响应头映射 body: any; // 已解析的 JSON 响应体含 data / errors }该返回结构并非plasmicpkgs/graphql自行定义而是直接透传自底层plasmicpkgs/fetch的fetch函数。查看 plasmicpkgs/fetch/src/index.ts 的实现可以发现三个重要的底层行为自动请求头若调用方未显式提供会默认补上Accept: application/json存在 body 时还会补上Content-Type: application/json。响应体自动解析响应文本会尝试JSON.parse解析失败时原样返回字符串maybeParseJSON。错误抛出非 2xx 状态码会抛出HttpErrorname为HttpError携带status与info字段错误处理模式参考自 SWR 文档。因此在 Plasmic 数据查询中使用时通常需要从body.data中读取 GraphQL 的data字段并自行检查body.errors处理服务端错误。registerGraphQL向 Plasmic 注册自定义函数registerGraphQL(loader?: Registerable)是包的第二个公共 API用于把fetchGraphQL及其元数据注册到 Plasmic 运行时export function registerGraphQL(loader?: Registerable) { if (loader) { loader.registerFunction(fetchGraphQL, registerGraphqlFetchParams); } else { registerFunction(fetchGraphQL, registerGraphqlFetchParams); } }无 loader 参数调用plasmicapp/host的全局registerFunction将函数推入window.__PlasmicFunctionsRegistry去重逻辑见 packages/host/src/registerFunction.ts。传入 loader若你使用的是自定义 loader如plasmicapp/loader-nextjs则调用 loader 实例上的registerFunction方法。在 Studio 画布环境中platform/canvas-packages/src/graphql.ts 直接调用registerGraphQL()完成注册这说明该函数会以GraphQL名称出现在 Studio 的函数/数据查询面板中注册元数据的displayName: GraphQL。注册元数据揭示的 Studio 集成细节registerGraphqlFetchParams源码定义了该函数在 Studio 中的呈现形态也是理解其既能查询又能变更能力的关键isQuery: true与isMutation: true意味着它既可作为数据查询在页面加载时执行也可作为**变更mutation**绑定到元素交互如按钮 onClick。isQuery/isMutation的语义定义见 packages/host/src/registerFunction.ts。参数面板采用display: flatten的对象形式各字段配置url字符串输入必填method四选一选择器GET/POST/PUT/DELETE默认POSTrequestGraphQL 代码编辑器lang: graphql必填且编辑器的header 与 endpoint 提示会动态取自opts.headers与opts.urlheaders: ([opts]) opts?.headers、endpoint: ([opts]) opts?.url ?? varOverrides显示名为 Variable overrides 的对象输入。在项目代码中接入安装pnpm add plasmicpkgs/graphql plasmicapp/host plasmicpkgs/fetch # 或 npm install plasmicpkgs/graphql plasmicapp/host plasmicpkgs/fetch注意plasmicpkgs/graphql声明了 peer 依赖plasmicapp/host 1.0.211与plasmicpkgs/fetch ^0.0.5安装时需要一并满足。使用 loader 注册推荐在 loader 模式如 Next.js 的plasmic-init.ts中import { registerGraphQL } from plasmicpkgs/graphql; // 或直接从本地源码路径引入plasmicpkgs/graphql/src/index.ts registerGraphQL(); // 全局注册函数会出现在 Studio 的 GraphQL 数据查询中若使用自定义 loader 实例则可改为registerGraphQL(loader)。直接调用函数脱离 StudiofetchGraphQL本身就是普通 async 函数可在任意 JS/TS 环境中直接调用import { fetchGraphQL } from plasmicpkgs/graphql; const res await fetchGraphQL({ url: https://graphql.contentful.com/content/v1/spaces/YOUR_SPACE_ID, method: POST, headers: { Authorization: Bearer YOUR_ACCESS_TOKEN, }, request: { query: query GetPosts { blogPostCollection(order: date_DESC, limit: 10) { items { slug title date } } } , }, }); console.log(res.statusCode); // 200 console.log(res.body.data); // GraphQL data作为 GraphQL 查询与响应解析的参考范式仓库的 examples/contentful/lib/api.ts 展示了针对 Contentful GraphQL 端点含Authorization头、查询字符串常量、data字段提取的完整写法其中query字符串与响应提取逻辑可平滑迁移到fetchGraphQL的request.query与body.data上。在 Studio 中的典型用法打开 Plasmic Studio进入支持数据查询的组件/页面添加数据查询Data Query选择GraphQL函数填写URLGraphQL 端点与GraphQL 查询request代码编辑器会基于 URL 提供端点补全按需选择method默认 POST、配置headers如认证 Token若需运行时动态变量通过Variable overrides传入覆盖值查询结果以{ statusCode, headers, body }形式暴露绑定到组件属性时取body.data路径若要触发写操作mutation将该函数绑定到元素交互动作函数元数据中isMutation: true使 Studio 允许此用途。注意事项与边界查询字符串长度GET 方式将整个 query 与序列化后的 variables 放入 URL超长查询可能导致 URL 超限或被代理截断复杂查询建议使用 POST。变量合并优先级varOverrides始终覆盖request.variables中的同名键请避免命名冲突造成意外覆盖。错误处理网络/HTTP 层错误由plasmicpkgs/fetch以HttpError携带status与info抛出GraphQL 层错误errors数组则以正常 200 返回在body.errors中需要在业务侧判断。版本约束包名与 API 以当前仓库为准0.0.48peer 依赖plasmicapp/host 1.0.211Studio 内嵌注册入口见 platform/canvas-packages/src/graphql.ts。进一步阅读公共 API 报告plasmicpkgs/graphql/api/index.api.md核心实现plasmicpkgs/graphql/src/index.ts底层 HTTP 执行器plasmicpkgs/fetch/src/index.ts自定义函数注册机制与元数据定义packages/host/src/registerFunction.ts包配置与依赖声明plasmicpkgs/graphql/package.jsonGraphQL 查询参考范式examples/contentful/lib/api.ts赞分享低代码前端后端【免费下载链接】plasmicVisual builder for React. Build apps, websites, and content. Integrate with your codebase.项目地址https://gitcode.com/gh_mirrors/pl/plasmic点击查看免费下载相关推荐SVGR与GraphQL在数据查询中集成SVG组件的方案SVGR与GraphQL在数据查询中集成SVG组件的方案 你是否还在为数据可视化中的图标系统与GraphQL数据查询难以协同工作而烦恼本文将展示如何通过SV前端开发工具next.roadmap.sh 中的 GraphQL 集成高效数据查询方案next.roadmap.sh 中的 GraphQL 集成高效数据查询方案 GraphQL 作为一种高效的数据查询语言在 next.roadmap.sh 项DataV GraphQL集成高效数据查询方案DataV GraphQL集成高效数据查询方案 引言数据可视化的痛点与解决方案 在现代数据可视化Data Visualization项目中开发者常常面前端数据可视化UI组件上一篇react-slingshot 前端构建工具配置生成器自动化配置工具下一篇Python项目管理Douyin-Bot的依赖更新与版本控制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 Plasmic 数据查询中集成 GraphQL：`@plasmicpkgs/graphql` 自定义函数深度解析
低代码前端后端【免费下载链接】plasmicVisual builder for React. Build apps, websites, and content. Integrate with your codebase.项目地址https://gitcode.com/gh_mirrors/pl/plasmic点击查看免费下载plasmicpkgs/graphql是 Plasmic 官方维护的包用于在 Plasmic Studio 的数据查询Data Queries与交互动作Mutations中直接执行 GraphQL 请求。通过本文你将掌握fetchGraphQL函数的完整参数语义、GET/POST 请求构造的底层原理、返回值结构以及如何在代码中通过registerGraphQL完成注册并与你自己的 React 代码库打通。包概览从 API 报告到真实源码本仓库中与本文直接相关的文档是 plasmicpkgs/graphql/api/index.api.md它是由 API Extractor 自动生成的公共 API 报告完整刻画了该包的对外接口面。结合 plasmicpkgs/graphql/src/index.ts 的实现我们可以得到一张完整的技术地图。从 plasmicpkgs/graphql/package.json 可知包名plasmicpkgs/graphql当前仓库版本0.0.48定位Custom functions for running GraphQL queries from Plasmic data queries.为 Plasmic 数据查询提供执行 GraphQL 查询的自定义函数模块格式同时提供 CJSdist/index.js、ESMdist/index.esm.js与类型声明dist/index.d.ts兼容各类打包器Peer 依赖plasmicapp/host 1.0.211注册机制、plasmicpkgs/fetch ^0.0.5底层 HTTP 执行器包对外只暴露两个公共 APIfetchGraphQL函数与registerGraphQL注册函数它们构成了执行与注册两个核心环节。FetchGraphQLOpts参数契约详解根据 index.api.md 中的接口定义fetchGraphQL接受一个名为opts的对象其类型为FetchGraphQLOpts字段类型必填说明urlstring是GraphQL 端点地址例如https://graphql.contentful.com/content/v1/spaces/spacemethodGET \| POST \| PUT \| DELETE是HTTP 方法Studio 面板中默认值为POSTheadersRecordstring, string否附加请求头如Authorization、Content-Type默认{}request{ query: string; variables?: object }是核心请求体query为 GraphQL 查询字符串variables为查询变量对象varOverridesRecordstring, any否变量覆盖层用于在运行时注入/覆盖variables中的同名变量从 源码实现 可以看到其硬性校验url、method、request三者缺一不可否则直接抛出Error(url, method, and request are required)。这一点与 Studio 注册元数据中url、request均标记为required: true完全对应。请求构造GET 与 POST/PUT/DELETE 的分支逻辑fetchGraphQL的核心在于按 HTTP 方法分两条路径构造请求源码 如下if (method GET) { // https://graphql.org/learn/serving-over-http/#get-request-and-parameters const urlWithQueryParams new URL(url); urlWithQueryParams.searchParams.set(query, request.query); urlWithQueryParams.searchParams.set( variables, JSON.stringify({ ...request.variables, ...varOverrides }) ); return fetch({ url: urlWithQueryParams.toString(), method: GET, headers }); } else { return fetch({ url, method, headers, body: { query: request.query, variables: { ...request.variables, ...varOverrides }, }, }); }两条路径的关键差异GET遵循 GraphQL over HTTP 规范代码注释明确引用了 graphql.org 的 GET 参数规范将query作为普通 URL 查询参数、variables作为JSON.stringify后的查询参数拼接到 URL 上不发送请求体。POST/PUT/DELETE将{ query, variables }作为 JSON 请求体发送。值得注意的合并逻辑{ ...request.variables, ...varOverrides }意味着varOverrides中声明的变量会覆盖request.variables中的同名变量。这正是Variable overrides字段的设计意图——在 Studio 面板中配置的静态变量可以被运行时传入的动态值如页面参数、用户上下文覆盖。返回值结构fetchGraphQL返回一个 Promiseresolve 值为{ statusCode: number; // HTTP 状态码 headers: { [k: string]: string }; // 响应头映射 body: any; // 已解析的 JSON 响应体含 data / errors }该返回结构并非plasmicpkgs/graphql自行定义而是直接透传自底层plasmicpkgs/fetch的fetch函数。查看 plasmicpkgs/fetch/src/index.ts 的实现可以发现三个重要的底层行为自动请求头若调用方未显式提供会默认补上Accept: application/json存在 body 时还会补上Content-Type: application/json。响应体自动解析响应文本会尝试JSON.parse解析失败时原样返回字符串maybeParseJSON。错误抛出非 2xx 状态码会抛出HttpErrorname为HttpError携带status与info字段错误处理模式参考自 SWR 文档。因此在 Plasmic 数据查询中使用时通常需要从body.data中读取 GraphQL 的data字段并自行检查body.errors处理服务端错误。registerGraphQL向 Plasmic 注册自定义函数registerGraphQL(loader?: Registerable)是包的第二个公共 API用于把fetchGraphQL及其元数据注册到 Plasmic 运行时export function registerGraphQL(loader?: Registerable) { if (loader) { loader.registerFunction(fetchGraphQL, registerGraphqlFetchParams); } else { registerFunction(fetchGraphQL, registerGraphqlFetchParams); } }无 loader 参数调用plasmicapp/host的全局registerFunction将函数推入window.__PlasmicFunctionsRegistry去重逻辑见 packages/host/src/registerFunction.ts。传入 loader若你使用的是自定义 loader如plasmicapp/loader-nextjs则调用 loader 实例上的registerFunction方法。在 Studio 画布环境中platform/canvas-packages/src/graphql.ts 直接调用registerGraphQL()完成注册这说明该函数会以GraphQL名称出现在 Studio 的函数/数据查询面板中注册元数据的displayName: GraphQL。注册元数据揭示的 Studio 集成细节registerGraphqlFetchParams源码定义了该函数在 Studio 中的呈现形态也是理解其既能查询又能变更能力的关键isQuery: true与isMutation: true意味着它既可作为数据查询在页面加载时执行也可作为**变更mutation**绑定到元素交互如按钮 onClick。isQuery/isMutation的语义定义见 packages/host/src/registerFunction.ts。参数面板采用display: flatten的对象形式各字段配置url字符串输入必填method四选一选择器GET/POST/PUT/DELETE默认POSTrequestGraphQL 代码编辑器lang: graphql必填且编辑器的header 与 endpoint 提示会动态取自opts.headers与opts.urlheaders: ([opts]) opts?.headers、endpoint: ([opts]) opts?.url ?? varOverrides显示名为 Variable overrides 的对象输入。在项目代码中接入安装pnpm add plasmicpkgs/graphql plasmicapp/host plasmicpkgs/fetch # 或 npm install plasmicpkgs/graphql plasmicapp/host plasmicpkgs/fetch注意plasmicpkgs/graphql声明了 peer 依赖plasmicapp/host 1.0.211与plasmicpkgs/fetch ^0.0.5安装时需要一并满足。使用 loader 注册推荐在 loader 模式如 Next.js 的plasmic-init.ts中import { registerGraphQL } from plasmicpkgs/graphql; // 或直接从本地源码路径引入plasmicpkgs/graphql/src/index.ts registerGraphQL(); // 全局注册函数会出现在 Studio 的 GraphQL 数据查询中若使用自定义 loader 实例则可改为registerGraphQL(loader)。直接调用函数脱离 StudiofetchGraphQL本身就是普通 async 函数可在任意 JS/TS 环境中直接调用import { fetchGraphQL } from plasmicpkgs/graphql; const res await fetchGraphQL({ url: https://graphql.contentful.com/content/v1/spaces/YOUR_SPACE_ID, method: POST, headers: { Authorization: Bearer YOUR_ACCESS_TOKEN, }, request: { query: query GetPosts { blogPostCollection(order: date_DESC, limit: 10) { items { slug title date } } } , }, }); console.log(res.statusCode); // 200 console.log(res.body.data); // GraphQL data作为 GraphQL 查询与响应解析的参考范式仓库的 examples/contentful/lib/api.ts 展示了针对 Contentful GraphQL 端点含Authorization头、查询字符串常量、data字段提取的完整写法其中query字符串与响应提取逻辑可平滑迁移到fetchGraphQL的request.query与body.data上。在 Studio 中的典型用法打开 Plasmic Studio进入支持数据查询的组件/页面添加数据查询Data Query选择GraphQL函数填写URLGraphQL 端点与GraphQL 查询request代码编辑器会基于 URL 提供端点补全按需选择method默认 POST、配置headers如认证 Token若需运行时动态变量通过Variable overrides传入覆盖值查询结果以{ statusCode, headers, body }形式暴露绑定到组件属性时取body.data路径若要触发写操作mutation将该函数绑定到元素交互动作函数元数据中isMutation: true使 Studio 允许此用途。注意事项与边界查询字符串长度GET 方式将整个 query 与序列化后的 variables 放入 URL超长查询可能导致 URL 超限或被代理截断复杂查询建议使用 POST。变量合并优先级varOverrides始终覆盖request.variables中的同名键请避免命名冲突造成意外覆盖。错误处理网络/HTTP 层错误由plasmicpkgs/fetch以HttpError携带status与info抛出GraphQL 层错误errors数组则以正常 200 返回在body.errors中需要在业务侧判断。版本约束包名与 API 以当前仓库为准0.0.48peer 依赖plasmicapp/host 1.0.211Studio 内嵌注册入口见 platform/canvas-packages/src/graphql.ts。进一步阅读公共 API 报告plasmicpkgs/graphql/api/index.api.md核心实现plasmicpkgs/graphql/src/index.ts底层 HTTP 执行器plasmicpkgs/fetch/src/index.ts自定义函数注册机制与元数据定义packages/host/src/registerFunction.ts包配置与依赖声明plasmicpkgs/graphql/package.jsonGraphQL 查询参考范式examples/contentful/lib/api.ts赞分享低代码前端后端【免费下载链接】plasmicVisual builder for React. Build apps, websites, and content. Integrate with your codebase.项目地址https://gitcode.com/gh_mirrors/pl/plasmic点击查看免费下载相关推荐SVGR与GraphQL在数据查询中集成SVG组件的方案SVGR与GraphQL在数据查询中集成SVG组件的方案 你是否还在为数据可视化中的图标系统与GraphQL数据查询难以协同工作而烦恼本文将展示如何通过SV前端开发工具next.roadmap.sh 中的 GraphQL 集成高效数据查询方案next.roadmap.sh 中的 GraphQL 集成高效数据查询方案 GraphQL 作为一种高效的数据查询语言在 next.roadmap.sh 项DataV GraphQL集成高效数据查询方案DataV GraphQL集成高效数据查询方案 引言数据可视化的痛点与解决方案 在现代数据可视化Data Visualization项目中开发者常常面前端数据可视化UI组件上一篇react-slingshot 前端构建工具配置生成器自动化配置工具下一篇Python项目管理Douyin-Bot的依赖更新与版本控制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考