@ capaly- labs/ react- hooks

[大
我们的 3.0 反应钩子库的发布候选件目前作为能动-js的模块可供使用,它包括使用上下文提供者和提供API以响应连接错误和信道错误等重大改进. 请看 新反应钩子 REDME 用于安装指令和使用示例.

使用 Ably 在您的反应应用程序中使用平庸,容易使用, React Hooks!

您可以使用此软件包 :

• 使用反应钩与Ably频道进行交互.
• 通过 Ably 使用频道发送信件
• 获取频道中用户存在的通知
• 发送存在更新

钩子为与Ably互动提供了简化的语法,并管理了Ably SDK实例的生命周期,供您在反应组件重接时注意订阅并不订阅频道和事件.

• 安装
  • 兼容反应版本
  • Ably 频道和 API 密钥
• 使用量
  • 使用频道
  • 使用常识
• 开发者笔记

安装

船钩作为ES6舱,所以你可以使用 import 反应代码中的语法.

npm install --save @ably-labs/react-hooks

这在盒子里有用 create-react-app - 你可以马上使用包裹.

兼容反应版本

此套件的最新版本跟踪最新版本的反应.

Ably 频道和 API 密钥

为了使用这些钩子,您需要Ably API 键. 如果你还没有注册,你可以 现在报名免费Ably账户一旦你有Ably账户:

1. 进入您的应用仪表板.
2. 下 “你的应用程序”,单击 “管理软件” 用于您想要用于此教程的任何应用程序,或创建“创建新应用程序”按钮的新应用程序.
3. 点击 “API 密钥” 选项卡.
4. 复制这个秘密 “API 密钥” 从你的"根"键得到的值,我们会使用这个 当我们建立我们的应用程序.

强烈建议您使用 托肯认证,这需要超出此读取范围的服务器侧码。 在下面的例子中,我们直接在加价时使用 API 键,这是用于 *仅当地发展 财务报告和审定财务报表 不应用于生产代码 财务报告和审定财务报表 不应该 献身于你的仓库.

使用量

一旦你用 npm 对你的项目,你可以用你的钩子 react 代码.

以添加对钩的引用开始

import { configureAbly, useChannel } from "@ably-labs/react-hooks";

那你需要用那个 configureAbly 函数创建实例 Ably JavaScript SDK (英语).

configureAbly({ key: "your-ably-api-key", clientId: generateRandomId() });

configureAbly 匹配 Ably SDK 的方法签名 - 并且需要任意一种 string 或一个 AblyClientOptions。您可以使用此配置对象来设置您的 API 密钥, 或者按您通常的方式进行符号认证 。 如果你想用这个 usePresence 钩子,你需要明确提供 clientId。 。 。 .

一旦你这样做,你可以使用 hooks 在你的代码。 最简单的例子如下:

const [channel] = useChannel("your-channel-name", (message) => {
    console.log(message);
});

每次发送消息 your-channel-name 它会登录到控制台。 你可以随心所欲地处理那些留言.

使用频道

使用Channel 钩子可以让您订阅一个频道并从中接收消息.

const [channel, ably] = useChannel("your-channel-name", (message) => {
    console.log(message);
});

频道实例和Ably JavaScript SDK实例都从使用Channel调用中返回.

useChannel 与正则反应结合时真的会发光 useState 钩子 - 例如, 您可以在应用程序状态中保存信件列表, 并使用 useChannel 钩入订阅频道, 当新消息到达时更新状态 .

const [messages, updateMessages] = useState([]);
const [channel] = useChannel("your-channel-name", (message) => {
    updateMessages((prev) => [...prev, message]);
});

// Convert the messages to list items to render in a react component
const messagePreviews = messages.map((msg, index) => <li key={index}>{msg.data.someProperty}</li>);

useChannel 支持常规调用的所有参数组合 channel.subscribe,因此您可以通过提供 message type 页:1 useChannel 函数 :

const [channel] = useChannel("your-channel-name", "test-message", (message) => {
    console.log(message); // Only logs messages sent using the `test-message` message type
});

这个 channel 实例返回 useChannel 可用于向频道发送消息。 这只是一个普通的 Ably JavaScript SDK channel 举个例子.

channel.publish("test-message", { text: "message text" });

因为我们把频道实例 和Ably SDK实例从我们 useChannel 钩子,您可以随后使用这些来进行您喜欢的频道操作 .

例如,你可以这样检索历史:

const [channel] = useChannel("your-channel-name", (message) => {
    console.log(message);
});

const history = channel.history((err, result) => {
    var lastMessage = resultPage.items[0];
    console.log('Last message: ' + lastMessage.id + ' - ' + lastMessage.data);
});

同样值得强调的是 useChannel 钩子支持常规的Ably SDK所做的所有附加参数,因为我们只是通过调用. 这意味着你可以使用像 rewind数字 :

const [channel] = useChannel("[?rewind=100]your-channel-name", (message) => {
    // This call will rewind 100 messages
    console.log(message);
});

我们支持提供 频道选项 页:1 useChannel 钩:

const [channel] = useChannel({ channelName: "your-channel-name", options: { ... } }, (message) => {
    ...
});

我们也支持提供你自己的 Realtime 实例 useChannel,如果在同一页上需要一个以上的 Ably 客户端,则可能有用 :

import { useChannel, Realtime } from '@ably-labs/react-hooks'

const realtime = new Realtime(options);

useChannel({ channelName: "your-channel-name", realtime: realtime }, (message) => {
    ...
})

对于任何必须提供频道选项的情况(例如设置加密密钥).

使用常识

使用Presence hook 允许您订阅频道上的存在事件 - 这将允许您在用户加入或离开频道时得到通知 .

请注意 获取当前成员被执行 作为一种效果,所以它会加载 之后 您的组件是第一次.

const [presenceData, updateStatus] = usePresence("your-channel-name");

// Convert presence data to list items to render    
const peers = presenceData.map((msg, index) => <li key={index}>{msg.clientId}: {msg.data}</li>);

usePresence 返回存在消息的数组 - 每一个消息都是一种常规的 Ably JavaScript SDK presenceMessage 举个例子.

您可以选择提供字符串 usePresence 设置初始 presence data 绳子.

const [presenceData, updateStatus] = usePresence("your-channel-name", "initial state");

// The `updateStatus` function can be used to update the presence data for the current client
updateStatus("new status");

新状态会被发送到频道,其他订阅频道的客户将立即被通知更改.

如果你不想用这个 presenceData 从使用中返回 Presence, 您可以配置回调

const [_, updateStatus] = usePresence("your-channel-name", "initial state", (presenceUpdate) => {
    console.log(presenceUpdate);
});

使用支持对象以及字符串

usePresence("your-channel-name", { foo: "bar" });

如果你正在使用 TypeScript 有类型的提示可以确保更新是相同的 type 或提供的通用类型参数:

const TypedUsePresenceComponent = () => {
    // In this example MyPresenceType will be checked - if omitted, the shape of the initial 
    // value will be used ...and if that's omitted, `any` will be the default.

    const [val] = usePresence<MyPresenceType>("testChannelName", { foo: "bar" });

    return (
        <div role='presence'>
            {JSON.stringify(val)}
        </div>
    );
}

interface MyPresenceType {
    foo: string;
}

PresenceData 这是储存同步、每个客户元数据的好办法, 所以这里的类型特别有价值.

我们也支持提供你自己的 Realtime 实例 usePresence,如果在同一页上需要一个以上的 Ably 客户端,则可能有用 :

import { useChannel, Realtime } from '@ably-labs/react-hooks'

const realtime = new Realtime(options);

usePresence({ channelName: "your-channel-name", realtime: realtime }, (presenceUpdate) => {
    ...
})