jira云端插件开发05-JIiraHook的使用

useState

创建一个值以及改变它值的函数

函数签名：

function useState<V>(
  initialValue: V | (() => V) | (() => Promise<V>)
): [V, (newState: V) => void];

参数可以是一个值、一个返回值的函数或一个返回 Promise 的函数。如果返回一个 Promise，则 Promise 的解析值就是初始状态。

返回值：

两个元素的数组。第一个元素是钩子的当前状态。第二个值是用于更新状态的函数。这个函数的参数是新状态的值。

代码块样例：

import ForgeUI, { render,useState, Button, Fragment, Macro, Text } from "@forge/ui";

const App = () => {

  const [count,setCount] = useState(0);
  return (
    <Button
    text={`Count is ${count}`}
    onClick = {()=>{
      setCount(count+1);
    }}
    ></Button>
  );
};

export const run = render(
  <Macro
    app={<App />}
  />
);

useAction

与state类似只不过根据当前值做出改变

函数签名：

function useAction<V, P>(
  reducer: (currentState: V, payload: P) => V | Promise<V>,
  initialValue: V | (() => V) | (() => Promise<V>)
): [V, (payload?: P) => void];

参数currentState是当前值，initialValue是传入的值可以为函数可以为promise;

返回值：

两个元素的数组。第一个元素是钩子的当前状态。第二个值是用于更新状态的函数。您调用此函数的参数将传递给 reducer 函数的第二个参数。

代码块样例：

import ForgeUI,{ render,useAction, Button, Macro} from "@forge/ui";

const App = () => {

  const [count,setCount] = useAction(
    (currentCount, step) => currentCount + step,
    30
  );
  return (
    <Button
    text={`Count is ${count}`}
    onClick = {()=>{
      setCount(5);
    }}
    ></Button>
  );
};

export const run = render(
  <Macro
    app={<App />}
  />
);

useEffect

监听值改变从而触发函数

函数签名：

function useEffect = (
  onChange: () => void | Promise<void>,
  dependencies: (boolean | string | number | object)[]
): void;

onChange 是当绑定值改变时执行的函数，没有返回值或一个promise
dependencies 是当前绑定值可以是任意格式的变量

返回值：

没有返回值

代码块样例：

import ForgeUI, { render,Text, useEffect,Button, useState, Fragment,Macro } from '@forge/ui';

const sendLog = async () => Promise.resolve('send!');

const LogData = ({ counter }) => {
  const [logSend, setLogSend] = useState();

  useEffect(async () => {
    await sendLog();

    setLogSend(Date.now());
  }, [counter]);

  return <Text>Last log: {logSend}</Text>;
};

const App = () => {
  const [count, setCount] = useState(0);
  return (
    <Fragment>
      <Button
        text={`Count is ${count}`}
        onClick={() => {
          setCount(count + 1);
        }}
      />
      <LogData counter={count} />
    </Fragment>
  );
};

export const run = render(<Macro app={<App />} />);

useProductContext

返回当前上下文信息

函数返回值见：https://developer.atlassian.com/platform/forge/ui-kit-hooks-reference/#useproductcontext

代码块样例：

import ForgeUI, { useProductContext, Text, Macro, render } from '@forge/ui';

const App = () => {
  const context = useProductContext();
  return <Text>All info about my context: {JSON.stringify(context)}</Text>;
};

export const run = render(<Macro app={<App />} />);

useConfig

获取当前配置信息，需要设置配置后才可使用（使用useConfig时需要在manifest配置配置函数）

代码块样例：

import ForgeUI, {
  useConfig,
  Text,
  TextField,
  Macro,
  MacroConfig,
  render,
} from '@forge/ui';

const defaultConfig = {
  name: "Unnamed Pet",
  age: "0"
};

const App = () => {
  // Retrieve the configuration
  const config = useConfig()|| defaultConfig;
  console.log(useConfig());
  // Use the configuration values
  return (
    <Text>
      {config.name} is {config.age} years old.
    </Text>
  );
};

export const run = render(<Macro app={<App />} />);

// Function that defines the configuration UI
const Config = () => {
  return (
    <MacroConfig>
      <TextField name="name" label="Pet name" />
      <TextField name="age" label="Pet age" />
    </MacroConfig>
  );
};


export const config = render(<Config />);

useContentProperty

与usestate类似，只不过把信息存入当前插件中

函数签名：

function useContentProperty<V>(
  key: string,
  defaultValue: V
): [
  V,
  ((value: V | ((prevValue: V) => V), retries?: number) => Promise<V>),
  () => Promise<void>
];

key：内容属性的键。该键是自动命名的，并与 form 键一起存储forge-${localId}-${key}。
defaultValue：如果内容属性尚不存在，则使用的默认值。

代码块样例：

import ForgeUI, { Button, Macro, render } from '@forge/ui';
import { useContentProperty } from '@forge/ui-confluence';

const App = () => {
  const [count, setCount] = useContentProperty('count', 0);
  return (
    <Button
      text={`Count is ${count}`}
      onClick={async () => {
        // replace current value (regardless of if changed by someone else)
        await setCount(count + 1);
        await setCount((prevCount) => prevCount + 1);
      }}
    />
  );
};

export const run = render(<Macro app={<App />} />);

函数返回值：
（数组）

第一个元素是内容属性的当前值（如果内容属性不存在，则为默认值）。
第二个元素是用于更新内容属性的函数。有两种方法可以使用它：
	提供一个新值，它将创建或替换内容属性。
	提供一个更新函数，它获取存储在内容属性中的当前值并返回一个更新的值来存储。如果更新失败（由于其他更新），每个函数调用可能会多次调用更新。第二个可选值指定尝试的重试次数（默认为 2）。
第三个元素是可用于删除空间属性的函数。

useIssueProperty

与useContentProperty 类似但是只能在jira中使用

代码块样例：

import ForgeUI, { render, IssuePanel, Text, Button } from '@forge/ui';
import { useIssueProperty } from '@forge/ui-jira';
const App = () => {
  const [count, setCount] = useIssueProperty('counter', 1);
  return (
    <IssuePanel>
      <Text>Current value {count}</Text>
      <Button
        text="Add one (modify)"
        onClick={async () => {
          await setCount(count + 1);
        }}
      />
    </IssuePanel>
  );
};
export const run = render(<App />);

useSpaceProperty

配置可以全局使用的变量

函数签名：

function useSpaceProperty<V>(
  key: string,
  defaultValue: V
): [
  V,
  ((value: V | ((prevValue: V) => V), retries?: number) => Promise<V>),
  () => Promise<void>
];

代码块样例：

import ForgeUI, { Button, Macro, render } from '@forge/ui';
import { useSpaceProperty } from '@forge/ui-confluence';

const App = () => {
  const [count, setCount] = useSpaceProperty('space-wide-count', 0);
  return (
    <Button
      text={`Count is ${count}`}
      onClick={async () => {
        // replace current value (regardless of if changed by someone else)
        await setCount(count + 1);
      }}
    />
  );
};

export const run = render(<Macro app={<App />} />);