gatsby_使用TinaCMS + Gatsby编辑Markdown的3种方法

gatsby

Supercharge your static site with real-time content editing! 🚀

通过实时内容编辑增强您的静态网站！ 🚀

In this post, I will explore the three different methods Tina offers to edit Markdown on your Gatsby site. You’ll learn how to set up Tina with both Page Queries and Static Queries.

在本文中，我将探讨Tina提供的三种不同方法来在您的Gatsby网站上编辑Markdown。 您将学习如何通过页面查询和静态查询来设置Tina。

This post will not cover the basics of using Tina with Gatsby. Please reference the documentation on how to initially set up Tina with Gatsby.

这篇文章不会涵盖在Gatsby中使用Tina的基础知识。 请参考有关如何使用Gatsby初始设置Tina的文档 。

页面查询和静态查询有什么关系？ (What’s the deal with Page Queries and Static Queries?)

Before we dive down into editing Markdown with Tina, we have to understand how Gatsby handles querying data with GraphQL.

在开始使用Tina编辑Markdown之前，我们必须了解Gatsby如何使用GraphQL处理查询数据。

You can source data from almost anywhere in Gatsby. In our case, we’re using Markdown. When you build your site, Gatsby creates a GraphQL schema for all the data. Then you use GraphQL in your React components to query your sourced data.

您可以从盖茨比的几乎任何地方获取数据。 在我们的例子中，我们使用Markdown 。 建立网站时，Gatsby会为所有数据创建GraphQL模式。 然后，在React组件中使用GraphQL来查询源数据。

Gatsby allows you to query your data in two ways: Page Queries and Static Queries. Since the release of the React Hooks API and the useStaticQuery hook in Gatsby, it is very easy to query your data.

Gatsby允许您以两种方式查询数据： 页面查询和静态查询 。 自从发布了React Hooks API和Gatsby中的useStaticQuery钩子以来，查询数据非常容易。

There are cases when you can’t use a Static Query though. First, let’s explore the differences.

在某些情况下，您不能使用静态查询。 首先，让我们探索差异。

两个主要区别是： (The two main differences are:)

• Page Queries can accept GraphQL variables. Static Queries can’t.
  页面查询可以接受GraphQL变量。 静态查询不能。
• Page Queries can only be added to page components. Static Queries can be used in all components.
  页面查询只能添加到页面组件。 静态查询可以在所有组件中使用。

So, why can’t we use GraphQL variables in a Static Query? The reason for that is a Static Query doesn’t have access to the page context like a Page Query does. The result is that a Static Query won’t be able to access variables that are defined in the page context.

那么，为什么我们不能在静态查询中使用GraphQL变量呢？ 原因是静态查询无法像页面查询那样访问页面上下文。 结果是静态查询将无法访问在页面上下文中定义的变量。

You can define the page context in your gatsby-node.js file in your createPage function. Here you can supply your page with different variables that will get injected to your page on build time.

您可以在createPage函数的gatsby-node.js文件中定义页面上下文。 在这里，您可以为页面提供不同的变量，这些变量将在构建时注入到页面中。

I use Static Queries as much as possible because I love the hooks API and the ease of composition possibilities it brings. For example, you can create custom hooks and reuse them in multiple components.

我尽可能使用静态查询，因为我喜欢钩子API及其带来的轻松编写可能性。 例如，您可以创建自定义钩子，并将其在多个组件中重复使用。

Let’s say that you have a GraphQL query that grabs metadata that you want on multiple pages. Create a custom React hook with the useStaticQuery Gatsby hook inside of it. Then you can use your custom hook wherever you want and always easily get that data into your component. When you need to have variables in your component, you have to use a Page Query. Page Queries cannot be used with the hooks API and have to be unique and attached to the specific page component.

假设您有一个GraphQL查询，可在多个页面上获取所需的元数据。 创建一个自定义的React挂钩，并在其中使用useStaticQuery Gatsby挂钩。 然后，您可以在任何需要的地方使用自定义钩子，并且始终可以轻松地将数据导入组件中。 当需要在组件中包含变量时，必须使用页面查询。 页面查询不能与hooks API一起使用，并且必须是唯一的并附加到特定的页面组件。

Another great thing with Static Queries is that you can grab the data in the component that needs the data. That prevents prop drilling and your data is more tightly coupled to the component where it is used.

静态查询的另一个优点是，您可以在需要数据的组件中获取数据。 这样可以防止进行钻探，并且您的数据将更紧密地耦合到使用它的组件。

React概述 (React overview)

For getting data, we can use Gatsby's query options. For structuring our components, React also offers a couple of options. You can either create your component as a class or a functional component. Before the React Hooks API, you had to use class components to have state in your components. Now with hooks, you can do this with functional components.🥰

为了获取数据，我们可以使用盖茨比的查询选项。 为了构造我们的组件，React还提供了两个选项。 您可以将您的组件创建为类或功能组件 。 在使用React Hooks API之前，您必须使用类组件才能在组件中具有状态。 现在有了钩子，您可以使用功能组件来完成此操作。

使用Tina编辑Markdown的三种方法 (Three ways to edit markdown with Tina)

Given all the options for creating components and souring data in Gatsby, we have to choose the most suitable approach for the project. Tina can work with all of these options, providing three different approaches for editing Markdown with Gatsby as described below.

给定Gatsby中用于创建组件和优化数据的所有选项，我们必须为该项目选择最合适的方法。 Tina可以使用所有这些选项，提供如下三种使用Gatsby编辑Markdown的不同方法 。

• remarkForm - A Higher Order Component used when you source data from a Page Query in Gatsby. This component can be utilized with both functional and class components. Please note the subtle difference here! The only difference in naming from the render props component is the lowercase “r”.

  remarkForm-从Gatsby中的页面查询中获取数据时使用的高阶组件 。 该组件可以与功能组件和类组件一起使用。 请注意此处的细微差别！ 与render props组件在命名上的唯一区别是小写字母“ r”。

• useLocalRemarkForm - A React Hook that is intended for functional components sourcing data from either a Static or a Page Query. If the component is sourcing static data, Gatsby's useStaticQuery hook would be called.

  useLocalRemarkForm-一个React Hook ，用于功能组件从“静态”或“页面查询”中获取数据。 如果组件正在获取静态数据，则将调用Gatsby的useStaticQuery挂钩。

• RemarkForm - A Render Props Component that you can use in class components sourcing data from either a Static or a Page Query. Static data would be sourced via Gatsby’s StaticQuery render props component.

  RemarkForm-一个渲染道具组件 ，您可以在类组件中使用该组件从静态查询或页面查询中获取数据。 静态数据将通过Gatsby的StaticQuery渲染道具组件获取。

remarkForm-如何使用它以及为什么它不能与静态查询一起使用。 (remarkForm - How to use it and why it won’t work with Static Queries.)

First, Let’s dive into how to hook up TinaCMS with a Page Query. The remarkForm Component in TinaCMS is a Higher Order Component, a HOC in short. This means that it is a function that takes in another component and will return a new component that has added functionality to it.

首先，让我们深入研究如何通过页面查询连接TinaCMS。 remarkForm中的remarkForm组件是一个高阶组件 ，简称HOC。 这意味着它是一个接受另一个组件的函数，并将返回为其添加了功能的新组件。

If you’re not familiar with HOC's, I suggest you read about them in the React official docs. They are considered “advanced usage” in the React world.

如果您不熟悉HOC，建议您在React官方文档中阅读它们。 在React世界中，它们被视为“高级用法”。

The remarkForm component wants another component as an argument and is intended for Page Queries. A Page Query injects the data as a prop to the component and we access the data from this prop. With a useStaticQuery hook, the data is collected in a variable, that you choose, inside the component itself. That means if you're using the useStaticQuery hook in Gatsby you won’t have a component to give the remarkForm HOC. Bummer!😞 That’s why you can only use the remarkForm component with Page Queries.

remarkForm组件需要另一个组件作为参数，并用于页面查询。 页面查询将数据作为道具注入组件，我们从该道具访问数据。 使用useStaticQuery挂钩，可以将数据收集到您选择的组件本身内部的变量中。 这意味着，如果您在Gatsby中使用useStaticQuery挂钩，则将没有组件来提供remarkForm HOC。 这就是为什么您只能在页面查询中使用remarkForm组件的原因。

So how do you use this component with a Page Query in Gatsby? First, check out the fictive Star Wars component below. It will show the three steps needed to hook everything up:

那么如何在Gatsby中的页面查询中使用此组件 ？ 首先，查看下面的虚拟星球大战组件。 它将显示连接所有内容所需的三个步骤：

// 1. Import the `remarkForm` HOC
import { remarkForm } from 'gatsby-tinacms-remark'

const StarWarsMovie = ({ data: { markdownRemark } }) => {
  return <h1>{markdownRemark.frontmatter.title}</h1>
}

// 2. Wrap your component with `remarkForm`
export default remarkForm(StarWarsMovie)

// 3. Add the required ...TinaRemark fragment to your Page Query
export const pageQuery = graphql`
  query StarWarsMovieById($id: String!) {
    markdownRemark(fields: { id: { eq: $id } }) {
      id
      html
      frontmatter {
        title
        releaseDate
        crawl
      }
      ...TinaRemark
    }
  }
`

The above code is a component that displays information about Star Wars movies. For now, it just displays a title, but it could also display the release date and the crawl text in the intro to the film. But that’s another story in a galaxy far far away ... ⭐

上面的代码是显示有关《星球大战》电影的信息的组件。 目前，它仅显示标题，但也可以在电影简介中显示发行日期和抓取文本。 但这是一个遥远的星系中的另一个故事...-

The first step in this example is to import the remarkForm hook from the Gatsby plugin ‘gatsby-tinacms-remark’. This is the plugin that makes TinaCMS work with Markdown files.

此示例中的第一步是从Gatsby插件“ gatsby-tinacms-remark”导入remarkForm钩子。 这是使TinaCMS处理Markdown文件的插件。

There’s no need to do any additions to the code inside of the component itself. It could be any component — functional or class — structured in the way you want it. The only thing you have to do with the component itself is to wrap your component with the remarkForm HOC when you export it.

无需在组件本身内部添加任何代码。 它可以是您想要的任何结构化的组件(功能或类)。 您与组件本身唯一要做的就是在导出组件时使用remarkForm HOC包装组件。

One more thing you have to do before you are good to go is to add the GraphQL fragment ...TinaRemark in your query. This is needed for TinaCMS to recognize your data and create the required editor fields in the TinaCMS sidebar. After that, you only have to start up your dev server to show the site and the Tina sidebar.

在做好准备之前，您还需...TinaRemark在查询中添加GraphQL片段...TinaRemark 。 TinaCMS需要此功能来识别您的数据并在TinaCMS边栏中创建所需的编辑器字段。 之后，您只需要启动开发服务器即可显示该站点和Tina侧栏。

Easy enough isn’t it? Just three small steps and you’ll have a beautiful sidebar to edit your content on your site. 🤟

够容易不是吗？ 仅需三个小步骤，您就会拥有一个漂亮的侧边栏，可以在您的网站上编辑内容。 🤟

But what if you want to use a Static Query and not a Page Query?

但是，如果要使用静态查询而不是页面查询该怎么办？

useLocalRemarkForm来解救！ (useLocalRemarkForm to the rescue!)

We’ve learned that the remarkForm HOC won’t work on Static Queries. So we’ll have to find another solution for using Static Queries with TinaCMS.

我们了解到， remarkForm HOC在静态查询中不起作用。 因此，我们必须找到另一种将静态查询与TinaCMS结合使用的解决方案。

Great news!

好消息！

The remarkForm component is essentially a "wrapper" for the useLocalRemarkForm hook. 👀 It takes in a component as an argument, calls useLocalRemarkForm with the Page Query data and returns a new component with the query data and TinaCMS connected to it.

remarkForm组件本质上是useLocalRemarkForm挂钩的“包装器”。 👀它接受一个组件作为参数，使用Page Query数据调用useLocalRemarkForm并返回一个新组件，其中包含查询数据和与其连接的TinaCMS。

We can use the useLocalRemarkForm hook directly, without using the remarkForm HOC. This can be useful with Static Queries or if we just prefer working with hooks!

我们可以直接使用useLocalRemarkForm钩子，而无需使用remarkForm HOC。 这对于“静态查询”或如果我们只喜欢使用钩子很有用！

Take a look at the code example below to get an idea of how useLocalRemarkForm works.

请看下面的代码示例，以了解useLocalRemarkForm工作原理。

// 1. Import useLocalRemarkForm hook
import React from ‘react’;
import { useLocalRemarkForm } from ‘gatsby-tinacms-remark’;
import { useStaticQuery } from ‘gatsby’;

const StarWarsMovie = () => {
  // 2. Add required TinaCMS fragment to the GrahpQL query
    const data = useStaticQuery(graphql`
      query StarWarsMovieById {
        markdownRemark(fields: { id: { eq: "sw-01" } }) {
          id
          html
          frontmatter {
            title
            releaseDate
            crawl
          }
          ...TinaRemark
        }
      }
    `);
  // 3. Call the useLocalRemarkForm hook and pass in the data
  const [markdownRemark] = useLocalRemarkForm(data.markdownRemark);
  return <h1>{markdownRemark.frontmatter.title}</h1>
}

export default StarWarsMovie;

This is just an example component illustrating how useLocalRemarkForm works. In the real world, it would not be an optimal solution using a Static Query for this. That’s because, as you can see, you can’t use variables inside the useStaticQuery hook to make it dynamic. You have to hardcode the movie id. So this query will work for that specific movie only, which is no good.

这只是一个示例组件，说明useLocalRemarkForm工作方式。 在现实世界中，这不是使用静态查询的最佳解决方案。 如您所见，这是因为您无法在useStaticQuery挂钩中使用变量来使其动态化。 您必须对电影ID进行硬编码。 因此，此查询仅适用于该特定电影，这是不好的。

Let’s break down what’s happening here:

让我们分解一下这里发生的事情：

1. We import the useLocalRemarkForm custom hook so we can use it in our component.

   我们导入useLocalRemarkForm自定义钩子，以便可以在组件中使用它。

2. Just as before, the ...TinaRemark fragment is needed in the GraphQL query. So we add that one there.

   和以前一样，在GraphQL查询中需要...TinaRemark片段。 因此，我们在那里添加了一个。

3. When we’ve got our data back from the Gatsby useStaticQuery hook we can call the TinaCMS useLocalRemarkForm hook with that data. This hook will return an array with two elements. The first element is practically the data that we called the hook with. It has the same shape and is ready for us to use in our component. The second element is a reference to the Tina form. We don’t need that one so we don’t destructure it out as we do with the markdownRemark.

   从Gatsby的useStaticQuery挂钩中获取数据后，我们可以使用该数据调用TinaCMS的useLocalRemarkForm挂钩。 这个钩子将返回一个包含两个元素的数组。 实际上，第一个元素是我们称为“挂钩”的数据。 它具有相同的形状，可以随时在组件中使用。 第二个元素是对Tina表单的引用。 我们不需要那个，所以我们不会像对markdownRemark那样进行markdownRemark 。

If you're wondering about this line:

如果您想知道以下内容：

const [markdownRemark] = useLocalRemarkForm(heroData.markdownRemark)

It is an example of ES6 destructuring. As we get an array with two elements back, I destructure out the first element (which is our data) and name it markdownRemark. You can name it whatever you want.

这是ES6销毁的一个示例。 当我们得到一个包含两个元素的数组时，我解构了第一个元素(即我们的数据)并将其命名为markdownRemark 。 您可以随意命名。

RemarkForm-渲染道具组件 (RemarkForm - The Render Prop Component)

You can’t use React Hooks on class components. That’s why Tina provides a RemarkForm component that uses the Render Props pattern.

您不能在类组件上使用React Hooks。 这就是Tina提供使用Render Props模式的RemarkForm组件的原因。

This component works with both Page and Static Queries. I will show how to use it with a Page Query below.

此组件可与页面查询和静态查询一起使用。 我将在下面的页面查询中展示如何使用它。

Take a look at below example:

看下面的例子：

// 1. import the RemarkForm render prop component
import { RemarkForm } from '@tinacms/gatsby-tinacms-remark'

class StarWarsMovie extends React.Component {
  render() {
    /*
     ** 2. Return RemarkForm, pass in markdownRemark
     **    to the remark prop and pass in what you
     **    want to render to the render prop
     */
    return (
      <RemarkForm
        remark={this.props.data.markdownRemark}
        render={({ markdownRemark }) => {
          return <h1>{markdownRemark.frontmatter.title}</h1>
        }}
      />
    )
  }
}

export default StarWarsMovie

// 3. Add the required ...TinaRemark fragment to your Page Query
export const pageQuery = graphql`
  query StarWarsMovieById($id: String!) {
    markdownRemark(fields: { id: { eq: $id } }) {
      id
      html
      frontmatter {
        title
        releaseDate
        crawl
      }
      ...TinaRemark
    }
  }
`

Ok, yet again, let’s see what’s happening here:

好的，再次让我们看看这里发生了什么：

1. We import the RemarkForm component for us to use in our code.

   我们导入RemarkForm组件供我们在代码中使用。

2. In our return statement we return the RemarkForm component and pass in it's predefined, and required props. The remark prop provides RemarkForm with the markdown data sourced from the Page Query. The render prop gets the JSX that we want to render through a function, or a render prop. RemarkForm will hook up Tina for editing the data and then render whatever is specified in the render prop function.

   在我们的return语句中，我们返回RemarkForm组件，并传入其预定义的必需道具。 备注道具为RemarkForm提供来自页面查询的markdown数据。 渲染道具通过函数或渲染道具获取我们要渲染的JSX。 RemarkForm将连接Tina来编辑数据，然后渲染render prop函数中指定的内容。

3. Just as before we have to add the ...TinaRemark fragment to the Page Query.

   和之前一样，我们必须在页面查询中添加...TinaRemark片段。

下一步 (Next steps)

That's it! Three ways of using Tina for editing Markdown files in Gatsby. 🎉

就是这样 ！ 使用Tina在Gatsby中编辑Markdown文件的三种方式。 🎉

In this post, we learned about how to set up Tina with both Static Queries and Page Queries in Gatsby. We also learned about three different ways to edit markdown with Tina depending on your type of React component.

在本文中，我们学习了如何在Gatsby中使用静态查询和页面查询来设置Tina 。 我们还学习了三种不同的方式来编辑Tina的markdown，这取决于您的React组件类型。

This is just the basics to get you started. If you like Tina and want to learn more you should check out the official docs. There’s a lot more stuff to read there and some interesting use cases.

这只是入门的基础。 如果您喜欢Tina并想了解更多信息，请查看官方文档 。 那里还有很多东西要读，还有一些有趣的用例。

For example, you can learn how to apply inline editing and also how to customize the form fields in the Tina sidebar.

例如，您可以学习如何应用内联编辑以及如何在Tina边栏中自定义表单字段 。

Tina is a great addition to the React ecosystem and static site generators like Gatsby. It gives your site a pleasant and easy way to edit and interact with your content. I’m thrilled to see how big TinaCMS will be and what it can do as it evolves!

Tina是React生态系统和Gatsby等静态站点生成器的重要补充。 它为您的网站提供了一种轻松愉快的方式来编辑您的内容并与之交互。 我很高兴看到TinaCMS将会有多大，以及它的发展能做什么！

Originally published on TinaCMS.org

最初发布于TinaCMS.org

翻译自: https://www.freecodecamp.org/news/3-ways-to-edit-markdown-with-tina-gatsby/

gatsby