Alley 块编辑器工具

此软件包包含一组模块,用于 齐列 帮助为 WordPress 块编辑器构建特性.

安装

在您的工程中安装此软件包 :

npm install @alleyinteractive/block-editor-tools --save

使用量

要使用此软件包中的模块,请使用 import 声明.

示例

import { usePostMeta } from '@alleyinteractive/block-editor-tools';

const MyComponent = () => {
  const [meta, setMeta] = usePostMeta();
  const { my_meta_key: myMetaKey } = meta;

  return (
    <TextControl
      label={__('My Meta Key', 'alley-scripts')}
      value={myMetaKey}
      onChange={(newValue) => setMeta({ ...meta, my_meta_key: newValue })}
    />
  );
};

以下是所有可用组件、钩子和服务的文件.

构成部分

反应组件可以在WordPress块编辑器内使用.

音频选择器

允许用户使用媒体模式或通过直接方式选择或删除音频 URL条目. 这个部件是薄薄的包裹 MediaPicker 设置 允许类型 MediaPicker 改为 audio 以及提供习惯 在编辑器中嵌入所选音频的预览组件.

关于如何使用这一组件的更多信息,参见: 媒体选择器。 。 。 .

使用量

<AudioPicker
  className="audio-picker"
  onReset={() => setAttributes({ audioId: 0 })}
  onUpdate={({ id }) => setAttributes({ audioId: id })}
  value={audioId}
/>

道具

复选框

提供一个使用 Checkbox 提供同等条件的组件 多选择而无需使用 SelectControl 组件.

使用量

<Checkboxes
  label={__('Setting', 'alley-scripts')}
  value={setting}
  onChange={(newValue) => setAttributes({ setting: newValue })}
  options={[
    { value: 'option-1', label: __('Option 1', 'alley-scripts') },
    { value: 'option-2', label: __('Option 2', 'alley-scripts') },
  ]}
/>

道具

CSV上载器

允许用户上传一个CSV文件,该文件在浏览器中被解析,被转换为JSON结构,通过用户指定的回调功能来进行进一步转换,并被保存来阻断属性. 此组件旨在将生成的 JSON 数据保存到 postmeta 中,但这在母块范围中被控制.

使用量

将一个CSV上传组件与回调来进一步处理JSON数据.

  <CSVUploader
    attributeName="data"
    callback={transformData}
    setAttributes={setAttributes}
  />

回调函数

回调函数是可选的,可以进一步处理解析器返回的数据.

回调函数接受一组对象作为其唯一的参数. 每个对象都将是CSV中一行的描述,密钥匹配文件头.

使用以下格式的 CSV 文件 :

title,slug,description
Sample Title,sample-title,Lorem ipsum dolor sit amet.

传递到回调函数的对象阵列将采取以下形式:

[
  {
    title: 'Sample Title',
    slug: 'sample-title',
    description: 'Lorem ipsum dolor sit amet.',
  },
]

在引擎盖下,CSV解析器使用PapaParse,并试图根据每列中的数据对数据格式进行智能选择. 例如,整数的列应作为整数通过.

图像选择器

允许用户使用媒体模式或通过直接 URL条目. 这个部件是薄薄的包裹 MediaPicker 设置 允许类型 MediaPicker 改为 image 以及提供习惯 在编辑器中嵌入所选图像的预览组件.

关于如何使用这一组件的更多信息,参见: 媒体选择器。 。 。 .

使用量

<ImagePicker
  className="image-picker"
  imageSize="thumbnail"
  onReset={() => setAttributes({ imageId: 0 })}
  onUpdate={({ id }) => setAttributes({ imageId: id })}
  value={imageId}
/>

道具

媒体选择器

允许为块设置一个简单的媒体上传/替换/移动功能.

使用量

<MediaPicker
  allowedTypes={['application/pdf']}
  className="media-picker"
  onReset={() => setAttributes({ mediaId: 0 })}
  onUpdate={({ id }) => setAttributes({ mediaId: id })}
  value={mediaId}
/>

价值 mediaId 是媒体元素的标识,并且从 props.attributes。 。 。 .

对于MediaPicker还有额外的选项,可以通过 以下为道具. 例如,MediaPicker 也支持 URL 条目 作为自定义预览组件, 当您想要渲染图像时有用 或嵌入,而不只是文本链接到选定的资产.

道具

邮箱

允许一个简单的职位选择/替换/移动功能,类似于从媒体库中选择一个项目.

使用量

<PostPicker
  allowedTypes={['post']}
  className="post-picker"
  onReset={() => setAttributes({ postId: 0 })}
  onUpdate={( id ) => setAttributes({ postId: id })}
  value={postId}
/>

PostPicker 还有其他选项,可以通过 以下为道具. 例如, PostPicker 也支持自定义参数 发送到搜索端点、 预览自定义渲染器、 搜索自定义渲染器 结果,以及一个自定义函数,用于获取带有后标识的后台数据.

道具

安全带

用于安全创建组件的轻量级可再利用组件 包含任意 HTML,例如来自 REST API.

用途 dangerouslySetInnerHTML 财务报告和审定财务报表 DOMPurify 在引擎盖下.

因为如何 dangerouslySetInnerHTML 工作,你必须 提供一个标记以注入 HTML 。 如果您想要的 HTML 注射被包裹在您想要使用的标签中, 您需要 先把它脱了.

使用量

<SafeHTML
  className="some-classname"
  html="<p>some arbitrary html</p>"
  tag="div"
/>

道具

选择器

允许用户根据 REST API 选择一个项或多个项。 可选的,接受限制搜索的子类型列表. 使用搜索端点,所以项目必须在 REST API 中具有适当的能见度才能出现在结果列表中.

重要的是,此组件不会保存选中的项目, 它只是返回到 onSelect 方法。 附加块或组件负责以某种方式管理所选项目,并使用该组件作为选择新项目的方法.

使用量

  <Selector
    className="custom-autocomplete-classname"
    emptyLabel="No items."
    label="Label"
    multiple
    onSelect={onSelect}
    placeholder="Placeholder..."
    subTypes={['post', 'page']}
    selected={[{
      id: 123,
      title: 'Title of Element',
    }]}
    threshold={3}
  />

道具

术语选择器

允许用户使用针对REST API的搜索查询来选择一个名词或多个名词. 可选的,接受限制搜索的子类型列表. 使用搜索端点,所以术语必须在REST API中具有适当的能见度才能出现在结果列表中.

重要的是,这个组件没有保存选中的术语, 它只是返回到 onSelect 方法。 附加区块或组件负责以某种方式管理所选术语,并使用该组件作为选择新术语的方法.

使用量

  <TermSelector
    className="custom-termselector-classname"
    label="Select a category"
    multiple
    onSelect={onSelect}
    placeholder="Select a category..."
    subTypes={['category', 'post_tag']}
    selected={[{
      id: 123,
      title: 'Title of Category',
    }]}
  />

道具

视频选择器

允许用户使用媒体模式或通过直接 URL条目. 这个部件是薄薄的包裹 MediaPicker 设置 允许类型 MediaPicker 改为 video 以及提供习惯 在编辑器中嵌入所选视频的预览组件.

关于如何使用这一组件的更多信息,参见: 媒体选择器。 。 。 .

使用量

<VideoPicker
  className="video-picker"
  onReset={() => setAttributes({ videoId: 0 })}
  onUpdate={({ id }) => setAttributes({ videoId: id })}
  value={videoId}
/>

道具

钩子

Hooks是自定义的反应钩子,在块编辑器内提供各种功能.

使用锁定Name

自定义反应钩子返回块名 .

使用量

const MyBlock = ({ clientId }) => {
  const blockName = useBlockName(clientId);

  ...
};

const MyBlock = ({ clientId }) => {
  const parentBlockClientId = useParentClientId(clientId);
  const parentBlockName = useBlockName(parentBlockClientId);
  ...
};

使用当前 PostId

自定义回放钩子以获取当前后置ID .

使用量

const MyBlock = () => {
  const currentPostID = useCurrentPostId();

  if (currentPostID) {
    ...
  }
};

调试

自定义反应钩子, 创建并返回一个新的已解开的已传递值版本, 它将推迟执行, 直至自上次被引用以来的等待已过毫秒后

@ 见 https://github.com/alleyinteractive/alley-scripts/issues/250 页面存档备份,存于互联网档案馆

使用量

const MyComponent = () => {
  const [value, setValue] = useState('');
  const debouncedValue = useDebounce(value, 500);

  // This value will display after 500 miliseconds
  useEffect(() => {
    // Kickoff Function on a delay.
  }, [debouncedValue]);

  return (
    <>
      <TextControl
        label={__('Set Value', 'your-textdomain-here')}
        onChange={(next) => setValue(next)}
        value={value}
      />
    </>
  );
};

使用 Has 内锁

自定义反应钩,它决定一个块是否有内块.

使用量

const MyBlock = ({
 clientId
}) => {
  const hasInnerBlocks = useHasInnerBlocks(clientId);

  if (hasInnerBlocks) {
    ...
  } else {
    ...
  }

  ...
};

使用内锁索引

返回当前块相对于其兄弟姐妹的索引的自定义反应钩 在母块内.

使用量

const MyBlock = ({
 clientId
}) => {
  const blockIndex = useInnerBlockIndex(clientId);

  ...
};

使用内锁属性

自定义回弹钩,返回当前块的内块属性.

使用量

const MyBlock = ({
 clientId
}) => {
  const innerBlockAttributes = useInnerBlocksAttributes(clientId);

  ...
};

使用内锁

自定义回击钩, 返回当前块的内块数 .

使用量

const MyBlock = ({
 clientId
}) => {
  const innerBlocksCount = useInnerBlocksCount(clientId);

  ...
};

使用媒体

给定了 ID 的附件数据的自定义反应钩子 .

使用量

const MyBlock = ({
    imageID,
}) => {
  const image = useMedia(imageID);

  ...
};

使用父目录

返回当前块的父块的自定义反光钩 .

使用量

const MyBlock = ({ clientId }) => {
  const parentBlock = useParentBlock(clientId);

  ...
};

使用父目录属性

自定义反应钩子,返回当前块的父块属性 .

使用量

const MyBlock = ({
 clientId
}) => {
  const parentBlockAttributes = useParentBlockAttributes(clientId);

  ...
};

使用父关

自定义反应钩子,可以返回当前块母块的客户端ID.

使用量

const MyBlock = ({ clientId }) => {
  const parentBlockClientId = useParentClientId(clientId);

  ...
};

使用邮箱

一个自定义的 React 钩子,用于获取给定的后端ID和后端类型的后端数据.

使用量

const MyBlock = ({
 postID,
 postType = 'post',
 options = { context: 'view' }
}) => {
  const post = usePost(postID, postType, options);

  if (post) {
    ...
  }
};

使用后边键

自定义反应钩钩以获取只给定的后端ID的数据 . 如果您有邮件类型, 请使用 usePost 换句话说.

使用量

const MyBlock = ({
 postID,
}) => {
  const post = usePostById(postID);

  if (post) {
    ...
  }
};

您也可以通过一个函数来查找通过后 id 的邮件类型 . 此函数必须返回属于员额类型的字符串 .

const MyBlock = ({
 postID,
}) => {
  const myCustomPostTypeLookup = (id) => (
    myCustomPostTypeMap[id]
  );

  const post = usePostById(postID, myCustomPostTypeLookup);

  if (post) {
    ...
  }
};

您也可以将选项传递给基本的 API 查询 。 譬如说, 在这里,我们将如何获得一个带有编辑背景的文章.

const MyBlock = ({
 postID,
}) => {
  const post = usePostById(postID, null, { context: 'edit' });

  if (post) {
    ...
  }
};

使用后视网膜

一个自定义的回放钩子,可以用实体Prop来包装与postmeta合作. 这个 钩子旨在减少需要读取的组件中的锅炉板代码 并写邮报。 默认情况下,它运行 在邮站上为当前职位, 但是,您可以选择通过一个邮件类型和发送ID,以便获取和设定 用于任意员额的元员额.

使用量

编辑当前帖子的元

const MyComponent = () => {
  const [meta, setMeta] = usePostMeta();
  const { my_meta_key: myMetaKey } = meta;

  return (
    <TextControl
      label={__('My Meta Key', 'your-textdomain-here')}
      onChange={(next) => setMeta({ ...meta, my_meta_key: next })}
      value={myMetaKey}
    />
  );
};

编辑另一篇文章的Meta

const MyComponent = ({
  postId,
  postType,
}) => {
  const [meta, setMeta] = usePostMeta(postType, postId);
  const { my_meta_key: myMetaKey } = meta;

  return (
    <TextControl
      label={__('My Meta Key', 'your-textdomain-here')}
      onChange={(next) => setMeta({ ...meta, my_meta_key: next })}
      value={myMetaKey}
    />
  );
};

使用PostMetaValue 数据

自定义的回放钩子, 它用实体 Prop 来包装特定的工作 邮递值。 它返回指定元密钥的值以及 a 元值设置器。 这个钩子是为了减少锅炉板码 在需要读取和写出邮编的组件中。 这和 使用 PostMeta 在其中操作特定元键/值对. 默认情况下,它运行在 postmeta 上,用于当前职位,但你可以 可选择通过一个员额类型和员额ID,以获取和设置员额元a 专设职位.

使用量

编辑当前帖子的元

const MyComponent = () => {
  const [myMetaKey, setMyMetaKey] = usePostMetaValue('my_meta_key');

  return (
    <TextControl
      label={__('My Meta Key', 'your-textdomain-here')}
      onChange={setMyMetaKey}
      value={myMetaKey}
    />
  );
};

编辑另一篇文章的Meta

const MyComponent = ({
  postId,
  postType,
}) => {
  const [myMetaKey, setMyMetaKey] = usePostMetaValue('my_meta_key', postType, postId);

  return (
    <TextControl
      label={__('My Meta Key', 'your-textdomain-here')}
      onChange={setMyMetaKey}
      value={myMetaKey}
    />
  );
};

使用邮箱

一个自定义的 React 钩子来取取多个帖子的数据,给定了一系列帖子ID和单一帖子类型.

使用量

const MyBlock = ({
 postIDs,
}) => {
  const posts = usePosts(postIDs, postType);

  if (posts) {
    ...
  }
};

术语

一个自定义的回放钩子,它用实体Prop来包接邮件的术语. 它返回一个数组,该数组包含一个从一个 给定分类,以及设置给定条件的辅助函数 员额。 这个钩子旨在减少组件中的锅炉板代码 需要更新一个职位的条件。 默认情况下,它按下列条件运作: 当前员额,但您可以选择通过一个员额类型和员额ID,以便 获得并设定任意职位的条件.

使用量

编辑当前职位术语

const MyComponent = ({
  taxonomy,
}) => {
  const [terms, setTerms] = useTerms(null, null, taxonomy);

  return (
    <SelectControl
      label={__('My Terms', 'your-textdomain-here')}
      multiple
      onChange={(next) => setTerms(next)}
      options={options}
      value={terms}
    />
  );
};

编辑另一邮政术语

const MyComponent = ({
  postId,
  postType,
  taxonomy,
}) => {
  const [terms, setTerms] = useTerms(postType, postId, taxonomy);

  return (
    <SelectControl
      label={__('My Terms', 'your-textdomain-here')}
      multiple
      onChange={(next) => setTerms(next)}
      options={options}
      value={terms}
    />
  );
};

服务

服务是提供额外功能的公用事业功能.

解析CSV文件

分析一个 CSV 文件并将其转换成一系列对象.

鉴于一个包含 CSV 数据的文件对象, parseCSVFile 解析 CSV 并返回由列名键入的一系列对象。 假定CSV中的第一行为列名. 跳过空行并尝试进行自动类型转换.

参数

• { file - CSV文件对象.

回返

• {保证} - 一个能解决一行对象的保证 .

获取媒体Url

从媒体对象中取出媒体项目的URL,其大小为请求的大小.

考虑到从 WordPress REST API 返回的媒体对象,如果媒体项目存在,则以请求的大小提取其URL,如果没有,则提取其全部大小。 如果找不到空字符串, 则返回空字符串 。 使用Gutenberg图像组件用于从媒体REST API响应中选择正确图像大小的超集逻辑.

参数

• {对象} media - WordPress API返回的媒体对象.
• {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}你来干什么 size - 媒体大小需要请求。 默认: 已满

回返

• {string} - 资产上的 URL, 或者失败时的空字符串 .

更改日志

这个项目保持 更改日志。 。 。 .

发展进程

这个软件包是作为以下文件的一部分开发的: Alley 脚本 gitHub 上的项目。 该项目是作为一个单簧管组织,使用 npm 工作空间 和单个软件包在 @ alley 交互 组织.

捐款

您可通过多种方式为该项目做出贡献:

• 访问主 Alley 脚本 GitHub repo 改为 打开一个问题 或者提交公关.

释放

本项目遵循 语义版 2.0.0 规格。 所有主要的、次要的和补丁的发布都发布到npm,并在repo中贴上标签。 我们将为每个小版本(例如:块-编辑工具/0.1)保持单独的分支,以管理补丁释放,同时将未来的开发保持在 main 树枝.

维护者

这个项目由下列机构积极维持: Alley 交互式就像你看到的一样? 跟我们一起工作吧。 。 。 .

许可证

本软件根据GNU通用公共许可证版本2或后期任何版本的条款发布.